游戏客户端架构 / 系统课时
Position 和 Point 要不要统一
Position 和 Point 要不要统一
一个库叫 Position,另一个叫 Point,并不意味着可以直接重命名后替换。位置通常强调对象状态,点强调几何实体,而真正影响运算的是参考空间与是否接收平移。本节建立小而明确的命名契约,避免统一接口后反而丢失语义。
学习目标
- 用语义与空间决定接口命名
- 区分位置状态读取和几何点变换
- 避免一个通用向量函数承担所有转换
可以统一业务语言,不能删除区别
业务层可以把世界位置统一叫世界点,但应保留来源、目标空间与单位。某对象的位置属性常描述其原点在父空间中的位置;网格顶点则是对象局部空间里的任意点。两者都可使用点变换,却不是同一个属性或同一个参考系。
更容易混淆的是方向。无论位置与方向底层是否都用三维向量,点接收平移,位移不接收平移,纯旋转朝向可能还忽略缩放,法线需要逆转置。把它们都命名为 transform_vector,调用方就只能靠记忆猜行为。
| 建议接口意图 | 明确的契约 |
|---|---|
| 读取对象世界位置 | 返回该对象原点的世界点 |
| 转换几何点 | 输入来源空间,输出目标空间,包含平移 |
| 转换位移 | 相同两空间,忽略平移,按约定继承缩放 |
| 转换单位朝向 | 明确只旋转还是线性后归一化 |
点与位移使用两个入口
下面用两个平行局部坐标系演示:A 原点在世界 (10,0,0),B 原点在世界 (0,5,0)。使用 Python 3.12、NumPy 2.3.5 保存并执行 python demo.py。
python
import numpy as np
def convert_point(value, source_to_world, destination_to_world):
h = np.append(value, 1.)
return (np.linalg.inv(destination_to_world) @ source_to_world @ h)[:3]
def convert_delta(value, source_to_world, destination_to_world):
# w=0,使两个参考系原点之间的平移不参与位移转换。
h = np.append(value, 0.)
return (np.linalg.inv(destination_to_world) @ source_to_world @ h)[:3]
a = np.eye(4)
a[:3, 3] = [10, 0, 0]
b = np.eye(4)
b[:3, 3] = [0, 5, 0]
print("point_a_to_b", convert_point([2, 3, 0], a, b).tolist())
print("delta_a_to_b", convert_delta([1, 0, 0], a, b).tolist())
# 目标回来源后,应恢复原来那个点的描述。
assert np.allclose(convert_point(convert_point([2, 3, 0], a, b), b, a), [2, 3, 0])预期输出:
text
point_a_to_b [12.0, -2.0, 0.0]
delta_a_to_b [1.0, 0.0, 0.0]命名应让空间流动可读
使用 weapon_local_point 与 hit_world_point,比只叫 position1、position2 更容易检查。函数名标出操作,参数或类型标出空间。不要依赖“全项目默认世界空间”来解释所有变量,因为动画、网格、UI 和物理接口仍会带入其他空间。
统一抽象还应明确出错方式。非法点、不可逆矩阵和空间不匹配应返回失败或抛出约定异常,未命中也应使用显式空结果。世界零点是合法位置,不能作为通用错误标志。
若一处封装需要许多布尔参数才能表示点、方向、法线、是否继承缩放,通常说明职责过多。拆成少量具有稳定数学含义的入口,维护成本更低。Position 与 Point 的词汇可以统一,数学规则与参考空间必须继续留在接口里。
按自己的节奏,确认真正理解。