miaoda-game-devkit 0.2.6 → 0.2.7

package/dist/{gameplay-audit-XBGq_jIV.d.mts → gameplay-audit-CusQfLYQ.d.mts}

@@ -18,7 +18,9 @@ interface HeadlessGameHost<TScene extends Phaser.Scene> {
     /** 推进完整 Phaser 帧并等待异步 update 或生命周期完成。 */
     stepFramesAsync(count?: number): Promise<void>;
     /** 在限定帧数内推进游戏，直到条件成立。 */
-    stepUntil(condition: () => boolean, maxFrames?: number): number;
+    stepUntil(condition: () => boolean, maxFrames?: number | {
+        maxFrames?: number;
+    }): number;
     /** 精确推进指定次数的 Arcade Physics 单步。 */
     stepPhysics(steps?: number): void;
     /** 记录由测试定义的可序列化玩法检查点。 */

package/dist/{gameplay-audit-XBGq_jIV.d.ts → gameplay-audit-CusQfLYQ.d.ts}

@@ -18,7 +18,9 @@ interface HeadlessGameHost<TScene extends Phaser.Scene> {
     /** 推进完整 Phaser 帧并等待异步 update 或生命周期完成。 */
     stepFramesAsync(count?: number): Promise<void>;
     /** 在限定帧数内推进游戏，直到条件成立。 */
-    stepUntil(condition: () => boolean, maxFrames?: number): number;
+    stepUntil(condition: () => boolean, maxFrames?: number | {
+        maxFrames?: number;
+    }): number;
     /** 精确推进指定次数的 Arcade Physics 单步。 */
     stepPhysics(steps?: number): void;
     /** 记录由测试定义的可序列化玩法检查点。 */

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-XBGq_jIV.mjs';
-export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-XBGq_jIV.mjs';
+import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CusQfLYQ.mjs';
+export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-CusQfLYQ.mjs';
 import * as Phaser from 'phaser';
 import { TestContext, TestOptions } from 'vitest';
 
@@ -23,6 +23,8 @@ interface GameplayTestOptions extends GameplayContractOptions {
 interface GameplayContractHandle<TScene extends Phaser.Scene> {
     /** 将当前 contract 绑定到实际创建的 HEADLESS host。 */
     attachHost(host: HeadlessGameHost<TScene>): void;
+    /** 记录一个由测试先断言、再声明的玩法检查点。 */
+    checkpoint(id: string): void;
     /** 立即验证证据；通常由 onTestFinished 自动执行。 */
     verify(): void;
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-XBGq_jIV.js';
-export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-XBGq_jIV.js';
+import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CusQfLYQ.js';
+export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-CusQfLYQ.js';
 import * as Phaser from 'phaser';
 import { TestContext, TestOptions } from 'vitest';
 
@@ -23,6 +23,8 @@ interface GameplayTestOptions extends GameplayContractOptions {
 interface GameplayContractHandle<TScene extends Phaser.Scene> {
     /** 将当前 contract 绑定到实际创建的 HEADLESS host。 */
     attachHost(host: HeadlessGameHost<TScene>): void;
+    /** 记录一个由测试先断言、再声明的玩法检查点。 */
+    checkpoint(id: string): void;
     /** 立即验证证据；通常由 onTestFinished 自动执行。 */
     verify(): void;
 }

package/dist/index.js

@@ -1021,7 +1021,8 @@ async function createHeadlessGame(scene, options = {}) {
       stepFrames(count);
       await settleRuntime();
     },
-    stepUntil(condition, maxFrames = 120) {
+    stepUntil(condition, maxFramesOrOptions = 120) {
+      const maxFrames = typeof maxFramesOrOptions === "number" ? maxFramesOrOptions : maxFramesOrOptions.maxFrames ?? 120;
       assertStepCount(maxFrames, "stepUntil maxFrames");
       throwRuntimeError();
       for (let frame = 0; frame <= maxFrames; frame += 1) {
@@ -1193,6 +1194,14 @@ function registerGameplayContract(context, options) {
       }
       host = currentHost;
     },
+    checkpoint(id) {
+      if (!host) {
+        throw new Error(
+          `Gameplay contract "${options.id}" must attach a HEADLESS host before recording a checkpoint.`
+        );
+      }
+      host.checkpoint(id);
+    },
     verify
   };
 }

package/dist/index.mjs

@@ -979,7 +979,8 @@ async function createHeadlessGame(scene, options = {}) {
       stepFrames(count);
       await settleRuntime();
     },
-    stepUntil(condition, maxFrames = 120) {
+    stepUntil(condition, maxFramesOrOptions = 120) {
+      const maxFrames = typeof maxFramesOrOptions === "number" ? maxFramesOrOptions : maxFramesOrOptions.maxFrames ?? 120;
       assertStepCount(maxFrames, "stepUntil maxFrames");
       throwRuntimeError();
       for (let frame = 0; frame <= maxFrames; frame += 1) {
@@ -1151,6 +1152,14 @@ function registerGameplayContract(context, options) {
       }
       host = currentHost;
     },
+    checkpoint(id) {
+      if (!host) {
+        throw new Error(
+          `Gameplay contract "${options.id}" must attach a HEADLESS host before recording a checkpoint.`
+        );
+      }
+      host.checkpoint(id);
+    },
     verify
   };
 }

package/dist/lint/gameplay-contract.contract.mjs

@@ -983,7 +983,8 @@ async function createHeadlessGame(scene, options = {}) {
       stepFrames(count);
       await settleRuntime();
     },
-    stepUntil(condition, maxFrames = 120) {
+    stepUntil(condition, maxFramesOrOptions = 120) {
+      const maxFrames = typeof maxFramesOrOptions === "number" ? maxFramesOrOptions : maxFramesOrOptions.maxFrames ?? 120;
       assertStepCount(maxFrames, "stepUntil maxFrames");
       throwRuntimeError();
       for (let frame = 0; frame <= maxFrames; frame += 1) {
@@ -1155,6 +1156,14 @@ function registerGameplayContract(context, options) {
       }
       host = currentHost;
     },
+    checkpoint(id) {
+      if (!host) {
+        throw new Error(
+          `Gameplay contract "${options.id}" must attach a HEADLESS host before recording a checkpoint.`
+        );
+      }
+      host.checkpoint(id);
+    },
     verify
   };
 }
@@ -1190,7 +1199,8 @@ describe("gameplay contract lifecycle integration", () => {
       id: "InputScene.hit",
       kind: "playthrough",
       requireInput: true,
-      requireFrameAdvance: true
+      requireFrameAdvance: true,
+      requireCheckpoint: "hit-recorded"
     });
     let host;
     try {
@@ -1199,12 +1209,14 @@ describe("gameplay contract lifecycle integration", () => {
       host.stepFrames();
       await host.input.mouse.click(40, 40);
       expect(host.scene.hits).toBe(1);
+      contract.checkpoint("hit-recorded");
       host.destroy();
       await callbacks[0]?.();
       expect(context.task.meta.gameplayContract).toMatchObject({
         id: "InputScene.hit",
         evidence: {
           clicks: 1,
+          checkpoints: ["hit-recorded"],
           frames: 1,
           mouseEvents: 3
         }

package/dist/lint/phaser-headless.contract.mjs

@@ -983,7 +983,8 @@ async function createHeadlessGame(scene, options = {}) {
       stepFrames(count);
       await settleRuntime();
     },
-    stepUntil(condition, maxFrames = 120) {
+    stepUntil(condition, maxFramesOrOptions = 120) {
+      const maxFrames = typeof maxFramesOrOptions === "number" ? maxFramesOrOptions : maxFramesOrOptions.maxFrames ?? 120;
       assertStepCount(maxFrames, "stepUntil maxFrames");
       throwRuntimeError();
       for (let frame = 0; frame <= maxFrames; frame += 1) {
@@ -1149,6 +1150,9 @@ describe("Phaser HEADLESS host", () => {
     expect(() => boundedHost.stepUntil(() => false, 1.5)).toThrow(
       "stepUntil maxFrames must be a non-negative safe integer"
     );
+    expect(() => boundedHost.stepUntil(() => false, { maxFrames: 0 })).toThrow(
+      "Condition was not met within 0 complete Phaser frames"
+    );
     expect(() => boundedHost.stepPhysics(-1)).toThrow(
       "stepPhysics steps must be a non-negative safe integer"
     );

package/dist/vitest-config.d.mts

@@ -1,5 +1,5 @@
 import { ViteUserConfig } from 'vitest/config';
-import { c as GameplayAuditOptions } from './gameplay-audit-XBGq_jIV.mjs';
+import { c as GameplayAuditOptions } from './gameplay-audit-CusQfLYQ.mjs';
 import 'phaser';
 
 interface GameVitestConfigOptions {

package/dist/vitest-config.d.ts

@@ -1,5 +1,5 @@
 import { ViteUserConfig } from 'vitest/config';
-import { c as GameplayAuditOptions } from './gameplay-audit-XBGq_jIV.js';
+import { c as GameplayAuditOptions } from './gameplay-audit-CusQfLYQ.js';
 import 'phaser';
 
 interface GameVitestConfigOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miaoda-game-devkit",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Shared lint and deterministic Phaser HEADLESS testing tools for Miaoda games",
   "license": "MIT",
   "main": "./dist/index.js",