Merge remote-tracking branch 'origin/codex/power-tiers' into codex/item-provenance

This commit is contained in:
Meta Vens 2026-09-19 03:00:02 +02:00
commit 8a717542a4
17 changed files with 634 additions and 28 deletions

View file

@ -111,6 +111,9 @@ public class AetherDrive : Behavior, IPowerConsumer
return (draw.x + draw.y + draw.z) * dt;
}
// Cut 5 (docs/stats-and-power-cut.md §1.3, PowerTiers.cs): Medium -- mobility, same as Thruster.
public int DefaultPowerTier => PowerTiers.Medium;
public override bool Execute(float dt)
{
var rotorSpeed = Rpm * _data.RotorDiameter / 100;

View file

@ -124,11 +124,6 @@ public interface IProgressBehavior
float Progress { get; }
}
public interface IOrderedBehavior
{
int Order { get; }
}
public interface IPopulationAssignment
{
int AssignedPopulation { get; set; }
@ -140,9 +135,14 @@ public interface IPopulationAssignment
// point -- a resolved stat and, where the map calls for one, a behaviour-supplied scalar such as Thruster's
// throttle axis (set externally before the tick) -- never from work Execute itself would otherwise do. The
// behaviour reads back how much of its own request was granted from Item.PowerSupply during its own Execute.
//
// Cut 5 (docs/stats-and-power-cut.md §1.3): every kind of consumer also names the priority tier (PowerTiers.cs)
// it defaults to. EquippedItem reads this exactly once, to seed EquippableItem.PowerTier the first time an item
// without a player-chosen tier gets equipped -- after that the stored field is what PowerBus reads, never this.
public interface IPowerConsumer
{
float PowerRequest(float dt);
int DefaultPowerTier { get; }
}
[Inspectable,

View file

@ -77,6 +77,9 @@ public class ConstantWeapon : Weapon, IProgressBehavior, IEventBehavior, IPowerC
// Deactivate) before Entity.Update calls PowerBus.Step, so it is already current when this runs.
public float PowerRequest(float dt) => _firing && StanceAllowsFire ? Evaluate(_data.Energy) * dt : 0f;
// Cut 5 (docs/stats-and-power-cut.md §1.3, PowerTiers.cs): Low -- offense, same as InstantWeapon.
public int DefaultPowerTier => PowerTiers.Low;
public override bool Execute(float dt)
{
base.Execute(dt);

View file

@ -45,6 +45,10 @@ public class EnergyDraw : Behavior, IPowerConsumer
// direct Entity.TryConsumeEnergy spend that used to happen inside Execute.
public float PowerRequest(float dt) => Evaluate(_data.EnergyDraw) * (_data.PerSecond ? dt : 1);
// Cut 5 (docs/stats-and-power-cut.md §1.3, PowerTiers.cs): Utility -- the generic/unclassified draw. An item
// that declares power use without asking for a specific tier should not accidentally outrank a named one.
public int DefaultPowerTier => PowerTiers.Utility;
public override bool Execute(float dt)
{
// A consumable-hosted instance (Item null) has no PowerBus entry (§1.2's grants are keyed by

View file

@ -143,6 +143,10 @@ public class InstantWeapon : Weapon, IProgressBehavior, IEventBehavior, IPowerCo
return _capacitor.RequestedFill(dt);
}
// Cut 5 (docs/stats-and-power-cut.md §1.3, PowerTiers.cs): Low -- offense. The ruling's own example of what
// a reactor throttle should sacrifice first.
public int DefaultPowerTier => PowerTiers.Low;
// 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

View file

@ -70,6 +70,10 @@ public class Radiator : Behavior, IAlwaysUpdatedBehavior, IInitializableBehavior
return Evaluate(_data.EnergyUsage) * tempRatio * dt;
}
// Cut 5 (docs/stats-and-power-cut.md §1.3, PowerTiers.cs): Critical -- the closest thing this game has to
// life support. A starved radiator cascades into wear and shutdown across every other item on the hull.
public int DefaultPowerTier => PowerTiers.Critical;
public override bool Execute(float dt)
{
PumpedHeat = Evaluate(_data.PumpedHeat);

View file

@ -34,7 +34,7 @@ public class ReactorData : BehaviorData
}
}
public class Reactor : Behavior, IOrderedBehavior
public class Reactor : Behavior
{
private ReactorData _data;
@ -44,8 +44,9 @@ public class Reactor : Behavior, IOrderedBehavior
public float CurrentLoadRatio { get; private set; }
public int Order => 100;
// Cut 5 (docs/stats-and-power-cut.md §1.3): IOrderedBehavior/Order (was 100, the highest, so Reactor always
// ran last) is deleted -- the bus now steps before any equipment's Execute regardless of order, and nothing
// else claimed IOrderedBehavior, so the whole interface goes with its only implementer (§7 O3).
public Reactor(ReactorData data, EquippedItem item) : base(data, item)
{
_data = data;

View file

@ -100,6 +100,9 @@ public class Sensor : Behavior, IEventBehavior, IPowerConsumer
return _capacitor.RequestedFill(dt);
}
// Cut 5 (docs/stats-and-power-cut.md §1.3, PowerTiers.cs): Utility -- everything else.
public int DefaultPowerTier => PowerTiers.Utility;
public void Ping()
{
// Whole-or-nothing against the ping's own input capacitor -- fires only at full charge (operator

View file

@ -105,6 +105,10 @@ public class Shield : Behavior, IProgressBehavior, IPowerConsumer
return _reserve.RequestedFill(dt);
}
// Cut 5 (docs/stats-and-power-cut.md §1.3, PowerTiers.cs): High -- hull survival the player is actively
// trading power for, but not the life-support constant Radiator is, so it sits one tier below.
public int DefaultPowerTier => PowerTiers.High;
public override bool Execute(float dt)
{
Efficiency = Evaluate(_data.Efficiency);

View file

@ -76,6 +76,10 @@ public class Thruster : Behavior, IAnalogBehavior, IPowerConsumer
// PowerBus.Step, so it is already current when this runs.
public float PowerRequest(float dt) => _input > .01f ? _input * Evaluate(_data.EnergyUsage) : 0f;
// Cut 5 (docs/stats-and-power-cut.md §1.3, PowerTiers.cs): Medium -- mobility. Losing thrust for a tick
// under brownout is an inconvenience, not the cascading failure a starved radiator or shield causes.
public int DefaultPowerTier => PowerTiers.Medium;
public override bool Execute(float dt)
{
Item.SetAudioParameter(SpecialAudioParameter.Intensity, _input);

View file

@ -591,7 +591,7 @@ public abstract class Entity
}
Equipment.Remove(item);
_orderedEquipment = Equipment.OrderBy(x => x.SortPosition).ToArray();
_orderedEquipment = Equipment.ToArray();
var hullData = ItemManager.GetData(Hull) as HullData;
var itemData = ItemManager.GetData(item.EquippableItem);
@ -812,7 +812,7 @@ public abstract class Entity
}
Mass += itemData.Mass;
_orderedEquipment = Equipment.OrderBy(x => x.SortPosition).ToArray();
_orderedEquipment = Equipment.ToArray();
return true;
}
@ -1184,7 +1184,9 @@ public class ConsumableItemEffect : IStatContext
// entity and a running simulation behind it.
public class EquippedItem : IStatContext
{
public int SortPosition;
// SortPosition (Cut 3-era, only ever set by Reactor.Order) is deleted by Cut 5 (docs/stats-and-power-cut.md
// §1.3): "EquippedItem.SortPosition must no longer influence who is fed" -- the tiered allocation pass
// replaces it, and IOrderedBehavior/Reactor.Order go with it (§7 O3).
public EquippableItem EquippableItem;
public int2 Position;
@ -1339,11 +1341,19 @@ public class EquippedItem : IStatContext
foreach (var behavior in Behaviors)
{
if (behavior is IOrderedBehavior orderedBehavior)
SortPosition = orderedBehavior.Order;
if(behavior is IPopulationAssignment populationAssignment)
entity.PopulationAssignments.Add(populationAssignment);
}
// Cut 5 (docs/stats-and-power-cut.md §1.3, Q5 "defaulted per behaviour kind"): seed the stored tier
// exactly once, the first time this unit is ever equipped. A unit the player has already assigned a
// tier to (or one seeded on an earlier equip) keeps it -- this never runs again for that unit.
if (EquippableItem.PowerTier == PowerTiers.Unassigned)
{
var consumerTiers = Behaviors.OfType<IPowerConsumer>().Select(c => c.DefaultPowerTier).ToArray();
if (consumerTiers.Length > 0)
EquippableItem.PowerTier = consumerTiers.Min();
}
}
// Cut 2 (docs/stats-and-power-cut.md): the resolver owns the value; this is the caller's read of it, keyed by

View file

@ -52,6 +52,13 @@ public class EquippableItem : CraftedItemInstance
{
[JsonProperty("durability"), Key(7)] public float Durability;
[JsonProperty("override"), Key(8)] public bool OverrideShutdown;
// Cut 5 (docs/stats-and-power-cut.md §1.3, §0b "A power tier"): a player choice, stored on the unit rather
// than the design, so two units of the same design can be prioritized differently. PowerTiers.Unassigned
// until the first equip seeds a behaviour-kind default (EquippedItem's constructor) or the player overrides
// it from the schematic UI; from then on PowerBus only ever reads it, never derives it. An old run store
// missing key 12 deserializes to this same field initializer, so no migration is needed (§ Cut 5).
[JsonProperty("powerTier"), Key(12)] public int PowerTier = PowerTiers.Unassigned;
}
[MessagePackObject, JsonObject(MemberSerialization.OptIn)]

View file

@ -11,9 +11,14 @@ using static CultMath.math;
// Entity.TryConsumeEnergy/CanConsumeEnergy: at HEAD every draw succeeded as long as one reactor was online, and
// any shortfall was silently taxed onto the reactor as heat instead of ever being refused (§0.5). The bus makes
// the ceiling real: demand beyond what this tick's generation and stored capacitor charge can cover goes unmet.
// There are no tiers yet (Cut 5 adds them), so a shortfall rations the whole pool by the same fraction for every
// consumer alike -- the death of the old "whoever equipped first drains the capacitors first" hidden priority
// (§0.5), not a replacement for it.
//
// Cut 5 (docs/stats-and-power-cut.md §1.3) replaces the single shared fraction with priority tiers
// (PowerTiers.cs): the total this tick's supply can cover (TotalGrant, unchanged by tiers -- see below) is
// walked tier by tier, lowest number first. A tier is fed in full before the next tier sees anything left; a
// tier with no demand simply passes its whole share down; within a tier, every consumer's own request is
// rationed by the same fraction, so two requests of unequal size still divide proportionally. This is the death
// of the old "whoever equipped first drains the capacitors first" hidden priority (§0.5), replaced with an
// authored one instead of no priority at all.
//
// 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
@ -32,16 +37,34 @@ public class PowerBus
public float TotalGeneration { get; private set; }
public float TotalDemand { get; private set; }
// Energy actually delivered this tick: generation first, then whatever stored capacitor charge covers the
// rest, capped at demand. Equal to TotalDemand whenever supply covers it; equal to (generation + available
// charge) otherwise -- never more, which TryConsumeEnergy could never promise (a reactor always paid the
// remainder as heat, so overdraw was invisible at this level).
// Energy actually delivered this tick, summed across every tier: generation first, then whatever stored
// capacitor charge covers the rest, capped at demand. Equal to TotalDemand whenever supply covers it; equal
// to (generation + available charge) otherwise -- never more, which TryConsumeEnergy could never promise (a
// reactor always paid the remainder as heat, so overdraw was invisible at this level). Which consumers that
// total actually reaches is what tiering (below) decides; this figure is unaffected by tiers -- the ceiling
// is a property of supply, not of priority.
public float TotalGrant { get; private set; }
// Fraction of every consumer's own request actually granted this tick, shared by every consumer alike (no
// tiers yet). Also written onto every consuming EquippedItem.PowerSupply.
// Aggregate fraction of all demand granted this tick (TotalGrant / TotalDemand) -- a fleet-wide summary, not
// what any one consumer necessarily received. Still written onto every consuming EquippedItem.PowerSupply
// when every tier in play happens to land on the same ratio (single-tier loadouts, the common case in the
// Cut 3/4 test fixtures), but a multi-tier shortfall gives different tiers different ratios -- read
// TierGrantRatio or the item's own PowerSupply for that.
public float GrantRatio { get; private set; } = 1f;
// Cut 5: this tick's within-tier grant ratio, indexed by PowerTiers.Critical..Utility. 1f means that tier's
// demand was fully met (including a tier with no demand at all, per the array's own default-init); anything
// below 1f is exactly the "starved" state a future UI (Cut 8) reads instead of reconstructing it from
// per-item PowerSupply. A tier below a starved one is always 0f -- §1.3's "a tier boundary does not leak".
public float[] TierGrantRatio { get; } = InitFullTiers();
private static float[] InitFullTiers()
{
var ratios = new float[PowerTiers.Count];
for (var i = 0; i < ratios.Length; i++) ratios[i] = 1f;
return ratios;
}
// What Reactor.Execute reads to run its own heat/throttle arithmetic (Cut 3: "the arithmetic survives, moved
// under the bus's numbers"). Positive: demand left unmet after generation AND stored charge, split evenly
// across online reactors for overload heat. Negative: generation left over after demand and after topping up
@ -49,11 +72,22 @@ public class PowerBus
// a reported total, not a sink (§1.2).
public float NetDraw { get; private set; }
// One equipped item's power request for this tick, captured once so PowerRequest -- which some behaviours
// (Shield, InstantWeapon, Sensor) implement by refreshing their own cached stats -- is never called twice in
// one Step.
private readonly struct Draw
{
public readonly EquippedItem Item;
public readonly int Tier;
public readonly float Request;
public Draw(EquippedItem item, int tier, float request) { Item = item; Tier = tier; Request = request; }
}
public void Step(float dt)
{
var reactors = new List<Reactor>();
var capacitors = new List<Capacitor>();
var consumers = new List<IPowerConsumer>();
var draws = new List<Draw>();
foreach (var item in _entity.Equipment)
foreach (var behavior in item.Behaviors)
{
@ -67,11 +101,20 @@ public class PowerBus
break;
}
if (behavior is IPowerConsumer consumer)
consumers.Add(consumer);
{
// Cut 5 (docs/stats-and-power-cut.md §1.3): the item's own stored choice wins once it has one;
// PowerTiers.Unassigned only survives past EquippedItem's constructor for a consumer added to
// the game after this unit was minted, which the constructor never saw -- fall back to the
// behaviour's own default rather than stranding it at an invalid tier.
var tier = item.EquippableItem.PowerTier;
if (tier == PowerTiers.Unassigned) tier = consumer.DefaultPowerTier;
tier = clamp(tier, 0, PowerTiers.Count - 1);
draws.Add(new Draw(item, tier, max(0f, consumer.PowerRequest(dt))));
}
}
TotalGeneration = reactors.Sum(r => r.Generation(dt));
TotalDemand = consumers.Sum(c => max(0f, c.PowerRequest(dt)));
TotalDemand = draws.Sum(d => d.Request);
var availableCharge = capacitors.Sum(c => c.Charge);
var preCapacitorNet = TotalDemand - TotalGeneration;
@ -92,9 +135,33 @@ public class PowerBus
TotalGrant = TotalDemand - overload;
GrantRatio = TotalDemand <= 1e-4f ? 1f : saturate(TotalGrant / TotalDemand);
foreach (var item in _entity.Equipment)
if (item.Behaviors.Any(b => b is IPowerConsumer))
item.PowerSupply = GrantRatio;
AllocateTiers(draws);
}
// Cut 5 (docs/stats-and-power-cut.md §1.3): walks tiers lowest-number-first, feeding each in full before the
// next sees anything. remaining only ever shrinks, and once it hits 0 every later tier's ratio is 0 by the
// same division -- a lower tier can never take from a higher one (§1.3 "a tier boundary does not leak"),
// because a higher tier's share is committed (remaining -= grant) before a lower tier is even considered.
// Within a tier every consumer shares that tier's one ratio against its own request, so two unequal requests
// still divide proportionally -- the same property Cut 3 proved for the whole ship, now proved per tier.
private void AllocateTiers(List<Draw> draws)
{
var tierDemand = new float[PowerTiers.Count];
foreach (var draw in draws) tierDemand[draw.Tier] += draw.Request;
var remaining = TotalGrant;
var ratios = TierGrantRatio;
for (var tier = 0; tier < PowerTiers.Count; tier++)
{
var demand = tierDemand[tier];
if (demand <= 1e-4f) { ratios[tier] = 1f; continue; }
var grant = min(demand, remaining);
ratios[tier] = saturate(grant / demand);
remaining -= grant;
}
foreach (var draw in draws)
draw.Item.PowerSupply = ratios[draw.Tier];
}
// Mirrors Entity.TryConsumeEnergy's old do/while exactly (draw evenly across every capacitor that still has

View file

@ -0,0 +1,39 @@
/* 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/. */
// Cut 5 (docs/stats-and-power-cut.md §1.3, Q5: "four or five tiers, defaulted per behaviour kind"). Five tiers,
// numbered so the lowest number is fed first -- PowerBus's allocation pass walks 0..Count-1 in order. Naming
// them here, once, means IPowerConsumer.DefaultPowerTier implementations read as a sentence ("Radiator is
// Critical") instead of a bare integer repeated eight times.
//
// Assignment, per behaviour kind, and why:
// - Critical: Radiator. This game has no dedicated life-support behaviour, and heat is the closest thing to
// one -- a starved radiator does not just fail itself, it cascades into wear and eventual shutdown across
// every other item on the hull (EquippedItem.UpdatePerformance). Feed it first or lose the rest anyway.
// - High: Shield. Hull survival the player is actively trading power for; not a life-support constant, so it
// sits below Radiator rather than beside it.
// - Medium: Thruster, AetherDrive. Mobility -- needed to hold position, evade, or disengage, but a ship that
// loses thrust for a tick under brownout is inconvenienced, not dead the way an overheating hull is.
// - Low: ConstantWeapon, InstantWeapon. Offense. The ruling's own framing ("low-priority subsystems starve
// first") names weapons as the default example of what a reactor throttle should sacrifice first.
// - Utility: Sensor, EnergyDraw. Everything else, including the generic/unclassified draw -- an item that
// declares power use without asking for a specific tier should not accidentally outrank a named priority.
//
// A tier is a stored player choice once assigned (EquippableItem.PowerTier), not a derivation the bus repeats
// every tick (§1.3 "Derived state: nothing"). These defaults are read exactly once, in EquippedItem's
// constructor, to seed that stored field the first time an item without a chosen tier gets equipped.
public static class PowerTiers
{
public const int Critical = 0;
public const int High = 1;
public const int Medium = 2;
public const int Low = 3;
public const int Utility = 4;
public const int Count = 5;
// EquippableItem.PowerTier's sentinel for "the player has not chosen one and this item has never been
// equipped yet" -- distinct from 0 (Critical), which is a real, meaningful choice.
public const int Unassigned = -1;
}

View file

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