游戏客户端架构 / 系统课时

封装空间转换时该暴露什么

封装空间转换时该暴露什么

一个只接收向量和矩阵的转换函数很短,却无法发现拿错节点或混用两帧姿态的问题。本节让接口显式携带空间标识、采样帧与变换快照,在转换之前拒绝不一致输入,而不是在结果漂移后补偏移。

学习目标

  • 为转换接口定义空间、时间和单位契约
  • 使用不可变矩阵快照避免缓存污染
  • 将失败条件留在边界处理

暴露业务需要的信息

点转换至少需要点值、来源空间、目标空间,以及同一时间的变换。单位可以固定为米并在类型或空间标识中写清。若某个接口只收两个矩阵,调用方很难看出它们是否来自正确节点,更无法知道父级是否已经移动。

同一帧标签不自动保证采样阶段一致。动画更新前与更新后的矩阵都可能标为同一帧,应把采样阶段纳入真实项目的快照标识。异步查询还要保留查询时的目标姿态,不能用当前矩阵解释上一帧返回的局部命中。

捕获后不要允许外部改矩阵

Python 3.12、NumPy 2.3.5 可运行下例,保存为 demo.py 后执行 python demo.py。空间名称包含单位;代码仅接受可逆仿射矩阵,避免把投影矩阵误放进普通点转换。

python
from dataclasses import dataclass
import numpy as np

@dataclass(frozen=True)
class Frame:
    name: str
    tick: int
    to_world: np.ndarray

def capture(name, tick, matrix):
    m = np.array(matrix, dtype=float, copy=True)
    if m.shape != (4, 4) or not np.all(np.isfinite(m)):
        raise ValueError("invalid matrix")
    if not np.allclose(m[3], [0, 0, 0, 1]) or np.linalg.cond(m) > 1e10:
        raise ValueError("invalid affine frame")
    m.setflags(write=False)  # 快照不共享可变的源数组。
    return Frame(name, tick, m)

def point_between(value, source, destination):
    if source.tick != destination.tick:
        raise ValueError("snapshot mismatch")
    point = np.asarray(value, dtype=float)
    if point.shape != (3,) or not np.all(np.isfinite(point)):
        raise ValueError("invalid point")
    return (np.linalg.inv(destination.to_world) @ source.to_world @ np.append(point, 1))[:3]

matrix = np.eye(4)
matrix[:3, 3] = [10, 0, 0]
source = capture("weapon:m", 7, matrix)
destination = capture("world:m", 7, np.eye(4))
matrix[0, 3] = 999  # 不应污染已捕获的姿态。
print("point", point_between([2, 0, 0], source, destination).tolist())
try:
    point_between([2, 0, 0], source, capture("world:m", 8, np.eye(4)))
except ValueError as error:
    print("rejected", str(error))

预期输出:

text
point [12.0, 0.0, 0.0]
rejected snapshot mismatch

缓存要跟随祖先失效

同一快照内可以缓存矩阵逆,减少大量点转换的重复开销。节点本身没有修改不代表世界矩阵没有变化,父级移动也必须触发失效。使用引擎的世界变换版本或集中采样机制,比每个调用点各自猜测缓存是否新鲜更可靠。

不要为追求统一而暴露所有引擎对象。业务层可以只看点、方向、空间标识和失败结果,适配层负责查询引擎姿态并转换单位。需要修改场景节点时走另一组明确的写入接口,避免一个“转换”函数暗中移动对象。

NumPy 的只读标记用于防止正常调用中的意外写入,不是安全隔离;真实 API 仍需约束构造入口。验证重点应是源矩阵后续变化不会影响快照、时间不匹配会被拒绝、逆不存在会失败,以及同一快照内往返误差保持在约定范围内。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

封装空间转换时该暴露什么

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通