ludum
v4.0.0
Published
ludum — a small, engine-agnostic, deterministic TypeScript toolkit for composable gameplay systems (ECS, resources, state machines, dialogue, weighted selection, geometry, interaction).
Maintainers
Readme
ludum
语言 / Language: 中文 · English
Composable, deterministic gameplay systems for TypeScript — designed for developers and coding agents.
一组可组合、确定性、零运行时依赖的玩法系统:资源与修饰符、加权随机与保底、 状态机、分支对话、无放回抽取、几何与交互。可在任意 JS/TS 宿主(浏览器、Node、 Deno、Bun)中运行,可 headless 测试、可快照存档。
完整文档 · Cookbook(可执行范例) · 核心价值审计
为什么用 ludum
- 确定性是默认能力:注入
RandomSource/Clock,同种子同结果;所有有状态 模块支持 JSON 快照往返,「中断恢复字节级一致」有测试保证(examples/headless)。 - 填补真实空档:加权抽取 + 动态权重 + pity 保底 + 会话统计 + 快照的组合, npm 生态没有有采用者的等价包;带状态快照的种子化 RNG、headless 弹簧物理同理。
- Agent-First:每个玩法需求有明确模块与可复制范例(Cookbook 8 例全部
编译 + 测试验证);API 陷阱(如
onThreshold的'below'失效)在文档与 Cookbook 显式标注。 - 小而可整读:核心模块 20–60 行,最大的 ECS 435 行;零依赖、MIT、ESM。
基准数据(AGENT_BENCHMARK.md):同一行为规范下, pity 掉落任务 ludum 24 行 vs 原生 54 行;HP+限时 buff 任务 21 行 vs 47 行; 纯移动模拟任务原生 24 行最小(ludum 30 行)——优势集中在数值玩法,不在所有场景。
安装
npm install ludumimport { Resource } from "ludum/resource";
const hp = new Resource({ id: "hp", value: 100, max: 100 });
hp.subtract(25);
console.log(hp.get()); // 75也可从 ludum 根入口统一导入。各模块有独立子路径(见下表)。
模块一览(按生态空档排序)
| 模块 | 导入 | 一句话 |
|---|---|---|
| WeightedTable / WeightedSession | ludum/weighted | 加权抽取 + 动态权重 + pity 保底 + 统计 + 快照(旗舰) |
| Resource / DerivedResource | ludum/resource | 数值资源:钳制、限时修饰符、阈值事件、快照(旗舰) |
| SeededRandom 等 | ludum/runtime | 注入式随机/时钟/倒计时;SeededRandom 支持状态快照 |
| ShuffleBag | ludum/shuffle-bag | 无放回抽取(标准 60 行解法) |
| DialogueSession / selectLine | ludum/dialogue | TS 对象定义分支对话 + 类型化谓词选项 |
| StateMachine | ludum/state | 上下文驱动 + 优先级条件(4 个概念)+ 临时状态 + 快照 |
| Aspect 纯函数 | ludum/aspect | 标签+等级数值模型(聚合/门槛/增量) |
| ConditionExpression | ludum | JSON 可序列化条件 AST(数据驱动门槛) |
| World(ECS,可选) | ludum/ecs | 类型化组件 + JSON 快照;玩法规模适用(数百实体) |
| DefinitionRegistry | ludum | fail-fast 的 id 内容表 |
| Shape2D / Spring2D / ProceduralShape | ludum/geometry | 表现层工具(自绘宿主) |
| InteractionRegion / Router | ludum/interaction | 无引擎宿主的指针语义状态机 |
什么时候不用 ludum
- 渲染 / 物理 / 音频 / 场景 → 游戏引擎(Phaser / PixiJS / Three.js)。ludum 不是引擎。
- 万级实体高性能 ECS → bitecs(0.4+ 自带 序列化,MPL-2.0)或 koota。
- 长篇叙事创作(变量/线程/作者工具链)→ Ink / inkjs。
- 事件编排 / actor / 工作流 → XState。
- 在 Phaser / Pixi 内做实体拾取 → 直接用引擎输入系统(
Interaction*只服务无引擎宿主)。
v4 变更(Breaking,2026-10)
核心价值审计后删除了零使用者的 API(Deck、Situation/Heartbeat、
ResourceRegistry、IdGenerator、CompileResult、根导出 VERSION),新增
Resource.restore() 与 StateMachine 快照。所有保留模块行为与 v3 一致。
逐项迁移见 docs/migration-v4.md(English)。
架构
- 核心原语:
Clock·RandomSource·Countdown·ValueSource<T>·Predicate<T>·Signal<T>·ConditionExpression·DefinitionRegistry。 - 玩法系统(可独立使用,无需 ECS):
Resource·WeightedTable/Session·ShuffleBag·StateMachine·DialogueSession·Aspect。 - 可选系统:
World(ECS)· 几何 / 交互(表现与自绘宿主)。 - 示例:Phaser 4 演示 · Cocos 参考 · headless 切片 · 卡牌工艺切片 · Cookbook 8 例。
设计原则(Definition ≠ Runtime、纯算法 + 有状态外壳、能力注入、ECS 可选)见
ADR 目录。核心只针对 lib: ["ES2022"] 编译——在核心里用
window / process / Phaser 会直接 typecheck 失败。
命令
| 命令 | 作用 |
|---|---|
| npm run check | typecheck(核心 + 测试 + 示例)+ 测试 + build:lib —— 完整门禁 |
| npm test / npm run test:ecs 等 | 全部 / 按子系统定向测试(Vitest) |
| npm run cookbook | 运行 8 个可执行玩法范例 |
| npm run bench | 轻量基准 + 四任务三实现对比套件 |
| npm run build:lib | 构建库(ESM + .d.ts)到 dist/ |
| npm run verify:package | npm pack 产物完整性 + tarball 安装后逐入口 import 回归 |
| npm run example:headless / example:craft | 确定性垂直切片(含快照往返自检) |
| npm run dev | Phaser 4 演示(仅开发) |
仓库结构
src/gamelib/ # 库核心(引擎无关,零运行时依赖)
cookbook/ # 8 个可执行玩法范例(tests/cookbook.test.ts 断言)
bench/ # 基准:core.bench.ts + agent-comparison/(4 任务 × 3 实现)
examples/ # headless · card-crafting · phaser · cocos
tests/ # Vitest 单元 + 集成 + cookbook + 基准断言
docs/ # 模块文档 · ADR(0001–0014)· audit/(审计/生态对比/基准)· 迁移指南
spec/ # 可移植行为规范
AGENTS.md # 维护者契约 + 消费者指南License
MIT — Copyright (c) 2026 ludum Team.
