Amethyst 迁移实战指南：从 cgmath 到 nalgebra 的完整代码改造手册

【免费下载链接】amethystData-oriented and>项目地址https://gitcode.com/gh_mirrors/ame/amethyst点击查看免费下载导读Amethyst 在引擎内部以nalgebra全面取代了cgmath作为核心数学库这对所有使用amethyst::core::cgmath或amethyst::renderer旧 API 的项目代码、Prefab 配置文件都是一次波及面很广的破坏性变更。本文以官方迁移速查表 book/src/appendices/b_migration_notes/cgmath_to_nalgebra.md 为骨架逐条整理类型重命名、Transform 访问器 API、投影参数顺序、角度单位等关键差异并结合本仓库源码验证每一条迁移规则的底层实现。读完本文你可以系统性地完成一次 cgmath → nalgebra 的全量代码迁移并理解这些 API 变化背后的设计动机。迁移背景与速查表使用方式为什么需要这份迁移文档迁移后 Amethyst 将nalgebra以别名math重新导出这是所有迁移代码的统一入口。源码证据位于 amethyst_core/src/lib.rspub use nalgebra as math;这意味着旧代码中的amethyst::core::cgmath::Vector3一律改为amethyst::core::math::Vector3其余nalgebra的既有能力四元数、矩阵、刚体变换等也全部可以通过math前缀访问。官方速查表按两类变化组织Type Changes类型变化原来用this::Type现在用another::ThingLogic Changes逻辑变化原来调用object.method(args)现在改为object.other(stuff)。该文档明确说明自己并非详尽无遗如果遇到速查表未覆盖的类型或方法文档作者欢迎以 PR 形式补充。此外文档刻意设计为可搜索查找某个具体类型或方法时直接使用Ctrl F搜索TypeName即可。本文在整理时保留了这一风格方便你按图索骥。类型迁移命名空间与类型名的双重变化同名类型仅换命名空间大量类型在nalgebra下保留了相同的简单名称迁移时只需替换导入路径-use amethyst::core::cgmath::{Vector2, Vector3, Matrix4}; use amethyst::core::math::{Vector2, Vector3, Matrix4};此类同名类型包括但不限于Vector2、Vector3、Matrix4、Quaternion等逐一列出意义不大速查表只强调简单名称不同的类型。异名类型类型名本身发生变化少数类型在nalgebra中换了名字需要同时修改类型名与构造方式-cgmath::Ortho math::Orthographic3 -cgmath::PerspectiveFov math::Perspective3从源码看nalgebra的Orthographic3与Perspective3是直接以近远裁剪面 视锥参数构造的投影类型。不过要注意一个重要的实现细节Amethyst 渲染引擎使用 Vulkan 坐标系深度方向为 1→0因此引擎内部的相机并不直接使用nalgebra的这两个投影类型而是封装了自己的Camera投影方法见下文相机与投影一节Orthographic3/Perspective3通常只出现在纯数学计算场景。数学 API 逻辑变化函数名与调用签名常量向量构造cgmath的unit_z()在nalgebra中改为静态方法z()-Vector3::unit_z() Vector3::z()同理nalgebra还提供x_axis()/y_axis()/z_axis()这类返回单位向量UnitVector3的方法它们经常配合旋转 API 使用见下文 Transform 旋转部分transform.rs 中的prepend_rotation_x_axis等即基于此实现。从矩阵提取向量cgmath通过访问矩阵的z成员并truncate()提取平移分量nalgebra则使用列访问 .xyz()-matrix4.z.truncate() matrix4.column(2).xyz().into()这是因为nalgebra的矩阵以列优先存储平移分量位于第 3 列下标 2column(2)返回该列向量.xyz()丢弃齐次坐标的 w 分量后得到Vector3。仓库中同样可以找到这种用法例如 submodules/gather.rs 通过transform.global_matrix().column(3).xyz()提取全局平移。transform_point 需要显式引用nalgebra的transform_point要求传入引用因为要避免隐式拷贝、支持对非 Copy 类型调用-matrix4.transform_point(origin) matrix4.transform_point(origin)Transform 组件 API 迁移从公开字段到访问器方法这是整个迁移中最容易踩坑的部分涉及amethyst::core::transform::Transform的公开 API 彻底重构。先从源码层面理解原因迁移后的Transform内部使用nalgebra的Isometry3f32刚体变换旋转 平移存储位姿缩放分量单独保存且三者都被标记为私有字段见 transform.rs#[serde(from TransformValues, into TransformValues)] pub struct Transform { #[serde_diff(opaque)] isometry: Isometry3f32, #[serde_diff(opaque)] scale: Vector3f32, #[serde_diff(opaque)] global_matrix: Matrix4f32, #[serde_diff(opaque)] parent_matrix: Matrix4f32, }因此旧代码中直接读写transform.translation、transform.scale、transform.rotation字段的写法全部失效必须改用访问器方法。基础读写整体赋值与整体取值-transform.translation Vector3::new(5.0, 2.0, -0.5); -transform.scale Vector3::new(2.0, 2.0, 2.0); -transform.rotation Quaternion::new(1.0, 0.0, 0.0, 0.0); transform.set_translation_xyz(5.0, 2.0, -0.5); transform.set_scale(2.0, 2.0, 2.0); transform.set_rotation(Unit::new_normalize(Quaternion::new(1.0, 0.0, 0.0, 0.0)));注意set_rotation接受的不是裸Quaternion而是UnitQuaternion单位四元数。源码签名印证了这一点transform.rspub fn set_rotationN: RealField SubsetOff32( mut self, rotation: UnitQuaternionN, ) - mut SelfUnit::new_normalize会在构造时归一化避免传入非单位四元数导致变换矩阵非法。通过可变引用修改如果不希望整体覆盖可以用*_mut()系列方法拿到可变引用后直接赋值// Translations -transform.translation Vector3::new(0.0, 0.0, 0.0); *transform.translation_mut() Vector3::new(0.0, 0.0, 0.0); -transform.set_position(Vector3::new(6.0, 6.0, -6.0)); transform.set_translation_xyz(6.0, 6.0, -6.0); // or *transform.translation_mut() Vector3::new(6.0, 6.0, -6.0);// Scaling -transform.scale Vector3::new(1.0, 1.0, 1.0); *transform.scale_mut() Vector3::new(1.0, 1.0, 1.0);对应实现见 transform.rstranslation()返回Vector3f32translation_mut()返回mut Vector3f32rotation()返回UnitQuaternionf32rotation_mut()返回mut UnitQuaternionf32。读取与差值计算读取方向的变化是字段访问 → 方法调用注意所有读取方法都以()结尾-transform_0.translation - transform_1.translation transform_0.translation() - transform_1.translation() -transform.translation[0] x; transform.set_translation_x(position.x); -let ball_x transform.translation[0]; let ball_x transform.translation().x;set_translation_x只改 x 分量源码实现为直接给isometry.translation.vector.x赋值transform.rs另有set_translation_y、set_translation_z同理。增量平移prepend / append 系列旧代码直接对translation.x做加减运算新 API 提供语义更清晰的增量方法-translation.x 0.1; -translation.y - 0.1; transform.prepend_translation_x(0.1); transform.prepend_translation_y(-0.1); // or transform.translation_mut().x 0.1; transform.translation_mut().y - 0.1;这里要特别注意prepend与append的语义差异。源码注释给出了精确定义transform.rsprepend_translation_*沿父级或全局的坐标轴平移即叠加到当前平移向量上不经过自身旋转append_translation沿自身局部坐标轴平移等价于先把平移量按当前旋转旋转后再叠加源码为self.isometry.translation.vector self.isometry.rotation * translation。例如物体绕 Y 轴旋转 45° 后prepend_translation_z仍沿父级 Z 轴移动而append_translation会沿旋转后的局部 Z 轴移动。游戏开发中这两种需求都很常见迁移时务必按语义选择。旋转 API欧拉角与轴角旧代码用Deg角度包装器 set_rotation新代码改为弧度制的set_rotation_euler或单轴方法-use amethyst::core::cgmath::Deg; - -transform.set_rotation(Deg(75.96), Deg(0.0), Deg(0.0)); transform.set_rotation_x_axis(1.3257521); // or transform.set_rotation_euler(1.3257521, 0.0, 0.0);源码显示transform.rspub fn set_rotation_x_axis(mut self, angle: f32) - mut Self { self.set_rotation_euler(angle, 0.0, 0.0) }set_rotation_euler的实现是UnitQuaternion::from_euler_angles(x, y, z)欧拉顺序为 x → y → z所有角度均为弧度transform.rs。示例中的1.3257521正是75.96°的弧度值约等于75.96_f32.to_radians()。完整的旋转方法族还包括set_rotation_y_axis(angle)/set_rotation_z_axis(angle)清除其他旋转后绕指定轴设置旋转prepend_rotation_x_axis / y_axis / z_axis(delta_angle)绕父级/全局轴增量旋转append_rotation_x_axis / y_axis / z_axis(delta_angle)绕局部轴增量旋转set_rotation_2d(angle)/rotate_2d(delta_angle)2D 游戏最常用的绕 Z 轴旋转快捷方法内部即set_rotation_euler(0.0, 0.0, angle)见 transform.rseuler_angles()读取当前旋转的欧拉角三元组弧度。欧拉角语义Amethyst 与 nalgebra 的坐标系差异这是迁移后最容易产生困惑的点。源码注释transform.rs特别警告nalgebra自带的from_euler_angles/euler_angles基于roll / pitch / yaw语义且假设Z up的坐标系而 Amethyst 使用Y up的坐标系。因此如果直接用nalgebra的欧拉方法roll对应绕 X 轴、pitch对应绕 Y 轴、yaw对应绕 Z 轴与 Amethyst 的语义错位Amethyst 因此提供了自己的set_rotation_euler(x, y, z)x → y → z逐轴含义与 Amethyst 坐标系一致迁移时应优先使用该方法而不是nalgebra的欧拉方法。四元数整体赋值-transform.rotation [1.0, 0.0, 0.0, 0.0].into(); use amethyst::core::math::{Quaternion, Unit}; *transform.rotation_mut() Unit::new_normalize(Quaternion::new( 1.0, // w 0.0, // x 0.0, // y 0.0, // z ));nalgebra的Quaternion::new(w, x, y, z)参数顺序是w 在前与cgmath的Quaternion::new(s, v)语义一致但写入Transform时必须包一层Unit::new_normalize。Transform 构造方式如果需要在创建时指定完整位姿可以走Transform::new(position, rotation, scale)泛型构造transform.rslet position Translation3::new(0.0, 2.0, 4.0); let rotation UnitQuaternion::from_euler_angles(0.4, 0.2, 0.0); let scale Vector3::new(1.0, 1.0, 1.0); let t Transform::new(position, rotation, scale);其中Translation3::new(x, y, z)是nalgebra的平移类型Isometry3::from_parts将平移与单位四元数组合成刚体变换。默认构造Transform::default()则是单位刚体变换 各分量为 1.0 的缩放transform.rs。Prefab 序列化格式变化Transform 不再使用具名字段Transform的 PrefabRON 序列化格式也随迁移改变。新格式使用裸元组/数组不再使用x: / y: / z:标签和s: / v:四元数分解。旧格式// scene.ron data: ( transform: ( - translation: (x: 0.0, y: 0.0, z: -4.0), - rotation: (s: 0.0, v: (x: 0.0, y: 1.0, z: 0.0),), - scale: (x: 4.0, y: 2.0, z: 1.0), translation: (0.0, 0.0, -4.0), rotation: (0.0, 0.0, 1.0, 0.0), scale: (4.0, 2.0, 1.0), ),从源码可以确认新的序列化契约。Transform通过 serde 的from/into属性对接TransformValues结构transform.rs#[serde(rename Transform, default)] pub struct TransformValues { translation: [f32; 3], rotation: [f32; 4], scale: [f32; 3], }其中rotation: [f32; 4]的顺序是(w, x, y, z)默认值[0.0, 0.0, 0.0, 1.0]即单位四元数w 在首位。所以 Prefab 中写rotation: (0.0, 0.0, 1.0, 0.0)表示绕 Y 轴的单位四元数分量排列。迁移现有scene.ron时务必同步更新所有含transform:的节点。GlobalTransform 求逆invert 改名为 try_inverseamethyst::renderer::GlobalTransform包装Matrix4的求逆方法在nalgebra中更名为try_inverse因为矩阵求逆可能失败nalgebra将其设计为返回Option-global.0.invert() global.0.try_inverse()需要自行处理None分支如expect或默认矩阵。这种失败显式化是nalgebraAPI 的整体风格同类情况在相机代码中也有体现Camera::from_matrix内部即使用matrix.try_inverse().expect(...)camera.rs。顶点结构 Pos* 字段数组改为 nalgebra 向量amethyst::renderer::Pos*系列顶点结构PosTex、PosNormTex、PosNormTangTex等的字段由固定长度数组改为nalgebra向量类型pub struct PosTex { - pub position: [f32; 3], - pub tex_coord: [f32; 2], pub position: Vector3f32, pub tex_coord: Vector2f32, }构造方式随之变化PosTex { - position: [0.0, 0.0, 0.0], - tex_coord: [0.0, 0.0], position: Vector3::new(0.0, 0.0, 0.0), tex_coord: Vector2::new(0.0, 0.0), }仓库佐证PosTex等顶点结构仍定义于 shape.rsPosTex { position, tex_coord }而nalgebra向量与渲染用 POD 类型的转换桥接位于 pod.rsimpl IntoPodvec2 for amethyst_core::math::Vector2f32 { ... } impl IntoPodvec3 for amethyst_core::math::Vector3f32 { ... }即顶点数据在上传 GPU 时会由IntoPod转换回vec2/vec3布局业务代码中则统一使用math::Vector2/3f32编写。Matrix4 构造平移矩阵的新写法cgmath的Matrix4::from_translation在nalgebra中不存在同名方法官方推荐两种等价写法-Matrix4::from_translation(Vector3::new(x, y, z)) Matrix4::new_translation(Vector3::new(x, y, z)) // OR use amethyst::core::math::Translation3; Translation3::new(x, y, z).to_homogeneous()第一种直接构造 4×4 平移矩阵第二种先构造Translation3nalgebra的 3D 平移变换再通过to_homogeneous()提升为齐次坐标下的Matrix4语义上更贴近刚体变换由平移 旋转组合的建模思路。相机与投影手性、参数顺序与角度单位UnitQuaternion::rotation_between 的手性反转-// cgmath 时代为左手系 // nalgebra 为右手系 UnitQuarternion::rotation_between // 注意拼写实际是 UnitQuaternion速查表明确指出UnitQuaternion::rotation_between在两个库中计算结果的手性相反——cgmath是左手系nalgebra是右手系。如果你的代码依赖rotation_between让物体朝向某方向例如Transform::face_towards的实现见 transform.rs其内部即调用UnitQuaternion::face_towards迁移后朝向可能出现镜像翻转需要通过交换up向量或对旋转结果取逆来修正。正交投影参数顺序从 (left, right, top, bottom) 变为 (left, right, bottom, top)这是最容易静默出错的一处。cgmath::Ortho的参数顺序为(left, right, top, bottom, near, far)而nalgebra的Orthographic3顺序为(left, right, bottom, top, near, far)Projection::orthographic( 0.0, // left ARENA_WIDTH, // right - ARENA_HEIGHT, // top 0.0, // bottom ARENA_HEIGHT, // top ) -use amethyst::core::cgmath::Ortho; - -Ortho { left, right, top, bottom, near, far } use amethyst::core::math::Orthographic3; Orthographic3::new(left, right, bottom, top, near, far)对于left 0、bottom 0的对称情形top与bottom恰好互换数值位置后结果不变代码仍能编译但含义已经改变务必逐项核对。Amethyst 自带的Camera::orthographic同样采用(left, right, bottom, top, z_near, z_far)顺序camera.rs且该函数会在 debug 模式下断言left ! right、bottom ! top、z_near ! z_far帮助提前发现参数颠倒。另一个值得注意的实现细节源码注释明确说明camera.rs由于 Amethyst 内部使用 Vulkan 坐标系右手系、深度 1→0直接使用nalgebra的Orthographic3/Perspective3结果是错误的因此引擎封装了Camera::orthographic/Camera::perspective并手工构造投影矩阵。换句话说游戏代码里的相机应尽量走Camera组件纯数学场景才直接用nalgebra投影类型。透视投影角度一律使用弧度cgmath::Deg包装器在nalgebra中不复存在fovy垂直视场角直接以弧度传递use amethyst::renderer::Projection; -amethyst::core::cgmath::Deg; Projection::perspective( 1.33333, - Deg(90.0) std::f32::consts::FRAC_PI_2, )FRAC_PI_2即π/290° 的弧度值。Camera::perspective(aspect, fov, z_near)的签名也要求fov为弧度camera.rs引擎内部的standard_3d使用FRAC_PI_360°作为默认视场角camera.rs。Prefab 中相机的字段重命名RON 文件中Perspective相机的序列化格式同步调整fovy不再包Rad(...)近远裁剪面字段从near/far改为znear/zfar// scene.ron data: ( camera: Perspective(( aspect: 1.3, - fovy: Rad (1.0471975512), fovy: 1.0471975512, - near: 0.1, - far: 2000.0, znear: 0.1, zfar: 2000.0, )), )1.0471975512正是 60° 的弧度值≈FRAC_PI_3。aspect本身是比值、无单位保持不变。光源角度从度数改为弧度渲染器的两类光源角度字段统一改为弧度制迁移时用to_radians()显式转换或直接写弧度常量SpotLight { - angle: 60.0, angle: std::f32::consts::FRAC_PI_3, .. }SunLight { - ang_rad: 0.0093, ang_rad: 0.0093_f32.to_radians(), .. }源码印证SpotLight的默认angle已是FRAC_PI_360° 的弧度值light.rsSunLight的默认角度为0.0093_f32.to_radians()太阳视半径约 0.0093 弧度light.rs。需要提醒的是当前仓库中SunLight的实际字段名是angle见 light.rs速查表中示例使用的ang_rad是迁移过渡期的名称最终以源码为准——你在迁移时请按实际编译报错修正字段名。另外注意PointLight不受此影响其radius/smoothness本身与角度无关而DirectionalLight的方向字段direction: Vector3f32同样遵循数组 → 向量的迁移规则light.rs。迁移检查清单完成一次 cgmath → nalgebra 迁移后建议按以下清单逐项核查导入路径所有amethyst::core::cgmath::*改为amethyst::core::math::*cgmath::Ortho→math::Orthographic3cgmath::PerspectiveFov→math::Perspective3。Transform 字段访问transform.translation/.scale/.rotation全部改为访问器方法translation()/scale_mut()/rotation_mut()等整体赋值用set_translation_xyz/set_scale/set_rotation。旋转单位所有角度改为弧度优先用std::f32::consts常量或to_radians()欧拉旋转使用 Amethyst 提供的set_rotation_eulerx → y → z避免直接使用nalgebra的 roll/pitch/yaw 方法。增量移动语义区分prepend_*父级/全局轴与append_*局部轴。Prefab 格式scene.ron中transform节点改用元组/数组格式rotation为 w 在前的四元数相机节点fovy去Rad(...)、near/far改为znear/zfar。投影参数正交投影参数顺序为(left, right, bottom, top)透视fovy为弧度。矩阵操作invert()→try_inverse()处理OptionMatrix4::from_translation→Matrix4::new_translation(v)或Translation3::to_homogeneous()。顶点数据Pos*结构字段使用Vector2/3f32构造。光源SpotLight::angle、SunLight::angle均为弧度。手性rotation_between/face_towards迁移后检查朝向是否翻转。延伸阅读本次迁移与引擎内其他两项 API 重构关系密切迁移时建议一并对照Transform API 变更说明Transform访问器 API 的完整演进记录Specs 迁移笔记 与 Rendy 迁移笔记ECS 与渲染后端的同步升级。这三份笔记与本文同属 book/src/appendices/b_migration_notes 目录共同构成 Amethyst 大规模重构期的迁移知识库。若在迁移中发现速查表遗漏的差异官方欢迎以 PR 补充修正。赞分享【免费下载链接】amethystData-oriented and>项目地址https://gitcode.com/gh_mirrors/ame/amethyst点击查看免费下载相关推荐Amethyst 版本迁移指南cgmath 到 nalgebra、Transform API 重构与 Rendy 渲染迁移Amethyst 版本迁移指南cgmath 到 nalgebra、Transform API 重构与 Rendy 渲染迁移 Amethyst 在 0.9 至PixiJS v8 迁移实战指南从 v7 到 v8 的破坏性变更清单与代码改造手册PixiJS v8 迁移实战指南从 v7 到 v8 的破坏性变更清单与代码改造手册 本指南基于 PixiJS 仓库中 v8 迁移 Skill skills/前端图形学Sinon 迁移指南从 Spy 平滑迁移到 Fake 的完整实战手册Sinon 迁移指南从 Spy 平滑迁移到 Fake 的完整实战手册 本指南以 Sinon 官方文档 docs/concepts/spies/migratin测试开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考