bevy-porting

Bevy 0.19——从其他引擎移植

何时使用此技能

• 将现有游戏从 Unity、Unreal、Godot、Cocos、原生 JavaScript / Phaser、Flash/SWF、Defold、Roblox 或 GameMaker 移植到 Bevy 0.19。
• 评估可行性——我的引擎中的功能 X 是否有 Bevy 0.19 对应功能？
• 决定先移植哪个子系统（我们建议：渲染 + 一个可玩的切片）。
• 无需安装源引擎，即可从源引擎的项目树中提取资源和场景数据——请参阅下方的 scripts/ 政策。
• 使用 cargo + Cargo.toml 功能替换引擎专属的构建流程（Unity Build Settings、Unreal Build Configuration 等）。

引擎覆盖范围

引擎	覆盖范围	脚本
Unity	深入（8 个子系统参考）——参阅下方的 § Unity	scripts/unity/ 中的 4 个 Python 提取器
Unreal Engine 5	references/unreal.md——Actor/Component → ECS、UMG → bevy_ui、Niagara/动画的差距	scripts/unreal/ue5_python_export.py（放入 UE5 编辑器中）
Godot 4	references/godot.md——节点树 → ECS、.tscn 文本格式、GDScript → Rust	scripts/godot/tscn_inventory.py（标准库，无需 Godot）
Cocos Creator 3	references/cocos.md——TypeScript 节点树 → ECS、JSON .scene/.prefab	参考文档中的内嵌 Python 示例
原生 JavaScript / Canvas / HTML5	references/javascript.md——类 + rAF 循环 → ECS 系统、Canvas 2D → Sprite	—（移植需重写，而非提取）
Phaser 3	references/phaser.md——Scene/preload/update → 系统、Arcade 物理、补间动画	—
Flash / SWF	references/flash-swf.md——基于 ffdec 的提取、AS3 → Rust 重写	scripts/flash/swf_assets.py（要求 ffdec 位于 PATH 中）
Defold	references/defold.md——消息传递 → Bevy Message、Lua → Rust、以 2D 为先	参考文档中的内嵌 Python 示例
Roblox	references/roblox.md——Instance 树 → ECS、资源 ID 提取、Luau → Rust	scripts/roblox/rbxlx_inventory.py（仅支持 XML .rbxlx）
GameMaker Studio 2	references/gamemaker.md——对象事件 → 系统、JSON 项目文件	scripts/gamemaker/gms2_inventory.py（标准库，遍历 .yyp）

Unity（优先）

Unity 是覆盖最深入的引擎。八份子系统参考和四个提取脚本共同涵盖了端到端移植：

子系统	参考资料	Bevy 基础构件
架构（GameObject、MonoBehaviour、ScriptableObject、协程）	references/unity-architecture.md	Entity + ChildOf、Component + System、Asset/Resource、异步任务
资源管线（Prefab、Material、Addressables、GUID）	references/unity-assets.md	Bundle/生成函数、StandardMaterial、AssetServer + Handle<T>
场景 → glTF 提取	references/unity-scenes-gltf.md	bevy_gltf、WorldAssetRoot、glTFast / Blender 桥接
Animator / Mecanim	references/unity-animation.md	AnimationGraph、AnimationTransitions::play、#[derive(AnimationEvent)]
输入系统	references/unity-input.md	ButtonInput、Axis、Touches、Gamepad*
UGUI / UI Toolkit	references/unity-ui.md	Node、BackgroundColor、BorderColor、Taffy/flex
音频（AudioSource、AudioListener、混音器）	references/unity-audio.md	AudioPlayer、SpatialListener、bevy_audio
构建 / 部署（Build Settings、IL2CPP、WebGL）	references/unity-build.md	cargo build --target、Cargo.toml 功能、WASM

提取脚本（均使用 Python 标准库，无需安装 Unity）：

脚本	功能
scripts/unity/scene_inventory.py	解析 .unity YAML → 输出 GameObject + 变换 + 组件的 JSON 清单
scripts/unity/prefab_inspector.py	解析 .prefab YAML → 输出每个 prefab 的组件图
scripts/unity/animation_extractor.py	解析 .anim YAML → 输出关键帧 JSON，格式适用于 AnimatableKeyframeCurve::new([...])
scripts/unity/asset_audit.py	遍历 Assets/ → 按类型、大小、GUID 和（可选的）依赖图生成清单

运行各脚本并加上 --help 即可查看所有标志。每个脚本的文档字符串都指向对应的参考资料。

通用移植原则

无论源引擎是什么，以下几点都适用：

1. 转向 ECS。 Bevy 之外的引擎大多采用场景图 + 脚本模型（一个类 = 一个节点上的数据 + 行为）。Bevy 采用面向数据的设计：数据存放在 Component 中，行为则放在独立的 fn System 中。不要试图用一个 Rust 结构体重新创建 MonoBehaviour / Actor / Node；应将其拆分。
2. 先移植最小可玩切片。 在单个场景中实现一个角色的移动，并支持一种输入和一种动画。完成编译并运行后，再逐步迭代其余部分。避免试图“并行移植所有内容”。
3. 资源管线是耗时最长的环节。 移植代码比处理资源快。应优先安排资源提取；开始编写游戏逻辑代码前，先搭建能生成 glTF + KTX2 + 音频格式的内容管线。
4. 采用固定时间步思维。 大多数引擎会隐藏可变与固定时间步之间的选择。Bevy 将其明确化：确定性模拟应放在 FixedUpdate 中，由帧驱动的主世界呈现应放在 Update 中，渲染器工作应放在渲染调度中。使用 Time<Fixed> 进行插值。尽早决定各系统应放在哪里——参见 bevy-core-concepts 和 bevy-animation/references/procedural-animation.md。
5. 坐标系转换。 Unity 采用左手 Y 向上；Unreal 采用左手 Z 向上；Godot 采用右手 Y 向上；Bevy 采用右手 Y 向上（与 glTF 一致）。大多数导出器会处理转换；导入一个已知不对称的方向性资源并确认其没有镜像，以进行抽查。

脚本策略

scripts/<engine>/ 包含可运行的单文件 Python 辅助脚本，用于从源引擎的项目目录中提取数据。此集合遵循以下约定：

• 尽可能仅使用标准库。 使用 re 而非 pyyaml 解析 Unity 的 YAML，这样更容易安装。
• 无需源引擎。 所有 Unity 脚本都直接读取文本格式的 .unity/.prefab/.anim/.meta 文件。对于文件为二进制格式的引擎（Roblox .rbxl、部分 GMS2 文件），则在对应参考文档中提供操作方案。
• 清点 + 提取，而非自动转换。 这些脚本都不会生成 Bevy 项目。它们会提供 JSON，让你（或下游工具）了解需要移植的内容。对于游戏项目，可将它们视为 tree + file + stat。
• 有参考文档支撑。 每个脚本都会在文件顶部的文档字符串中注明对应的参考文档。

注意事项

• 一次性移植行不通。 应根据项目内容规模而非代码规模来分配时间。
• Prefab 语义无法直接迁移。 Unity 的“Prefab + Variant + Nested Prefab”继承机制在 Bevy 中没有直接对应方案。视觉 Prefab 可烘焙为 glTF；数据 Prefab 则编写生成函数。
• 动画重定向依赖引擎。 尤其是 Mecanim Humanoid 重定向，在 Bevy 中没有开箱即用的对应方案——参见 references/unity-animation.md。
• 坐标系翻转可能静默失败。 大多数导出器都能处理，但务必抽查。
• 编辑器脚本不在范围内。 Unity [CustomEditor]、Unreal Blueprints 的编辑器工具、Godot 工具脚本都无法转换。Bevy 的编辑器方案仍在演变；移植时仅考虑运行时功能。
• 不要复刻引擎内部 ID。 Unity GUID、Unreal FName、Godot RID、Roblox InstanceID 都只是仅在提取过程中有用的旁路元数据。Bevy 使用基于路径的句柄和 ECS 实体 ID。
• 将物理集成版本固定为 Bevy 0.19。 当前兼容版本为 bevy_rapier2d/bevy_rapier3d 0.36 和 avian2d/avian3d 0.7。 物理与渲染相互独立；选择无头或调试渲染功能前，请参见 bevy-rendering。

另请参阅

• bevy — 路由器；固定使用 Bevy 0.19，并索引所有同级技能。
• bevy-animation — AnimationGraph、AnimationTransitions、#[derive(AnimationEvent)]。unity-animation.md 中有交叉链接。
• bevy-ui — Node + Taffy/弹性布局模型。unity-ui.md 中有交叉链接。
• bevy-cargo-features — 替代 Unity Build Settings / PlayerSettings。
• bevy-wasm-webgpu — Unity WebGL → wasm32 / WebGPU 移植方案。
• bevy-cameras — RenderTarget 组件和相机模式；与 Unity 的 Camera 组件相近。
• bevy-rendering — 渲染器选择以及物理与渲染的边界。
• bevy-physics — Rapier 刚体、碰撞体、控制器、 查询和固定步长集成。
• bevy-migration-0-17-to-0-18 — 如果你找到固定使用 0.18 之前版本的教程，这份文档会很有用。