developing-with-crisp-game-lib

使用 crisp-game-lib 开发

本技能用于使用 crisp-game-lib（一个用于快速开发街机游戏的 JavaScript 库）创建浏览器迷你游戏。

一、用途与适用范围

当被要求使用 crisp-game-lib 创建或修复迷你游戏时使用本技能。如果用户要求 Godot 或其他引擎，或未指定引擎，则不要使用本技能，除非现有项目已经是 crisp-game-lib 项目。

本指南区分三部分：有序的实现步骤（按顺序做什么）、强制约束（始终适用的规则）、可复用模式与参考（可选支持）。

二、实现前决策

选择项目搭建方式

根据项目上下文选择合适的方式。

方式 A：CDN（最简单——单个 HTML 文件）

创建包含 index.html 和 main.js 的项目目录。当脚本 URL 固定到已验证版本时，CDN 可用于最终项目。仅对于快速原型，明确标注为草稿的文件可以使用 crisp-game-lib@latest。

对于可复现的作业或已提交项目：CDN 可以，可复现性问题在于未固定、会变动的版本（如 @latest）。只固定项目已指定的版本，或你已从包元数据/CDN 访问中验证过的版本。不要凭空编造 crisp-game-lib 版本号。如果使用 algo-chip 辅助工具，已验证的 crisp-game-lib 版本必须为 1.5.0 或更高。如果没有可用已验证版本，则将版本选择视为最终提交骨架的阻塞项：询问现有项目版本，或请求检查包/CDN 元数据的许可。你只能在明确标注的草稿中展示 @latest，不能作为最终提交形式。

index.html 结构（含 viewport、可选 algo-chip 脚本、crisp-game-lib bundle.js、main.js 及 load 事件绑定）。其他可选脚本标签（如需在 bundle.js 之前添加）：GIF 捕获（当 options.isCapturing 为 true 时）、WebGL 主题（pixel、shape、shapeDark、crt 时需 pixi.js 与 pixi-filters）。

方式 B：npm + 打包器（Vite、Webpack 等）

假定打包器已配置（例如项目已有 package.json 和 Vite/Webpack 等开发服务器入口）。如果没有，先引导打包器（如 npm create vite@latest）再添加 crisp-game-lib。其他仅 CDN 的可选标签（gif-capture-canvas、pixi.js + pixi-filters）没有文档化的 npm 替代方案——如使用则保留为 index.html 中的 script 标签。

安装命令：npm install crisp-game-lib。如果项目还使用 algo-chip 辅助工具，安装或固定 crisp-game-lib 为 1.5.0 或更高。

打包器版本的 main.js 使用 const、import 和 init()。

三、实现流程

步骤 1：创建 main.js

按给定结构编写 main.js。实现前和实现期间：需要精确函数行为、参数形态、碰撞语义或可用颜色/声音时，阅读 references/api.md；当请求的游戏与所列模式之一相似，或需要完整可运行循环来改编时，阅读 references/examples.md。对于一键游戏，在编码前说明确切的输入解释（例如点击切换状态、点击施加冲量、按住蓄力或松开开火）。

步骤 2：实现核心游戏循环

用清晰的每帧顺序填充 update()：输入处理 → 物理/状态更新 → 生成 → 绘制（含碰撞检测）→ 分数更新 → 游戏结束条件。使用 if (!ticks) { ... } 做一次性初始化。

步骤 3：应用强制规则并验证

将第四节（强制规则）作为必需验证标准，然后在桌面端和/或移动端运行第六节清单。

对于本仓库的自动化测试器：在本仓库生成的测试夹具中，将游戏专属辅助逻辑保留在 update() 内；测试器执行可能遗漏在其外部定义的辅助函数。在普通用户项目中，如果目标构建/测试框架能正确运行，小型顶层辅助函数是可以接受的。

在有用时，用可检测的术语（如 obstacles、enemies 或 hazards）命名移动危险物数组。详细 GA 日志使用这些名称填充生成分析。

当需要在测试器日志中获得准确的分数事件位置时，优先使用 addScore(points, x, y) 而非 addScore(points, pos)。

四、强制规则（始终适用）

严格遵守这些规则。违反会导致静默 bug。

绘制顺序决定碰撞检测。 对象只能与同一帧中先于它绘制的图形检测碰撞。正确做法：先绘制目标，再绘制检测者（例如先绘制 enemies，再让 player 检测 isColliding.rect.red）。错误做法：检测尚未绘制的对象。

不要手动绘制分数。 库会自动显示。绝不要调用 text() 显示分数。

白色在所有主题下不可见（与背景相同）。改用 light_ 变体或其他颜色。

使用对象格式的 particle()：particle(pos, { count: 5, speed: 2, angle: PI }) 为推荐写法；particle(pos, 5, 2, PI, PI) 为旧格式。

五、常见实现模式（可选）

一键/点击游戏（最适合移动端）：if (input.isJustPressed) { /* 跳跃、射击或改变方向 */ }
滑动控制：player.pos.x = input.pos.x; player.pos.clamp(5, 95, 5, 95);
难度递增生成：在游戏状态层声明 nextEnemyTicks，首帧初始化为 0，倒计时并生成，间隔用 rnd(60, 120) / difficulty。
使用 remove() 更新实体：remove(enemies, (e) => { ...; return e.pos.x < -10; })。
物理（重力 + 跳跃）：player.vy += 0.15; player.pos.y += player.vy; 地面碰撞处理；if (input.isJustPressed && player.onGround) { player.vy = -4; play("jump"); }

六、验证清单

在浏览器中打开游戏并检查：游戏初始化无错误；控制响应正确；碰撞检测正常（绘制顺序正确）；分数适当增加；end() 正确触发游戏结束；移动端：如适用，触摸控制正常。

七、关键 API 速查

绘制：rect(x,y,w,h)、box(pos,w,h)、line(p1,p2,t)、bar(pos,len,t,angle)、arc(pos,r,t,start,end)
文本：text(str,x,y)、char(ch,x,y)、addWithCharCode(ch,offset)
颜色：color("red")——red、green、blue、yellow、purple、cyan、black、light_* 变体、transparent
输入：input.pos、input.isPressed、input.isJustPressed、keyboard.code["Space"].isJustPressed
音频：play("coin")——所列名称：coin、powerUp、hit、jump、select、lucky。将此列表视为示例；调用其他名称前查阅 references/api.md 获取完整枚举。
向量：vec(x,y)、.add()、.sub()、.mul()、.clamp(xMin,xMax,yMin,yMax)、.wrap()、.addWithAngle()、.distanceTo()
工具：times(n,fn)、range(n)、remove(arr,fn)、rnd(max)、rndi(max)、clamp(v,min,max)、wrap(v,min,max)——注意自由函数 clamp/wrap 接受标量；同名 Vector 方法接受 4 个轴边界。
状态：ticks、score、difficulty、addScore(points)、addScore(points,pos)、addScore(points,x,y)、end()
效果：particle(pos, {count, speed, angle, angleWidth})