vaststars架构揭秘：C++核心库+Lua玩法层+双层ECS如何协作打造手机工厂游戏-平芜编程栈

vaststars架构揭秘：C++核心库+Lua玩法层+双层ECS如何协作打造手机工厂游戏

【免费下载链接】vaststarsA game demo for Ant engine项目地址: https://gitcode.com/gh_mirrors/va/vaststars

vaststars（Red Frontier）是一款由灵犀互娱开发的手机工厂建设游戏，也是开源游戏引擎 Ant 的第一个完整项目范例。它的架构堪称移动端游戏工程的教科书：C++ 核心库负责高性能模拟，Lua 玩法层负责快速迭代的逻辑与数据，双层 ECS（C++ 层 + Lua 层）则把两者无缝焊接在一起。本文带你用最短的路径看懂这套架构是如何协作的。

🏗️ 整体架构：三个目录，三套职责

打开仓库，项目结构天然地把三层职责分得非常清楚：

目录	角色	一句话概括
`3rd/ant`	引擎（Ant Engine）	渲染、窗口、资源、ECS 基座
`clibs/gameplay/`	C++ 核心库	背包、仓库、流体、电网、路网等重性能逻辑
`startup/pkg/`	Lua 玩法层	玩法系统、渲染表现、原型数据、UI、启动流程

整个游戏的启动入口是 startup/main.lua，它通过import_package机制按需加载功能包（feature），最后交给 Ant 引擎的ant.window拉起窗口。

⚙️ C++ 核心库：把"算得重的"放到底层

工厂类游戏的痛点在于：成千上万个建筑、电力网络、流体管道、运输卡车每帧都在更新。这些活儿全部交给 C++，代码集中在 clibs/gameplay/src：

core/ 业务核心：world.cpp（世界）、backpack.cpp（背包）、chest.cpp（仓库）、fluidflow.cpp（流体网络）、heatnet.c（热量网络）、saveload.cpp（存档）
roadnet/ 路网系统：network.cpp（道路网络）、lorry.cpp（运输车）、route.cpp（路径）
system/ 建筑行为：building.cpp、generator.cpp、powergrid.cpp、drone.cpp 等

C++ 如何"暴露"给 Lua？

看 gameplay.def 就一目了然——每个 C++ 模块都导出一个luaopen_*符号：

LIBRARY vaststars EXPORTS luaopen_vaststars_world_core luaopen_vaststars_fluidflow_core luaopen_vaststars_roadnet_system ...

这就是标准的 Lua C 模块协议：编译成动态库后，Lua 侧直接require即可调用，无需手写胶水代码。

🧬 双层 ECS：Lua 定义组件，C++ 执行数据

这是 vaststars 架构中最巧妙的部分。

第一层：Lua ECS（数据驱动层）。所有组件的定义都用纯 Lua 写在一个文件里——startup/pkg/vaststars.gameplay/init/component.lua：

mainkey "building" { "uint16 prototype", "uint8 x", "uint8 y", "uint8 direction", } mainkey "lorry" { "uint16 prototype", "roadnet::straightid ending", "uint16 item_amount", ... }

第二层：C++ ECS（性能执行层）。构建时，compile_ecs.lua 脚本会读取上面这份 Lua 组件定义，自动生成 C 头文件src/util/component.h（由 make.lua 中的compile_gameplay_ecs任务驱动）。C++ 的 ECS 用这份头文件以紧凑的 SoA 内存布局持有全部组件数据，遍历速度极快。

一句话总结：Lua 是组件的"单一事实来源"，代码生成保证 C++ 与 Lua 永远同步，既拿到了 C++ 的性能，又保住了 Lua 的改配置即生效。

🔄 协作流程：一帧游戏是如何跑起来的

整套协作可以概括为一条流水线（pipeline），定义在 startup/pkg/vaststars.gameplay/init/pipeline.lua：

输入与编辑：玩家在触屏上放置建筑，vaststars.gamerender包（建造器、选择框、指示器等）把操作翻译成 ECS 实体变更；
Lua 玩法层驱动：register/csystem.lua 把 C++ 系统注册进 ECS 更新管道，每帧update阶段按序执行；
C++ 核心结算：电力、流体、制造、运输等重计算在 C++ 中批量完成，直接读写组件内存；
表现层读取：vaststars.gamerender/render_updates/下的 Lua 系统（如assembling.lua、fluidbox.lua）读取最新状态，驱动动画、粒子与 UI；
数据层兜底：vaststars.prototype 包以纯数据形式定义所有建筑、配方（recipe.lua）、科技树（technology.lua）、教程模板，策划改数值不碰代码。

📱 为什么这套架构特别适合手机工厂游戏

热更新友好：玩法与数值全在 Lua 与数据包里，手机开发时用 Ant 的文件服务器即可实时同步修改（见README.md的 iOS 开发流程）；
性能有底：电网、流体、路网这类 O(N) 重计算锁定在 C++，中低端机型也能跑满建筑；
团队分工清晰：策划改vaststars.prototype、程序写clibs/gameplay、渲染逻辑写vaststars.gamerender，互不踩脚；
引擎范例价值：作为 Ant Engine 首个项目，它完整演示了import_package功能包机制、ECS 代码生成、C/Lua 混合开发的推荐姿势。