EVE Frontier world-contracts详解（1）

EVE Frontier world-contracts详解（1）

阅读前可以先学习 Move 及 Sui：

https://docs.sui.io/

当然，即使你不会也不妨碍阅读本文，了解下基本架构还是没问题的哦 OvO

项目地址：

https://github.com/evefrontier/world-contracts

此文章用于对 EVE Frontier world 合约部分进行拆分讲解 每个合约都干了些什么，方便大家理解学习，欢迎指出错误以及交流讨论（可以理解为学习笔记）建议对照项目源码阅读

部分内容学习参考了这个网站的博客 https://frontier.scetrov.live/ 这个是由几个海外开发者所著，写的也很好，但是感觉不是很好理解，不适合中国宝宝体质，感兴趣的朋友也可以看下

项目目前仍为测试版本，合约在更新后可能会有部分细节与实际不符，该文仅作参考

（注：本文所有文字内容均为笔者手搓，AI 负文本责格式优化）

先来看下项目结构

contracts/
  extension_examples/
    sources/                    # 拓展（第 3 层）
    config.move                 # 配置
        gate.move               # 星门
        tribe_permit.move       # 联盟许可
        corpse_gate_bounty.move # 星门残骸赏金
    ......
  world/
    sources/·
      access/              # 访问控制
        access_control.move
      assemblies/          # 装配体（第 2 层）
        assembly.move
        gate.move          # 星门
        storage_unit.move  # SU 存储单元
      character/
        character.move     # 角色管理
      crypto/
        sig_verify.move    # 签名验证
      killmail/
        killmail.move      #击杀邮件
      network_node/
        network_node.move  # 网络节点
      primitives/          # 基础单元（第 1 层）
        energy.move        # 能源
        fuel.move          # 燃料
        in_game_id.move    # 游戏内 ID
        inventory.move     # 库存
        location.move      # 位置
        status.move        # 状态
        metadata.move
      registry/               # 注册表
        object_registry.move  # 对象注册表
      world.move              # 主 world 模块
    tests/                    # 测试部分
        ......

我们先大致梳理下整体结构

游戏内部分的游戏资源是直接与链上合约交互的，例如：建筑的燃料消耗，物品的存取转移是上链的

那么也是有一些资源是不会上链的，例如：玩家的战斗数据

游戏世界的基础是由能量，燃料，存储信息，位置信息，状态信息及游戏内物品 ID 这几个 Primitive 所构成

整个 world 可以大致分为三个层级

这些 Primitive 基础组件可以归为 一层 ，然后由这些基础资源组建出游戏内标准组件，例如星门此为 二层，然后玩家可以针对游戏内标准组件进行个性化功能的增加，此为 三层

我们先从第一层来开始

Primitive 详解：

1. Energy-能源：

这个合约里面设置了装配体所需的能源，装配体（assembly）为直译过来的意思 我有的时候会称装配体为组件更顺口一些，可以理解为游戏内的装置组件，例如 SU（storage_unit）即可

Struct：

• struct EnergyConfig // 存储 assembly 该类型上线所需能量
• struct EnergySource // 存储 assembly 个体功率容量配置和当前负载

Event struct：

• struct StartEnergyProductionEvent // 启动发电事件：记录能源源启动后当前发电量
• struct StopEnergyProductionEvent // 停止发电事件：记录能源源已停止
• struct EnergyReservedEvent // 预留能量事件：某类 assembly 成功占用一部分能量
• struct EnergyReleasedEvent // 释放能量事件：某类 assembly 释放了占用能量

Admin Functions：

• set_energy_config // 设置或更新某个 assembly 的能耗配置
• remove_energy_config // 删除某个 assembly 类型的能耗配置

能量流程示例参考：

（这个流程只是便于理解学习，并非都得这么调，部分调用逻辑会根据实际需要所改变）

流程图（左）	流程注释（右）
start_energy_production	启动能量生产 这个方法在网络节点上线的时候会进行调用，还是比较底层的一个方法，传参为 EnergySource 与 energy_source_id（开始生产的网络节点 ID）发出启动事件 StartEnergyProductionEvent
↓	（能量预留部分）
reserve_energy	为某个 assembly 类型预留能量 调用前提：能源源已开启发电，且可用能量足够，可用能量必须覆盖需求，发出事件 EnergyReservedEvent
↓
release_energy	释放某个 assembly 类型对应的能量预留 扣减该类型对应的预留量，若当前没有可释放额度，则直接 return ，发出事件 EnergyReleasedEvent
↓
stop_energy_production	停止能量生产 传参与 start_energy_production 相同，发出停止事件 StopEnergyProductionEvent

2. fuel-燃料：

那么好，问题来了，能量是怎么来的呢？这个时候就来到 fuel 燃料合约部分

fuel 燃料本身并不能直接产生能量，他的作用是支持网络节点的启动运转，网络节点来生产能量，并且所产生的能量是恒定的，不同的燃料所能维持网络节点运行的时间不同，也就是 fuel_efficiency 不同

Struct：

• struct FuelConfig // 燃料配置，每种燃料类型对应的效率
• struct Fuel // 燃料状态

Events Struct：

• struct FuelEvent // 燃料状态变更事件
• struct FuelEfficiencySetEvent // 设置燃料效率事件
• struct FuelEfficiencyRemovedEvent // 删除燃料效率事件

燃料流程示例参考：

流程图（左）	流程注释（右）
deposit	放置指定类型燃料，当燃料槽为空时会初始化类型，若已有库存则要求类型一致（禁止混加），发出燃料变更事件 FuelEvent ：DEPOSITED
↓
start_burning	启动燃烧：立即消耗 1 单位燃料并设置燃烧起点时间,需要有燃料库存，发出燃料变更事件 FuelEvent ：BURNING_STARTED
↓
（need_update）	检查燃料状态是否需要更新，基于时间推导本轮应消耗单位数，只要应消耗 > 0，就需要执行 update
↓
update	更新燃料消耗状态：由 calculate_units_to_consume 计算应消费单位数， 仅在燃料库存足够时执行实际扣减，库存不足停止燃烧
↓
stop_burning	停止燃烧，清空燃烧起始时间，发出燃料变更事件 FuelEvent ：BURNING_STOPPED
↓
withdraw	提取指定数量燃料，库存必须足够，减扣库存余额，发出燃料变更事件 FuelEvent ：WITHDRAWN

好我们了解完燃料以及能量后我觉得可以先了解下 network_node，这两个部分主要应用在 network_node 中，正好把目前已学知识点串一下

network_node 网络节点：

网络节点为一个二层模块，是 EVE Frontier 的主要能源基础设施，网络节点通过将燃料转化为可用能量为 gate，storge unit 等二层组件供能

Struct：

• struct OfflineAssemblies // 仍需处理的装配体 ID 列表
• struct HandleOrphanedAssemblies // 仍需处理的装配体 ID 列表
• struct UpdateEnergySources // 更新能源来源
• struct NetworkNode // 网络节点配置

Events Struct：

• struct NetworkNodeCreatedEvent // 网络节点创建事件

流程：

流程图（左）	流程注释（右）
anchor	管理员锚定建筑，确定网络节点配置，将权限给予 Character，发出事件 NetworkNodeCreatedEvent
↓
online	上线网络节点，调用 fuel.start_burning 及 energy_source.start_energy_production 开始消耗燃料并且产生能量
↓
connect_assemblies	连接装配体到网络节点 ，对 Assembly 调 assembly::update_energy_source_connected_assembly，这部分属于装配体，留给下篇详解
↓
offline	下线网络节点，先结算燃料，返回 OfflineAssemblies
↓
unanchor	发起网络节点拆除流程，每个装配体都需执行“下线 -> 释放能量 -> 清空能源源绑定”的处理步骤。
↓
destroy_network_node	发起网络节点拆除流程 在所有连接装配体处理完成（已下线且清空能源源）后销毁网络节点（销毁没有事件产生）

下一篇会讲解装配体 库存 位置等合约 ，利用空闲时间理解学习 效率可能不是很高 敬请期待