@adatechnology/game-contracts 0.21.0 → 0.23.0

package/dist/index.js

@@ -16,6 +16,83 @@ function blastShove(blast, target, options = {}) {
   return { speed, direction: [direction[0] / length, direction[1] / length, direction[2] / length], distance, falloff };
 }
 
+// src/blast-knock.ts
+var KNOCK_DOWN_SPEED = 2.5;
+var KNOCKED_DOWN_ANGLE = 1.35;
+var LIE_SECONDS = 1.6;
+var STAND_UP_PER_SPEED = 0.25;
+var FALL_SECONDS = 0.25;
+var RISE_SECONDS = 0.6;
+var GROUND_FRICTION = 7;
+var GRAVITY = 9.81;
+var KNOCK_CHEST = 1.1;
+var CHEST = KNOCK_CHEST;
+var bodyMass = (height, build = 1) => 70 * (height / 1.75) ** 2 * build;
+function knockOf(blast, feet, mass, options) {
+  const hit = blastShove(blast, { position: [feet[0], feet[1] + CHEST, feet[2]], mass }, options);
+  if (!hit) return void 0;
+  const [dx, dy, dz] = hit.direction;
+  return { velocity: [dx * hit.speed, Math.max(0, dy * hit.speed), dz * hit.speed], airborne: dy > 0, lying: 0, lieLeft: 0, down: hit.speed >= KNOCK_DOWN_SPEED };
+}
+function stepKnock(knock, position, dt, groundAt, alive) {
+  const v = knock.velocity;
+  position.x += v[0] * dt;
+  position.z += v[2] * dt;
+  const ground = groundAt(position.x, position.z);
+  if (knock.airborne || position.y > ground + 1e-4) {
+    v[1] -= GRAVITY * dt;
+    position.y += v[1] * dt;
+    if (position.y <= ground) {
+      position.y = ground;
+      v[1] = 0;
+      knock.airborne = false;
+    }
+  } else position.y = ground;
+  const horizontal = Math.hypot(v[0], v[2]);
+  if (!knock.airborne && horizontal > 0) {
+    const slowed = Math.max(0, horizontal - GROUND_FRICTION * dt);
+    v[0] *= slowed / horizontal;
+    v[2] *= slowed / horizontal;
+  }
+  const moving = horizontal > 0.05 || knock.airborne;
+  if (knock.down) {
+    if (moving) knock.lying = Math.min(1, knock.lying + dt / FALL_SECONDS);
+    else {
+      knock.lying = 1;
+      if (alive) {
+        knock.lieLeft = knock.lieLeft > 0 ? knock.lieLeft : LIE_SECONDS + Math.hypot(v[0], v[2]) * STAND_UP_PER_SPEED;
+        knock.lieLeft -= dt;
+        if (knock.lieLeft <= 0) knock.down = false;
+      }
+    }
+  } else if (knock.lying > 0) knock.lying = Math.max(0, knock.lying - dt / RISE_SECONDS);
+  return !moving && !knock.down && knock.lying === 0;
+}
+
+// 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 +199,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 };
 };
 
@@ -526,6 +612,21 @@ var checkToolClips = (clips, partIds) => {
   }
   return { ok: problems.length === 0, problems };
 };
+var leadClipEvents = (clip) => {
+  const events = clip.events ?? [];
+  if (!events.some((event) => (event.lead ?? 0) > 0)) return clip;
+  let floor = 0;
+  const led = events.map((event) => {
+    const lead = Math.max(0, Math.min(event.t - floor, event.lead ?? 0));
+    const t = event.t - lead;
+    floor = Math.max(floor, t);
+    if (event.lead === void 0) return event;
+    const moved = { ...event, t, data: lead > 0 ? { ...event.data, lead } : { ...event.data } };
+    delete moved.lead;
+    return moved;
+  });
+  return { ...clip, events: led };
+};
 var createToolClipPlayer = (options) => {
   const { clips, rig, onEvent } = options;
   let instances = [];
@@ -568,7 +669,7 @@ var createToolClipPlayer = (options) => {
       }
       const found = find(step.clip, step.variant);
       if (!found) return;
-      const clip = step.duration && step.duration > 0 ? scaleClip(found.clip, step.duration) : found.clip;
+      const clip = leadClipEvents(step.duration && step.duration > 0 ? scaleClip(found.clip, step.duration) : found.clip);
       const interval = options.repeatInterval?.() ?? 0.1;
       instances = instances.filter((existing) => existing.name !== found.name || existing.delay > 0);
       for (let round = 0; round < (step.repeat ?? 1); round++) {
@@ -597,6 +698,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 +780,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,21 +1025,147 @@ 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,
+  KNOCKED_DOWN_ANGLE,
+  KNOCK_CHEST,
+  KNOCK_DOWN_SPEED,
+  LANDING_IDS,
+  LAND_SOUND_IDS,
+  MATERIAL_SURFACES,
   MISSING_BITS,
   STAGE_EVENT,
+  SURFACE_IDS,
+  SWING_LEAD_SECONDS,
   TOOL_CLIP,
   TWIST_LIFT,
   applyPatches,
   blastShove,
+  bodyMass,
   checkAnimation,
   checkBench,
   checkCategorized,
+  checkDeferredQueue,
   checkDestructible,
   checkHit,
   checkSpec,
@@ -886,11 +1176,18 @@ export {
   defineCategories,
   fillFactor,
   footprintBlocker,
+  footstepSoundId,
+  hitSoundId,
   ignitionChance,
+  isSurfaceId,
   kitOriginOf,
+  knockOf,
+  landSoundId,
+  leadClipEvents,
   markKitOrigin,
   mergeById,
   removeIds,
+  resetWarnOnce2 as resetWarnOnce,
   resolveEntry,
   resolveIgnitionRules,
   sampleClip,
@@ -900,9 +1197,13 @@ export {
   shotExtras,
   shotToHit,
   sparkTargetFactor,
+  stepKnock,
+  surfaceOfMaterial,
+  swingSoundId,
   toolAnimationStep,
   twistStroke,
   unmarkedDrawings,
-  useToHit
+  useToHit,
+  warnOnce
 };
 //# sourceMappingURL=index.js.map