@adatechnology/game-contracts 0.20.0 → 0.22.0

package/dist/index.global.js

@@ -21,13 +21,28 @@ var GameContracts = (() => {
   // src/index.ts
   var index_exports = {};
   __export(index_exports, {
+    BLOW_IDS: () => BLOW_IDS,
+    BODY_FOLEY_IDS: () => BODY_FOLEY_IDS,
+    BODY_SOUND_IDS: () => BODY_SOUND_IDS,
     DEFAULT_BLAST_SHOVE: () => DEFAULT_BLAST_SHOVE,
     DEFAULT_ENVIRONMENT: () => DEFAULT_ENVIRONMENT,
     DEFAULT_IGNITION_RULES: () => DEFAULT_IGNITION_RULES,
+    DEFAULT_SURFACE: () => DEFAULT_SURFACE,
+    DEFERRED_PRIORITY: () => DEFERRED_PRIORITY,
+    DEFERRED_QUEUE_ID: () => DEFERRED_QUEUE_ID,
+    FOOTSTEP_SOUND_IDS: () => FOOTSTEP_SOUND_IDS,
+    FRAME_PHASES: () => FRAME_PHASES,
+    GAIT_IDS: () => GAIT_IDS,
+    HEAVY_LANDING_SPEED: () => HEAVY_LANDING_SPEED,
     IMPACT_CONTRACT: () => IMPACT_CONTRACT,
     KIT_ORIGIN_KEY: () => KIT_ORIGIN_KEY,
+    LANDING_IDS: () => LANDING_IDS,
+    LAND_SOUND_IDS: () => LAND_SOUND_IDS,
+    MATERIAL_SURFACES: () => MATERIAL_SURFACES,
     MISSING_BITS: () => MISSING_BITS,
     STAGE_EVENT: () => STAGE_EVENT,
+    SURFACE_IDS: () => SURFACE_IDS,
+    SWING_LEAD_SECONDS: () => SWING_LEAD_SECONDS,
     TOOL_CLIP: () => TOOL_CLIP,
     TWIST_LIFT: () => TWIST_LIFT,
     applyPatches: () => applyPatches,
@@ -35,6 +50,7 @@ var GameContracts = (() => {
     checkAnimation: () => checkAnimation,
     checkBench: () => checkBench,
     checkCategorized: () => checkCategorized,
+    checkDeferredQueue: () => checkDeferredQueue,
     checkDestructible: () => checkDestructible,
     checkHit: () => checkHit,
     checkSpec: () => checkSpec,
@@ -45,11 +61,16 @@ var GameContracts = (() => {
     defineCategories: () => defineCategories,
     fillFactor: () => fillFactor,
     footprintBlocker: () => footprintBlocker,
+    footstepSoundId: () => footstepSoundId,
+    hitSoundId: () => hitSoundId,
     ignitionChance: () => ignitionChance,
+    isSurfaceId: () => isSurfaceId,
     kitOriginOf: () => kitOriginOf,
+    landSoundId: () => landSoundId,
     markKitOrigin: () => markKitOrigin,
     mergeById: () => mergeById,
     removeIds: () => removeIds,
+    resetWarnOnce: () => resetWarnOnce2,
     resolveEntry: () => resolveEntry,
     resolveIgnitionRules: () => resolveIgnitionRules,
     sampleClip: () => sampleClip,
@@ -59,10 +80,13 @@ var GameContracts = (() => {
     shotExtras: () => shotExtras,
     shotToHit: () => shotToHit,
     sparkTargetFactor: () => sparkTargetFactor,
+    surfaceOfMaterial: () => surfaceOfMaterial,
+    swingSoundId: () => swingSoundId,
     toolAnimationStep: () => toolAnimationStep,
     twistStroke: () => twistStroke,
     unmarkedDrawings: () => unmarkedDrawings,
-    useToHit: () => useToHit
+    useToHit: () => useToHit,
+    warnOnce: () => warnOnce
   });
 
   // src/blast-shove.ts
@@ -83,6 +107,30 @@ var GameContracts = (() => {
     return { speed, direction: [direction[0] / length, direction[1] / length, direction[2] / length], distance, falloff };
   }
 
+  // src/impact-cost.ts
+  var DEFAULT_COST_READS = 1e4;
+  var DEFAULT_COST_CEILING_MS = 50;
+  var DEFAULT_COST_ALLOCATION_BYTES = 1024 * 1024;
+  var heapUsedBytes = () => {
+    const nodeProcess = globalThis.process;
+    return nodeProcess?.memoryUsage?.().heapUsed;
+  };
+  var checkReadCost = ({ name, read, options, problems }) => {
+    const reads = options.reads ?? DEFAULT_COST_READS;
+    const ceilingMs = options.ceilingMs ?? DEFAULT_COST_CEILING_MS;
+    const allocationBytes = options.allocationBytes ?? DEFAULT_COST_ALLOCATION_BYTES;
+    if (read() !== read()) problems.push(`${name}() returns a new object on each read: cache it between changes (cost contract)`);
+    for (let i = 0; i < reads; i++) read();
+    const heapBefore = heapUsedBytes();
+    const started = performance.now();
+    for (let i = 0; i < reads; i++) read();
+    const elapsedMs = performance.now() - started;
+    const heapAfter = heapUsedBytes();
+    if (elapsedMs > ceilingMs) problems.push(`${name}() took ${elapsedMs.toFixed(1)} ms for ${reads} reads, over the ${ceilingMs} ms ceiling (cost contract)`);
+    if (heapBefore !== void 0 && heapAfter !== void 0 && heapAfter - heapBefore > allocationBytes)
+      problems.push(`${name}() grew the heap by ${heapAfter - heapBefore} bytes over ${reads} reads, over the ${allocationBytes} byte ceiling (cost contract)`);
+  };
+
   // src/impact.ts
   var IMPACT_CONTRACT = {
     ballistic: { required: ["type", "point", "direction", "energy", "caliber"], optional: ["space", "source"], note: "bullets and pellets: joules and diameter in millimetres" },
@@ -189,6 +237,15 @@ var GameContracts = (() => {
     } catch (e) {
       problems.push(`reset() threw: ${String(e)}`);
     }
+    if (options.cost) {
+      const cost = options.cost === true ? {} : options.cost;
+      try {
+        checkReadCost({ name: "state", read: () => impl.state(), options: cost, problems });
+        checkReadCost({ name: "describe", read: () => impl.describe(), options: cost, problems });
+      } catch (e) {
+        problems.push(`cost measurement threw: ${String(e)}`);
+      }
+    }
     return { ok: problems.length === 0, problems };
   };
 
@@ -664,6 +721,66 @@ var GameContracts = (() => {
     };
   };
 
+  // src/frame.ts
+  var FRAME_PHASES = ["input", "fixedSimulate", "lateSimulate", "present", "render", "idle"];
+  var DEFERRED_QUEUE_ID = {
+    DESTRUCTION_EVENTS: "destruction.events",
+    BREACH_PAINT: "floorplan.breach-paint",
+    AUDIO_VOICES: "audio.voices",
+    VEHICLE_CREASE: "vehicles.crease"
+  };
+  var DEFERRED_PRIORITY = {
+    [DEFERRED_QUEUE_ID.DESTRUCTION_EVENTS]: { priority: 300, phase: "present" },
+    [DEFERRED_QUEUE_ID.BREACH_PAINT]: { priority: 250, phase: "present" },
+    [DEFERRED_QUEUE_ID.AUDIO_VOICES]: { priority: 200, phase: "idle", reserveMs: 1 },
+    [DEFERRED_QUEUE_ID.VEHICLE_CREASE]: { priority: 100, phase: "idle" }
+  };
+  function checkDeferredQueue(queue, fill) {
+    const problems = [];
+    fill();
+    const waiting = queue.pending(1);
+    if (waiting < 2) problems.push(`fill() must leave at least 2 units waiting (pending is ${waiting})`);
+    if (queue.pending(1) !== waiting) problems.push("pending(frame) changed between two calls in the same frame");
+    const ran = queue.run(0, () => 1);
+    if (ran !== 1) problems.push(`run with a deadline already past must run exactly one unit (ran ${ran})`);
+    if (waiting >= 2 && queue.pending(2) !== waiting - 1) problems.push(`one unit ran but pending went from ${waiting} to ${queue.pending(2)}`);
+    try {
+      queue.attach?.();
+      queue.attach?.();
+      queue.detach?.();
+      queue.detach?.();
+    } catch (error) {
+      problems.push(`attach/detach must be idempotent: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    queue.flush();
+    if (queue.pending(3) !== 0) problems.push(`flush must leave nothing pending (pending is ${queue.pending(3)})`);
+    if (queue.run(0, () => 1) !== 0) problems.push("run on an empty queue must run no unit");
+    return { ok: problems.length === 0, problems };
+  }
+
+  // src/warn.ts
+  var WARNED_KEY = /* @__PURE__ */ Symbol.for("@adatechnology/game-contracts.warned");
+  var warnedKeys = () => {
+    const holder = globalThis;
+    return holder[WARNED_KEY] ?? (holder[WARNED_KEY] = /* @__PURE__ */ new Set());
+  };
+  var isProduction = () => {
+    try {
+      return process.env.NODE_ENV === "production";
+    } catch {
+      return false;
+    }
+  };
+  var isQuiet = () => globalThis.__GAME_KIT_QUIET__ === true;
+  var warnOnce = (key, message) => {
+    if (isQuiet() || isProduction()) return;
+    const seen = warnedKeys();
+    if (seen.has(key)) return;
+    seen.add(key);
+    console.warn(`[game-kit] ${message}`);
+  };
+  var resetWarnOnce = () => warnedKeys().clear();
+
   // src/registry.ts
   var UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
   var isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
@@ -686,10 +803,13 @@ var GameContracts = (() => {
     for (const [id, patch] of Object.entries(patches ?? {})) {
       const entry = entries.get(id);
       if (entry) entries.set(id, deepMerge(entry, patch));
+      else warnOnce(`registry.patch.${id}`, `patch for "${id}" ignored: no entry has that id`);
     }
   };
   var removeIds = (entries, ids) => {
-    for (const id of ids ?? []) entries.delete(id);
+    for (const id of ids ?? []) {
+      if (!entries.delete(id)) warnOnce(`registry.remove.${id}`, `remove of "${id}" ignored: no entry has that id`);
+    }
   };
 
   // src/bench.ts
@@ -928,6 +1048,112 @@ var GameContracts = (() => {
       return lx > fp.minX - radius && lx < fp.maxX + radius && lz > fp.minZ - radius && lz < fp.maxZ + radius;
     };
   }
+
+  // src/foley.ts
+  var SURFACE_IDS = ["concrete", "asphalt", "wood", "tile", "dirt", "grass", "gravel", "sand", "metal", "water", "glass", "carpet"];
+  var DEFAULT_SURFACE = "concrete";
+  var GAIT_IDS = ["walk", "run"];
+  var LANDING_IDS = ["light", "heavy"];
+  var HEAVY_LANDING_SPEED = 5.5;
+  var BLOW_IDS = ["punch", "kick", "shove", "blade", "blunt", "chop"];
+  var BODY_SOUND_IDS = [
+    "jump",
+    "cloth_rustle",
+    "body_fall",
+    "fall_damage",
+    "player_hurt",
+    "player_breath_run",
+    "player_death",
+    "bite",
+    "grab",
+    "punch_swing",
+    "punch_hit_body",
+    "punch_hit_face",
+    "punch_hit_object",
+    "kick_swing",
+    "kick_hit",
+    "kick_hit_object",
+    "shove_two_hands",
+    "knife_swing",
+    "knife_stab",
+    "knife_slash",
+    "knife_hit_object",
+    "blunt_swing",
+    "blunt_hit",
+    "blunt_hit_object",
+    "axe_swing",
+    "axe_chop",
+    "axe_hit_object"
+  ];
+  var footstepSoundId = (surface, gait) => `footstep_${surface}_${gait}`;
+  var landSoundId = (surface, fallSpeed) => `land_${surface}_${fallSpeed >= HEAVY_LANDING_SPEED ? "heavy" : "light"}`;
+  var FOOTSTEP_SOUND_IDS = SURFACE_IDS.flatMap((surface) => GAIT_IDS.map((gait) => footstepSoundId(surface, gait)));
+  var LAND_SOUND_IDS = SURFACE_IDS.flatMap((surface) => LANDING_IDS.map((landing) => `land_${surface}_${landing}`));
+  var BODY_FOLEY_IDS = [...FOOTSTEP_SOUND_IDS, ...LAND_SOUND_IDS, ...BODY_SOUND_IDS];
+  var SWING = {
+    punch: "punch_swing",
+    kick: "kick_swing",
+    // two hands pushed out do not whistle: the shove is one sound, at the contact
+    shove: null,
+    blade: "knife_swing",
+    blunt: "blunt_swing",
+    chop: "axe_swing"
+  };
+  var SWING_LEAD_SECONDS = { punch: 0.07, kick: 0.09, shove: 0, blade: 0.05, blunt: 0.1, chop: 0.11 };
+  var swingSoundId = (blow) => SWING[blow];
+  var HIT = {
+    punch: { body: "punch_hit_body", head: "punch_hit_face", object: "punch_hit_object" },
+    kick: { body: "kick_hit", head: "kick_hit", object: "kick_hit_object" },
+    shove: { body: "shove_two_hands", head: "shove_two_hands", object: "shove_two_hands" },
+    blade: { body: "knife_stab", head: "knife_stab", object: "knife_hit_object" },
+    blunt: { body: "blunt_hit", head: "blunt_hit", object: "blunt_hit_object" },
+    chop: { body: "axe_chop", head: "axe_chop", object: "axe_hit_object" }
+  };
+  var hitSoundId = (blow, target) => HIT[blow][target];
+  var MATERIAL_SURFACES = {
+    concrete: "concrete",
+    mortar: "concrete",
+    stone: "concrete",
+    brick: "concrete",
+    plaster: "concrete",
+    asphalt: "asphalt",
+    wood_soft: "wood",
+    wood_hard: "wood",
+    green_wood: "wood",
+    plywood: "wood",
+    mdf: "wood",
+    ceramic: "tile",
+    plastic: "tile",
+    soil: "dirt",
+    wax: "dirt",
+    flesh_fruit: "dirt",
+    turf: "grass",
+    foliage: "grass",
+    cactus: "grass",
+    gravel: "gravel",
+    sand: "sand",
+    steel: "metal",
+    cast_iron: "metal",
+    aluminium: "metal",
+    copper: "metal",
+    water: "water",
+    glass: "glass",
+    tempered_glass: "glass",
+    fabric: "carpet",
+    foam: "carpet",
+    leather: "carpet",
+    rubber: "carpet",
+    paper: "carpet"
+  };
+  var isSurfaceId = (value) => typeof value === "string" && SURFACE_IDS.includes(value);
+  function surfaceOfMaterial(material, table = MATERIAL_SURFACES, fallback = DEFAULT_SURFACE) {
+    if (material === void 0) return fallback;
+    if (isSurfaceId(material)) return material;
+    return table[material] ?? fallback;
+  }
+
+  // src/index.ts
+  var resetWarnOnce2 = resetWarnOnce;
   return __toCommonJS(index_exports);
 })();
 //# sourceMappingURL=index.global.js.map