npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

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).

Readme

ludum

语言 / Language: 中文 · English

Composable, deterministic gameplay systems for TypeScript — designed for developers and coding agents.

一组可组合、确定性、零运行时依赖的玩法系统:资源与修饰符、加权随机与保底、 状态机、分支对话、无放回抽取、几何与交互。可在任意 JS/TS 宿主(浏览器、Node、 Deno、Bun)中运行,可 headless 测试、可快照存档。

完整文档 · Cookbook(可执行范例) · 核心价值审计

为什么用 ludum

每一项都可验证(依据见 审计 与 生态对比):

  1. 确定性是默认能力:注入 RandomSource / Clock,同种子同结果;所有有状态 模块支持 JSON 快照往返,「中断恢复字节级一致」有测试保证(examples/headless)。
  2. 填补真实空档:加权抽取 + 动态权重 + pity 保底 + 会话统计 + 快照的组合, npm 生态没有有采用者的等价包;带状态快照的种子化 RNG、headless 弹簧物理同理。
  3. Agent-First:每个玩法需求有明确模块与可复制范例(Cookbook 8 例全部 编译 + 测试验证);API 陷阱(如 onThreshold 的 'below' 失效)在文档与 Cookbook 显式标注。
  4. 小而可整读:核心模块 20–60 行,最大的 ECS 435 行;零依赖、MIT、ESM。

基准数据(AGENT_BENCHMARK.md):同一行为规范下, pity 掉落任务 ludum 24 行 vs 原生 54 行;HP+限时 buff 任务 21 行 vs 47 行; 纯移动模拟任务原生 24 行最小(ludum 30 行)——优势集中在数值玩法,不在所有场景。

安装

npm install ludum
import { 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.