【免费下载链接】amethystData-oriented and>项目地址https://gitcode.com/gh_mirrors/ame/amethyst点击查看免费下载导读Prefab预制体是 Amethyst 中把实体Entity的组件数据与实例化逻辑分离的关键机制组件类型的定义和实例化流程编译进可执行文件而组件的具体取值则以数据文件的形式随游戏发布改动数值无需重新编译。本文以 Amethyst 数据导向设计理念为主线先讲清 Prefab 是什么、能做什么再带你逐层掌握 PrefabData 的五种实现模式Simple / Adapter / Aggregate / Asset / Multi-Handle、Prefab 文件语法与加载流程最后落到仓库源码级原理与可运行的示例。读完你可以独立为任意组件编写 PrefabData、设计可组合的场景 Prefab并理解 PrefabLoaderSystem 在后台的工作细节。为什么需要 Prefab把数值变成数据Amethyst 是一个采用数据导向Data-oriented设计的 Rust 游戏引擎。假设游戏里有一种怪物Monster实体它带有以下组件Position位置Velocity速度Health points生命值Attack damage攻击力如果把这些组件的取值直接写在代码里那么每次调整怪物数值都必须重新编译整个可执行文件。等待几分钟重新编译仅仅为了改一个数值既低效又令人沮丧。数据导向设计的思路是实例化怪物是逻辑属于可执行文件的一部分而怪物组件的取值是数据可以从外部读取。可执行文件只需要一套实例化逻辑就能根据数据文件中的内容生成任意种类的怪物。这份描述如何组装实体的数据文件就是 PrefabPremade fabrication预先制造好的装配件。从概念上一个 Prefab 文件大致长这样示意非当前仓库实际语法// 这是 Prefab 可能长什么样的示例。 // 其他引擎可能把 Prefab 存成二进制格式必须用编辑器才能读取和修改。 Prefab( id: 00000000-0000-0000-0000-000000000000, // 该 Prefab 在游戏中的唯一 id objects: [ // 数组中的每个对象代表一个实体 Entity(( // 每个 Entity 由一个 UUID 和一组组件描述 id: 00000000-0000-0000-0000-000000000000, // 唯一标识该实体 components: [ // 一个实体可以有任意数量的组件 ( type: 00000000-0000-0000-0000-000000000000, // 该组件类型的 UUID data: ( // 这里是组件结构体的字段 position: (0.0, 0.0, 0.0), velocity: (0.0, 0.0, 0.0), health: 100, attack: 10, ), ), ] )), Entity(( // 一个 Prefab 中可以包含多个实体 id: 00000000-0000-0000-0000-000000000000, components: [ ( type: 00000000-0000-0000-0000-000000000000, data: ( position: [200.0, 200.0] ), ), ] )), ] )这份文件随可执行文件一起作为游戏的一部分分发也可以在大版本发布时烘焙成二进制格式。Prefab 的用途与核心特性Prefab 拥有两个关键性质正是它们让它成为定义场景和关卡的理想工具所有基于该 Prefab 创建的实体实例都会收到对 Prefab 所做的修改。也就是说Prefab 是模板而非快照——改一处模板所有派生实例共享更新后的定义。Prefab 可以嵌套其他 Prefab。更大的 Prefab 可以由若干更小的 Prefab 组合而成。由此可以自然地组织出层级化场景城市CityPrefab由地形terrain、建筑buildings、植被foliage等 Prefab 组合而成迷宫MazePrefab由墙壁walls、玩家player、怪物monster等 Prefab 组合而成。Prefab 的两种表示形式与核心数据结构Amethyst 把 Prefab 当作一种资产Asset 处理因此它通常以文件形式存放、在运行时加载。加载完成后Prefab 还要经过额外的处理才能变成组件并挂到实体上。整个过程涉及两种表示存储表示Stored representation随应用一起分发的文件形式加载表示Loaded representation运行时用于实例化实体和组件的形式。在源码层面Prefab这个 Asset 类型定义在 amethyst_assets/src/prefab/assets.rspub struct Prefab { /// contains Legion World and Entity Mappings pub(crate) cooked: Optionlegion_prefab::CookedPrefab, /// Contains World to cook and references to other prefabs pub(crate) raw: legion_prefab::Prefab, #[serde(skip)] pub(crate) dependencies: VecHandlePrefab, #[serde(skip)] pub(crate) dependers: FnvHashSetWeakHandle, /// Incremented everytime the prefab is cooked. #[serde(skip)] pub(crate) version: u32, }raw持有未经处理的 legion Prefab 定义cooked存放烹饪cook之后的世界与实体映射dependencies/dependers记录 Prefab 之间的引用关系version在每次重新烹饪时递增——这套结构支撑了改模板、全部实例共享更新的特性。在 Amethyst 中使用 Prefab四步流程从用户视角看使用一个 Prefab 分为四个步骤加载使用LoaderAssetStorage加载或使用更便捷的PrefabLoader包装器。为此需要一个能返回Prefab的Format。管理句柄妥善保管返回的HandlePrefabT。等待加载完成通过Progress等待 Prefab 完全加载。请求实例化把HandlePrefabT放到 World 中的一个Entity上。如何加载一个 Prefab看仓库自带的 prefab 示例cargo run -p prefab加载动作非常直接let loader data.resources.get_mut::DefaultLoader().unwrap(); let prefab_handle: HandlePrefab loader.load(prefab/test.prefab); self.prefab_handle Some(prefab_handle.clone()); data.world.push((prefab_handle,));把HandlePrefab作为组件push进 World就是请求实例化——接下来的工作交给PrefabLoaderSystem完成。当前仓库真实 Prefab 文件长什么样examples/prefab/assets/prefab/test.prefab 是当前仓库中真实可用的 Prefab 文件它展示了与旧文档 RON 语法不同的现代语法——实体与组件的类型都用 UUID 标识Prefab( // Prefab AssetUuid id: 14dec17f-ae14-40a3-8e44-e487fc423287, objects: [ // Inline definition of an entity and its components Entity(( // Entity AssetUuid id: 62b3dbd1-56a8-469e-a262-41a66321da8b, // Component data and types components: [ ( // Component AssetTypeId type: f5780013-bae4-49f0-ac0e-a108ff52fec0, data: ( position: [100.0, 100.0] ), ), ] )), Entity(( // Entity AssetUuid id: df6df3fd-4a0c-4640-bd71-7969f1e568a1, components: [ ( // Component AssetTypeId type: f5780013-bae4-49f0-ac0e-a108ff52fec0, data: ( position: [200.0, 200.0] ), ), ] )), ] )注意其中两个实体都引用了f5780013-bae4-49f0-ac0e-a108ff52fec0这个组件类型 UUID——它对应示例main.rs中Position2D组件通过#[uuid f5780013-bae4-49f0-ac0e-a108ff52fec0]声明的类型标识并用register_component_type!(Position2D);注册进组件注册表。这正是数据与逻辑分离的直接体现数据文件通过 UUID 与代码里的类型一一对应逻辑在代码里数值在文件里。PrefabData让数据文件与组件对接的桥梁Prefab 文件只是序列化数据真正把数据变成组件、挂到实体上的是PrefabDatatrait。Amethyst 提供#[derive(PrefabData)]派生宏来为类型自动生成实现支持两类场景单个Component聚合Aggregate的PrefabData结构体或枚举其内部包含其他PrefabData构造也可以内联普通数据组件。注意派生Prefab要求当前作用域内可见amethyst::Error、amethyst::ecs::Entity和amethyst::assets::{PrefabData, ProgressCounter}这是 Rust 宏展开机制的硬性要求。PrefabData 的核心方法PrefabData的两个关键方法是add_to_entity把自身的PrefabData数据实际插入到某个Entity的对应组件存储中。它接收四个参数目标Entity、mut Self::SystemData从 World 中取出的系统数据、以及两个实体切片分别表示所有受该 Prefab 影响的实体、以及新建的子实体。load_sub_assets异步加载该 PrefabData 引用的其他资产如贴图、网格。若触发了子资产加载必须遵守两条规则加载时必须把给定的ProgressCounter作为参数传给Loader的 load 函数否则进度追踪会出错函数必须返回Ok(true)除非发生Error。以下面这个简化的Transform实现为例可以直观看到PrefabData的骨架impla PrefabDataa for Transform { type SystemData WriteStoragea, Transform; // 从 World 中取出 Transform 组件存储 type Result (); // 本例无需返回额外结果 fn add_to_entity( self, entity: Entity, storage: mut Self::SystemData, _: [Entity], _: [Entity], ) - Result(), Error { storage .insert(entity, self.clone()) .map(|_| ()) .map_err(Into::into) } }SystemData是加载与实例化该 PrefabData 时从 World 中取出的数据add_to_entity里把数据克隆后插入实体即可。因为Transform不引用任何外部资产所以无需实现load_sub_assets。系统提供的特殊 PrefabData 实现资产系统为常见场景提供了两组 blanket 实现让组合非常灵活OptionT任意T: PrefabData的Option包装元组Tuple实现了PrefabData的类型构成的元组最大支持 20 元。仓库中的场景 Prefab 常常直接用元组组合而成例如渲染场景的 PrefabData 可以写成( OptionGraphicsPrefabObjFormat, TextureFormat, OptionTransform, OptionLight, OptionCameraPrefab, )五种 PrefabData 定义模式如何选择Prefab 系统极其灵活但正因为如此选择正确的实现模式很重要。how_to_define_prefabs_prelude给出了决策表详见 book/src/prefabs/how_to_define_prefabs_prelude.md组件类型序列化表示示例Prefab 数据类型适用指南YourTypeSelf组件自身完全可序列化PositionPositionSimpleYourType多种构造方式V1(..)、V2(..)CameraCameraPrefabAdapterYourTypeYourType的子集含运行时才有数据AudioListenerAudioPrefabAssetHandleA由A::Data加载Mesh、TextureMeshData、TexturePrefabAssetManyHandles组件内部存有多个句柄MaterialMaterialPrefabMulti-Handle下面逐一拆解每种模式。模式一Simple——组件自身完全可序列化适用于组件类型本身数据自包含、可整体序列化的场景。以Position为例让它可在 Prefab 中使用只需三步1. 确保依赖最低 Amethyst 版本 0.10[dependencies] amethyst .. # Minimum version 0.10 serde { version 1, features [derive] }2. 导入所需项use amethyst::{ assets::{PrefabData, ProgressCounter}, derive::PrefabData, ecs::Entity, Error, }; use serde::{Deserialize, Serialize};3. 给类型加上派生与属性#[derive(Clone, Copy, Component, Debug, Default, Deserialize, Serialize, PrefabData)] #[prefab(Component)] #[serde(deny_unknown_fields)] pub struct Position(pub f32, pub f32, pub f32);关键点#[prefab(Component)]告知PrefabData派生宏这个类型本身就是一个 Component而不是由若干实现PrefabData的字段组合而成。这决定了派生生成的是直接插入该组件的代码。#[serde(default)]可选允许 Prefab 文件中省略字段省略时使用Default值不加该属性则所有字段都必须显式写出。#[serde(deny_unknown_fields)]反序列化时遇到未知字段直接报错能第一时间暴露 Prefab 文件中的笔误如拼错的字段名。完成后即可在 Prefab 文件中使用#![enable(implicit_some)] Prefab( entities: [ PrefabEntity( data: Position(1.0, 2.0, 3.0), ), ], )运行cargo run -p prefab可看到完整示例。模式二Adapter——一个组件多种序列化表示当同一个组件有多种合法的构造/序列化方式时用中间类型adapter承接。经典的CameraPrefab就是这样既支持正交投影Orthographic也支持透视投影Perspective每种是一组不同的字段。以Position为例先定义一个可(反)序列化的枚举每个变体代表一种表示#[derive(Clone, Copy, Deserialize, PartialEq, Serialize)] #[serde(deny_unknown_fields)] pub enum PositionPrefab { Pos3f { x: f32, y: f32, z: f32 }, Pos3i { x: i32, y: i32, z: i32 }, }再手动为 adapter 实现PrefabData。核心是add_to_entity根据枚举变体构造出真正的组件写入组件存储impla PrefabDataa for PositionPrefab { type SystemData WriteStoragea, Position; // 写入 Position 组件存储 type Result (); fn add_to_entity( self, entity: Entity, positions: mut Self::SystemData, _entities: [Entity], _children: [Entity], ) - Result(), Error { let position match *self { PositionPrefab::Pos3f { x, y, z } (x, y, z).into(), PositionPrefab::Pos3i { x, y, z } (x, y, z).into(), }; positions.insert(entity, position).map(|_| ())?; Ok(()) } }这里依赖From(i32, i32, i32) for Position和From(f32, f32, f32) for Position两个转换实现。之后 Prefab 文件中就能同时使用两种表示#![enable(implicit_some)] Prefab( entities: [ PrefabEntity(data: Pos3f(x: 1.0, y: 2.0, z: 3.0)), PrefabEntity(data: Pos3i(x: 4, y: 5, z: 6)), ], )运行cargo run -p prefab_adapter查看完整示例。模式三Aggregate——聚合多个组件为一块 PrefabData当实体需要挂多个组件时定义一个聚合类型字段逐个实现PrefabData。派生宏会生成递归调用的代码加载与挂载时逐个遍历字段把每个字段对应的组件挂到实体上。#[derive(Debug, Deserialize, Serialize, PrefabData)] #[serde(deny_unknown_fields)] pub struct Player { name: Named, // 实现 PrefabData 的组件 position: Position, // 实现 PrefabData 的组件 }对应 Prefab 文件#![enable(implicit_some)] Prefab( entities: [ PrefabEntity( data: Player( name: Named(name: Zero), position: Position(1.0, 2.0, 3.0), ), ), ], )实例化时 Amethyst 会递归进入Player的每个字段把Named与Position组件分别挂上。如果同一个 Prefab 里要混合不同类型的实体例如玩家和武器必须用枚举作为聚合PrefabData每个变体对应一种实体#[derive(Debug, Deserialize, Serialize, PrefabData)] #[serde(deny_unknown_fields)] pub enum CustomPrefabData { Player { name: Named, position: OptionPosition, }, Weapon { weapon_type: Weapon, position: OptionPosition, }, }Prefab 文件中的第二个实体用parent: 0声明它的父实体是列表中的第 0 个玩家#![enable(implicit_some)] Prefab( entities: [ // Player PrefabEntity( data: Player( name: Named(name: Zero), position: Position(1.0, 2.0, 3.0), ), ), // Weapon PrefabEntity( parent: 0, data: Weapon( weapon_type: Sword, position: Position(4.0, 5.0, 6.0), ), ), ], )实例化结果如下表所示对应prefab_custom示例EntityHandlePrefabCustomPrefabDataParentPositionPlayerWeaponEntity(0)Handle { id: 0 }NonePosition(1.0, 2.0, 3.0)Named { name: Zero }NoneEntity(1)NoneEntity(0)Position(4.0, 5.0, 6.0)NoneSword规则是持有HandlePrefabT的那个实体主实体接收列表中第一个PrefabEntity的组件列表中的后续条目各自创建一个新实体。聚合模式的经典陷阱组件写入冲突构建枚举型PrefabData时有一条重要限制同一个PrefabData内包括其嵌套的任何PrefabData不能有两个字段写入同一个Component除非全部是只读访问。即使字段位于枚举的不同变体中也一样。违反的话会在运行时加载失败。原因在于 Amethyst 底层的 ECS 系统基于静态类型决定资源访问无法判断枚举中同一时刻只有一个变体被使用于是会对同一组件存储尝试两次可变借用直接导致运行期错误。例如下面这段代码就会踩坑——两个变体里的SpriteScenePrefab都需要写Transformpub enum CustomPrefabData { MundaneCreature { sprite: SpriteScenePrefab, }, MagicalCreature { special_power: SpecialPower, sprite: SpriteScenePrefab, }, }正确做法是分层定义PrefabData让每个组件只出现一次把共享的sprite提出来放在外层结构体中枚举只保留差异部分pub enum CreatureDetailsPrefab { MundaneCreature {}, MagicalCreature { special_power: SpecialPower }, } pub struct CustomPrefabData { sprite: SpriteScenePrefab, // 只出现一次 creature_details: CreatureDetailsPrefab, }这样共享组件只被写入一次两个枚举变体互不冲突。运行cargo run -p prefab_custom聚合枚举示例或cargo run -p prefab_multi聚合结构体示例可验证上述行为。模式四Asset——在 Prefab 中加载子资产当组件是HandleAA 实现AssetA::Data可序列化或组件本身大部分可序列化、只有少数数据如设备 ID、资产句柄只能在运行时获得时需要用AssetPrefab在 Prefab 加载阶段同步加载子资产。AssetPrefab本身就是一个PrefabData实现定义在资产系统中pub enum AssetPrefabA, F where A: Asset, F: FormatA::Data, { /// From existing handle #[serde(skip)] Handle(HandleA), /// From file, (name, format, format options) File(String, F), }它的load_sub_assets实现会执行真正的加载并把内部表示变形morph为AssetPrefab::Handle变体之后add_to_entity运行时直接取出内部已存的Handle插入实体fn load_sub_assets( mut self, progress: mut ProgressCounter, system_data: mut Self::SystemData, ) - Resultbool, Error { let handle match *self { AssetPrefab::File(ref name, ref format) Some(system_data.0.load( name.as_str(), format.clone(), progress, system_data.2, )), _ None, }; if let Some(handle) handle { *self AssetPrefab::Handle(handle); } Ok(true) }注意load_sub_assets接收mut self因此PrefabData在子资产加载阶段是可变的——这是它在 Prefab 内部变形的技术前提。这也解释了为什么add_to_entity在后续阶段只接收self所有需要异步加载的数据此时已经就绪。模式五Multi-Handle——组件内部持有多个句柄当组件本身存着多个Handle_典型如Material的 albedo / emission 贴图句柄时对应的PrefabData需要逐一把句柄加载并组装成组件。仓库中对应的范例是MaterialPrefab。注意how_to_define_prefabs_multi_handle.md目前仍是占位文档尚未撰写实际用法以MaterialPrefab等源码实现为准。Prefab 加载的完整生命周期Prefab 的生命周期可以划分为三个阶段理解它们对调试加载问题很有帮助详见 book/src/prefabs/prefabs_technical_explanation.md阶段一加载Loading与 Amethyst 中所有资产一致用户用LoaderSourceFormat发起加载。Format返回一个Prefab用户拿到HandlePrefabTT 实现PrefabData。阶段二子资产加载Sub asset loading一个PrefabData实现可能引用其他需要异步加载的资产我们不希望在一切就绪之前就把Complete通知发给用户的Progress。因此当Format从Source加载完 Prefab、PrefabLoaderSystem在AssetStorage上执行process后系统会调用每个PrefabData实现的load_sub_assets。等所有子资产加载完成由PrefabLoaderSystem借助ProgressCounter追踪才向上发出Complete信号。阶段三实例化Prefab instantiation发生在 Prefab 完全加载、Complete已发出、且HandlePrefabT被放到某个Entity上之后。此时所有内部数据与子资产均已就绪PrefabLoaderSystem会不可变地遍历 Prefab 数据为列表中除第一项外的每个条目创建新实体然后对每个PrefabData调用add_to_entity。嵌套 Prefab 的帧内一致性对于引用了其他 Prefab 的 Prefab例如 gltf 场景 Prefab其内部 gltf loader 本身就使用 Prefab 系统为了让实例化在单个帧内完成低层级的PrefabLoaderSystem需要依赖高层级的系统通过系统调度依赖保证执行顺序。Prefab 支持的文件格式Amethyst 提供多种能产出 Prefab 的FormatRonFormat以 RON 格式加载 Prefab适用于任何同时实现serde::Deserialize的PrefabDataJsonFormat以 JSON 格式加载 Prefab同样要求PrefabData实现serde::Deserialize需要启用jsonfeature 标志GltfSceneFormat加载 glTF 文件内部使用 Prefab 系统组装场景UiFormat以专用 DSL 格式加载 UI 组件。小结Prefab 是 Amethyst 数据导向设计的核心实践组件逻辑写在代码里、组件取值放在数据文件里改动数值不再需要重新编译。掌握PrefabData的五种实现模式Simple、Adapter、Aggregate、Asset、Multi-Handle理解PrefabLoaderSystem三阶段生命周期加载 → 子资产加载 → 实例化你就可以高效地组织场景、关卡与可复用实体模板。想继续深入可以在 book/src/prefabs/ 目录阅读各专题指南并运行仓库中的prefab、prefab_multi、prefab_custom、prefab_adapter四个示例对照 amethyst_assets/src/prefab/ 下的实现源码逐行验证。赞分享【免费下载链接】amethystData-oriented and>项目地址https://gitcode.com/gh_mirrors/ame/amethyst点击查看免费下载相关推荐RoboBrain2.5与Robo-Dopamine集成构建强化学习智能体完整指南RoboBrain2.5与Robo Dopamine集成构建强化学习智能体完整指南 RoboBrain2.5是一款先进的机器人智能系统结合深度视觉感知与时间Motor开发者指南深入理解异步MongoDB驱动实现Motor开发者指南深入理解异步MongoDB驱动实现 项目背景与现状 Motor是MongoDB官方提供的异步Python驱动它作为PyMongo的异步封后端Amethyst 系统初始化指南深入理解 SystemDesc 与 World 资源装配Amethyst 系统初始化指南深入理解 SystemDesc 与 World 资源装配 System 在实例化时往往需要访问 World 中的资源例如为上一篇DINO探索下一代目标检测技术的革命性突破下一篇Jest 对象 API 完全指南Mock 模块、Mock 函数与 Fake Timers 权威参考创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考