@adatechnology/game-contracts 0.21.0 → 0.22.0

package/dist/index.js

@@ -16,6 +16,30 @@ function blastShove(blast, target, options = {}) {
   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" },
@@ -122,6 +146,15 @@ var checkDestructible = (impl, options = {}) => {
   } 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 };
 };
 
@@ -597,6 +630,66 @@ var createToolClipPlayer = (options) => {
   };
 };
 
+// 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;
@@ -619,10 +712,13 @@ var applyPatches = (entries, patches) => {
   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
@@ -861,14 +957,135 @@ function footprintBlocker(object, footprint) {
     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;
 export {
+  BLOW_IDS,
+  BODY_FOLEY_IDS,
+  BODY_SOUND_IDS,
   DEFAULT_BLAST_SHOVE,
   DEFAULT_ENVIRONMENT,
   DEFAULT_IGNITION_RULES,
+  DEFAULT_SURFACE,
+  DEFERRED_PRIORITY,
+  DEFERRED_QUEUE_ID,
+  FOOTSTEP_SOUND_IDS,
+  FRAME_PHASES,
+  GAIT_IDS,
+  HEAVY_LANDING_SPEED,
   IMPACT_CONTRACT,
   KIT_ORIGIN_KEY,
+  LANDING_IDS,
+  LAND_SOUND_IDS,
+  MATERIAL_SURFACES,
   MISSING_BITS,
   STAGE_EVENT,
+  SURFACE_IDS,
+  SWING_LEAD_SECONDS,
   TOOL_CLIP,
   TWIST_LIFT,
   applyPatches,
@@ -876,6 +1093,7 @@ export {
   checkAnimation,
   checkBench,
   checkCategorized,
+  checkDeferredQueue,
   checkDestructible,
   checkHit,
   checkSpec,
@@ -886,11 +1104,16 @@ export {
   defineCategories,
   fillFactor,
   footprintBlocker,
+  footstepSoundId,
+  hitSoundId,
   ignitionChance,
+  isSurfaceId,
   kitOriginOf,
+  landSoundId,
   markKitOrigin,
   mergeById,
   removeIds,
+  resetWarnOnce2 as resetWarnOnce,
   resolveEntry,
   resolveIgnitionRules,
   sampleClip,
@@ -900,9 +1123,12 @@ export {
   shotExtras,
   shotToHit,
   sparkTargetFactor,
+  surfaceOfMaterial,
+  swingSoundId,
   toolAnimationStep,
   twistStroke,
   unmarkedDrawings,
-  useToHit
+  useToHit,
+  warnOnce
 };
 //# sourceMappingURL=index.js.map