本页目录

Concord:面向 LÖVE 的 Lua ECS 实体组件系统库

Concord · Concord-Studio/Concord

Concord 是一个用 Lua 编写、面向 LÖVE 框架的 ECS(实体-组件-系统)库,README 自称功能完整,主打性能与易用性。安装方式是把 concord 文件夹复制进项目后 require 引入;提供 entity、component、system、world 等模块以及 assemblag...

其他 LÖVE2D Lua 游戏状态管理 ECS 架构 中级
★ Stars 325 Forks 27 License MIT 更新 2026-11-17

国内开发环境适配

Windows
未知
Linux
未知
macOS
未知
引擎 / 框架:LÖVE2D 暂无中文教程标记 未标记站长实测
纯 Lua 库,无编译与第三方依赖,复制文件夹即可使用;README 中的 GitHub Pages 文档在国内网络下可能需要代理访问,待核验。

中文项目介绍

Concord 是一个用 Lua 编写、面向 LÖVE 框架的 ECS(Entity Component System,实体-组件-系统)库。README 开篇即自称「feature complete ECS for LÖVE」,也就是功能完整的 ECS 实现,并把性能与易用性列为主要设计目标,希望在保持代码整洁的同时写出运行较快的游戏逻辑。

它并不是一个可以直接运行的示例游戏,而是一套开发者可以引入自己项目的架构库:你把仓库里的 concord 文件夹复制进项目,require 之后就能用统一的 API 组织组件、实体与系统。整个库使用 LDoc 格式撰写注释,仓库的 docs 目录以及 GitHub Pages 上都有自动生成的 API 文档可查。

补充说明

安装与引入

安装步骤相当轻量,README 给出的方式只有两步:

  • 下载仓库,将 concord 文件夹复制到自己的项目目录中;
  • 在代码里按实际路径 require:
local Concord = require("path.to.concord")

引入后可以从 Concord 上取出各个模块与容器,例如 Concord.entity、Concord.component、Concord.system、Concord.world,以及用于存放组件类的 Concord.components 容器。这种「单一入口 + 子模块」的结构,让项目里不必到处 require 零散文件。

ECS 三要素

README 用较大篇幅解释 ECS 的基本概念:它把组合置于继承之上,因此更容易写出模块化的代码,让游戏对象可以自由拼装行为。Concord 的三块核心分别是组件、实体和系统。

组件:只有数据

组件是纯粹的数据,在 Concord 里就是一个带字段的 table,例如位置组件可能是 { x = 100, y = 50 },生命值组件可能是 { currentHealth = 10, maxHealth = 100 }。README 特别强调:组件是数据,除此之外什么都不是,本身没有任何功能。

定义组件类时需要传入名字,通常再传一个 populate 函数来填充字段:

Concord.component("position", function(component, x, y)
    component.x = x or 0
    component.y = y or 0
end)

也可以只传名字、不传填充函数,这类组件没有任何字段,适合用来标记某种状态(README 以「可推动 pushable」为例)。

实体:组件的容器

实体是游戏里实际存在的对象,比如玩家、敌人、箱子或子弹。每个实体拥有自己的一套组件及各自的数值。同一类组件在一个实体上最多只能有一个,实体之间也不能共享组件实例。

常用操作包括:

  • Entity() 创建实体,Entity(world) 创建时直接加入某个 World;
  • entity:give("position", 100, 50) 给予组件(若已存在则覆盖);
  • entity:ensure("position", 0, 0) 仅在不存在时才添加;
  • entity:remove("position") 移除组件;
  • entity:getComponents() 取回全部组件,README 明确警告该表为只读、不要修改;
  • entity:assemble(...) 应用一个装配函数,entity:inWorld() / entity:getWorld() 查询所在世界,entity:destroy() 销毁实体。

系统:真正干活的部分

系统承载游戏逻辑,每个系统负责一件具体的事,例如绘制。系统通过 pools(池)访问实体,池由过滤器定义,可以定义多个:

local mySystemClass = Concord.system({
    pool = { "position", "velocity" },
    secondPool = { "health", "damageable" }
})

池中只包含拥有所需组件集合的实体,其余组件与系统无关。系统可以定义 :init(world)(创建时调用)以及 :update(dt) 之类的回调,在回调里遍历 self.pool 处理组件数据。系统还支持启用/禁用:setEnabled(true/false) 与 isEnabled();禁用期间回调不会执行,但文档说明池仍会更新,作者认为这主要用于调试信息类系统。系统默认是启用的。

README 的小结很直接:组件只含数据,实体持有任意组件组合,系统对满足所需组件集合的实体生效。因此给箱子加上 controllable 组件它就受输入控制,给敌人子弹加上 health 组件它就能被打掉——无需额外代码。

通用设计与 API 约定

在「General design」一节里,README 解释了若干不那么直观的设计:

  • 批量加载文件:Concord.utils.loadNamespace("path/to/components") 会加载目录下所有文件,组件会自动注册到 Concord.components;也可以传入第二个表参数,把返回值按文件名(不含扩展名)收集起来,便于集中注册系统。
  • 方法链:几乎所有方法都返回 self,因此可以写成 entity:give(...):give(...):remove(...):destroy() 或 world:addEntity(a):addEntity(b):clear():emit("test")。

World 与 Assemblages

World 是实体与系统共同生活的容器。同一个 SystemClass 在一个 World 中只有一个实例,而实体数量不限。它的能力包括:

  • addEntity / removeEntity 增删实体,clear() 清空全部实体;
  • addSystem / addSystems 添加一个或多个系统,hasSystem / getSystem 查询;
  • emit("update", dt) 触发事件:所有带该回调的系统会被调用,按添加顺序执行;也可以 emit 任意自定义事件并携带任意参数;
  • 可覆写 onEntityAdded(e) 与 onEntityRemoved(e) 钩子。

Assemblages(装配)则是「把实体做成某种东西」的函数。README 强调一个重要区别:装配是追加组件而非替换。装配函数可以调用其他装配函数(e:assemble(animal, ...)),从而组合出更具体的类型,例如先装配出「动物」再补上猫叫音效就成为「猫」。

文档与示例

除本 README 外,Concord 全库使用 LDoc 注释,自动生成的文档位于仓库 docs 目录,也发布在 GitHub Pages(keyslam-group.github.io/Concord/)。README 还包含一个「Quick Example」快速示例章节,以及 Contributors 与 License 章节;仓库主页为 concord.studio。

学习建议

Concord 属于架构型库,学习曲线不在语法而在 ECS 思维:先理解「组件是纯数据、系统只处理满足条件的实体」,再练习用 assemblages 复用实体模板、用 loadNamespace 组织目录。建议先在小型 LÖVE 工程里跑通一个位置+速度+渲染的最小闭环,再逐步引入多池、系统启停与自定义事件。由于文档是自动生成的 API 参考,遇到具体方法签名时以其为准更稳妥。

开源许可证与版权说明

许可证标识:MIT。源码、资源与依赖许可可能不同,请以官方仓库为准。本站仅做索引,不托管源码。

相似项目