iron-requiem/src/game/systems/HeatSystem.js

/**
 * HeatSystem — tracks tank thermal state.
 *
 * Heat builds from engine runtime, firing, and taking hits.
 * Passive cooling brings temperature down when idle.
 * Freeze-thaw: engine must reach warmupThreshold before full power.
 * Overheat penalties: reduced speed and accuracy.
 *
 * @module src/game/systems/HeatSystem
 */

const DEFAULTS = {
  maxHeat: 100,
  overheatThreshold: 80,
  coolingRate: 5,
  engineHeatRate: 20,
  fireHeat: 25,
  hitHeat: 40,
  warmupThreshold: 30,
  coldSpeedMultiplier: 0.5,
  overheatSpeedPenalty: 0.6,
  overheatAccuracyPenalty: 0.7,
  maxFuel: 100,
  fuelDepletionRate: 5, // units per second while engine runs
};

export class HeatSystem {
  /**
   * @param {object} [config={}] — optional overrides for any default
   */
  constructor(config = {}) {
    this.maxHeat = config.maxHeat ?? DEFAULTS.maxHeat;
    this.overheatThreshold = config.overheatThreshold ?? DEFAULTS.overheatThreshold;
    this.coolingRate = config.coolingRate ?? DEFAULTS.coolingRate;
    this.engineHeatRate = config.engineHeatRate ?? DEFAULTS.engineHeatRate;
    this.fireHeat = config.fireHeat ?? DEFAULTS.fireHeat;
    this.hitHeat = config.hitHeat ?? DEFAULTS.hitHeat;
    this.warmupThreshold = config.warmupThreshold ?? DEFAULTS.warmupThreshold;
    this.coldSpeedMultiplier = config.coldSpeedMultiplier ?? DEFAULTS.coldSpeedMultiplier;
    this.overheatSpeedPenalty = config.overheatSpeedPenalty ?? DEFAULTS.overheatSpeedPenalty;
    this.overheatAccuracyPenalty = config.overheatAccuracyPenalty ?? DEFAULTS.overheatAccuracyPenalty;
    this.fuelDepletionRate = config.fuelDepletionRate ?? DEFAULTS.fuelDepletionRate;

    this._temperature = 0;
    this._engineReady = false;
    this._fuel = config.maxFuel ?? DEFAULTS.maxFuel;
  }

  /** Current temperature (0 – maxHeat). */
  get temperature() {
    return this._temperature;
  }

  /** True when temperature exceeds overheatThreshold. */
  get isOverheated() {
    return this._temperature > this.overheatThreshold;
  }

  /** True once temperature has reached warmupThreshold (persists). */
  get engineReady() {
    return this._engineReady;
  }

  /** Current fuel level (0 – maxFuel). */
  get fuel() {
    return this._fuel;
  }

  /**
   * Advance the thermal simulation by dt seconds.
   *
   * @param {number} dt — delta time in seconds
   * @param {object} state
   * @param {boolean} [state.engineOn] — engine is running
   * @param {boolean} [state.fired] — a shot was fired this frame
   * @param {boolean} [state.wasHit] — the tank took a hit this frame
   * @param {number}  [state.engineHeatRate_override] — temporary engine heat rate
   */
  update(dt, state = {}) {
    // Heat sources
    if (state.engineOn) {
      const rate = state.engineHeatRate_override ?? this.engineHeatRate;
      this._temperature += rate * dt;
    }

    if (state.fired) {
      this._temperature += this.fireHeat;
    }

    if (state.wasHit) {
      this._temperature += this.hitHeat;
    }

    // Passive cooling — only when idle
    if (!state.engineOn && !state.fired && !state.wasHit) {
      this._temperature = Math.max(0, this._temperature - this.coolingRate * dt);
    }

    // Cap
    if (this._temperature > this.maxHeat) {
      this._temperature = this.maxHeat;
    }
    // Prevent temperature from going negative due to cooling
    if (this._temperature < 0) {
      this._temperature = 0;
    }

    // Freeze-thaw latch
    if (this._temperature >= this.warmupThreshold) {
      this._engineReady = true;
    }

    // Fuel depletion while engine is running
    if (state.engineOn) {
      this._fuel = Math.max(0, this._fuel - this.fuelDepletionRate * dt);
    }
  }

  /**
   * Speed multiplier, factoring in engine readiness and overheat.
   * @returns {number} 0–1
   */
  getSpeedMultiplier() {
    if (this._temperature > this.overheatThreshold) {
      return this.overheatSpeedPenalty;
    }
    if (!this._engineReady) {
      return this.coldSpeedMultiplier;
    }
    return 1.0;
  }

  /**
   * Accuracy multiplier — unaffected by cold engine, penalized by overheat.
   * @returns {number} 0–1
   */
  getAccuracyMultiplier() {
    if (this._temperature > this.overheatThreshold) {
      return this.overheatAccuracyPenalty;
    }
    return 1.0;
  }

  /**
   * Snapshot of current thermal state for HUD / downstream systems.
   * @returns {{ temperature: number, isOverheated: boolean, engineReady: boolean, speedMultiplier: number, accuracyMultiplier: number }}
   */
  getState() {
    return {
      temperature: this._temperature,
      isOverheated: this.isOverheated,
      engineReady: this._engineReady,
      speedMultiplier: this.getSpeedMultiplier(),
      accuracyMultiplier: this.getAccuracyMultiplier(),
      fuel: this._fuel,
    };
  }
}