数学与容器：vectormath / vector / math、atl 容器、字符串与哈希、curve、spatialdata

本页覆盖 RAGE 的“基础词汇”：两代向量数学库（SIMD 封装的 vectormath 与旧式 vector）、标量数学工具（math、mathext），atl 模板容器（数组、哈希表、二分映射、池、侵入式容器、智能指针）、字符串与哈希命名约定（atStringHash、atHashString 及其命名空间），以及 curve、spatialdata、xmldata、init（INI 解析）和 deprecated 目录。几乎所有其他页面中出现的 Vec3V、atArray、atHashString、spdAABB 都在这里定义。

背景与相关页面#

• 资源构造函数、datResource 修复与 atArray 的资源化见 paging-and-resources.md。
• parser 对这些类型的反射（parMemberType 中的 TYPE_VEC3V、SUBTYPE_ATARRAY、SUBTYPE_ATBINARYMAP、SUBTYPE_ATNONFINALHASHSTRING 等）见 parser-and-metadata.md。
• 游戏层的对象池 fwPool/CPools 与本页的 atPool 不同，见 01-runtime/memory-and-pools.md 与 04-rage-framework/framework-systems.md。
• framework 数学扩展 fwmaths 见 04-rage-framework/framework-systems.md。

相关源码文件#

---

1. vectormath：SIMD 向量库#

1.1 后端选择#

• VECTORIZE = RSG_CPU_PPC || RSG_CPU_SPU || RSG_CPU_INTEL，USE_INTRINSICS = 1，SCALAR_TYPES_ONLY = __PSP2；三者满足时 UNIQUE_VECTORIZED_TYPE = 1，否则退化为标量结构实现（注释称适用于对齐受限的工具构建或调试） src/dev_ng/rage/base/src/vectormath/vectorconfig.h:10-40。
• 底层寄存器类型 Vec::Vector_4V：Xenon __vector4（passinreg）、PS3/SPU AltiVec vector float、Intel __m128（Durango/Orbis 假定 SSE4.1，PC 假定 SSE2）、PSP2 NEON float32x4_t src/dev_ng/rage/base/src/vectormath/vectortypes.h:205-214、src/dev_ng/rage/base/src/vectormath/vectortypes.h:255-265、src/dev_ng/rage/base/src/vectormath/vectortypes.h:303-346。
• 分层：vectormath.h 先声明 V1/V2/V3/V4 前缀的底层函数（V4Add、V4InvSqrt、V4Permute…），再按平台包含 v*vector4vcore_{ps3,xbox360,win32pc}.inl（平台核心实现），最后包含跨平台 .inl（基于核心函数组合）。注释约定：某函数若有平台特化的更快写法，应提升进 core 并为每个平台实现 src/dev_ng/rage/base/src/vectormath/vectormath.h:17-90、src/dev_ng/rage/base/src/vectormath/v4vector4v.h:467-884。

1.2 类型与约定#

classes.h 汇集 AoS 类型 BoolV/VecBoolV/ScalarV/Vec2V/Vec3V/Vec4V/QuatV/Mat33V/Mat34V/Mat44V/TransformV 与标量版 Vec2f/Vec3f/Vec4f/QuatF，以及自由函数 classfreefuncsf.h（标量）/classfreefuncsv.h（向量） src/dev_ng/rage/base/src/vectormath/classes.h:12-50。

SoA 版本（Vec3V_SoA 等，*_soa.h）用四个寄存器分别存 4 个向量的 x/y/z，用于批量运算。

1.3 与旧库互转#

legacyconvert.h 提供 RCC_VEC3V/RC_SCALARV/VECTOR3_TO_VEC3V 等宏，在 Vector3↔Vec3V、Matrix34↔Mat34V、Vector4↔Vec4V 间零成本 reinterpret_cast；LEGACYCONVERT_REINTERPRETCAST_DEBUG = __DEV 时通过函数包装做编译期类型检查 src/dev_ng/rage/base/src/vectormath/legacyconvert.h:12-54、src/dev_ng/rage/base/src/vectormath/vectorconfig.h:24-27。可以零成本互转的前提是两者内存布局一致（见下）。

---

2. vector：旧式数学库#

• Vector3 在 Intel 平台是 union { __m128 xyzw; struct { float x, y, z, w; }; ... }，即 16 字节、带 w；Xenon/PS3/PSP2 同样以向量寄存器类型为底；纯标量回退时由 VECTORIZED_PADDING（恒为 1）保证仍含 w src/dev_ng/rage/base/src/vector/vector3.h:1855-1963、src/dev_ng/rage/base/src/vector/vector3_config.h:10-20。
• vector3_config.h 的 VECTORIZED 只在 Xenon/PS3 为真——即 PC/PS4/XB1 上旧库不使用其 Xenon/PS3 专用的向量化路径（Intel 分支直接使用 SSE intrinsics 的 union 布局） src/dev_ng/rage/base/src/vector/vector3_config.h:10-11。
• Matrix34 是 4 个 Vector3：a, b, c（三轴）与 d（平移），与 Mat34V 的 4 列一一对应 src/dev_ng/rage/base/src/vector/matrix34.h:1630-1638。
• 其余：Vector2/Vector4/Matrix33/Matrix44/Quaternion、颜色 Color32/Color64/ColorVector3、大型几何工具集 geometry.h（相交/距离/求交测试）、凸包 hull.h、量化 quantize.h。

---

3. math 与 mathext#

---

4. 字符串哈希与命名约定#

4.1 哈希函数族#

全部基于 Bob Jenkins 的 one-at-a-time 哈希（逐字节 key += c; key += key<<10; key ^= key>>6，最后 atFinalizeHash：key += key<<3; key ^= key>>11; key += key<<15）：

离线工具中有同算法的 Python 实现（atLiteralStringHash、atStringHash = 小写 + \→/ 后再算字面哈希），parCodeGen 用它预计算 NameHash src/dev_ng/rage/base/tools/cli/parCodeGen/atHash.py:1-23。

4.2 atHashString 家族与命名空间#

哈希字符串类只存一个 u32 m_hash；字符串（若保留）存放在按命名空间划分的全局表中：

证据：命名空间枚举 src/dev_ng/rage/base/src/atl/hashstring.h:44-57；初始化参数 src/dev_ng/rage/base/src/atl/hashstring.cpp:315-333；typedef src/dev_ng/rage/base/src/atl/hashstring.h:362-389。

要点：

• 构建差异：atHashString 在 !__FINAL 下是带字符串的 atNonFinalHashString，在 Final 中退化为只有哈希的 atHashValue；atHashWithStringDev（仅 __DEV 保留）、atHashWithStringBank（仅 __BANK 保留）、atHashWithStringNotFinal 同理 src/dev_ng/rage/base/src/atl/hashstring.h:362-380。这正是 CHealthConfigInfo::GetName() 只在非 Final 可用的原因（见 parser-and-metadata.md 示例）。
• atNamespacedHashString 从字符串构造时同时计算哈希并 AddString 注册；atNamespacedHashValue 只算哈希不注册；二者间转换需显式（防止误把“值”当“串”） src/dev_ng/rage/base/src/atl/hashstring.h:118-203。
• AddString 在命名空间临界区内查表；同哈希不同串视为碰撞并断言——但源码保留了若干“GTA V 数据特有、无法通过改数据解决”的已知碰撞白名单；-breakonname 可在注册某名字时断点 src/dev_ng/rage/base/src/atl/hashstring.cpp:88-121、src/dev_ng/rage/base/src/atl/hashstring.cpp:16。
• 静态初始化顺序：hashstring.cpp 使用 #pragma init_seg(lib) / init_priority(101/102) 并提供 atHashStringNamespaceSupport::EarlyInit，供可能更早静态构造哈希串的翻译单元使用 src/dev_ng/rage/base/src/atl/hashstring.cpp:20-51、src/dev_ng/rage/base/src/atl/hashstring.h:76-82。
• 调试输出惯用 HASHFMT/HASHOUT(x) 打印“名字 (0x哈希)” src/dev_ng/rage/base/src/atl/hashstring.h:18-19。

命名约定小结：资产/实体/对象名用大小写不敏感的 atStringHash（atHashString/atFinalHashString/pgDictionary 键）；反射与 PSO 内部标识用区分大小写的 atLiteralStringHash（atLiteralHashString）；代码中的硬编码常量用 ATSTRINGHASH("x", 0x…) 包装以便断言构建校验。

4.3 其它字符串工具#

string/string.h 提供 safecpy/safecat/formatf/vformatf（带数组长度推导的模板版本）、ConstString（共享常量串，ConstStringDuplicate/ConstStringFree 不可与 StringFree 混用） src/dev_ng/rage/base/src/string/string.h:153、src/dev_ng/rage/base/src/string/string.h:256-386、src/dev_ng/rage/base/src/string/string.h:465-570。 atStringHeap 是基于句柄、可整理碎片的字符串堆（最大 512 KB、8192 句柄、≤240 字节分档空闲表、支持 Touch/GarbageCollect） src/dev_ng/rage/base/src/string/stringheap.h:15-37。另有 atStringBuilder、unicode.h（UTF-8/UTF-16 转换）、stringutil.h。

---

5. atl 容器#

5.1 数组族#

5.2 映射族#

5.3 池、链表与其它#

---

6. curve、spatialdata、xmldata、init、deprecated#

---

约束与边界行为#

• atArray 默认 u16 计数：超过 65535 个元素需显式使用 u32 计数器模板参数；Grow 线性增长，大数组反复 PushAndGrow 是 O(n²) 拷贝。
• atMap 槽数/条目数均为 u16，最大 65521 槽；SetAllowRecompute(false)（例如资源化或预分配的表）时不会扩容，链会无限变长。
• atBinaryMap 在 FinishInsertion() 前查找会断言；atStringMap 不保存原字符串，无法反查名字。
• atStringHash 大小写不敏感且把 \ 当 /，atLiteralStringHash 区分大小写——两者对同一字符串产生不同值，混用会导致查找失败。
• Final 构建中 atHashString 没有字符串：任何依赖 GetCStr() 的逻辑都必须用 atFinalHashString 或 #if !__FINAL 保护。
• ScalarV 必须保持 splat；Vec3V 的 w 分量不可依赖（spdAABB 等明确把 w 用作用户数据）。
• Win32 PC 上 Vec3V_In 是引用，其他平台是值，跨平台代码不应依赖参数别名语义。

未决问题 / 证据不足#

• vectormath 平台核心 .inl（尤其 win32pc 版本中 SSE4.1 指令的具体使用）与 SoA 类型的完整 API 未逐一核对。
• mathext/lcp.h 与物理求解器的具体调用关系留给 09-physics/rage-physics-engine.md。
• atPagedPool、atDynaPool、inmap 的实现细节只做了类型存在确认。