@series-inc/rundot-kinetix 0.0.0-bootstrap.0

package/native/kinetix-installed-f64-runtime.cpp

@@ -0,0 +1,1085 @@
+// Deterministic-f64 component runtime: C++ transliteration of
+// component-reference-runtime-f64.mjs. Every phase, iteration order,
+// floating-point expression shape, and RNG draw mirrors the TS reference so
+// canonical per-tick hashes are bit-identical.
+//
+// Numeric contract: IEEE-754 doubles; +,-,*,/ and sqrt only from hardware;
+// every transcendental from rundot::detmath. JS Math.hypot maps to the shim's
+// variadic left-fold: det_hypot2(det_hypot2(0.0, x), y). Compile with
+// -ffp-contract=off.
+
+#include "kinetix-installed-f64-runtime.hpp"
+
+#include <array>
+#include <bit>
+#include <cmath>
+#include <cstdint>
+#include <cstring>
+#include <stdexcept>
+
+#include "component_runtime.hpp"
+#include "deterministic_math.hpp"
+
+namespace rundot::f64rt {
+namespace {
+
+constexpr double TWO_PI = 6.283185307179586;
+
+[[noreturn]] void fail(const std::string& message) {
+  throw std::runtime_error("component runtime f64: " + message);
+}
+
+double detHypot(double x, double y) {
+  return rundot::detmath::det_hypot2(rundot::detmath::det_hypot2(0.0, x), y);
+}
+
+enum class Kind : std::uint8_t {
+  Transform2D,
+  TwinStickInput,
+  AxisDriveMover,
+  HeadingFromVectors,
+  SpawnShield,
+  WanderMover,
+  SeekMover,
+  Telegraph,
+  ArenaBounds,
+  AutoFireWeapon,
+  LinearMover,
+  Lifetime,
+  Health,
+  Emitter,
+  CollisionCircle,
+  ScoreValue,
+  ResourceCounter,
+  DecayingMultiplier,
+  Count,
+};
+
+constexpr std::size_t kKindCount = static_cast<std::size_t>(Kind::Count);
+
+const char* const kKindNames[kKindCount] = {
+    "Transform2D",
+    "TwinStickInput",
+    "AxisDriveMover",
+    "HeadingFromVectors",
+    "SpawnShield",
+    "WanderMover",
+    "SeekMover",
+    "Telegraph",
+    "ArenaBounds",
+    "AutoFireWeapon",
+    "LinearMover",
+    "Lifetime",
+    "Health",
+    "Emitter",
+    "CollisionCircle",
+    "ScoreValue",
+    "ResourceCounter",
+    "DecayingMultiplier",
+};
+
+Kind kindFromType(const std::string& type) {
+  for (std::size_t index = 0; index < kKindCount; ++index) {
+    if (type == kKindNames[index]) return static_cast<Kind>(index);
+  }
+  fail("unknown component type " + type);
+}
+
+enum class BoundsMode : std::uint8_t { Clamp, Cull, ReflectNegate, ReflectAbs };
+
+struct Component {
+  Kind kind = Kind::Transform2D;
+  // Transform2D
+  Vec2 position{};
+  Vec2 velocity{};
+  double heading = 0.0;
+  // TwinStickInput
+  std::string moveField;
+  std::string aimField;
+  std::string fireField;
+  std::int64_t slot = 0;
+  Vec2 move{};
+  Vec2 aim{};
+  bool fire = false;
+  // AxisDriveMover
+  std::string axisField;
+  double maxSpeedPxPerSec = 0.0;
+  // SpawnShield (seconds + remaining); Telegraph reuses remaining
+  double seconds = 0.0;
+  double remaining = 0.0;
+  // WanderMover (Emitter reuses speedPx + rngStream)
+  double speedPx = 0.0;
+  double rerollSeconds = 0.0;
+  double sigmaRad = 0.0;
+  std::string rngStream;
+  double rerollTimer = 0.0;
+  // SeekMover
+  double baseSpeedPx = 0.0;
+  double topSpeedPx = 0.0;
+  double accelStartSec = 0.0;
+  double accelEndSec = 0.0;
+  double aliveSeconds = 0.0;
+  // ArenaBounds
+  BoundsMode mode = BoundsMode::Clamp;
+  bool useRadius = false;
+  // AutoFireWeapon
+  double fireIntervalSec = 0.0;
+  double speedPxPerSec = 0.0;
+  double spreadRad = 0.0;
+  std::string bulletTemplate;
+  double cooldown = 0.0;
+  std::uint64_t nextBulletId = 1;
+  // Lifetime
+  double maxSeconds = 0.0;
+  double age = 0.0;
+  // Health
+  std::int64_t hp = 0;
+  // Emitter
+  std::string trigger;
+  std::string emitTemplate;
+  std::int64_t count = 0;
+  double extraOffsetPx = 0.0;
+  std::string pattern;
+  // CollisionCircle
+  double radius = 0.0;
+  std::string layer;
+  // ScoreValue
+  std::int64_t basePoints = 0;
+  // ResourceCounter
+  std::int64_t score = 0;
+  std::int64_t deaths = 0;
+  // DecayingMultiplier
+  double increment = 0.0;
+  double cap = 0.0;
+  double decayWindow = 0.0;
+  double value = 1.0;
+};
+
+const PropertyValue& prop(const ComponentDef& def, const char* name) {
+  const auto found = def.properties.find(name);
+  if (found == def.properties.end()) fail("missing property " + std::string(name) + " on " + def.type);
+  return found->second;
+}
+
+double propF64(const ComponentDef& def, const char* name) {
+  const PropertyValue& value = prop(def, name);
+  if (value.kind != PropertyValue::Kind::F64) fail("property " + std::string(name) + " on " + def.type + " is not f64");
+  return value.f64;
+}
+
+Vec2 propVec2(const ComponentDef& def, const char* name) {
+  const PropertyValue& value = prop(def, name);
+  if (value.kind != PropertyValue::Kind::Vec2) fail("property " + std::string(name) + " on " + def.type + " is not vec2");
+  return value.vec2;
+}
+
+const std::string& propStr(const ComponentDef& def, const char* name) {
+  const PropertyValue& value = prop(def, name);
+  if (value.kind != PropertyValue::Kind::String) fail("property " + std::string(name) + " on " + def.type + " is not string");
+  return value.str;
+}
+
+std::int64_t propInt(const ComponentDef& def, const char* name) {
+  const PropertyValue& value = prop(def, name);
+  if (value.kind != PropertyValue::Kind::Int) fail("property " + std::string(name) + " on " + def.type + " is not int");
+  return value.i64;
+}
+
+bool propBool(const ComponentDef& def, const char* name) {
+  const PropertyValue& value = prop(def, name);
+  if (value.kind != PropertyValue::Kind::Bool) fail("property " + std::string(name) + " on " + def.type + " is not bool");
+  return value.boolean;
+}
+
+BoundsMode boundsModeFromString(const std::string& mode) {
+  if (mode == "clamp") return BoundsMode::Clamp;
+  if (mode == "cull") return BoundsMode::Cull;
+  if (mode == "reflect-negate") return BoundsMode::ReflectNegate;
+  if (mode == "reflect-abs") return BoundsMode::ReflectAbs;
+  fail("unknown bounds mode " + mode);
+}
+
+Component instantiateComponent(const ComponentDef& def) {
+  Component component;
+  component.kind = kindFromType(def.type);
+  switch (component.kind) {
+    case Kind::Transform2D:
+      component.position = propVec2(def, "position");
+      component.velocity = propVec2(def, "velocity");
+      component.heading = propF64(def, "heading");
+      break;
+    case Kind::TwinStickInput:
+      component.moveField = propStr(def, "moveField");
+      component.aimField = propStr(def, "aimField");
+      component.fireField = propStr(def, "fireField");
+      component.slot = propInt(def, "slot");
+      break;
+    case Kind::AxisDriveMover:
+      component.axisField = propStr(def, "axisField");
+      component.maxSpeedPxPerSec = propF64(def, "maxSpeedPxPerSec");
+      break;
+    case Kind::HeadingFromVectors:
+      component.aimField = propStr(def, "aimField");
+      component.moveField = propStr(def, "moveField");
+      break;
+    case Kind::SpawnShield:
+      component.seconds = propF64(def, "seconds");
+      component.remaining = component.seconds;
+      break;
+    case Kind::WanderMover:
+      component.speedPx = propF64(def, "speedPx");
+      component.rerollSeconds = propF64(def, "rerollSeconds");
+      component.sigmaRad = propF64(def, "sigmaRad");
+      component.rngStream = propStr(def, "rngStream");
+      component.rerollTimer = component.rerollSeconds;
+      break;
+    case Kind::SeekMover:
+      component.baseSpeedPx = propF64(def, "baseSpeedPx");
+      component.topSpeedPx = propF64(def, "topSpeedPx");
+      component.accelStartSec = propF64(def, "accelStartSec");
+      component.accelEndSec = propF64(def, "accelEndSec");
+      break;
+    case Kind::Telegraph:
+      component.remaining = propF64(def, "seconds");
+      break;
+    case Kind::ArenaBounds:
+      component.mode = boundsModeFromString(propStr(def, "mode"));
+      component.useRadius = propBool(def, "useRadius");
+      break;
+    case Kind::AutoFireWeapon:
+      component.fireIntervalSec = propF64(def, "fireIntervalSec");
+      component.speedPxPerSec = propF64(def, "speedPxPerSec");
+      component.spreadRad = propF64(def, "spreadRad");
+      component.bulletTemplate = propStr(def, "bulletTemplate");
+      component.aimField = propStr(def, "aimField");
+      component.fireField = propStr(def, "fireField");
+      component.slot = propInt(def, "slot");
+      break;
+    case Kind::LinearMover:
+      break;
+    case Kind::Lifetime:
+      component.maxSeconds = propF64(def, "maxSeconds");
+      break;
+    case Kind::Health:
+      component.hp = propInt(def, "hp");
+      break;
+    case Kind::Emitter:
+      component.trigger = propStr(def, "trigger");
+      component.emitTemplate = propStr(def, "template");
+      component.count = propInt(def, "count");
+      component.speedPx = propF64(def, "speedPx");
+      component.extraOffsetPx = propF64(def, "extraOffsetPx");
+      component.pattern = propStr(def, "pattern");
+      component.rngStream = propStr(def, "rngStream");
+      break;
+    case Kind::CollisionCircle:
+      component.radius = propF64(def, "radius");
+      component.layer = propStr(def, "layer");
+      break;
+    case Kind::ScoreValue:
+      component.basePoints = propInt(def, "basePoints");
+      break;
+    case Kind::ResourceCounter:
+      component.score = propInt(def, "score");
+      component.deaths = 0;
+      break;
+    case Kind::DecayingMultiplier:
+      component.increment = propF64(def, "increment");
+      component.cap = propF64(def, "cap");
+      component.decayWindow = propF64(def, "decayWindow");
+      break;
+    default:
+      fail("unhandled component kind");
+  }
+  return component;
+}
+
+struct Entity {
+  std::string ref;
+  std::uint64_t spawnId = 0;
+  std::vector<Component> components;
+  std::array<int, kKindCount> byKind{};
+  std::map<std::string, Vec2> vecFields;
+  std::map<std::string, bool> boolFields;
+  bool alive = true;
+  bool hasSpawnPosition = false;
+  Vec2 spawnPosition{};
+};
+
+Component* findComponent(Entity& entity, Kind kind) {
+  const int index = entity.byKind[static_cast<std::size_t>(kind)];
+  return index < 0 ? nullptr : &entity.components[static_cast<std::size_t>(index)];
+}
+
+Entity makeEntity(const std::string& ref, std::uint64_t spawnId, const std::vector<ComponentDef>& defs) {
+  Entity entity;
+  entity.ref = ref;
+  entity.spawnId = spawnId;
+  entity.byKind.fill(-1);
+  entity.components.reserve(defs.size());
+  for (const ComponentDef& def : defs) {
+    Component component = instantiateComponent(def);
+    const std::size_t kindIndex = static_cast<std::size_t>(component.kind);
+    if (entity.byKind[kindIndex] >= 0) fail("duplicate component " + def.type + " on " + ref);
+    entity.byKind[kindIndex] = static_cast<int>(entity.components.size());
+    entity.components.push_back(std::move(component));
+  }
+  if (Component* transform = findComponent(entity, Kind::Transform2D)) {
+    entity.hasSpawnPosition = true;
+    entity.spawnPosition = transform->position;
+  }
+  return entity;
+}
+
+struct RngStreamRt {
+  std::string id;
+  std::uint32_t state = 0;
+};
+
+struct TemplateRt {
+  std::string id;
+  std::int64_t pool = 0;
+  Entity proto;
+  std::int64_t liveCount = 0;
+};
+
+struct Runtime {
+  const PackDef* pack = nullptr;
+  double dt = 1.0 / 60.0;
+  double width = 1280.0;
+  double height = 720.0;
+  std::int64_t tick = 0;
+  std::vector<RngStreamRt> rngStreams;
+  std::map<std::string, std::size_t> rngIndex;
+  std::vector<Entity> statics;
+  std::vector<Entity> pooled;
+  std::uint64_t nextSpawnId = 1;
+  std::vector<TemplateRt> templates;
+  std::map<std::string, std::size_t> templateIndex;
+  std::int64_t spawnsThisTick = 0;
+  std::size_t pooledCapacity = 0;
+  // Render-facing event log for the current tick (mirrors JS
+  // runtime.frameEvents). Not part of canonical state or hashing.
+  std::vector<FrameEventDef> frameEvents;
+};
+
+Entity& entityAt(Runtime& runtime, int handle) {
+  const int staticCount = static_cast<int>(runtime.statics.size());
+  return handle < staticCount ? runtime.statics[static_cast<std::size_t>(handle)]
+                              : runtime.pooled[static_cast<std::size_t>(handle - staticCount)];
+}
+
+Runtime createRuntime(const PackDef& pack) {
+  Runtime runtime;
+  runtime.pack = &pack;
+  for (const RngStreamDef& stream : pack.rngStreams) {
+    runtime.rngIndex[stream.id] = runtime.rngStreams.size();
+    runtime.rngStreams.push_back({stream.id, stream.seed});
+  }
+  for (const EntityDef& entity : pack.entities) {
+    runtime.statics.push_back(makeEntity(entity.id, 0, entity.components));
+  }
+  for (const TemplateDef& templateDef : pack.templates) {
+    runtime.templateIndex[templateDef.id] = runtime.templates.size();
+    runtime.templates.push_back({templateDef.id, templateDef.pool, makeEntity(templateDef.id, 0, templateDef.components), 0});
+  }
+  // Alive pooled entities are bounded by the summed template pools; dead ones
+  // linger only until the end-of-tick filter, so per-tick growth is bounded by
+  // maxSpawnsPerTick. Reserving the worst case keeps element pointers stable
+  // across mid-tick spawns.
+  std::size_t totalPool = 0;
+  for (const TemplateDef& templateDef : pack.templates) totalPool += static_cast<std::size_t>(templateDef.pool);
+  runtime.pooledCapacity = totalPool + static_cast<std::size_t>(pack.maxSpawnsPerTick);
+  runtime.pooled.reserve(runtime.pooledCapacity);
+  return runtime;
+}
+
+// liveEntities() in the reference includes ALL static entities (even dead
+// ones) plus alive pooled entities; only hashing filters statics by alive.
+std::vector<int> liveEntities(const Runtime& runtime) {
+  std::vector<int> handles;
+  handles.reserve(runtime.statics.size() + runtime.pooled.size());
+  const int staticCount = static_cast<int>(runtime.statics.size());
+  for (int index = 0; index < staticCount; ++index) handles.push_back(index);
+  for (std::size_t index = 0; index < runtime.pooled.size(); ++index) {
+    if (runtime.pooled[index].alive) handles.push_back(staticCount + static_cast<int>(index));
+  }
+  return handles;
+}
+
+std::uint32_t mulberry32Next(std::uint32_t& state) {
+  state = state + 0x6d2b79f5u;
+  std::uint32_t t = state;
+  t = static_cast<std::uint32_t>(static_cast<std::uint64_t>(t ^ (t >> 15)) * (t | 1u));
+  t = t ^ (t + static_cast<std::uint32_t>(static_cast<std::uint64_t>(t ^ (t >> 7)) * (t | 61u)));
+  return t ^ (t >> 14);
+}
+
+double rngFloat(Runtime& runtime, const std::string& streamId) {
+  const auto found = runtime.rngIndex.find(streamId);
+  if (found == runtime.rngIndex.end()) fail("unknown rng stream " + streamId);
+  RngStreamRt& stream = runtime.rngStreams[found->second];
+  const std::uint32_t value = mulberry32Next(stream.state);
+  return static_cast<double>(value) / 4294967296.0;
+}
+
+double gaussian(Runtime& runtime, const std::string& streamId) {
+  const double raw = rngFloat(runtime, streamId);
+  const double u1 = raw > 1e-9 ? raw : 1e-9;  // Math.max(raw, 1e-9); raw is never NaN
+  const double u2 = rngFloat(runtime, streamId);
+  return std::sqrt(-2.0 * rundot::detmath::det_log(u1)) * rundot::detmath::det_cos(TWO_PI * u2);
+}
+
+int spawnFromTemplate(Runtime& runtime, const std::string& templateId) {
+  const auto found = runtime.templateIndex.find(templateId);
+  if (found == runtime.templateIndex.end()) fail("unknown template " + templateId);
+  TemplateRt& templateRt = runtime.templates[found->second];
+  if (templateRt.liveCount >= templateRt.pool) return -1;
+  if (runtime.spawnsThisTick >= runtime.pack->maxSpawnsPerTick) return -1;
+  Entity entity = templateRt.proto;
+  entity.spawnId = runtime.nextSpawnId;
+  runtime.nextSpawnId += 1;
+  runtime.spawnsThisTick += 1;
+  templateRt.liveCount += 1;
+  runtime.pooled.push_back(std::move(entity));
+  return static_cast<int>(runtime.statics.size()) + static_cast<int>(runtime.pooled.size()) - 1;
+}
+
+void despawn(Runtime& runtime, Entity& entity) {
+  if (!entity.alive) return;
+  entity.alive = false;
+  const auto found = runtime.templateIndex.find(entity.ref);
+  if (found == runtime.templateIndex.end()) fail("despawn of non-pooled entity " + entity.ref);
+  runtime.templates[found->second].liveCount -= 1;
+}
+
+bool shipIsShielded(Entity& entity) {
+  Component* shield = findComponent(entity, Kind::SpawnShield);
+  return shield != nullptr && shield->remaining > 0;
+}
+
+bool entityTelegraphing(Entity& entity) {
+  Component* telegraph = findComponent(entity, Kind::Telegraph);
+  return telegraph != nullptr && telegraph->remaining > 0;
+}
+
+bool nearestShipPosition(Runtime& runtime, const Vec2& from, Vec2& out) {
+  bool found = false;
+  double bestDistSq = 0.0;
+  for (Entity& entity : runtime.statics) {
+    if (findComponent(entity, Kind::AxisDriveMover) == nullptr) continue;
+    Component* transform = findComponent(entity, Kind::Transform2D);
+    const double dx = transform->position.x - from.x;
+    const double dy = transform->position.y - from.y;
+    const double distSq = dx * dx + dy * dy;
+    if (!found || distSq < bestDistSq) {
+      found = true;
+      bestDistSq = distSq;
+      out = transform->position;
+    }
+  }
+  return found;
+}
+
+void applyBounds(Runtime& runtime, Entity& entity, Component& bounds) {
+  Component* transform = findComponent(entity, Kind::Transform2D);
+  Component* collision = findComponent(entity, Kind::CollisionCircle);
+  const double radius = bounds.useRadius && collision != nullptr ? collision->radius : 0.0;
+  Vec2& position = transform->position;
+  Vec2& velocity = transform->velocity;
+  if (bounds.mode == BoundsMode::Clamp) {
+    if (position.x < radius) position.x = radius;
+    if (position.y < radius) position.y = radius;
+    if (position.x > runtime.width - radius) position.x = runtime.width - radius;
+    if (position.y > runtime.height - radius) position.y = runtime.height - radius;
+    return;
+  }
+  if (bounds.mode == BoundsMode::Cull) {
+    if (position.x < 0 || position.x > runtime.width || position.y < 0 || position.y > runtime.height) {
+      despawn(runtime, entity);
+    }
+    return;
+  }
+  if (bounds.mode == BoundsMode::ReflectNegate) {
+    if (position.x < radius) { position.x = radius; velocity.x = -velocity.x; }
+    if (position.y < radius) { position.y = radius; velocity.y = -velocity.y; }
+    if (position.x > runtime.width - radius) { position.x = runtime.width - radius; velocity.x = -velocity.x; }
+    if (position.y > runtime.height - radius) { position.y = runtime.height - radius; velocity.y = -velocity.y; }
+    return;
+  }
+  // reflect-abs
+  if (position.x < radius) { position.x = radius; velocity.x = std::fabs(velocity.x); }
+  if (position.y < radius) { position.y = radius; velocity.y = std::fabs(velocity.y); }
+  if (position.x > runtime.width - radius) { position.x = runtime.width - radius; velocity.x = -std::fabs(velocity.x); }
+  if (position.y > runtime.height - radius) { position.y = runtime.height - radius; velocity.y = -std::fabs(velocity.y); }
+}
+
+// Installed projectile-family deterministic spread.
+double spreadForBullet(double id, double spreadRad) {
+  const double seeded = rundot::detmath::det_sin(id * 12.9898 + 78.233) * 43758.5453;
+  const double unit = seeded - std::floor(seeded);
+  return (unit * 2 - 1) * spreadRad;
+}
+
+bool circleHit(const Vec2& a, double ra, const Vec2& b, double rb) {
+  const double dx = a.x - b.x;
+  const double dy = a.y - b.y;
+  const double r = ra + rb;
+  return dx * dx + dy * dy <= r * r;
+}
+
+struct DeathEvent {
+  bool enemyKilled = false;  // false = ship-death
+  int handle = -1;
+};
+
+Vec2 getVecField(Entity& entity, const std::string& name) {
+  const auto found = entity.vecFields.find(name);
+  return found == entity.vecFields.end() ? Vec2{} : found->second;
+}
+
+bool getBoolField(Entity& entity, const std::string& name) {
+  const auto found = entity.boolFields.find(name);
+  return found != entity.boolFields.end() && found->second;
+}
+
+void runCollisionPass(Runtime& runtime, const std::vector<int>& live, const char* action, std::vector<DeathEvent>& events) {
+  for (const CollisionRuleDef& rule : runtime.pack->collisionRules) {
+    if (rule.action != action) continue;
+    std::vector<int> groupA;
+    std::vector<int> groupB;
+    for (const int handle : live) {
+      Entity& entity = entityAt(runtime, handle);
+      if (!entity.alive) continue;
+      Component* circle = findComponent(entity, Kind::CollisionCircle);
+      if (circle == nullptr) continue;
+      if (circle->layer == rule.layerA) groupA.push_back(handle);
+      if (circle->layer == rule.layerB) groupB.push_back(handle);
+    }
+    if (rule.action == "bullet-kill") {
+      for (const int bulletHandle : groupA) {
+        Entity& bullet = entityAt(runtime, bulletHandle);
+        if (!bullet.alive) continue;
+        Component* bulletCircle = findComponent(bullet, Kind::CollisionCircle);
+        Component* bulletTransform = findComponent(bullet, Kind::Transform2D);
+        for (const int enemyHandle : groupB) {
+          Entity& enemy = entityAt(runtime, enemyHandle);
+          if (!enemy.alive || entityTelegraphing(enemy)) continue;
+          Component* enemyCircle = findComponent(enemy, Kind::CollisionCircle);
+          Component* enemyTransform = findComponent(enemy, Kind::Transform2D);
+          if (!circleHit(bulletTransform->position, bulletCircle->radius, enemyTransform->position, enemyCircle->radius)) continue;
+          Component* health = findComponent(enemy, Kind::Health);
+          health->hp -= 1;
+          despawn(runtime, bullet);
+          if (health->hp <= 0) {
+            events.push_back({true, enemyHandle});
+          }
+          break;
+        }
+      }
+    } else if (rule.action == "ship-death") {
+      for (const int shipHandle : groupA) {
+        Entity& ship = entityAt(runtime, shipHandle);
+        if (shipIsShielded(ship)) continue;
+        Component* shipCircle = findComponent(ship, Kind::CollisionCircle);
+        Component* shipTransform = findComponent(ship, Kind::Transform2D);
+        for (const int enemyHandle : groupB) {
+          Entity& enemy = entityAt(runtime, enemyHandle);
+          if (!enemy.alive || entityTelegraphing(enemy)) continue;
+          Component* enemyCircle = findComponent(enemy, Kind::CollisionCircle);
+          Component* enemyTransform = findComponent(enemy, Kind::Transform2D);
+          if (!circleHit(shipTransform->position, shipCircle->radius, enemyTransform->position, enemyCircle->radius)) continue;
+          events.push_back({false, shipHandle});
+          break;
+        }
+      }
+    }
+  }
+}
+
+void handleDeathEvents(Runtime& runtime, const std::vector<DeathEvent>& events) {
+  Entity* game = nullptr;
+  for (Entity& entity : runtime.statics) {
+    if (findComponent(entity, Kind::ResourceCounter) != nullptr) {
+      game = &entity;
+      break;
+    }
+  }
+  for (const DeathEvent& event : events) {
+    Entity& target = entityAt(runtime, event.handle);
+    {
+      // Mirrors the JS push at the TOP of handleDeathEvents' per-event loop:
+      // position read before any respawn/despawn mutation.
+      Component* transform = findComponent(target, Kind::Transform2D);
+      runtime.frameEvents.push_back({event.enemyKilled ? "enemy-killed" : "ship-death", target.ref,
+                                     transform->position.x, transform->position.y});
+    }
+    if (event.enemyKilled) {
+      Component* emitter = findComponent(target, Kind::Emitter);
+      if (emitter != nullptr && emitter->trigger == "on-death") {
+        Component* transform = findComponent(target, Kind::Transform2D);
+        Component* circle = findComponent(target, Kind::CollisionCircle);
+        const double speed = detHypot(transform->velocity.x, transform->velocity.y);
+        const double baseAngle = speed > 1
+            ? rundot::detmath::det_atan2(transform->velocity.y, transform->velocity.x)
+            : rngFloat(runtime, emitter->rngStream) * TWO_PI;
+        const double phase = rngFloat(runtime, emitter->rngStream) * TWO_PI;
+        const auto templateFound = runtime.templateIndex.find(emitter->emitTemplate);
+        if (templateFound == runtime.templateIndex.end()) fail("unknown emitter template " + emitter->emitTemplate);
+        Entity& templateProto = runtime.templates[templateFound->second].proto;
+        Component* templateCircle = findComponent(templateProto, Kind::CollisionCircle);
+        const double childRadius = templateCircle != nullptr ? templateCircle->radius : 0.0;
+        const double spawnOffset = circle->radius + childRadius + emitter->extraOffsetPx;
+        // Snapshot spawn state used inside the loop: pooled growth may
+        // reallocate and invalidate transform/emitter pointers.
+        const Vec2 origin = transform->position;
+        const double emitSpeed = emitter->speedPx;
+        const std::string emitTemplate = emitter->emitTemplate;
+        const std::int64_t emitCount = emitter->count;
+        for (std::int64_t index = 0; index < emitCount; index += 1) {
+          const double angle = baseAngle + phase + (static_cast<double>(index) / static_cast<double>(emitCount)) * TWO_PI;
+          const double cos = rundot::detmath::det_cos(angle);
+          const double sin = rundot::detmath::det_sin(angle);
+          const int childHandle = spawnFromTemplate(runtime, emitTemplate);
+          if (childHandle >= 0) {
+            Entity& child = entityAt(runtime, childHandle);
+            Component* childTransform = findComponent(child, Kind::Transform2D);
+            childTransform->position.x = origin.x + cos * spawnOffset;
+            childTransform->position.y = origin.y + sin * spawnOffset;
+            childTransform->velocity.x = cos * emitSpeed;
+            childTransform->velocity.y = sin * emitSpeed;
+            // JS pushes 'spawned' inside spawnFromTemplate after setup ran;
+            // here setup is inlined at the call site, so push after it.
+            runtime.frameEvents.push_back({"spawned", emitTemplate, childTransform->position.x, childTransform->position.y});
+          }
+        }
+      }
+      Entity& entity = entityAt(runtime, event.handle);
+      Component* scoreValue = findComponent(entity, Kind::ScoreValue);
+      if (scoreValue != nullptr && game != nullptr) {
+        findComponent(*game, Kind::ResourceCounter)->score += scoreValue->basePoints;
+      }
+      if (entity.spawnId == 0) {
+        entity.alive = false;
+      } else {
+        despawn(runtime, entity);
+      }
+    } else {
+      if (game != nullptr) findComponent(*game, Kind::ResourceCounter)->deaths += 1;
+      Entity& entity = entityAt(runtime, event.handle);
+      Component* transform = findComponent(entity, Kind::Transform2D);
+      transform->position.x = entity.spawnPosition.x;
+      transform->position.y = entity.spawnPosition.y;
+      transform->velocity.x = 0;
+      transform->velocity.y = 0;
+      Component* shield = findComponent(entity, Kind::SpawnShield);
+      if (shield != nullptr) shield->remaining = shield->seconds;
+    }
+  }
+}
+
+void tickRuntime(Runtime& runtime, const std::vector<SlotInputDef>& inputs) {
+  const double dt = runtime.dt;
+  runtime.spawnsThisTick = 0;
+  runtime.frameEvents.clear();
+  runtime.pooled.reserve(runtime.pooledCapacity);
+  const std::vector<int> live = liveEntities(runtime);
+
+  // 1. inputs
+  for (const int handle : live) {
+    Entity& entity = entityAt(runtime, handle);
+    Component* twinStick = findComponent(entity, Kind::TwinStickInput);
+    if (twinStick == nullptr) continue;
+    SlotInputDef slotInput;
+    if (twinStick->slot >= 0 && static_cast<std::size_t>(twinStick->slot) < inputs.size()) {
+      slotInput = inputs[static_cast<std::size_t>(twinStick->slot)];
+    }
+    twinStick->move = slotInput.movement;
+    twinStick->aim = slotInput.aim;
+    twinStick->fire = slotInput.fire;
+    entity.vecFields[twinStick->moveField] = twinStick->move;
+    entity.vecFields[twinStick->aimField] = twinStick->aim;
+    entity.boolFields[twinStick->fireField] = twinStick->fire;
+  }
+
+  // 2. shield + telegraph countdowns
+  for (const int handle : live) {
+    Entity& entity = entityAt(runtime, handle);
+    Component* shield = findComponent(entity, Kind::SpawnShield);
+    if (shield != nullptr && shield->remaining > 0) {
+      const double next = shield->remaining - dt;
+      shield->remaining = next > 0 ? next : 0;  // Math.max(0, next)
+    }
+    Component* telegraph = findComponent(entity, Kind::Telegraph);
+    if (telegraph != nullptr && telegraph->remaining > 0) {
+      const double next = telegraph->remaining - dt;
+      telegraph->remaining = next > 0 ? next : 0;
+    }
+  }
+
+  // 3. driven movement
+  for (const int handle : live) {
+    Entity& entity = entityAt(runtime, handle);
+    Component* drive = findComponent(entity, Kind::AxisDriveMover);
+    if (drive == nullptr) continue;
+    Component* transform = findComponent(entity, Kind::Transform2D);
+    const Vec2 movement = getVecField(entity, drive->axisField);
+    const double mag = detHypot(movement.x, movement.y);
+    if (mag > 0.0001) {
+      const double denom = mag > 1 ? mag : 1;  // Math.max(mag, 1)
+      const double nx = movement.x / denom;
+      const double ny = movement.y / denom;
+      transform->position.x += nx * drive->maxSpeedPxPerSec * dt;
+      transform->position.y += ny * drive->maxSpeedPxPerSec * dt;
+    }
+    Component* bounds = findComponent(entity, Kind::ArenaBounds);
+    if (bounds != nullptr) applyBounds(runtime, entity, *bounds);
+    Component* headingComponent = findComponent(entity, Kind::HeadingFromVectors);
+    if (headingComponent != nullptr) {
+      const Vec2 aim = getVecField(entity, headingComponent->aimField);
+      const double aimMag = detHypot(aim.x, aim.y);
+      if (aimMag > 0.0001) {
+        transform->heading = rundot::detmath::det_atan2(aim.y, aim.x);
+      } else if (mag > 0.0001) {
+        transform->heading = rundot::detmath::det_atan2(movement.y, movement.x);
+      }
+    }
+  }
+
+  // 4. auto-fire (BulletSwarm.autoFire transcription)
+  for (const int handle : live) {
+    Entity& entity = entityAt(runtime, handle);
+    Component* weapon = findComponent(entity, Kind::AutoFireWeapon);
+    if (weapon == nullptr) continue;
+    const bool fire = getBoolField(entity, weapon->fireField);
+    if (!fire) {
+      weapon->cooldown = 0;
+      continue;
+    }
+    const Vec2 aim = getVecField(entity, weapon->aimField);
+    const double aimMag = detHypot(aim.x, aim.y);
+    if (aimMag < 0.0001) continue;
+    Component* transform = findComponent(entity, Kind::Transform2D);
+    const Vec2 origin = transform->position;
+    double cooldown = weapon->cooldown - dt;
+    int fired = 0;
+    while (cooldown <= 0) {
+      cooldown += weapon->fireIntervalSec;
+      const double nx = aim.x / aimMag;
+      const double ny = aim.y / aimMag;
+      const std::uint64_t bulletId = weapon->nextBulletId;
+      const double spread = spreadForBullet(static_cast<double>(bulletId), weapon->spreadRad);
+      const double cos = rundot::detmath::det_cos(spread);
+      const double sin = rundot::detmath::det_sin(spread);
+      const double sx = nx * cos - ny * sin;
+      const double sy = nx * sin + ny * cos;
+      const int bulletHandle = spawnFromTemplate(runtime, weapon->bulletTemplate);
+      if (bulletHandle < 0) break;  // pool cap: break WITHOUT incrementing nextBulletId
+      Entity& bullet = entityAt(runtime, bulletHandle);
+      Component* bulletTransform = findComponent(bullet, Kind::Transform2D);
+      bulletTransform->position.x = origin.x;
+      bulletTransform->position.y = origin.y;
+      bulletTransform->velocity.x = sx * weapon->speedPxPerSec;
+      bulletTransform->velocity.y = sy * weapon->speedPxPerSec;
+      bulletTransform->heading = rundot::detmath::det_atan2(sy, sx);
+      // JS pushes 'spawned' inside spawnFromTemplate after setup ran; here
+      // setup is inlined at the call site, so push after it.
+      runtime.frameEvents.push_back({"spawned", weapon->bulletTemplate, bulletTransform->position.x, bulletTransform->position.y});
+      weapon->nextBulletId += 1;
+      fired += 1;
+      if (fired > 100) break;
+    }
+    weapon->cooldown = cooldown;
+  }
+
+  // refresh live to include this tick's spawns for integration
+  const std::vector<int> liveAfterFire = liveEntities(runtime);
+
+  // 5. linear movers integrate + bounds
+  for (const int handle : liveAfterFire) {
+    Entity& entity = entityAt(runtime, handle);
+    if (!entity.alive || findComponent(entity, Kind::LinearMover) == nullptr) continue;
+    Component* transform = findComponent(entity, Kind::Transform2D);
+    transform->position.x += transform->velocity.x * dt;
+    transform->position.y += transform->velocity.y * dt;
+    Component* lifetime = findComponent(entity, Kind::Lifetime);
+    if (lifetime != nullptr) lifetime->age += dt;
+    Component* bounds = findComponent(entity, Kind::ArenaBounds);
+    if (bounds != nullptr) applyBounds(runtime, entity, *bounds);
+  }
+
+  std::vector<DeathEvent> events;
+  // 6. pre-AI bullet collisions
+  runCollisionPass(runtime, liveAfterFire, "bullet-kill", events);
+  handleDeathEvents(runtime, events);
+  events.clear();
+
+  // 7. steering behaviors
+  for (const int handle : liveEntities(runtime)) {
+    Entity& entity = entityAt(runtime, handle);
+    if (!entity.alive || entityTelegraphing(entity)) continue;
+    Component* wander = findComponent(entity, Kind::WanderMover);
+    if (wander != nullptr) {
+      Component* transform = findComponent(entity, Kind::Transform2D);
+      wander->rerollTimer -= dt;
+      if (wander->rerollTimer <= 0) {
+        wander->rerollTimer += wander->rerollSeconds;
+        const double current = rundot::detmath::det_atan2(transform->velocity.y, transform->velocity.x);
+        const double nudged = current + gaussian(runtime, wander->rngStream) * wander->sigmaRad;
+        transform->velocity.x = rundot::detmath::det_cos(nudged) * wander->speedPx;
+        transform->velocity.y = rundot::detmath::det_sin(nudged) * wander->speedPx;
+      }
+      transform->position.x += transform->velocity.x * dt;
+      transform->position.y += transform->velocity.y * dt;
+      Component* bounds = findComponent(entity, Kind::ArenaBounds);
+      if (bounds != nullptr) applyBounds(runtime, entity, *bounds);
+    }
+    Component* seek = findComponent(entity, Kind::SeekMover);
+    if (seek != nullptr) {
+      Component* transform = findComponent(entity, Kind::Transform2D);
+      seek->aliveSeconds += dt;
+      const double t = seek->aliveSeconds;
+      double speed = seek->baseSpeedPx;
+      if (t > seek->accelStartSec) {
+        const double raw = (t - seek->accelStartSec) / (seek->accelEndSec - seek->accelStartSec);
+        const double lerp = raw < 1 ? raw : 1;  // Math.min(1, raw)
+        speed = seek->baseSpeedPx + (seek->topSpeedPx - seek->baseSpeedPx) * lerp;
+      }
+      Vec2 target;
+      if (nearestShipPosition(runtime, transform->position, target)) {
+        const double dx = target.x - transform->position.x;
+        const double dy = target.y - transform->position.y;
+        const double mag = detHypot(dx, dy);
+        if (mag > 0.0001) {
+          transform->velocity.x = (dx / mag) * speed;
+          transform->velocity.y = (dy / mag) * speed;
+        }
+      }
+      transform->position.x += transform->velocity.x * dt;
+      transform->position.y += transform->velocity.y * dt;
+      Component* bounds = findComponent(entity, Kind::ArenaBounds);
+      if (bounds != nullptr) applyBounds(runtime, entity, *bounds);
+    }
+  }
+
+  // 8. post-AI collisions
+  const std::vector<int> liveAfterAi = liveEntities(runtime);
+  runCollisionPass(runtime, liveAfterAi, "bullet-kill", events);
+  runCollisionPass(runtime, liveAfterAi, "ship-death", events);
+  handleDeathEvents(runtime, events);
+  events.clear();
+
+  // 9. lifetimes
+  for (const int handle : liveEntities(runtime)) {
+    Entity& entity = entityAt(runtime, handle);
+    Component* lifetime = findComponent(entity, Kind::Lifetime);
+    if (lifetime != nullptr && lifetime->age >= lifetime->maxSeconds) despawn(runtime, entity);
+  }
+
+  std::vector<Entity> survivors;
+  survivors.reserve(runtime.pooled.size());
+  for (Entity& entity : runtime.pooled) {
+    if (entity.alive) survivors.push_back(std::move(entity));
+  }
+  runtime.pooled = std::move(survivors);
+  runtime.tick += 1;
+}
+
+void putBytes(std::vector<std::uint8_t>& buffer, const void* data, std::size_t size) {
+  const std::uint8_t* bytes = static_cast<const std::uint8_t*>(data);
+  buffer.insert(buffer.end(), bytes, bytes + size);
+}
+
+void putU32(std::vector<std::uint8_t>& buffer, std::uint32_t value) {
+  const std::uint8_t bytes[4] = {
+      static_cast<std::uint8_t>(value & 0xff),
+      static_cast<std::uint8_t>((value >> 8) & 0xff),
+      static_cast<std::uint8_t>((value >> 16) & 0xff),
+      static_cast<std::uint8_t>((value >> 24) & 0xff),
+  };
+  putBytes(buffer, bytes, 4);
+}
+
+void putU64(std::vector<std::uint8_t>& buffer, std::uint64_t value) {
+  std::uint8_t bytes[8];
+  for (int index = 0; index < 8; ++index) bytes[index] = static_cast<std::uint8_t>((value >> (index * 8)) & 0xff);
+  putBytes(buffer, bytes, 8);
+}
+
+void putI64(std::vector<std::uint8_t>& buffer, std::int64_t value) {
+  putU64(buffer, static_cast<std::uint64_t>(value));
+}
+
+void putF64(std::vector<std::uint8_t>& buffer, double value) {
+  putU64(buffer, std::bit_cast<std::uint64_t>(value));
+}
+
+void putString(std::vector<std::uint8_t>& buffer, const std::string& value) {
+  putU32(buffer, static_cast<std::uint32_t>(value.size()));
+  putBytes(buffer, value.data(), value.size());
+}
+
+void hashEntity(std::vector<std::uint8_t>& buffer, Entity& entity) {
+  putString(buffer, entity.ref);
+  putU64(buffer, entity.spawnId);
+  for (Component& component : entity.components) {
+    putString(buffer, kKindNames[static_cast<std::size_t>(component.kind)]);
+    switch (component.kind) {
+      case Kind::Transform2D:
+        putF64(buffer, component.position.x);
+        putF64(buffer, component.position.y);
+        putF64(buffer, component.velocity.x);
+        putF64(buffer, component.velocity.y);
+        putF64(buffer, component.heading);
+        break;
+      case Kind::TwinStickInput:
+        putF64(buffer, component.move.x);
+        putF64(buffer, component.move.y);
+        putF64(buffer, component.aim.x);
+        putF64(buffer, component.aim.y);
+        buffer.push_back(component.fire ? 1 : 0);
+        break;
+      case Kind::SpawnShield:
+      case Kind::Telegraph:
+        putF64(buffer, component.remaining);
+        break;
+      case Kind::WanderMover:
+        putF64(buffer, component.rerollTimer);
+        break;
+      case Kind::SeekMover:
+        putF64(buffer, component.aliveSeconds);
+        break;
+      case Kind::AutoFireWeapon:
+        putF64(buffer, component.cooldown);
+        putU64(buffer, component.nextBulletId);
+        break;
+      case Kind::Lifetime:
+        putF64(buffer, component.age);
+        break;
+      case Kind::Health:
+        putI64(buffer, component.hp);
+        break;
+      case Kind::ResourceCounter:
+        putI64(buffer, component.score);
+        putI64(buffer, component.deaths);
+        break;
+      default:
+        break;
+    }
+  }
+}
+
+std::string canonicalTickHash(Runtime& runtime) {
+  std::vector<std::uint8_t> buffer;
+  buffer.reserve(1 << 16);
+  putU64(buffer, static_cast<std::uint64_t>(runtime.tick));
+  for (const RngStreamRt& stream : runtime.rngStreams) {
+    putString(buffer, stream.id);
+    putU32(buffer, stream.state);
+  }
+  for (Entity& entity : runtime.statics) {
+    if (entity.alive) hashEntity(buffer, entity);
+  }
+  // pooled is maintained in spawn order == ascending spawnId
+  for (Entity& entity : runtime.pooled) {
+    if (entity.alive) hashEntity(buffer, entity);
+  }
+  return rundot::sha256Hex(buffer.data(), buffer.size());
+}
+
+}  // namespace
+
+F64RunResult runReplayF64(const PackDef& pack, const ReplayDef& replay, bool hashEveryTick) {
+  Runtime runtime = createRuntime(pack);
+  std::map<std::int64_t, const std::vector<SlotInputDef>*> inputsByTick;
+  for (const InputFrameDef& frame : replay.inputFrames) {
+    inputsByTick[frame.tick] = &frame.slots;
+  }
+  std::vector<SlotInputDef> currentInputs(static_cast<std::size_t>(pack.inputSlots));
+
+  F64RunResult result;
+  std::string streamAccum;
+  for (std::int64_t tick = 0; tick < replay.tickCount; tick += 1) {
+    const auto frame = inputsByTick.find(tick);
+    if (frame != inputsByTick.end()) currentInputs = *frame->second;
+    tickRuntime(runtime, currentInputs);
+    if (hashEveryTick || tick == replay.tickCount - 1) {
+      const std::string tickHash = canonicalTickHash(runtime);
+      if (hashEveryTick) {
+        result.tickHashes.push_back(tickHash);
+      } else {
+        result.tickHashes.assign(1, tickHash);
+      }
+      streamAccum += tickHash;
+    }
+  }
+  result.finalDigest = rundot::sha256Hex(reinterpret_cast<const std::uint8_t*>(streamAccum.data()), streamAccum.size());
+  result.completedTicks = replay.tickCount;
+  std::int64_t alivePooled = 0;
+  for (const Entity& entity : runtime.pooled) {
+    if (entity.alive) alivePooled += 1;
+  }
+  // liveEntities() counts all statics (even dead) plus alive pooled
+  result.liveEntitiesAtEnd = static_cast<std::int64_t>(runtime.statics.size()) + alivePooled;
+  for (Entity& entity : runtime.statics) {
+    Component* counter = findComponent(entity, Kind::ResourceCounter);
+    if (counter != nullptr) {
+      result.finalScore = counter->score;
+      result.shipDeaths = counter->deaths;
+      break;
+    }
+  }
+  return result;
+}
+
+// component_renderer_f64.cpp includes this .cpp verbatim (see its header
+// comment); it defines RUNDOT_F64RT_OMIT_SIM_STEPPER so the stepper's
+// external-linkage symbols are only emitted from this TU.
+#if !defined(RUNDOT_F64RT_OMIT_SIM_STEPPER)
+
+struct F64SimStepper::Impl {
+  Runtime runtime;
+};
+
+F64SimStepper::F64SimStepper(const PackDef& pack) : impl_(std::make_unique<Impl>()) {
+  impl_->runtime = createRuntime(pack);
+}
+
+F64SimStepper::~F64SimStepper() = default;
+
+void F64SimStepper::tick(const std::vector<SlotInputDef>& inputs) {
+  tickRuntime(impl_->runtime, inputs);
+}
+
+void F64SimStepper::liveView(std::vector<SimEntityView>& out) {
+  Runtime& runtime = impl_->runtime;
+  out.clear();
+  for (const int handle : liveEntities(runtime)) {
+    Entity& entity = entityAt(runtime, handle);
+    if (!entity.alive) continue;  // killed statics stay listed; never render them
+    SimEntityView view;
+    view.ref = entity.ref;
+    view.spawnId = entity.spawnId;
+    if (Component* transform = findComponent(entity, Kind::Transform2D)) {
+      view.hasTransform = true;
+      view.x = transform->position.x;
+      view.y = transform->position.y;
+      view.vx = transform->velocity.x;
+      view.vy = transform->velocity.y;
+      view.heading = transform->heading;
+    }
+    if (Component* telegraph = findComponent(entity, Kind::Telegraph)) {
+      view.hasTelegraph = true;
+      view.telegraphRemaining = telegraph->remaining;
+    }
+    out.push_back(std::move(view));
+  }
+}
+
+const std::vector<FrameEventDef>& F64SimStepper::frameEvents() const {
+  return impl_->runtime.frameEvents;
+}
+
+#endif  // !defined(RUNDOT_F64RT_OMIT_SIM_STEPPER)
+
+}  // namespace rundot::f64rt