游戏客户端架构 / 系统课时
封装空间转换时该暴露什么
封装空间转换时该暴露什么
一个只接收向量和矩阵的转换函数很短,却无法发现拿错节点或混用两帧姿态的问题。本节让接口显式携带空间标识、采样帧与变换快照,在转换之前拒绝不一致输入,而不是在结果漂移后补偏移。
学习目标
- 为转换接口定义空间、时间和单位契约
- 使用不可变矩阵快照避免缓存污染
- 将失败条件留在边界处理
暴露业务需要的信息
点转换至少需要点值、来源空间、目标空间,以及同一时间的变换。单位可以固定为米并在类型或空间标识中写清。若某个接口只收两个矩阵,调用方很难看出它们是否来自正确节点,更无法知道父级是否已经移动。
同一帧标签不自动保证采样阶段一致。动画更新前与更新后的矩阵都可能标为同一帧,应把采样阶段纳入真实项目的快照标识。异步查询还要保留查询时的目标姿态,不能用当前矩阵解释上一帧返回的局部命中。
捕获后不要允许外部改矩阵
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 仍需约束构造入口。验证重点应是源矩阵后续变化不会影响快照、时间不匹配会被拒绝、逆不存在会失败,以及同一快照内往返误差保持在约定范围内。
按自己的节奏,确认真正理解。