Cut 4: input capacitors close the last direct capacitor spend

Deletes Entity.CanSpendCapacitorCharge/TrySpendCapacitorCharge (and the
now-dead _capacitors bookkeeping list that only fed them) -- Cut 3's
named, temporary exception for the four instant draws. InstantWeapon
(both fire sites), Sensor.Ping, and Shield.CanTakeHit/TakeHit now spend
from their own InputCapacitor, filled continuously by PowerBus like
every other IPowerConsumer instead of touching the entity's shared bus
capacitors directly.

InputCapacitor's Capacity/Rate derive from the owning item's Energy and
Cooldown, with an authored-override hook (ChargedWeapon repurposes its
previously-unused ChargeEnergy stat as that override, per the map's own
instruction, rather than adding a new field). A weapon/sensor fire
attempt only ever spends exactly Capacity, so it only ever succeeds at
full charge -- no fractional shot. Shield is the map's named exception:
its reserve is continuous, not an activation buffer, so it allows a
partial draw; its size (no Energy/Cooldown pair exists on Shield) is a
flagged judgment call, not a spec'd formula.

Adds InputCapacitorTests.cs (8 tests) and
mutation_tests_stats_power_cut4.py (7 mutations, all behave as
declared); removes the one PowerBusTests.cs test and Cut 3 mutation
case that exercised the now-deleted Entity methods.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Assets/Scripts/ServerShared/Behaviors/ChargedWeapon.cs

@@ -67,6 +67,13 @@ public class ChargedWeapon : InstantWeapon
     public float ChargeTime { get; protected set; }
     public float ChargeEnergy { get; protected set; }
     public float ChargeHeat { get; protected set; }
+
+    // Cut 4 (docs/stats-and-power-cut.md, Cut 4): "its charge cycle already is a buffer, and ChargeEnergy
+    // should become the fill rate rather than a separate concept." ChargeEnergy was authored but never spent
+    // by anything (Trigger() always paid the base Weapon.Energy per shot); it becomes this weapon's input
+    // capacitor rate instead of the InstantWeapon default (Capacity / Cooldown), so a charged weapon's own
+    // authored charge-up speed IS its sustained rate of fire, not a second, disconnected number.
+    protected override float RateOverride => Evaluate(_data.ChargeEnergy);
     
     public override float DamagePerSecond => Damage * _data.ChargeFiringDamageMultiplier / (Cooldown + ChargeTime);
     public override float RangeDamagePerSecond(float range)

Assets/Scripts/ServerShared/Behaviors/InputCapacitor.cs

@@ -0,0 +1,59 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+using static CultMath.math;
+
+// Cut 4 (docs/stats-and-power-cut.md §1.2, §0b "An input capacitor"): the input-only buffer that lets an
+// instant activation (a shot, a ping, a shield's damage reserve) draw from the PowerBus continuously instead
+// of spending stored charge directly -- closing Cut 3's named, temporary exception
+// (Entity.TrySpendCapacitorCharge/CanSpendCapacitorCharge, both deleted with their last caller this cut).
+//
+// Not a Behavior of its own: per §0b, an input capacitor is identified by the Behavior instance that owns it
+// (InstantWeapon, Sensor, Shield), which holds one of these as a plain field. Two writers, disjoint signs,
+// named: the bus fills it, through AddCharge, called only from the owning behaviour's own Execute after it
+// reads back its granted fraction from Item.PowerSupply; the owning behaviour drains it, through TrySpend,
+// called only when it actually activates. Nothing else may touch Charge.
+public class InputCapacitor
+{
+    public float Capacity { get; private set; }
+    public float Rate { get; private set; }
+    public float Charge { get; private set; }
+
+    // Cut 4 (§7 Q4, operator ruling): "derived from the item's Energy and Cooldown ... with an authored
+    // override" so burst capacity and sustained rate stay separate levers. capacityOverride/rateOverride of 0
+    // mean "not authored, use the derived default" -- the same identity-when-absent convention PerformanceStat
+    // itself already uses (a term-less stat resolves to its identity factor). Cutting Charge down here (rather
+    // than only clamping in AddCharge) is what lets a Capacity that shrinks under a stat change immediately
+    // stop promising a shot it can no longer pay for.
+    public void UpdateStats(float energy, float cooldown, float capacityOverride = 0f, float rateOverride = 0f)
+    {
+        Capacity = capacityOverride > 0f ? capacityOverride : max(0f, energy);
+        Rate = rateOverride > 0f ? rateOverride : (cooldown > 0f ? Capacity / cooldown : Capacity);
+        Charge = clamp(Charge, 0f, Capacity);
+    }
+
+    // What PowerBus should count as this consumer's demand this tick (via the owning behaviour's
+    // IPowerConsumer.PowerRequest), and what that behaviour should scale by its own Item.PowerSupply and pass
+    // to AddCharge once its own Execute runs. The two calls must agree on dt and must not have let Charge move
+    // in between, because PowerBus.Step calls this before any behaviour's Execute runs this tick (§1.2:
+    // "computable from state that is already current at that point").
+    public float RequestedFill(float dt) => min(Rate * dt, max(0f, Capacity - Charge));
+
+    public void AddCharge(float amount) => Charge = clamp(Charge + amount, 0f, Capacity);
+
+    public bool CanSpend(float cost) => Charge >= cost;
+
+    // Atomic and whole-or-nothing, mirroring Entity.TrySpendCapacitorCharge's old contract exactly (down to the
+    // near-zero shortcut) but scoped to this one behaviour's own buffer instead of the entity's shared bus
+    // capacitors: either the cost is covered in full, or nothing moves. This is the mechanism behind the
+    // operator's ruling that no item ever receives a fraction of a shot -- callers that want that guarantee
+    // spend exactly Capacity, which only ever succeeds at full charge.
+    public bool TrySpend(float cost)
+    {
+        if (cost < .01f) return true;
+        if (!CanSpend(cost)) return false;
+        Charge -= cost;
+        return true;
+    }
+}

Assets/Scripts/ServerShared/Behaviors/InputCapacitor.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 2323335634942be0e17abf63f5c6d256
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

Assets/Scripts/ServerShared/Behaviors/InstantWeapon.cs

@@ -32,10 +32,14 @@ public class InstantWeaponData : WeaponData
     }
 }
 
-public class InstantWeapon : Weapon, IProgressBehavior, IEventBehavior
+public class InstantWeapon : Weapon, IProgressBehavior, IEventBehavior, IPowerConsumer
 {
     private InstantWeaponData _data;
 
+    // Cut 4 (docs/stats-and-power-cut.md, Cut 4): replaces the direct Entity.TrySpendCapacitorCharge spend at
+    // both Trigger() and Execute() below -- the named, temporary exception Cut 3 left standing.
+    protected readonly InputCapacitor _capacitor = new InputCapacitor();
+
     protected int _burstRemaining;
     private float _burstTimer;
     private float _burstInterval;
@@ -95,10 +99,7 @@ public class InstantWeapon : Weapon, IProgressBehavior, IEventBehavior
 
         // If 1 ammo is consumed per burst, perform ammo and energy consumption here
         // UseAmmo returns false when triggering reload; cancel firing if that is the case
-        // Cut 3 (docs/stats-and-power-cut.md): one of the four instant draws out of scope for the bus this cut
-        // (a burst) -- named, temporary exception, spending capacitor charge directly. Cut 4's input capacitor
-        // closes this.
-        if(_data.SingleAmmoBurst && (!Entity.TrySpendCapacitorCharge(Energy) || !UseAmmo())) return;
+        if(_data.SingleAmmoBurst && (!TrySpendActivationEnergy() || !UseAmmo())) return;
         
         _burstRemaining = (int) BurstCount;
         _burstInterval = BurstTime / _burstRemaining;
@@ -119,6 +120,36 @@ public class InstantWeapon : Weapon, IProgressBehavior, IEventBehavior
         Energy /= (int) BurstCount;
     }
 
+    // Cut 4 (docs/stats-and-power-cut.md §7 Q4): capacity and rate, resolved fresh rather than off the cached
+    // Energy/Cooldown properties above -- Capacitor.ResolveCapacity's precedent (PowerBus.Step, which calls
+    // PowerRequest below, runs before this behaviour's own Execute this tick, so those cached properties would
+    // still hold last tick's value). Capacity is one shot's own energy cost, exactly what the two deleted
+    // direct-spend call sites measured. Default rate keeps sustained fire exactly at Cooldown's pace when the
+    // bus grants the full request; RateOverride lets an owner replace that (ChargedWeapon does).
+    protected virtual float RateOverride => 0f;
+
+    protected void RefreshInputCapacitor()
+    {
+        var burstCount = max(1, (int) Evaluate(_data.Count));
+        var perShotEnergy = Evaluate(_data.Energy) / burstCount;
+        var cooldown = Evaluate(_data.Cooldown);
+        _capacitor.UpdateStats(perShotEnergy, cooldown, rateOverride: RateOverride);
+    }
+
+    // Cut 4: the request PowerBus needs before Execute runs, mirroring EnergyDraw's IPowerConsumer pattern.
+    public float PowerRequest(float dt)
+    {
+        RefreshInputCapacitor();
+        return _capacitor.RequestedFill(dt);
+    }
+
+    // Cut 4: whole-or-nothing against this behaviour's own input capacitor -- the operator's ruling ("no item
+    // ever receives a fraction of a shot") means a fire attempt only ever succeeds at full charge, so the cost
+    // spent is always exactly Capacity, never the possibly-stale cached Energy. A consumable-hosted instance
+    // (Item == null) has no PowerBus entry (Behaviors.cs: "no PowerBus entry ... always succeeds"), so nothing
+    // would ever fill this capacitor -- bypass it entirely rather than starving such an instance forever.
+    protected bool TrySpendActivationEnergy() => Item == null || _capacitor.TrySpend(_capacitor.Capacity);
+
     private bool UseAmmo()
     {
         if (_data.MagazineSize <= 1) return true;
@@ -156,6 +187,10 @@ public class InstantWeapon : Weapon, IProgressBehavior, IEventBehavior
     public override bool Execute(float dt)
     {
         base.Execute(dt);
+        // Cut 4: this tick's grant, read back via Item.PowerSupply -- Item is non-null here because a null-Item
+        // instance never reaches PowerBus.Step (see TrySpendActivationEnergy) and so never accrues charge.
+        if (Item != null)
+            _capacitor.AddCharge(_capacitor.RequestedFill(dt) * Item.PowerSupply);
         if (_coolingDown)
         {
             _cooldown -= dt / (_data.MagazineSize > 0 && _ammo == 0 ? _data.ReloadTime : Cooldown);
@@ -178,9 +213,7 @@ public class InstantWeapon : Weapon, IProgressBehavior, IEventBehavior
         {
             // If multiple ammo is consumed per burst, perform ammo and energy consumption here
             // UseAmmo returns false when triggering reload; cancel firing if that is the case
-            // Cut 3 (docs/stats-and-power-cut.md): one of the four instant draws out of scope this cut (a shot);
-            // see Trigger()'s SingleAmmoBurst branch above for the same named exception.
-            if (!_data.SingleAmmoBurst && (!Entity.TrySpendCapacitorCharge(Energy) || !UseAmmo()))
+            if (!_data.SingleAmmoBurst && (!TrySpendActivationEnergy() || !UseAmmo()))
             {
                 _burstRemaining = 0;
                 return false;

Assets/Scripts/ServerShared/Behaviors/Sensor.cs

@@ -50,9 +50,13 @@ public class SensorData : BehaviorData
     }
 }
 
-public class Sensor : Behavior, IEventBehavior
+public class Sensor : Behavior, IEventBehavior, IPowerConsumer
 {
     private SensorData _data;
+
+    // Cut 4 (docs/stats-and-power-cut.md, Cut 4): replaces the direct Entity.TrySpendCapacitorCharge spend in
+    // Ping() below -- the named, temporary exception Cut 3 left standing.
+    private readonly InputCapacitor _capacitor = new InputCapacitor();
     private float _pingCooldown;
     private float _pingLerp;
     private bool _pinging;
@@ -80,11 +84,28 @@ public class Sensor : Behavior, IEventBehavior
         OnPingEnd = null;
     }
 
-    // Cut 3 (docs/stats-and-power-cut.md): one of the four instant draws out of scope for the bus this cut (a
-    // ping) -- named, temporary exception, spending capacitor charge directly. Cut 4 closes this.
+    // Cut 4: capacity/rate, resolved fresh (Capacitor.ResolveCapacity's precedent -- PowerBus.Step calls
+    // PowerRequest below before this behaviour's own Execute runs this tick).
+    private void RefreshInputCapacitor()
+    {
+        var energy = Evaluate(_data.PingEnergy);
+        var cooldown = Evaluate(_data.PingCooldown);
+        _capacitor.UpdateStats(energy, cooldown);
+    }
+
+    // Cut 4: the request PowerBus needs before Execute runs.
+    public float PowerRequest(float dt)
+    {
+        RefreshInputCapacitor();
+        return _capacitor.RequestedFill(dt);
+    }
+
     public void Ping()
     {
-        if(_pingCooldown < 0 && Entity.TrySpendCapacitorCharge(Evaluate(_data.PingEnergy)))
+        // Whole-or-nothing against the ping's own input capacitor -- fires only at full charge (operator
+        // ruling: no fraction of a shot). A consumable-hosted instance (Item == null) has no PowerBus entry, so
+        // nothing would ever fill this capacitor; bypass it rather than starving such an instance forever.
+        if(_pingCooldown < 0 && (Item == null || _capacitor.TrySpend(_capacitor.Capacity)))
         {
             Entity.VisibilitySources[this] = Evaluate(_data.PingVisibility);
             _pinging = true;
@@ -108,6 +129,10 @@ public class Sensor : Behavior, IEventBehavior
 
     public override bool Execute(float dt)
     {
+        // Cut 4: this tick's grant, read back via Item.PowerSupply -- Item is non-null here because a null-Item
+        // instance never reaches PowerBus.Step (see Ping()) and so never accrues charge.
+        if (Item != null)
+            _capacitor.AddCharge(_capacitor.RequestedFill(dt) * Item.PowerSupply);
         if (_pinging)
         {
             _pingLerp += dt / _data.PingDuration;

Assets/Scripts/ServerShared/Behaviors/Shield.cs

@@ -26,13 +26,24 @@ public class ShieldData : BehaviorData
     }
 }
 
-public class Shield : Behavior, IProgressBehavior
+public class Shield : Behavior, IProgressBehavior, IPowerConsumer
 {
     public float Efficiency { get; private set; }
     public float EnergyUsage { get; private set; }
 
     private ShieldData _data;
 
+    // Cut 4 (docs/stats-and-power-cut.md, Cut 4): "a shield hit is not an activation the player chose, so its
+    // 'instant' draw is really a continuous reserve. Name it as such rather than giving it an activation
+    // buffer." Unlike InstantWeapon/Sensor above, TrySpend below is never called with exactly Capacity -- a hit
+    // can partially draw the reserve, same as the old direct capacitor spend could. Shield has no Energy/
+    // Cooldown pair to derive a size from (only EnergyUsage, a per-damage-point multiplier), so this is a
+    // judgment call, not a formula the map states: the reserve's Capacity and Rate both default to EnergyUsage
+    // itself, refilling in full every second (Cooldown's implicit identity value -- the same "absent means
+    // identity" convention InputCapacitor and PerformanceStat itself already use). Flagged for operator review
+    // against real catalog EnergyUsage magnitudes rather than presented as spec'd.
+    private readonly InputCapacitor _reserve = new InputCapacitor();
+
     public Shield(ShieldData data, EquippedItem item) : base(data, item)
     {
         _data = data;
@@ -42,24 +53,44 @@ public class Shield : Behavior, IProgressBehavior
         _data = data;
     }
 
+    // Cut 4: capacity/rate, resolved fresh (Capacitor.ResolveCapacity's precedent -- PowerBus.Step calls
+    // PowerRequest below before this behaviour's own Execute runs this tick).
+    private void RefreshReserve()
+    {
+        var energyUsage = Evaluate(_data.EnergyUsage);
+        _reserve.UpdateStats(energyUsage, cooldown: 1f);
+    }
+
+    // Cut 4: the request PowerBus needs before Execute runs.
+    public float PowerRequest(float dt)
+    {
+        RefreshReserve();
+        return _reserve.RequestedFill(dt);
+    }
+
     public override bool Execute(float dt)
     {
         Efficiency = Evaluate(_data.Efficiency);
         EnergyUsage = Evaluate(_data.EnergyUsage);
+        // Cut 4: this tick's grant, read back via Item.PowerSupply -- Item is non-null here because a null-Item
+        // instance never reaches PowerBus.Step (see CanTakeHit/TakeHit) and so never accrues charge.
+        if (Item != null)
+            _reserve.AddCharge(_reserve.RequestedFill(dt) * Item.PowerSupply);
         return true;
     }
 
-    // Cut 3 (docs/stats-and-power-cut.md): one of the four instant draws out of scope for the bus this cut (a
-    // hit taken, not a chosen activation) -- named, temporary exception, spending capacitor charge directly
-    // instead of through PowerBus. Cut 4 gives it a real continuous reserve model and closes this.
+    // Cut 4 (docs/stats-and-power-cut.md, Cut 4): a hit taken, not a chosen activation, drawing from the
+    // shield's own continuous reserve instead of the entity's shared bus capacitors -- closing Cut 3's named,
+    // temporary exception. A consumable-hosted instance (Item == null) has no PowerBus entry, so nothing would
+    // ever fill this reserve; bypass it rather than starving such an instance forever.
     public bool CanTakeHit(DamageType type, float damage)
     {
-        return Entity.CanSpendCapacitorCharge(damage * EnergyUsage);
+        return Item == null || _reserve.CanSpend(damage * EnergyUsage);
     }
 
     public void TakeHit(DamageType type, float damage)
     {
-        Entity.TrySpendCapacitorCharge(damage * EnergyUsage);
+        if (Item != null) _reserve.TrySpend(damage * EnergyUsage);
         AddHeat(damage / Efficiency);
     }
 

Assets/Scripts/ServerShared/Entity.cs

@@ -78,7 +78,6 @@ public abstract class Entity
     
     private EquippedItem[] _orderedEquipment;
     private List<Weapon> _weapons = new List<Weapon>();
-    private List<Capacitor> _capacitors = new List<Capacitor>();
     private List<Radiator> _heatsinks = new List<Radiator>();
 
     private List<ConsumableItemEffect> _activeConsumables = new List<ConsumableItemEffect>();
@@ -610,8 +609,6 @@ public abstract class Entity
                 _weapons.Remove(weapon);
                 foreach (var group in WeaponGroups) { group.items.Remove(item); group.weapons.Remove(weapon); }
             }
-            if (b is Capacitor capacitor)
-                _capacitors.Remove(capacitor);
             if (b is Radiator heatsink)
                 _heatsinks.Remove(heatsink);
             if (b is Shield)
@@ -793,8 +790,6 @@ public abstract class Entity
         {
             if (b is Weapon weapon)
                 _weapons.Add(weapon);
-            if(b is Capacitor capacitor)
-                _capacitors.Add(capacitor);
             if(b is Radiator heatsink)
                 _heatsinks.Add(heatsink);
             if (b is Shield shield)
@@ -858,37 +853,11 @@ public abstract class Entity
         return true;
     }
 
-    // Cut 3 (docs/stats-and-power-cut.md): replaces CanConsumeEnergy/TryConsumeEnergy for the four instant draws
-    // the cut map names as out of scope for the bus this cut (a burst, a shot, a ping, a hit taken) -- the named,
-    // temporary exception the map accepts, closed by Cut 4's input capacitors. Capacitor charge only: a reactor
-    // no longer bails out a draw it cannot cover for free, which is exactly the behaviour Cut 3 exists to remove
-    // (§0.5 -- "every draw succeeds while one reactor is online"). Atomic: either every capacitor together holds
-    // enough charge and it is spent, or nothing moves -- never TryConsumeEnergy's old partial drain-then-refuse.
-    public bool CanSpendCapacitorCharge(float energy) => _capacitors.Sum(cap => cap.Charge) >= energy;
-
-    public bool TrySpendCapacitorCharge(float energy)
-    {
-        if (energy < .01f) return true;
-        if (!CanSpendCapacitorCharge(energy)) return false;
-
-        var remaining = energy;
-        int chargedCapacitors;
-        do
-        {
-            chargedCapacitors = _capacitors.Count(capacitor => capacitor.Charge > .01f);
-            if (chargedCapacitors == 0) break;
-            var share = remaining / chargedCapacitors;
-            foreach (var cap in _capacitors)
-            {
-                if (cap.Charge <= .01f) continue;
-                var drawn = min(share, cap.Charge);
-                cap.AddCharge(-drawn);
-                remaining -= drawn;
-            }
-        } while (chargedCapacitors > 0 && remaining > .01f);
-
-        return true;
-    }
+    // Cut 4 (docs/stats-and-power-cut.md, Cut 4): CanSpendCapacitorCharge/TrySpendCapacitorCharge died here with
+    // their last caller. Cut 3 named them a temporary exception for the four instant draws (a burst, a shot, a
+    // ping, a hit taken); all four now spend from their own InputCapacitor instead (InstantWeapon, Sensor,
+    // Shield), fed continuously by PowerBus like every other consumer. The entity's shared bus capacitors are
+    // now touched only by PowerBus itself (§0b: "the bus fills; the owning behaviour spends").
 
     private void AddChild(Entity entity)
     {

Assets/Scripts/ServerShared/PowerBus.cs

@@ -16,9 +16,10 @@ using static CultMath.math;
 // (§0.5), not a replacement for it.
 //
 // Bus capacitors are charged and drained only here (§0b): Reactor no longer touches them, and neither does any
-// IPowerConsumer. The four instant draws the cut map names (a burst, a shot, a ping, a hit taken) are out of
-// scope for this cut and spend capacitor charge directly instead, through Entity.TrySpendCapacitorCharge -- a
-// named, temporary exception this cut accepts, closed by Cut 4.
+// IPowerConsumer. The four instant draws the cut map names (a burst, a shot, a ping, a hit taken) are
+// IPowerConsumers too as of Cut 4: each spends from its own InputCapacitor (InstantWeapon, Sensor, Shield),
+// never from these bus capacitors directly. Entity.TrySpendCapacitorCharge/CanSpendCapacitorCharge, Cut 3's
+// named, temporary exception, died with their last caller.
 public class PowerBus
 {
     private readonly Entity _entity;