orbit/data/combat.json

{
  "_comment": "COMBAT — all combat tuning, one file. Two contexts share the numbers: the standalone range (combat.html / the dev server's /combat — the WASD arena, js/combat/CombatScene.js) and the MAIN GAME (index.html?combat — js/combat/CombatSystem.js drops the pack into the normal game: click-to-fly, the deck swaps for the combat bar, the ship auto-fires at the nearest hostile). Pure rules (armor damage, orbit steering) are js/combat/Combat.js (tested: dev/combat.test.mjs).",
  "enabled": true,

  "game": {
    "_comment": "COMBAT IN THE MAIN GAME (the ?combat boot). spawnCount = hostiles that appear around the ship when the player starts (spawnRadius px out — the real spawn SCHEDULES, places + waves, land with the port); autoFire = the ship's guns — while a hostile is within range the ship fires at the NEAREST one (the mouse steers, the cannon tracks; the cannon's own numbers are player.weapon below).",
    "spawnCount": 3,
    "spawnRadius": 340,
    "autoFire": {
      "enabled": true,
      "range": 800
    }
  },

  "energy": {
    "_comment": "The player's ENERGY — the skill resource (the combat bar's right gauge). The eight skills (keys 1-8, the bar's middle seats) will spend it; for now it just sits full. regen = energy/s recovered (0 = static).",
    "max": 100,
    "regen": 0
  },

  "player": {
    "_comment": "The combat feel of YOUR ship in the range (the art, hull stats, and ship name still come from data/ship.json). WASD/arrows fly, SPACE/J fires (hold = auto-fire). The flight feel (js/combat/Combat.js → handleFeel, tested): thrust px/s^2 at full throttle, maxSpeed px/s cap, drag 1/s (exponential coast decay — the range OVERRIDES ship.drag with this, so data/combat.json is the one tuning surface), brake = the S/Down reverse-throttle as a fraction of FULL thrust (instant — a responsive stop). rotSpeed rad/s = the SUSTAINED keyboard turn rate; rotApproach 1/s = how fast the turn rate builds (a tap is a nudge, a hold is a full spin); thrustRamp 1/s = how fast the throttle reaches full on W; thrustDecay 1/s = how fast the throttle cuts when W lets go (no lingering kick). weapon.* = the player's cannon: cooldown s between shots, bulletSpeed px/s, damage per hit, spread rad of aim jitter, bulletLife s before a shot fizzles, color/size the tracer's glow.",
    "thrust": 2000,
    "maxSpeed": 560,
    "drag": 1.8,
    "rotSpeed": 6.4,
    "rotApproach": 20,
    "thrustRamp": 18,
    "thrustDecay": 30,
    "brake": 0.9,
    "weapon": {
      "key": "space",
      "cooldown": 0.16,
      "bulletSpeed": 680,
      "damage": 10,
      "spread": 0.03,
      "bulletLife": 1.15,
      "color": "#00e5ff",
      "size": 16
    }
  },

  "enemy": {
    "_comment": "The hostile craft. texture = spritesheet of frameWidth×frameHeight frames (frame picks which one — frame 0 = the red triple-boost fighter, art facing north, filling its frame; the sheet is 10×10 of 128px frames). size = hull length in world px (render = size × the art's footprint), hitRadius = the collision circle in world px (bullets + rams). count = hostiles in the arena at once. speed px/s + turn (1/s velocity-approach rate) = the chase feel. orbitRadius px = the standoff ring they keep around the player; orbitSpeed rad/s = how fast they circle it (direction alternates per craft). hull/shields = their armor (shields absorb first — js/combat/Combat.js). weapon.* = their lance: range px, cooldown s, bulletSpeed px/s, damage, spread rad, bulletLife s. ramDamage = hull damage a COLLISION deals you; ramDamageSelf = what the collision deals THEM (per hit, ramGrace s apart). respawn = the pack reforms (respawnDelay s) after a kill, so the range stays stocked while you tune.",
    "texture": "assets/images/ships-enemy.png",
    "frameWidth": 128,
    "frameHeight": 128,
    "frame": 0,
    "artFacing": "north",
    "size": 54,
    "hitRadius": 20,
    "count": 3,
    "speed": 165,
    "turn": 3.2,
    "orbitRadius": 300,
    "orbitSpeed": 0.6,
    "hull": 60,
    "shields": 0,
    "weapon": {
      "range": 560,
      "cooldown": 1.4,
      "bulletSpeed": 330,
      "damage": 8,
      "spread": 0.08,
      "bulletLife": 2.4,
      "color": "#ff2d6f",
      "size": 18
    },
    "ramDamage": 10,
    "ramDamageSelf": 22,
    "ramGrace": 0.8,
    "respawn": true,
    "respawnDelay": 2.5
  },

  "playerShip": {
    "_comment": "Your armor (both contexts — the real ship's stats.hullIntegrity/shields replace this when combat ships for real). shields absorb before the hull; after shieldRegenDelay s without a hit, shields regrow at shieldRegenRate/s up to their max. respawn = when your hull breaks you come back (respawnDelay s) instead of the run ending — a stand-in until the real death flow lands.",
    "hull": 100,
    "shields": 40,
    "shieldRegenDelay": 4,
    "shieldRegenRate": 14,
    "respawn": true,
    "respawnDelay": 2.0
  },

  "arena": {
    "_comment": "The range walls. inset = px between the screen edge and the bounce wall; bounce = the fraction of speed a ship keeps off a wall (1 = full mirror bounce). wallColor = the rim line, wallGlow = its neon edge.",
    "inset": 26,
    "bounce": 0.9,
    "wallColor": "#1b2c4a",
    "wallGlow": "#00e5ff"
  },

  "sandbox": {
    "_comment": "Sandbox conveniences — none of this ships with the real game. resetKey rebuilds the whole range (a fresh scene); pauseKey freezes the sim (handy for eyeballing positions via window.__COMBAT__ in the console); respawn = the player comes back (respawnDelay s) instead of dying permanently.",
    "resetKey": "R",
    "pauseKey": "P",
    "respawn": true,
    "respawnDelay": 1.6
  },

  "hud": {
    "_comment": "The range console chrome (colors fall back to data/theme.json). title = the corner label; hints = the control line at the bottom.",
    "title": "COMBAT // SANDBOX",
    "hints": "WASD / arrows — fly    ·    space — fire    ·    R — reset range    ·    P — pause"
  },

  "bar": {
    "_comment": "The COMBAT BAR (js/ui/CombatBar.js) — shown in place of the action deck while combat is live (the deck hides, the bar takes its place; when the pack is wiped it's the other way around). geometry = the bar's screen rect (margin/height mirror actionbar's, so it sits in the deck's place). Left = the vertical SHIELDS + HULL gauges; right = the vertical ENERGY gauge; middle = slot.count skill seats wearing keys 1-8 (the skills land later — for now they are empty seats). Colors fall back to data/theme.json where sensible.",
    "height": 92,
    "margin": { "left": 20, "right": 20, "bottom": 12 },
    "colors": {
      "bg": "#070d18",
      "bgAlpha": 0.92,
      "edge": "#22405f",
      "shield": "#00e5ff",
      "hull": "#7dff8a",
      "energy": "#ffd84d",
      "slotBg": "#0b1322",
      "slotBorder": "#22405f",
      "key": "#5c7196"
    },
    "gauge": { "width": 14, "gap": 8, "pad": 12, "labelSize": 11 },
    "slot": { "count": 8, "size": 64, "gap": 10, "keySize": 12 }
  }
}