diff --git a/game-runtime/docs/ENGINE-CAPABILITIES.md b/game-runtime/docs/ENGINE-CAPABILITIES.md new file mode 100644 index 00000000..52d05df6 --- /dev/null +++ b/game-runtime/docs/ENGINE-CAPABILITIES.md @@ -0,0 +1,206 @@ +# ENGINE-CAPABILITIES.md —— LittleJS 引擎真实能力索引（T1b-β Phase 0 P0/P1 产物） + +> **唯一证据源**：`node_modules/littlejsengine/dist/littlejs.d.ts`（v1.18.19，277KB，5710 行，TS `declare module "littlejsengine"`）。 +> **抽取纪律（R3 整改铁律）**：每条能力的签名/返回类型/坐标系**一律来自 `.d.ts` 源码 file:line**，不靠记忆、不靠文档转述、不脑补。核不到的项显式标「未核到/存疑」。 +> **用途**：供执行版 §7「插件×引擎重叠清单」按 §1.5 三分判定测试（①返回类型兼容 ②坐标系一致 ③语义一致）逐函数比对。裁定表见本仓返回件（不改 execution.md 正文）。 +> +> **坐标系总纲（贯穿全表，决定三分测试第②项）**： +> - 引擎**默认世界坐标（world space）**，`screenSpace=false`；Draw 系列均有可选 `screenSpace` 与可选 `context`（`CanvasRenderingContext2D`）尾参。 +> - 引擎几何类型 = `Vector2{x,y}`（类，可链式）；AABB 表示为 **`pos`（中心）+ `size`（全宽全高）** 的 `Vector2` 对（见 `isOverlapping` 签名）。 +> - 插件受控面几何 = 朴素 `{x,y}` number 对；插件 AABB = **`{x,y,hw,hh}`（中心 + 半宽半高）**。 +> - ∴ 引擎 `size`(全宽) vs 插件 `hw`(半宽) 差 **2× 换算**；引擎 `Vector2` 实例 vs 插件 POJO 形状不同——这是「坐标系一致」项普遍不过的根因（R3 已预判）。 + +--- + +## 0. 安装与构建事实（P0） + +| 项 | 值 | 证据 | +|---|---|---| +| 包名@版本 | `littlejsengine@1.18.19`（与 T1 spike / channel-spike 同钉版） | `package.json` deps；`npm ls littlejsengine` | +| 入口（main / module） | `dist/littlejs.esm.js`（640KB ESM） | `npm view littlejsengine main` | +| 类型 | `dist/littlejs.d.ts` | `npm view littlejsengine types` | +| esbuild 可 resolve | ✅ 实测 `import * as L from 'littlejsengine'` 经 esbuild `bundle+iife+es2019` 产物 432KB，核心符号 `ParticleEmitter`/`engineInit`/`drawTile`/`RandomGenerator` 入产物 | 本机 esbuild 0.28.1 试打包 | +| 渲染模型 | 混合渲染：`glCanvas`(WebGL2 批渲) + `mainCanvas`/`mainContext`(Canvas2D 叠加层，文字/UI/自定义绘制) | `.d.ts:1754-1755,1763-1767,2126` | + +--- + +## 1. 引擎生命周期 / 主循环（A0 地基所需） + +| 导出名 | 完整签名 | 返回 | 语义 / 坐标系 | 证据 | +|---|---|---|---|---| +| `engineInit` | `engineInit(gameInit: GameInitCallback, gameUpdate: GameCallback, gameUpdatePost: GameCallback, gameRender: GameCallback, gameRenderPost: GameCallback, imageSources?: Array, rootElement?: HTMLElement): Promise` | `Promise` | **引擎启动入口**。5 个回调：gameInit(启动一次,可 async)/gameUpdate(每帧 60fps,物理前,游戏逻辑)/gameUpdatePost(物理与对象更新后,即便暂停也调,UI)/gameRender(对象渲染前,画背景/世界)/gameRenderPost(对象渲染后,画 UI/叠层)。可选预载图与挂载 root DOM。 | `:148`（doc :129-147） | +| `engineUpdate` | **未导出**——主循环为引擎内部 RAF 驱动，外部只能经 engineInit 回调挂入；无独立 `engineUpdate` 导出 | — | A0 接管 = host 调 `engineInit` 让引擎掌帧，gameUpdate/gameRender 回调里接桩逻辑（不是手摇 engineUpdate） | grep `engineUpdate` 零命中（仅 `engineObjectsUpdate`） | +| `engineObjectsUpdate` | `engineObjectsUpdate(): void` | `void` | 手动更新所有对象/移除已毁/推进时间（一般由主循环自动调，可在循环外手动调） | `:152` | +| `engineAddPlugin` | `engineAddPlugin(update?: PluginCallback, render?: PluginCallback, glContextLost?: PluginCallback, glContextRestored?: PluginCallback): void` | `void` | 注册引擎级插件的 update/render 钩子（含 GL 上下文丢失/恢复回调）。`PluginCallback = () => any`。 | `:195`（type `:3`） | +| `frame` | `export let frame: number` | number | 当前更新帧序号（算时间用） | `:98` | +| `time` | `export let time: number` | number | **引擎起始至今秒数；受暂停/timeScale/帧率钳制影响**（游戏逻辑时钟） | `:99-102` | +| `timeReal` | `export let timeReal: number` | number | **真实墙钟秒数；不受暂停/timeScale/帧率钳制**（probe 启动耗时埋点应取此或独立墙钟） | `:103-106` | +| `timeScale` | `export let timeScale: number` | number | 全局时间缩放（hitStop/慢动作） | `:352` | +| `setTimeScale` | `setTimeScale(scale: number): void` | `void` | 设置 timeScale | `:638` | +| `paused` / `getPaused` / `setPaused` | `paused: boolean` / `getPaused(): boolean` / `setPaused(isPaused?: boolean): void` | — | 暂停态（暂停时 time 与对象不更新） | `:111,115,119` | + +> **A0 关键事实**：`time` 会被 timeScale/pause/帧率钳制污染（`:103` 注明 timeReal 才是「not affected by pause, timescale, or frame rate clamping」）。∴ 执行版 §5/门0「probe 启动耗时取墙钟、与引擎 time 解耦」**有引擎源码硬支撑**——probe 须用 `timeReal` 或自管 `performance.now()`，**不可用 `time` 作 P75 埋点**。 + +--- + +## 2. 数学 / 插值 / 工具（gamefeel easing、确定性随机所需） + +| 导出名 | 完整签名 | 返回 | 语义 | 证据 | +|---|---|---|---|---| +| `lerp` | `lerp(valueA: number, valueB: number, percent: number): number` | number | 线性插值 | `:987` | +| `lerpAngle` | `lerpAngle(angleA, angleB, percent: number): number` | number | 带环绕的角度插值 | `:980` | +| `lerpWrap` | `lerpWrap(valueA, valueB, percent, wrapSize?): number` | number | 带环绕的值插值 | `:967` | +| `smoothStep` | `smoothStep(percent: number): number` | number | smoothstep 缓动（对百分比施加） | `:1002` | +| `percent` | `percent(value, valueA, valueB): number` | number | value 在 [A,B] 间的百分比 | `:952` | +| `percentLerp` | `percentLerp(value, percentA, percentB, lerpA, lerpB): number` | number | percent+lerp 快捷组合 | `:997` | +| `oscillate` | `oscillate(frequency?, amplitude?, t?=time, offset?, type?): number` | number | 0~amplitude 振荡波；type 0=正弦/1=三角/2=方波/3=锯齿；**默认 t=`time`** | `:1052`（doc :1044-1051） | +| `clamp` | `clamp(value, min?, max?): number` | number | 钳制 | `:945` | +| `noise1D`/`noise2D` | `noise1D(x): number` / `noise2D(x,y): number` | number [0,1] | 梯度噪声（整数格确定性，非整数 smoothStep 插值） | `:1104,1110` | + +> **easing 缺口**：引擎仅 `lerp`/`smoothStep`/`oscillate`。gamefeel 的 `quadIn/Out`、`cubicIn/Out`、**`elasticIn/Out/InOut`、`backIn/Out/InOut`** 引擎**确无**（grep 无 elastic/back/cubic easing 导出）。只有 linear(≈lerp)/smoothstep 两个有对应。 + +### 2.1 随机（受控面 random 透传所需） + +| 导出名 | 完整签名 | 返回 | 语义 | 证据 | +|---|---|---|---|---| +| `RandomGenerator` (class) | `constructor(seed?: number)`；`float(a?,b?): number`；`int(a,b?): number`；`bool(chance?): boolean`；`sign(): number`；`floatSign(a?,b?): number`；`angle(): number`；`vec2(a?,b?): Vector2`；`randColor(...)`；`mutateColor(...)`；属性 `seed: number` | 见各方法 | **种子化确定性随机**（same seed → 同序）。引擎注释「Engine helper classes: …RandomGenerator」；引擎全局随机实现为 xorshift 类（spike 实证 same seed 同序） | `:1164-1212` | +| `rand` | `rand(valueA?, valueB?): number` | number | 全局（非种子）随机 | `:1118` | + +--- + +## 3. 绘制 API（render.js 切引擎、palette 基元所需） + +| 导出名 | 完整签名 | 返回 | 坐标系 | 证据 | +|---|---|---|---|---| +| `drawTile` | `drawTile(pos: Vector2, size?: Vector2, tileInfo?: TileInfo, color?: Color, angle?: number, mirror?: boolean, additiveColor?: Color, useWebGL?: boolean, screenSpace?: boolean, context?: CanvasRenderingContext2D\|OffscreenCanvasRenderingContext2D): void` | `void` | **世界坐标**（screenSpace 可切）；可选 context 落 Canvas2D | `:1844` | +| `drawRect` | `drawRect(pos: Vector2, size?: Vector2, color?: Color, angle?: number, useWebGL?: boolean, screenSpace?: boolean, context?): void` | `void` | 世界坐标，中心定位 | `:1854` | +| `drawRectGradient` | `drawRectGradient(pos, size?, colorTop?, colorBottom?, angle?, useWebGL?, screenSpace?, context?): void` | `void` | 世界坐标，顶→底渐变 | `:1865` | +| `drawText` | `drawText(text: string\|number, pos: Vector2, size?: number, color?: Color, lineWidth?: number, lineColor?: Color, textAlign?: CanvasTextAlign, font?: string, fontStyle?: string, maxWidth?: number, angle?: number, context?): void` | `void` | 世界坐标，自动换行；CJK 经默认 font（spike 已验中文） | `:2000` | +| `drawTextScreen` | `drawTextScreen(text, pos, size, color?, ...): void` | `void` | **屏幕坐标**文字 | `:2016` | +| `drawCanvas2D` | `drawCanvas2D(pos: Vector2, size: Vector2, angle?, mirror?, drawFunction?: Canvas2DDrawFunction, screenSpace?, context?): void` | `void` | 自定义 Canvas2D 绘制回调（世界坐标变换内）——**Canvas2D 逃生口** | `:1984` | +| `mainCanvas` / `mainContext` | `export let mainCanvas: HTMLCanvasElement` / `mainContext: CanvasRenderingContext2D` | — | Canvas2D 叠加层与其 2d context | `:1763,1767` | +| `glCanvas` | `export let glCanvas: HTMLCanvasElement` | — | WebGL2 批渲 canvas | `:2126` | + +### 3.1 颜色（palette-post RGB↔HSL 基元所需） + +| 导出名 | 完整签名 | 返回 | 语义 | 证据 | +|---|---|---|---|---| +| `Color` (class) | `constructor(r?,g?,b?,a?)`；属性 `r/g/b/a: number`；`setHSLA(h?,s?,l?,a?): Color`；`HSLA(): Array`；`setHex(hex): Color`；`toString(useAlpha?): string`；`lerp(c,percent): Color`；`add/subtract/multiply/divide/scale/clamp/mutate` | 见方法 | **单色 RGBA 对象，自带 HSL 互转**（setHSLA/HSLA）。**注意：是逐 Color 实例的转换，非像素缓冲批处理** | `:1365-1453` | + +> **palette 基元裁定要点**：`Color.setHSLA`/`HSLA()` 提供 RGB↔HSL（单色，0~1 浮点 r/g/b）。但 palette-post 的 `applyPaletteMapToBuffer`/`ditherImageData` 是对 **`Uint8ClampedArray` RGBA 像素缓冲 / `ImageData`** 的 CPU 批处理 + 索引色精确匹配表 + Bayer 抖动——引擎**无对应缓冲级操作**，索引色表确无。 + +--- + +## 4. 粒子（particles-juice 所需） + +| 导出名 | 完整签名 | 返回 | 坐标系 | 证据 | +|---|---|---|---|---| +| `ParticleEmitter` (class) | `constructor(pos: Vector2, angle?, emitSize?: number\|Vector2, emitTime?, emitRate?, emitConeAngle?, tileInfo?, colorStartA?, colorStartB?, colorEndA?, colorEndB?, particleTime?, sizeStart?, sizeEnd?, speed?, angleSpeed?, damping?, angleDamping?, gravityScale?, particleConeAngle?, fadeRate?, randomness?, collideTiles?, additive?, randomColorLinear?, renderOrder?, localSpace?)`；方法 `emitParticle(): Particle`、`isActive(): boolean`；**`extends EngineObject`** | 实例 | **世界坐标**：`pos` 世界位置，`emitSize`/`speed`(世界单位/帧@60fps) 全世界空间；发射器本身是引擎对象（自动入对象列表、随主循环更新渲染） | `:3232-3324`（constructor :3262） | +| `Particle` (class) | `constructor(emitter, pos, angle, colorStart, colorEnd, lifeTime, sizeStart, sizeEnd, velocity?, angleVelocity?)` | 实例 | 世界/局部空间；通常由 emitter 自动创建 | `:3329-3344` | +| `particleEmitRateScale` | `export let particleEmitRateScale: number` | number | 全局发射率缩放（低画质模式，0 禁用所有 emitter） | `:479` | + +> **坐标系冲突**：emitter 构造首参 `pos: Vector2` = **世界坐标**，且 `extends EngineObject`（受引擎主循环驱动）。particles-juice 受控面用朴素 `{x,y}` 像素坐标 + 自有 `EmitterConfig`/`evalCurve`/preset 体系——存在世界↔像素阻抗 + 「引擎对象生命周期 vs 插件自管发射」体系差。**A0 接管后才有引擎对象更新驱动**（否则 emitter 不 update = 空转）。 + +### 4.1 屏震 / 相机（particles-juice 屏震所需） + +| 导出名 | 完整签名 | 返回 | 证据 | +|---|---|---|---| +| `cameraPos` | `export let cameraPos: Vector2` | Vector2 | `:334` | +| `setCameraPos` | `setCameraPos(pos: Vector2): void` | `void` | `:626` | +| `cameraScale` / `setCameraScale` | `cameraScale: number` / `setCameraScale(scale): void` | — | `:344,634` | + +> **跨层警告**：屏震走引擎 `cameraPos` 需**渲染基座本身用引擎相机**（即 render.js 全切引擎 draw + 引擎相机）。若 render 仍是裸 Canvas2D，则 cameraPos 不被消费——屏震只能保留受控面像素偏移补层。 + +--- + +## 5. 音频（audio-music 所需） + +| 导出名 | 完整签名 | 返回 | 语义 / 坐标系 | 证据 | +|---|---|---|---|---| +| `zzfxG` | `zzfxG(volume?, randomness?, frequency?, attack?, sustain?, release?, shape?, shapeCurve?, slide?, deltaSlide?, pitchJump?, pitchJumpTime?, repeatTime?, noise?, modulation?, bitCrush?, delay?, sustainVolume?, decay?, tremolo?, filter?): any[]` | **`Array`（采样样本数据）** | **纯合成核**：返回 PCM 样本，不播放。与插件 zzfxG 同口径 | `:2724` | +| `zzfxM` | `zzfxM(instruments: any[], patterns: any[], sequence: any[], BPM?: number): any[]` | **`Array`（左右声道样本）** | 纯音乐样本生成，不播放 | `:3730` | +| `zzfx` | `zzfx(...zzfxSound: any[]): AudioBufferSourceNode` | **`AudioBufferSourceNode`（已在播放）** | 合成 + 立即播放（合成核与播放耦合在一起） | `:2699` | +| `Sound` (class) | `constructor(asset?: string\|Array, randomness?, range?, taper?, onloadCallback?)`；`play(pos?: Vector2, volume?, pitch?, randomnessScale?, loop?, paused?): SoundInstance`；`playMusic(volume?, loop?, paused?): SoundInstance`；`playNote(semitoneOffset?, pos?, volume?): SoundInstance`；属性 `sampleChannels: any[][]`、`range`、`taper` | 见方法 | **`play` 是世界坐标定位音**：`pos: Vector2` 世界位置 + `range`/`taper` 距离衰减。`new Sound([.5,.5])` 可建 zzfx 音。 | `:2514-2578`（play :2551） | +| `SoundInstance` (class) | `constructor(sound, volume?, rate?, pan?, loop?, paused?)`；setVolume/pause/resume/stop（doc 示例） | 实例 | 单次播放实例控制（pause/resume/pan 立体声） | `:2595` | +| `ZzFXMusic` (class) | `constructor(zzfxMusic: [any[],any[],any[],number])`；`playMusic(volume?, loop?): SoundInstance`；**`extends Sound`** | 实例 | zzfx 音乐对象（**不存在独立 `Music` 类**，实为 `ZzFXMusic extends Sound`） | `:3710-3722` | +| `audioContext` | `export let audioContext: AudioContext` | AudioContext | 全局 Web Audio 上下文 | `:2482` | + +> **音频裁定要点（§1.5 例已点名）**：①`zzfxG`/`zzfxM` = **纯合成核（返回样本）→ 可包装**。②`Sound.play(pos, ...)` = **世界坐标定位 + 相机距离衰减**；受控面无相机体系、用 PCM `playChannels` 直推声道——**空间语义不兼容 → 播放/混音层补层**。③`Music` 类**不存在**，须用 `ZzFXMusic`（extends Sound）或 `Sound.playMusic()`。 + +--- + +## 6. 碰撞 / 物理 / 瓦片（collision、physics-lite 所需） + +### 6.1 引擎几何查询函数（与 collision 插件 MTV/RayHit 契约比对） + +| 导出名 | 完整签名 | 返回 | 语义 / 坐标系 | 证据 | +|---|---|---|---|---| +| `isOverlapping` | `isOverlapping(posA: Vector2, sizeA: Vector2, posB: Vector2, sizeB?: Vector2): boolean` | **`boolean`** | AABB 重叠真假判；`pos`=中心,`size`=**全宽全高**；**无穿透深度/无 MTV 法线** | `:1021`（doc :1013-1020） | +| `isIntersecting` | `isIntersecting(start: Vector2, end: Vector2, pos: Vector2, size: Vector2): boolean` | **`boolean`** | **线段** start→end vs AABB 真假判；**无 t、无命中点、无法线** | `:1029`（doc :1022-1028） | +| `lineTest` | `lineTest(posStart: Vector2, posEnd: Vector2, testFunction: LineTestFunction, normal?: Vector2): Vector2\|undefined` | **`Vector2\|undefined`（命中位置）** | 沿线段逐点测试回调，返回首个碰撞**位置**；法线经可选 out 参数 `normal` 写回；**无标量 t、无结构化 RayHit** | `:1043`（doc :1035-1042） | + +### 6.2 引擎物理体系（EngineObject，与 physics-lite 解耦运动学比对） + +| 导出名 | 关键签名 / 属性 | 语义 | 证据 | +|---|---|---|---| +| `EngineObject` (class) | 属性 `pos/size/velocity: Vector2`、`mass/damping/angleDamping/restitution/friction/gravityScale/angleVelocity: number`、`clampSpeed: boolean`、`groundObject`、`collideTiles/collideSolidObjects/isSolid/collideRaycast: boolean`；方法 `updatePhysics(): void`、`updateTransforms(): void`、`applyForce(force: Vector2)`、`applyAcceleration(acceleration: Vector2)`、`getSpeed(): number`、`isOverlapping(pos, size?): boolean`、`isOverlappingObject(object): boolean`、`setCollision(...)`、`localToWorld/worldToLocal(pos: Vector2)` | **有状态 OOP 刚体**：对象入引擎对象列表，`updatePhysics()` 每帧由引擎自动调（60fps 帧步），velocity 为 `Vector2`，碰撞解析内建。坐标=世界 Vector2。 | `:2761-2920`（updatePhysics :2832,velocity :2804,clampSpeed :2812,applyForce :2886） | +| `objectMaxSpeed` | `export let objectMaxSpeed: number` | **全局**速度上限（防快速对象穿透） | `:469` | +| `gravity` | `export let gravity: Vector2` | **全局** Vector2 重力（spike 实证：`setGravity(标量)` 崩，须 Vector2） | `:470-474` | +| `objectDefaultFriction`/`objectDefaultRestitution` | `export let …: number` | 全局默认摩擦/弹性 | `:459,464` | + +### 6.3 瓦片碰撞（tileCollision*） + +| 导出名 | 完整签名 | 返回 | 证据 | +|---|---|---|---| +| `tileCollisionTest` | `tileCollisionTest(pos: Vector2, size?: Vector2, callbackObject?: EngineObject\|TileCollisionCallback, solidOnly?: boolean): TileCollisionLayer` | `TileCollisionLayer` | `:2950` | +| `tileCollisionRaycast` | `tileCollisionRaycast(posStart: Vector2, posEnd: Vector2, callbackObject?: EngineObject\|TileCollisionCallback, normal?: Vector2, solidOnly?: boolean): Vector2\|undefined` | `Vector2\|undefined`（位置，法线经 out 参） | `:2966` | + +> **collision/physics 裁定要点**：①引擎 `isOverlapping`→bool、`isIntersecting`→bool、`lineTest`/`tileCollisionRaycast`→`Vector2\|undefined`（位置，无标量 t）——**均满足不了插件 `Manifold{hit,depth,nx,ny}`(MTV) 与 `RayHit{hit,t,px,py,nx,ny}` 契约**。②`SpatialHash`/圆×圆/圆×AABB/SAT 多边形/圆射线——引擎**确无**对应导出（grep 无 `SpatialHash`/`satVsPolygon`/`circleVsCircle`）。③physics-lite 是**无状态 `dtSeconds` 秒级纯函数**(`{px,py,vx,vy}` POJO)，与引擎 `EngineObject` 有状态帧步刚体（`Vector2` velocity、全局 gravity/objectMaxSpeed）**体系级阻抗**。 + +--- + +## 7. 输入（受控面 input 所需） + +| 导出名 | 完整签名 | 返回 | 语义 | 证据 | +|---|---|---|---|---| +| `keyIsDown` | `keyIsDown(key: string\|number, device?: number): boolean` | boolean | **轮询态**：当前键是否按下 | `:2265` | +| `keyWasPressed` | `keyWasPressed(key: string\|number, device?: number): boolean` | boolean | 本帧是否刚按下（轮询态） | `:2271` | +| `mouseIsDown` | `mouseIsDown(button: number): boolean` | boolean | 鼠标键当前按下 | `:2302` | +| `mouseWasPressed` | `mouseWasPressed(button: number): boolean` | boolean | 鼠标键本帧刚按下 | `:2308` | +| `mousePos` | `export let mousePos: Vector2` | Vector2 | 鼠标世界坐标 | `:2330` | +| `gamepadIsDown` | `gamepadIsDown(button: number, gamepad?: number): boolean` | boolean | 手柄键轮询态 | `:2403` | + +> **input 裁定要点**：引擎输入是**每帧轮询态布尔**（isDown/wasPressed），无事件订阅。受控面 input 做「对引擎轮询态的归一化包装」（底层读引擎态），订阅形状留给消费者层——**归一化包装**成立。 + +--- + +## 8. 后处理（palette-post 所需）+ 两存疑项消解 + +### 8.1 存疑项 #1：postProcess 能否注入自定义 GLSL shader？ —— ✅ **可注入（确证）** + +| 导出名 | 完整签名 | 证据 | +|---|---|---| +| `PostProcessPlugin` (class) | `constructor(shaderCode: string, includeMainCanvas?: boolean, feedbackTexture?: boolean)`；属性 `shader: WebGLProgram`、`texture: WebGLTexture`、`vao: WebGLVertexArrayObject` | `:3578-3593` | +| `postProcess` | `export let postProcess: PostProcessPlugin`（全局实例） | `:3573` | + +- `.d.ts:3563-3567` 命名空间注释明文：**"Supports shadertoy style post processing shaders"**、`new PostProcessPlugin()` setup post processing、可让其它 canvas 过一道最终 shader。 +- 构造首参 = **原始 GLSL `shaderCode: string`**，编译成 `WebGLProgram`。**∴ 自定义 GLSL fragment shader 可注入**。 +- **但对 palette-post 的影响**：postProcess 钩子接 GLSL（GPU 片元着色器），而 palette-post 算法是 **CPU 侧 `Uint8ClampedArray` 像素缓冲 + 索引色精确匹配表(`applyPaletteMapToBuffer`) + Bayer 有序抖动(`ditherImageData`)**（见 §3.1）。引擎能注入 GLSL ≠ palette-post 现算法能零改写复用——**把 CPU 索引色/抖动逻辑迁到 GLSL = 整体重写**（与 P1 核名是两回事，R3 预判成立）。结论：palette-post **postProcess 走「整体缺件补层」**（引擎提供 GLSL 注入位，但平台调色逻辑须自实现，可选未来重写为 GLSL）。 + +### 8.2 存疑项 #2：medal 系统是否存在？ —— ✅ **存在（确证）** + +| 导出名 | 完整签名 | 证据 | +|---|---|---| +| `Medal` (class) | `constructor(id: number, name: string, description?: string, icon?: string, src?: string)`；属性 `id/name/description/icon: …`、`unlocked: boolean`、`image`；方法 `unlock(): void`、`render(hidePercent?): void`、`renderIcon(pos: Vector2, size: number): void` | `:3457-3489` | +| `NewgroundsMedal` (class) | `extends Medal`（Newgrounds 远程成就） | `:3561` | +| `newgrounds` / `NewgroundsPlugin` | 全局 + 类（远程榜/成就 API） | `:3502,3507` | + +- 引擎特性列（`.d.ts:60`）明文「Medal/achievement system with local storage」——**本地存储支撑的成就/勋章系统存在**。Phase A+ 若需成就可直接用（非本波范围，仅消存疑）。 + +--- + +## 附：覆盖能力清单核对（执行版 P1 点名项，逐项已核） + +`ParticleEmitter`✓ `Sound`✓ `Music`→**实为 ZzFXMusic/Sound.playMusic（无独立 Music 类）** `zzfx`✓ `zzfxM`✓ `zzfxG`✓ `EngineObject(updatePhysics✓/objectMaxSpeed✓/collideSolidObjects✓)` `isOverlapping`✓ `isIntersecting`✓ `tileCollisionTest`✓ `RandomGenerator`✓ `time`✓ `timeScale`✓ `frame`✓ `engineInit`✓ `engineUpdate`→**未导出（内部 RAF，经 engineInit 回调接管）** `engineAddPlugin`✓ `cameraPos`✓ `lerp`✓ `smoothStep`✓ `percent`✓ `oscillate`✓ `drawTile`✓ `drawText`✓ `drawRect`✓ `Color`✓ + postProcess(GLSL 可注入)✓ medal(存在)✓。 + +> 两处与执行版命名预期的偏差（**已核到、非脑补**）：①无独立 `Music` 类，引擎音乐 = `ZzFXMusic extends Sound` 或 `Sound.playMusic()`；②无 `engineUpdate` 导出，主循环为引擎内部 RAF，外部经 `engineInit` 五回调接管（A0 据此实现，不是手摇 engineUpdate）。 diff --git a/game-runtime/package-lock.json b/game-runtime/package-lock.json new file mode 100644 index 00000000..8fec36be --- /dev/null +++ b/game-runtime/package-lock.json @@ -0,0 +1,511 @@ +{ + "name": "game-runtime", + "version": "0.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "game-runtime", + "version": "0.0.0", + "dependencies": { + "littlejsengine": "1.18.19" + }, + "devDependencies": { + "esbuild": "0.28.1" + } + }, + "node_modules/@esbuild/aix-ppc64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.1.tgz", + "integrity": "sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.1.tgz", + "integrity": "sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.1.tgz", + "integrity": "sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.1.tgz", + "integrity": "sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.1.tgz", + "integrity": "sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.1.tgz", + "integrity": "sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.1.tgz", + "integrity": "sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.1.tgz", + "integrity": "sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.1.tgz", + "integrity": "sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.1.tgz", + "integrity": "sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ia32": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.1.tgz", + "integrity": "sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-loong64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.1.tgz", + "integrity": "sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-mips64el": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.1.tgz", + "integrity": "sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ==", + "cpu": [ + "mips64el" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ppc64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.1.tgz", + "integrity": "sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-riscv64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.1.tgz", + "integrity": "sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-s390x": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.1.tgz", + "integrity": "sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.1.tgz", + "integrity": "sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.1.tgz", + "integrity": "sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.1.tgz", + "integrity": "sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.1.tgz", + "integrity": "sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.1.tgz", + "integrity": "sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openharmony-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.1.tgz", + "integrity": "sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/sunos-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.1.tgz", + "integrity": "sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.1.tgz", + "integrity": "sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-ia32": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.1.tgz", + "integrity": "sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.1.tgz", + "integrity": "sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/esbuild": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.1.tgz", + "integrity": "sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.28.1", + "@esbuild/android-arm": "0.28.1", + "@esbuild/android-arm64": "0.28.1", + "@esbuild/android-x64": "0.28.1", + "@esbuild/darwin-arm64": "0.28.1", + "@esbuild/darwin-x64": "0.28.1", + "@esbuild/freebsd-arm64": "0.28.1", + "@esbuild/freebsd-x64": "0.28.1", + "@esbuild/linux-arm": "0.28.1", + "@esbuild/linux-arm64": "0.28.1", + "@esbuild/linux-ia32": "0.28.1", + "@esbuild/linux-loong64": "0.28.1", + "@esbuild/linux-mips64el": "0.28.1", + "@esbuild/linux-ppc64": "0.28.1", + "@esbuild/linux-riscv64": "0.28.1", + "@esbuild/linux-s390x": "0.28.1", + "@esbuild/linux-x64": "0.28.1", + "@esbuild/netbsd-arm64": "0.28.1", + "@esbuild/netbsd-x64": "0.28.1", + "@esbuild/openbsd-arm64": "0.28.1", + "@esbuild/openbsd-x64": "0.28.1", + "@esbuild/openharmony-arm64": "0.28.1", + "@esbuild/sunos-x64": "0.28.1", + "@esbuild/win32-arm64": "0.28.1", + "@esbuild/win32-ia32": "0.28.1", + "@esbuild/win32-x64": "0.28.1" + } + }, + "node_modules/littlejsengine": { + "version": "1.18.19", + "resolved": "https://registry.npmjs.org/littlejsengine/-/littlejsengine-1.18.19.tgz", + "integrity": "sha512-wJGeEJW8VLCQO/rd4lPUjgzdtWYvf708WxE6zmFY4Vd2ohg9T4czLKwrs1Ye80zT7UTgqxqN9JWc9+rhJJ8Drw==", + "license": "MIT", + "engines": { + "node": ">=18" + } + } + } +} diff --git a/game-runtime/package.json b/game-runtime/package.json new file mode 100644 index 00000000..bfb895e1 --- /dev/null +++ b/game-runtime/package.json @@ -0,0 +1,19 @@ +{ + "name": "game-runtime", + "private": true, + "version": "0.0.0", + "type": "module", + "description": "造梦AI 平台维护的 LittleJS 增强发行版（Tier1 引擎 + 能力插件库）。引擎钉版与 spike/channel-spike 一致(littlejsengine@1.18.19)；esbuild 仅集成段(mini-desktop)打包使用，lane 本机零依赖只跑 node --test。", + "scripts": { + "test": "node --test src/**/*.test.mjs", + "build": "node scripts/build.mjs", + "size": "node scripts/size.mjs", + "validate": "node scripts/validate-manifest.mjs" + }, + "dependencies": { + "littlejsengine": "1.18.19" + }, + "devDependencies": { + "esbuild": "0.28.1" + } +}