miaoda-game-devkit 0.7.3 → 0.8.0

package/README.md

@@ -93,6 +93,31 @@ Phaser 4 模板对应使用 `miaoda-phaser-game-lint`。命令类型不通过依
 模板即使预装 Phaser 3 及相关插件，也不会解析 Phaser 或运行 Phaser 4 检查。旧的
 `miaoda-game-lint` 不再发布，避免在同时包含 React 与 Phaser 依赖的项目中产生歧义。
 
+## 可编辑的游戏机制源码
+
+Devkit 发布统一的 `miaoda` 命令。裸 `miaoda-game-*` 包名默认从公开源码索引解析为
+当前稳定版本，Devkit 直接下载并校验该包及其传递机制依赖的源码归档；消费项目自己的 pnpm
+10 或 11 只负责最终 workspace 联动和普通第三方依赖安装。生产 TypeScript 源码写入
+`src/game-mechanics/<包名>/`。`.miaoda/mechanics-source.json` 只保存版本、索引地址与安装摘要，
+不保存第二份源码。
+
+```bash
+pnpm exec miaoda mechanics --help
+pnpm exec miaoda mechanics add miaoda-game-beam-core
+pnpm exec miaoda mechanics add miaoda-game-beam-core@1.2.3 \
+  --source-index=https://public.example.com/game-mechanics/stable.json
+pnpm exec miaoda mechanics status
+```
+
+默认索引是 `https://resource-static.bj.bcebos.com/miaoda-game/stable.json`。只有调试、测试或
+私有镜像场景才需要通过 `--source-index` 或 `MIAODA_MECHANICS_INDEX_URL` 覆盖。
+
+重复添加同版本不会覆盖源码；`status` 报告 `clean`、`modified` 或 `missing`。更新到不同版本时，
+若本地源码已修改，命令会在写入前失败。包内的单元测试、Vitest 配置、构建输出和 `node_modules`
+不会复制进游戏项目，避免它们进入游戏自身的 TypeScript 编译范围。索引中的相对 TGZ URL 以
+`stable.json` 为基准解析；每个版本必须提供精确的机制依赖和 SHA-256。机制源码只通过该索引
+解析，不回退 npm registry，也不接受绕过索引的直接 TGZ 或本地包路径。
+
 开发工具包自行维护并精确固定 Vitest 等工具版本，从自身依赖中解析可执行文件，使用方不需要重复声明
 Biome、Oxlint 或 tsgo。仓库中保留稳定的命令入口，因此 `dist/` 尚未生成时，pnpm
 也能正确建立命令链接；工作区开发状态下由 Nx 在模板检查前构建开发工具包，发布包则

package/bin/miaoda.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+void import('../mechanics/materialize-game-mechanics-source.mjs')
+	.then(({ main }) => main(process.argv.slice(2)))
+	.catch((error) => {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exitCode = 1;
+	});

package/dist/cli/phaser-lint.js

@@ -311,9 +311,15 @@ function checkReactProductTestAlignment() {
   console.error(`[${name}] ${audit.issues[0]}`);
   return { name, ok: false };
 }
+function styleLintRoots(target) {
+  const sourceRoots = (0, import_node_fs2.readdirSync)((0, import_node_path2.join)(projectRoot, "src"), {
+    withFileTypes: true
+  }).filter(({ name }) => name !== "game-mechanics").map(({ name }) => (0, import_node_path2.join)("src", name));
+  return target === "react" && (0, import_node_fs2.existsSync)((0, import_node_path2.join)(projectRoot, "tests")) ? [...sourceRoots, "tests"] : sourceRoots;
+}
 async function runAllChecks(target) {
   const targetChecks = target === "react" ? [checkVitestConfig("react"), checkReactProductTestAlignment()] : [checkPhaser4Dependency(), checkPhaserViteConfig(), checkVitestConfig("phaser")];
-  const lintRoots = target === "react" && (0, import_node_fs2.existsSync)((0, import_node_path2.join)(projectRoot, "tests")) ? ["src", "tests"] : ["src"];
+  const lintRoots = styleLintRoots(target);
   const [tsgo, biome] = await Promise.all([
     run("tsgo", "@typescript/native-preview", "tsgo", ["-p", "tsconfig.json"]),
     run("biome", "@biomejs/biome", "biome", [

package/dist/cli/react-lint.js

@@ -311,9 +311,15 @@ function checkReactProductTestAlignment() {
   console.error(`[${name}] ${audit.issues[0]}`);
   return { name, ok: false };
 }
+function styleLintRoots(target) {
+  const sourceRoots = (0, import_node_fs2.readdirSync)((0, import_node_path2.join)(projectRoot, "src"), {
+    withFileTypes: true
+  }).filter(({ name }) => name !== "game-mechanics").map(({ name }) => (0, import_node_path2.join)("src", name));
+  return target === "react" && (0, import_node_fs2.existsSync)((0, import_node_path2.join)(projectRoot, "tests")) ? [...sourceRoots, "tests"] : sourceRoots;
+}
 async function runAllChecks(target) {
   const targetChecks = target === "react" ? [checkVitestConfig("react"), checkReactProductTestAlignment()] : [checkPhaser4Dependency(), checkPhaserViteConfig(), checkVitestConfig("phaser")];
-  const lintRoots = target === "react" && (0, import_node_fs2.existsSync)((0, import_node_path2.join)(projectRoot, "tests")) ? ["src", "tests"] : ["src"];
+  const lintRoots = styleLintRoots(target);
   const [tsgo, biome] = await Promise.all([
     run("tsgo", "@typescript/native-preview", "tsgo", ["-p", "tsconfig.json"]),
     run("biome", "@biomejs/biome", "biome", [

package/mechanics/game-mechanics-capabilities.json

@@ -2,22 +2,27 @@
   "$schema": "./game-mechanics-capabilities.schema.json",
   "schemaVersion": 1,
   "requiredPackages": [
+    "miaoda-game-action-runtime-core",
     "miaoda-game-arcade-motion-core",
     "miaoda-game-adventure-interaction-cocos",
     "miaoda-game-adventure-interaction-core",
     "miaoda-game-adventure-interaction-phaser",
     "miaoda-game-adventure-interaction-react",
     "miaoda-game-adventure-scenario-bridge-core",
+    "miaoda-game-belt-core",
+    "miaoda-game-brawler-core",
     "miaoda-game-command-cocos",
     "miaoda-game-command-core",
     "miaoda-game-command-phaser",
     "miaoda-game-command-react",
+    "miaoda-game-combat2d-core",
     "miaoda-game-contact2d-core",
     "miaoda-game-controls-phaser",
     "miaoda-game-expression-core",
     "miaoda-game-fighter-cocos",
     "miaoda-game-fighter-core",
     "miaoda-game-fixed-step-core",
+    "miaoda-game-frame-action-core",
     "miaoda-game-grid-core",
     "miaoda-game-investigation-core",
     "miaoda-game-kinematic2d-core",
@@ -120,6 +125,53 @@
     "miaoda-game-tractor-analysis-core"
   ],
   "packages": {
+    "miaoda-game-action-runtime-core": {
+      "engine": "neutral",
+      "domains": ["action", "combat", "orchestration"],
+      "owns": [
+        "action-request-buffering",
+        "action-cancel-policy",
+        "action-priority-arbitration",
+        "action-cooldowns",
+        "action-constraint-derivation"
+      ],
+      "doesNotOwn": [
+        "simulation-clock",
+        "movement-integration",
+        "hitbox-resolution",
+        "damage-rules",
+        "animation-playback"
+      ],
+      "compatibleWith": [
+        "miaoda-game-frame-action-core",
+        "miaoda-game-fixed-step-core",
+        "miaoda-game-combat2d-core"
+      ],
+      "useInsteadWhen": [
+        {
+          "package": "miaoda-game-frame-action-core",
+          "condition": "Only a deterministic integer-tick timeline is needed, without request buffering, cancellation policy, priorities, cooldowns, or movement constraints."
+        }
+      ],
+      "persistence": "snapshot",
+      "guidance": {
+        "useFor": [
+          "Use ActionRuntime for game-facing action requests that need buffering, explicit cancel windows, priority arbitration, cooldowns, or tag-derived movement constraints."
+        ],
+        "keepOutside": [
+          "Keep movement integration, hit acceptance, damage rules, animation playback, and the simulation clock outside this package."
+        ],
+        "rules": [
+          "Call request(id) at the logical-input boundary and tick() exactly once per fixed simulation tick.",
+          "Use FrameActionRunner directly instead when the action only needs a deterministic timeline."
+        ]
+      },
+      "testability": {
+        "observation": "snapshot-and-step-result",
+        "advance": "tick",
+        "methods": { "observe": "snapshot, tick() result", "advance": "tick()" }
+      }
+    },
     "miaoda-game-arcade-motion-core": {
       "engine": "neutral",
       "domains": ["input", "motion", "racing"],
@@ -134,6 +186,101 @@
         "methods": { "observe": "snapshot()", "advance": "update(dt, input, curve?)" }
       }
     },
+    "miaoda-game-belt-core": {
+      "engine": "neutral",
+      "domains": ["brawler", "motion", "spatial"],
+      "owns": [
+        "belt-spatial-model",
+        "belt-motion-integration",
+        "belt-jump-and-launch",
+        "belt-lane-queries",
+        "belt-screen-projection",
+        "belt-depth-sorting"
+      ],
+      "doesNotOwn": [
+        "simulation-clock",
+        "hitbox-resolution",
+        "attack-state",
+        "pathfinding",
+        "rendering"
+      ],
+      "compatibleWith": [
+        "miaoda-game-belt-phaser",
+        "miaoda-game-brawler-core",
+        "miaoda-game-combat2d-core",
+        "miaoda-game-fixed-step-core"
+      ],
+      "useInsteadWhen": [],
+      "persistence": "snapshot",
+      "guidance": {
+        "useFor": [
+          "Use BeltBody for the authoritative x/depth/height model, walking, jumping, launch and knockback arcs, lane queries, screen projection, and ground-depth sorting."
+        ],
+        "keepOutside": [
+          "Keep attack state, hit acceptance, AI and pathfinding, rendering, and fixed-tick scheduling outside this package."
+        ],
+        "rules": [
+          "Advance BeltBody.step(dtSeconds) from the single fixed simulation owner and render only from its committed snapshot and projection helpers.",
+          "Use belt lane queries as a depth pre-filter and combat2d as the hit-acceptance authority; do not implement a second hit resolver in BeltBody."
+        ]
+      },
+      "testability": {
+        "observation": "snapshot-and-step-result",
+        "advance": "step",
+        "methods": { "observe": "BeltBody.snapshot", "advance": "BeltBody.step(dtSeconds)" }
+      }
+    },
+    "miaoda-game-brawler-core": {
+      "engine": "neutral",
+      "domains": ["brawler", "combat", "orchestration"],
+      "owns": [
+        "brawler-combo-windows",
+        "brawler-hurt-and-knockdown",
+        "brawler-attack-token-pacing",
+        "brawler-crowd-role-coordination",
+        "brawler-grapple-relationships",
+        "brawler-hit-reaction-policy",
+        "brawler-juggle-budgets"
+      ],
+      "doesNotOwn": [
+        "simulation-clock",
+        "hitbox-resolution",
+        "hp-damage-application",
+        "movement-integration",
+        "pathfinding",
+        "rendering"
+      ],
+      "compatibleWith": [
+        "miaoda-game-frame-action-core",
+        "miaoda-game-fixed-step-core",
+        "miaoda-game-belt-core",
+        "miaoda-game-combat2d-core"
+      ],
+      "useInsteadWhen": [],
+      "persistence": "snapshot",
+      "guidance": {
+        "useFor": [
+          "Use this package for brawler combo windows, stagger and knockdown, shared enemy attack pacing, crowd roles and slots, grapples, hit reactions, and bounded juggling."
+        ],
+        "keepOutside": [
+          "Keep raw hitbox acceptance in combat2d, HP mutation in a stats owner, body integration in a movement owner, and rendering in the host."
+        ],
+        "rules": [
+          "Choose HurtState or HitReactionResolver for an actor profile; never apply both to the same hit.",
+          "BrawlerCrowdCoordinator attack eligibility is the single slot-level permit; do not combine it with an unrelated second attack-token authority.",
+          "GrappleCoordinator is the only holder/victim relationship authority; do not mirror writable isGrabbing or isGrabbed flags on actors.",
+          "Advance all selected brawler components from one fixed simulation owner, never from animation completion callbacks."
+        ]
+      },
+      "testability": {
+        "observation": "snapshot-and-step-result",
+        "advance": "tick",
+        "methods": {
+          "observe": "component snapshot properties and BrawlerCrowdCoordinator.inspect()",
+          "advance": "tick(), update(input), resolve(context), or advance(session, definition) on the selected component"
+        }
+      }
+    },
     "miaoda-game-adventure-interaction-cocos": {
       "engine": "cocos",
       "domains": ["adventure", "narrative"],
@@ -288,6 +435,56 @@
       ],
       "persistence": "delegated"
     },
+    "miaoda-game-combat2d-core": {
+      "engine": "neutral",
+      "domains": ["collision", "combat", "simulation"],
+      "owns": [
+        "combat-hit-acceptance",
+        "combat-team-mask-filtering",
+        "combat-attack-hit-deduplication",
+        "combat-invincibility-frames",
+        "combat-pierce-limits",
+        "combat-aabb-circle-overlap"
+      ],
+      "doesNotOwn": [
+        "simulation-clock",
+        "attack-timelines",
+        "damage-formulas",
+        "hit-reaction-policy",
+        "movement-integration",
+        "rendering"
+      ],
+      "compatibleWith": [
+        "miaoda-game-combat2d-cocos",
+        "miaoda-game-combat2d-phaser",
+        "miaoda-game-frame-action-core",
+        "miaoda-game-fixed-step-core",
+        "miaoda-game-belt-core",
+        "miaoda-game-brawler-core"
+      ],
+      "useInsteadWhen": [],
+      "persistence": "snapshot",
+      "guidance": {
+        "useFor": [
+          "Use CombatField to turn geometry overlaps or engine contacts into accepted combat hits with team masks, once-per-attack deduplication, invincibility frames, and pierce limits."
+        ],
+        "keepOutside": [
+          "Keep attack timelines, damage formulas, semantic hit reactions, movement integration, rendering, and fixed-tick scheduling outside this package."
+        ],
+        "rules": [
+          "Update registered positions and resolve hits exactly once at the logical gameplay-tick boundary.",
+          "Route each accepted HitEvent once to the stats, reaction, movement, status, and presentation owners; do not duplicate combat acceptance in those systems."
+        ]
+      },
+      "testability": {
+        "observation": "snapshot-and-result",
+        "advance": "update",
+        "methods": {
+          "observe": "CombatField.snapshot and resolve()/resolveContacts() results",
+          "advance": "update(...) then resolve(defaultIframes), or resolveContacts(contacts, defaultIframes)"
+        }
+      }
+    },
     "miaoda-game-contact2d-core": {
       "engine": "neutral",
       "domains": ["collision", "geometry", "physics"],
@@ -359,12 +556,73 @@
       "compatibleWith": ["miaoda-game-controls-phaser"],
       "useInsteadWhen": [],
       "persistence": "none",
+      "guidance": {
+        "useFor": [
+          "Use FixedStepper as the single fixed gameplay-tick owner, LogicalInputBuffer between host-frame sampling and tick consumption, and InputTapeRecorder for deterministic logical-input replay."
+        ],
+        "keepOutside": [
+          "Keep game rules, physics ownership, rendering, wall-clock scheduling, and presentation interpolation outside the fixed-step package."
+        ],
+        "rules": [
+          "Sample hardware input once per host frame, consume logical input inside fixed callbacks, and advance each gameplay system exactly once per logical tick.",
+          "Use alpha only for presentation interpolation and never feed interpolated state back into gameplay.",
+          "Disable engine or adapter auto-step before manually driving the same simulation to prevent duplicate time authority."
+        ]
+      },
       "testability": {
         "observation": "snapshot-and-step-result",
         "advance": "step",
         "methods": { "observe": "snapshot", "advance": "step(count, callback)" }
       }
     },
+    "miaoda-game-frame-action-core": {
+      "engine": "neutral",
+      "domains": ["action", "orchestration", "simulation"],
+      "owns": [
+        "deterministic-action-timelines",
+        "action-step-entry-events",
+        "action-run-identity",
+        "action-timeline-snapshots"
+      ],
+      "doesNotOwn": [
+        "simulation-clock",
+        "input-buffering",
+        "action-cancel-policy",
+        "hitbox-resolution",
+        "damage-rules",
+        "animation-playback"
+      ],
+      "compatibleWith": [
+        "miaoda-game-action-runtime-core",
+        "miaoda-game-fixed-step-core",
+        "miaoda-game-combat2d-core",
+        "miaoda-game-brawler-core"
+      ],
+      "useInsteadWhen": [
+        {
+          "package": "miaoda-game-action-runtime-core",
+          "condition": "Game-facing action requests need buffering, explicit cancellation, priority arbitration, cooldowns, or movement constraints in addition to the timeline."
+        }
+      ],
+      "persistence": "snapshot",
+      "guidance": {
+        "useFor": [
+          "Use FrameActionRunner for deterministic integer-tick startup, active, recovery, pose, tag, payload, and entry-event timelines whose gameplay timing must not depend on animation playback."
+        ],
+        "keepOutside": [
+          "Keep input buffering, cancel and cooldown policy, hit acceptance, damage rules, animation playback, and the simulation clock outside this package."
+        ],
+        "rules": [
+          "Call tick() exactly once per fixed simulation tick and use sample.instanceId as the stable action-run identity when connecting timelines to combat or effects.",
+          "Use ActionRuntime on top when requests need buffering, cancellation, priorities, cooldowns, or movement constraints; do not rebuild those policies beside FrameActionRunner."
+        ]
+      },
+      "testability": {
+        "observation": "snapshot-and-step-result",
+        "advance": "tick",
+        "methods": { "observe": "snapshot, current, tick() result", "advance": "tick()" }
+      }
+    },
     "miaoda-game-grid-core": {
       "engine": "neutral",
       "domains": ["grid", "pathfinding", "search"],

package/mechanics/game-mechanics-capabilities.schema.json

@@ -49,6 +49,12 @@
       "uniqueItems": true,
       "items": { "$ref": "#/$defs/packageName" }
     },
+    "proseList": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
     "alternative": {
       "type": "object",
       "additionalProperties": false,
@@ -107,6 +113,26 @@
           "enum": ["none", "snapshot", "envelope", "delegated"],
           "description": "Persistence responsibility: none, package snapshot, versioned envelope, or delegated to another owner."
         },
+        "guidance": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["useFor", "keepOutside", "rules"],
+          "description": "Concise natural-language implementation contract copied into consumer AI context for packages whose token boundaries need composition guidance.",
+          "properties": {
+            "useFor": {
+              "$ref": "#/$defs/proseList",
+              "description": "Concrete situations and logic for which consumers should use this package."
+            },
+            "keepOutside": {
+              "$ref": "#/$defs/proseList",
+              "description": "Adjacent implementation that must stay in the game, engine, or another package."
+            },
+            "rules": {
+              "$ref": "#/$defs/proseList",
+              "description": "Composition, ordering, and single-authority rules that prevent plausible integration mistakes."
+            }
+          }
+        },
         "testability": {
           "type": "object",
           "additionalProperties": false,
@@ -126,7 +152,7 @@
               "description": "Smallest stable readback shape exposed by the package."
             },
             "advance": {
-              "enum": ["none", "command", "update", "step", "scheduler", "manual"],
+              "enum": ["none", "command", "update", "tick", "step", "scheduler", "manual"],
               "description": "How a consumer explicitly advances or samples the package."
             },
             "methods": {