本页目录

Lua 游戏开发工具库(Batteries)

batteries · 1bardesign/batteries

Batteries 是面向 Lua 游戏开发的通用工具库,尤其适配 LÖVE 框架。它补足 Lua 标准库中较精简的部分,并提供游戏中常见的算法与数据结构实现。文档以代码内联注释形式给出,未压缩体积约一百千字节(含许可证与本 README),可按需裁剪...

其他 LÖVE2D Lua 碰撞检测 游戏状态管理 中级
★ Stars 437 Forks 31 License Zlib 更新 2026-10-28

国内开发环境适配

Windows
未知
Linux
未知
macOS
未知
引擎 / 框架:LÖVE2D 暂无中文教程标记 未标记站长实测
纯 Lua 库,无原生编译步骤;README 未涉及国内镜像或网络说明,若以 git submodule 从 GitHub 拉取遇到网络问题需自行处理(待核验)。运行依赖 LÖVE 或标准 Lua 环境,需自行安装。

中文项目介绍

Batteries 是一个面向 Lua 游戏开发的通用工具库,作者明确将其定位为「用 Lua 做游戏时的顺手工具箱」,尤其针对 LÖVE 框架做了适配。它的核心思路有两条:一是补足 Lua 标准库中相对精简的部分,二是把游戏中反复出现的常见算法与数据结构预先实现好,让项目能更快起步。

按照 README 的说法,Batteries 兼顾通用场景与特殊场景,代码中附带大量行内注释进行说明;未压缩体积约一百千字节(其中还包括许可证文件与本 README),作者用「每字节能换来不少东西」来形容这种密度。如果只需要其中一部分能力,也可以按需裁剪。

补充说明

安装与引入

Batteries 不需要单独的构建步骤,把仓库文件放进项目可访问的目录即可,许可证文件已随仓库提供。README 给出的步骤是:

  • 将文件放在项目可访问的独立目录中;
  • require 那个包含 init.lua 的 batteries 根目录,注意路径使用点号写法;
  • 在常规的 require 环境(例如原版 LÖVE 或标准 Lua)下,init.lua 会自动引入全部子模块;
  • Batteries 采用常见的 init.lua 约定。若运行环境本身不支持该约定(例如 Windows 上的原生 Lua 5.1),需在 require 之前追加 package.path = package.path .. ";./?/init.lua",也可以修改 LUA_PATH 环境变量;
  • 可选地把所有内容导出到全局环境;
  • 若需要语言服务器(LSP)支持,社区另有一个独立的注解项目。

README 给出的两种典型用法,一种是通过 require("path.to.batteries"):export() 全部导出为全局,另一种是 local batteries = require("path.to.batteries") 保持自包含、通过模块名访问。

模块总览

README 按用途把模块分成四组,这也是理解这个库最快的入口。

Lua 核心扩展(对既有核心模块补充缺失功能,并带有别名):

  • mathx:数学扩展,别名 math;
  • tablex:表操作扩展,别名 table;
  • stringx:字符串处理扩展,别名 string。

通用工具:

  • class:用一个函数实现带继承与接口的面向对象;
  • functional:函数式编程设施,提供 map、reduce、any、match、minmax、mean 等;
  • sequence:顺序表的面向对象封装,可写 t:insert(i, v) 而非 table.insert(t, i, v),并支持与 functional 配合的方法链;
  • set:集合类型,提供完整的集合运算、快速成员判断与 ipairs 风格遍历;
  • sort:稳定的归并+插入排序,README 称在 luajit 下常常还快于 table.sort,另暴露 insertion_sort,别名 stable_sort;
  • state_machine:有限状态机,含状态转移等配套功能,可用于游戏状态、AI、过场等;
  • timer:倒计时式计时器,带进度与完成回调;
  • pubsub:自包含的发布/订阅消息总线,为立即模式而非队列模式、为本地而非联网设计;
  • pretty:用于调试检查的表美化打印。

几何:

  • intersect:2D 相交/求交例程,README 坦言目前还比较稀疏;
  • vec2:带方法链与省垃圾的原地修改操作的 2D 向量;
  • vec3:同类 3D 向量,成熟度较低。

特殊兴趣(只对部分人、部分场合有用,或打磨程度不足):

  • async:异步/「后台」任务管理,本质是对 Lua 协程的封装;
  • colour:颜色转换与编码例程,别名 color;
  • manual_gc:把 GC 从 update/draw 调用中移开,便于获得更准确的性能剖析数据,但需要自行规划垃圾预算;
  • measure:基准测试辅助,测量某段代码耗时或内存占用;
  • make_pooled:为类添加池化/复用能力。

所有别名在 batteries 模块层级以及导出后的全局环境中都会提供。

文档与示例在哪里

README 明确说明:示例放在独立的 batteries-examples 仓库中,以避免在作为子模块使用时污染仓库历史与项目文件系统,里面覆盖了大部分功能且写法简短直接。文档则以代码旁的行内注释形式提供,作者认为那是最「抗腐坏」的位置——自动生成的文档往往会过时,注解本身也会让代码臃肿。使用建议是用编辑器的全局搜索功能,或直接翻阅源码;上面的模块总览是唯一的非代码文档,定位是「跳板」而不是参考手册。

全局导出与依赖管理

作者强烈推荐以 require("batteries"):export() 这种「一劳永逸」的方式使用:它会修改 Lua 内建模块(如 table、math),并把其余模块直接暴露为全局,这样在整个项目里就不必到处 require,也不用纠结 table.remove_value 到底是内置的还是库加的。作者承认这与「永不用全局」的教条相冲突,但认为对于这类几乎处处都会用到的基础库,启动时导入一次是合理的。

当然也可以只用单个模块(显式 require 单个文件),或统一 require 整个 batteries 后通过 batteries.functional.map 之类访问。后一种方式依赖关系更清晰,代价是需要在各处重复 require 或先把库提为全局。

关于获取方式,README 对比了两种:作为 git 子模块便于 git pull 更新与回滚、也便于向上游回馈;静态安装更难更新,但更方便裁剪,而且「永远不会在更新时神秘地坏掉」。裁剪方面,不少模块可以独立工作,部分模块依赖 class(一并带上即可),更大的模块之间存在一些互相依赖,需要自行判断是补依赖还是剥离相关功能。

版本策略与代码风格

README 说明该库目前采用滚动发布:master 分支头部即面向公众使用,虽然尽量保持稳定,但破坏性 API 变更确实会发生,且还有更多变更在计划中。因此建议更新前先看提交历史,而不是盲目拉取。若用户主动告知在活跃使用,作者通常愿意提前通知即将进入 master 的破坏性改动;如果未来用户规模足够大,也会考虑引入版本号方案与仓库外的更新日志。

命名风格上,作者个人偏好 snake_case,也承认这是口味问题并会让部分人退避;为此提供了实验性的自动 API 转换(类型用 UpperCamelCase、方法用 lowerCamelCase),在 :export() 之前调用 :camelCase() 即可启用。LSP 注解则不放进主仓库,而是由社区项目维护。

许可证

Batteries 使用 zlib 许可证,具体条款见仓库中的 license.txt。

学习建议

这个库更适合已经会写 Lua、准备做游戏原型或中小型项目的开发者。建议的阅读顺序是:先看模块总览挑出与自己需求相关的模块,再到 batteries-examples 仓库找对应示例,最后回到源码读行内注释确认细节。若担心全局污染,先用 local batteries = require(...) 的方式接入,等确认依赖范围后再决定是否 :export()。另外由于是滚动发布,锁版本或固定子模块提交比跟随 master 更适合长期项目。

开源许可证与版权说明

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

相似项目