EVE Frontier world-contracts 详解（2）

Primitive 详解

3. in_game_id-游戏内 ID

这个很简单，主要就是构建了一个 TenantItemId

Struct：

• struct TenantItemId // TenantItem 游戏内标识符

主要为创建 TenantItemId 方法：create_key // 传入 item_id: u64, tenant: String 直接返回组合键结构，二者组合可用于派生确定性的链上对象 ID

4. inventory-库存

该模块实现了库存操作的逻辑，例如在库存之间存入、取出和转移物品

Structs：

• struct Inventory // 仓库状态，存储信息有 最大容量，当前已占用容量，存储物品列表
• struct Item // 链上物品对象，存储信息有 物品类型，体积，数量，item_id 等信息

Events Structs：

• struct ItemMintedEvent // 铸造事件 由 装配体 ID，操作角色 ID，物品 ID，物品类型，铸造数量等信息组成
• struct ItemBurnedEvent // 销毁事件 event 所含信息同上
• struct ItemDepositedEvent // 存入事件 event 所含信息同上
• struct ItemWithdrawnEvent // 提取事件 event 所含信息同上

我们首先要了解一下游戏内物品链上链下交互的一个大致流程：

桥接一个物品从游戏到链，游戏服务器调用 mint_items 来 mint 物品到链上对应库存

桥接一个物品从链到游戏，调用链上 链发出一个事件并 burn 链上的物品，游戏服务器监听事件来创建游戏中的物品

流程：

流程图（左）	流程注释（右）
mint_items	游戏侧物品"铸造成链上 Item 并写入库存，两种情况： ---- 库存中已存在该 type_id，走"叠加数量"路径，避免重复创建 Item 对象，然后增加容量，触发 ItemMintedEvent ---- 首次出现该 type_id，需要创建新的 Item 对象。
↓
deposit_item	mint_items 后物品为独立的 Item，通过此方法把已存在的链上物品 Item 放进目标库存，检查目标库存容量是否足够，完成后发出入库事件 ItemDepositedEvent
↓
withdraw_item	从目标库存提取 Item，从 VecMap 中移除该 type_id，并取得移除出的 Item，发出事件 ItemWithdrawnEvent
↓
burn_items	这个方法由 burn_items_with_proof 调用，但是根据作者注释后续应该会改成 mint_items 这种不需要校验位置证明的方式，并改为 public。该方法实现了把链上的 item burn 掉转换为游戏侧 然后发出 ItemBurnedEvent 事件

5. location-位置

位置验证模块：通过签名证明校验是否在邻近范围

本模块提供位置哈希的存储与位置证明校验两类能力，可挂载到任意游戏结构体上（例如库存、物品、舰船、装配体等）

其核心目标是：在允许交互前，先验证玩家确实位于目标结构附近，从而实现基于邻近性的访问控制

Structs：

• struct Location // 挂载在游戏结构体上的位置哈希
• struct LocationProofMessage // 位置证明消息体，包含服务器地址，玩家地址，服务端计算的两者距离，目标结构位置哈希，等信息构成
• struct LocationProof // 位置证明，由 LocationProofMessage 和服务器签名 signature 构成

Function：

流程图（左）	流程注释（右）
create_location_proof	创建位置证明
↓
verify_proximity	验证证明是否有效，先解构了 LocationProof，然后调用 validate_proof_message 检查 服务器地址是否在白名单，玩家地址与当前 sender 是否一致，目标位置哈希与链上对象位置是否一致，is_deadline_valid 校验是否过期，最后检查私钥签名是否正确

• verify_proximity_proof_from_bytes // 和上面方法几乎一样，但输入是字节版 proof
• verify_distance // 在验证证明是否有效的基础上加了 assert!(message.distance <= max_distance, EOutOfRange); 距离上限约束

6. metadata-元数据

每个 assembly 都有一个独立的 metadata 用于存储装配体的信息存储与展示

Structs：

• struct Metadata // 包含绑定的 assembly 对象 ID，assembly 名称，描述以及外部 URL

Events Structs：

• struct MetadataChangedEvent // 元数据变化事件，任意字段变更都会发

Function：

• update_name // 校验 owner_cap，写入新 name，触发 emit_metadata_changed，发出事件 MetadataChangedEvent
• update_description // 写入新描述，其他同上
• update_url // 写入新 URL，其他同上

7. status-状态

该模块用于管理 world 中 assembly（装配体/组件）的生命周期状态。

基础状态流转包含：Anchor（锚定）、Unanchor/Destroy（拆除/销毁）、Online（上线）、Offline（下线）。

Structs：

• enum Status // 结构状态枚举 NULL：无状态/不存在/已拆除 | OFFLINE：已锚定但离线 | ONLINE：已上线 表示当前状态
• enum Action // 状态动作枚举 ANCHORED：锚定 | ONLINE：在线 | OFFLINE：离线 | UNANCHORED：非锚定 表示发生了什么

Events：

• struct StatusChangedEvent // 状态变化事件 包含对象 ID，变更后状态，本次变更动作

Function：

• online // 将 assembly 从离线切换为上线，仅允许 OFFLINE -> ONLINE，写入新状态，然后发出事件 StatusChangedEvent
• offline // 将 assembly 从上线切换为下线，其他同上
• unanchor // 对 assembly 执行 unanchor 拆除流程，动作为 UNANCHORED，状态为 NULL，发出事件 StatusChangedEvent

本篇讲完了 Primitive 部分，下篇讲解除了 assemblies 的其他剩余合约组件