Merge origin/master into eureka/aetheria-release-link-rig-record

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

Assets/Editor/AetheriaBuild.cs

@@ -0,0 +1,106 @@
+using System;
+using System.Diagnostics;
+using System.IO;
+using System.Linq;
+using System.Text.RegularExpressions;
+using UnityEditor;
+using UnityEditor.AddressableAssets.Settings;
+using UnityEditor.Build.Reporting;
+using Debug = UnityEngine.Debug;
+
+// The one way to make a Win64 player directory. Owns what the directory contains: Aetheria.exe and its data,
+// GameData/Aetheria.cc, GameData/Narrative/**, GameData/Mods/** and ModTools/AetherDb. Manual builds, smokes and
+// release cuts all call this and stage nothing themselves.
+//
+//   Unity -batchmode -quit -projectPath <repo> -executeMethod AetheriaBuild.Build
+//         -aetheriaVersion <semver> -aetheriaOut <dir> -logFile <log>
+//
+// AetherDb is published from tools/AetherDb, so the headless build's CULTLIB_ROOT / CULTMATH_ROOT (Directory.Build.props)
+// must be set for dotnet when the defaults do not hold the pinned revisions.
+// Any failure logs "AetheriaBuild FAILED at <step>" and exits 1.
+public static class AetheriaBuild
+{
+    private static readonly Regex SemVer = new Regex(@"^\d+\.\d+\.\d+([-+][0-9A-Za-z.-]+)?$");
+
+    public static void Build()
+    {
+        var step = "arguments";
+        try
+        {
+            var version = Argument("-aetheriaVersion");
+            if (!SemVer.IsMatch(version)) throw new InvalidOperationException("-aetheriaVersion is not a semver");
+            var output = Path.GetFullPath(Argument("-aetheriaOut"));
+            var repoRoot = Directory.GetParent(UnityEngine.Application.dataPath).FullName;
+
+            step = "version";
+            UnityEditor.PlayerSettings.bundleVersion = version; // the game has its own global PlayerSettings
+
+            step = "addressables";
+            AddressableAssetSettings.BuildPlayerContent(out var content);
+            if (!string.IsNullOrEmpty(content.Error)) throw new InvalidOperationException("Addressables build reported an error: " + content.Error);
+
+            step = "player";
+            Directory.CreateDirectory(output);
+            var scenes = EditorBuildSettings.scenes.Where(scene => scene.enabled).Select(scene => scene.path).ToArray();
+            if (scenes.Length == 0) throw new InvalidOperationException("EditorBuildSettings has no enabled scene");
+            var report = BuildPipeline.BuildPlayer(new BuildPlayerOptions
+            {
+                scenes = scenes,
+                locationPathName = Path.Combine(output, "Aetheria.exe"),
+                target = BuildTarget.StandaloneWindows64,
+                options = BuildOptions.None,
+            });
+            if (report.summary.result != BuildResult.Succeeded || report.summary.totalErrors != 0)
+                throw new InvalidOperationException($"BuildPlayer ended {report.summary.result} with {report.summary.totalErrors} errors");
+
+            step = "gamedata";
+            PlayerStaging.Stage(repoRoot, output);
+
+            step = "aetherdb";
+            Publish(repoRoot, Path.Combine(output, "ModTools"));
+
+            step = "burst";
+            var burst = Path.Combine(output, "Aetheria_BurstDebugInformation_DoNotShip");
+            if (Directory.Exists(burst)) Directory.Delete(burst, true);
+
+            Debug.Log($"AetheriaBuild OK {version} {output}");
+        }
+        catch (Exception error)
+        {
+            Debug.LogError($"AetheriaBuild FAILED at {step}: {error.GetType().Name}: {error.Message}");
+            EditorApplication.Exit(1);
+            return;
+        }
+        EditorApplication.Exit(0);
+    }
+
+    private static void Publish(string repoRoot, string modTools)
+    {
+        var info = new ProcessStartInfo("dotnet")
+        {
+            Arguments = $"publish tools/AetherDb -c Release -r win-x64 --self-contained -p:PublishSingleFile=true -o \"{modTools}\"",
+            WorkingDirectory = repoRoot,
+            UseShellExecute = false,
+            RedirectStandardOutput = true,
+            RedirectStandardError = true,
+        };
+        using (var process = Process.Start(info))
+        {
+            var errors = process.StandardError.ReadToEndAsync();
+            var text = process.StandardOutput.ReadToEnd();
+            process.WaitForExit();
+            if (process.ExitCode != 0)
+                throw new InvalidOperationException($"dotnet publish exited {process.ExitCode}:\n{text}\n{errors.Result}");
+        }
+        if (!File.Exists(Path.Combine(modTools, "AetherDb.exe")))
+            throw new InvalidOperationException("dotnet publish produced no ModTools/AetherDb.exe");
+    }
+
+    private static string Argument(string name)
+    {
+        var args = Environment.GetCommandLineArgs();
+        var at = Array.IndexOf(args, name);
+        if (at < 0 || at + 1 >= args.Length) throw new InvalidOperationException(name + " is required");
+        return args[at + 1];
+    }
+}

Assets/Editor/AetheriaBuild.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: d38caad223051494ba36c734ce79950d

Assets/Editor/PlayerStaging.cs

@@ -0,0 +1,42 @@
+using System;
+using System.IO;
+
+// What a player directory holds beside the executable's data: GameData/Aetheria.cc, GameData/Narrative/** and, when
+// the repo has one, GameData/Mods/**. Nothing else under GameData ships (run.cc and player.cc are the player's own;
+// SoundbanksInfo.json is read by no code). Unity-free so the headless suite can prove the rules; AetheriaBuild is the
+// only caller.
+internal static class PlayerStaging
+{
+    public const string Catalog = "Aetheria.cc";
+    public const string Narrative = "Narrative";
+    public const string Mods = "Mods";
+
+    // Replaces <playerDir>/GameData with a copy of the three shipped entries of <repoRoot>/GameData.
+    // Throws InvalidOperationException naming the entry when the catalog or Narrative is absent.
+    public static void Stage(string repoRoot, string playerDir)
+    {
+        var source = Path.Combine(repoRoot, "GameData");
+        var destination = Path.Combine(playerDir, "GameData");
+        var catalog = Path.Combine(source, Catalog);
+        var narrative = Path.Combine(source, Narrative);
+        var mods = Path.Combine(source, Mods);
+
+        if (!File.Exists(catalog)) throw new InvalidOperationException($"GameData/{Catalog} is missing; a player never ships without its catalog.");
+        if (!Directory.Exists(narrative)) throw new InvalidOperationException($"GameData/{Narrative} is missing.");
+
+        if (Directory.Exists(destination)) Directory.Delete(destination, true);
+        Directory.CreateDirectory(destination);
+        File.Copy(catalog, Path.Combine(destination, Catalog));
+        CopyTree(narrative, Path.Combine(destination, Narrative));
+        if (Directory.Exists(mods)) CopyTree(mods, Path.Combine(destination, Mods));
+    }
+
+    private static void CopyTree(string from, string to)
+    {
+        Directory.CreateDirectory(to);
+        foreach (var directory in Directory.GetDirectories(from, "*", SearchOption.AllDirectories))
+            Directory.CreateDirectory(Path.Combine(to, directory.Substring(from.Length + 1)));
+        foreach (var file in Directory.GetFiles(from, "*", SearchOption.AllDirectories))
+            File.Copy(file, Path.Combine(to, file.Substring(from.Length + 1)));
+    }
+}

Assets/Editor/PlayerStaging.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: 16dce8087f9149b44b6e294cb0851dd8

Assets/Scripts/ServerShared/AetheriaStores.cs

@@ -1,4 +1,5 @@
 using System;
+using System.IO;
 using System.Linq;
 using GameCult.Caching;
 using GameCult.Caching.MessagePack;
@@ -15,6 +16,9 @@ public static class AetheriaStores
     // no records at all, a seed store being authored from nothing; a populated catalog is held to it however it opens.
     public static CultCache Open(string catalogPath, string runPath = null, string playerPath = null, bool catalogWritable = false)
     {
+        // A read-only open of an absent catalog would hydrate an empty game; a shipped player missing its catalog stops here.
+        if (!catalogWritable && !File.Exists(catalogPath))
+            throw new FileNotFoundException($"Catalog {catalogPath} does not exist; a read-only open never invents one.", catalogPath);
         var cache = new CultCache();
         try
         {

Assets/Scripts/ServerShared/Behaviors/Behaviors.cs

@@ -187,6 +187,8 @@ public interface IPowerConsumer
  // superseded draft quoted -- checked directly here rather than trusted from that document.
  Union(39, typeof(TargetingSystemData)),
  Union(40, typeof(MineLayerData)),
+ Union(41, typeof(ThrottleLockData)),
+ Union(42, typeof(VapourDumpData)),
  JsonObject(MemberSerialization.OptIn)]
 public abstract class BehaviorData
 {

Assets/Scripts/ServerShared/Behaviors/Sensor.cs

@@ -160,17 +160,18 @@ public class Sensor : Behavior, IEventBehavior, IPowerConsumer
 
             var diff = entity.Position.xz - Entity.Position.xz;
             var dist = length(diff);
+            var obscuration = Entity.Zone.Obscuration(Entity.Position.xz, entity.Position.xz);
             float previous, next;
             Entity.EntityInfoGathered.TryGetValue(entity, out previous);
             if (!_pingedEntities.Contains(entity) && dist < _pingRadius)
             {
                 _pingedEntities.Add(entity);
-                next = saturate(previous + Gain(entity.Visibility, Evaluate(_data.Sensitivity), Evaluate(_data.PingBoost), dist, dt, true));
+                next = saturate(previous + Gain(entity.Visibility, Evaluate(_data.Sensitivity), Evaluate(_data.PingBoost), dist, dt, true, obscuration));
             }
             else
             {
                 var angle = acos(dot(forward, normalize(diff)));
-                next = saturate(previous + Gain(entity.Visibility, Evaluate(_data.Sensitivity), _data.SensitivityCurve.Evaluate(angle / PI), dist, dt, false));
+                next = saturate(previous + Gain(entity.Visibility, Evaluate(_data.Sensitivity), _data.SensitivityCurve.Evaluate(angle / PI), dist, dt, false, obscuration));
             }
             next *= 1 - ItemManager.GameplaySettings.TargetInfoDecay * dt;
             //Context.Log($"{entity.Name} visibility {(int)(previous * 100)}% -> {(int)(next * 100)}%");
@@ -182,12 +183,14 @@ public class Sensor : Behavior, IEventBehavior, IPowerConsumer
     // Mining Cut 3 (docs/mining-cut-refresh.md): the one detection gain rule -- the info one observation of a
     // target adds. A ping adds `visibility × sensitivity × PingBoost × distance` once; a passive tick adds
     // `visibility × sensitivity × curve(angle/π) × dt / distance`. `response` is PingBoost for a ping and the
-    // sensitivity curve at the bearing for a passive tick. The entity loop above and the chunk query
-    // (Entity.ChunkInfo, through PassiveRate) both call this; nothing else multiplies these terms.
-    public static float Gain(float visibility, float sensitivity, float response, float distance, float dt, bool ping) =>
-        ping
+    // sensitivity curve at the bearing for a passive tick. `obscuration` is the fraction of the signal that
+    // survives the vapour clouds on the sight line (Zone.Obscuration, 1f with none), scaling both. The entity
+    // loop above and the chunk query (Entity.ChunkInfo, through PassiveRate) both call this; nothing else
+    // multiplies these terms.
+    public static float Gain(float visibility, float sensitivity, float response, float distance, float dt, bool ping, float obscuration) =>
+        (ping
             ? visibility * sensitivity * response * distance
-            : visibility * sensitivity * response * dt / distance;
+            : visibility * sensitivity * response * dt / distance) * obscuration;
 
     // The passive gain per second this sensor draws from a target of `visibility` at the planar `position`:
     // Gain over one second, with the bearing measured from this sensor's own facing exactly as Execute does.
@@ -195,7 +198,8 @@ public class Sensor : Behavior, IEventBehavior, IPowerConsumer
     {
         var diff = position - Entity.Position.xz;
         var angle = acos(dot(Direction.xz, normalize(diff)));
-        return Gain(visibility, Evaluate(_data.Sensitivity), _data.SensitivityCurve.Evaluate(angle / PI), length(diff), 1f, false);
+        return Gain(visibility, Evaluate(_data.Sensitivity), _data.SensitivityCurve.Evaluate(angle / PI), length(diff), 1f, false,
+            Entity.Zone.Obscuration(Entity.Position.xz, position));
     }
 
     // An upper bound on sensitivity x response over every bearing, so PassiveRate(v, p) <= v x this / distance

Assets/Scripts/ServerShared/Behaviors/ThrottleLock.cs

@@ -0,0 +1,35 @@
+/* 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 MessagePack;
+using Newtonsoft.Json;
+
+// Presence marks the lock: Entity.ThrottleLocked is true while an active effect carries one, and Ship.Update
+// then reads full forward intent in place of MovementDirection. The behaviour holds no state and does nothing
+// itself; turning stays with the pilot.
+[Inspectable, MessagePackObject, JsonObject(MemberSerialization.OptIn), RuntimeInspectable]
+public class ThrottleLockData : BehaviorData
+{
+    public override Behavior CreateInstance(EquippedItem item)
+    {
+        return new ThrottleLock(this, item);
+    }
+    public override Behavior CreateInstance(ConsumableItemEffect item)
+    {
+        return new ThrottleLock(this, item);
+    }
+}
+
+public class ThrottleLock : Behavior
+{
+    public ThrottleLock(ThrottleLockData data, EquippedItem item) : base(data, item)
+    {
+    }
+
+    public ThrottleLock(ThrottleLockData data, ConsumableItemEffect item) : base(data, item)
+    {
+    }
+
+    public override bool Execute(float dt) => true;
+}

Assets/Scripts/ServerShared/Behaviors/VapourDump.cs

@@ -0,0 +1,61 @@
+using MessagePack;
+using Newtonsoft.Json;
+
+// A coolant dump that becomes a vapour cloud: the first time it runs it vents one cloud around its venter,
+// drifting with the venter's velocity. Radius, Opacity and Lifetime are evaluated through the host, so role
+// quality applies as for any other stat. Later runs vent nothing.
+[Inspectable, MessagePackObject, JsonObject(MemberSerialization.OptIn), RuntimeInspectable]
+public class VapourDumpData : BehaviorData
+{
+    [Inspectable, JsonProperty("radius"), Key(1), RuntimeInspectable]
+    public PerformanceStat Radius = new PerformanceStat();
+
+    // How much of a sight line's signal a fresh cloud removes, in [0, 1].
+    [Inspectable, JsonProperty("opacity"), Key(2), RuntimeInspectable]
+    public PerformanceStat Opacity = new PerformanceStat();
+
+    // Seconds from venting until the cloud has faded away and is removed.
+    [Inspectable, JsonProperty("lifetime"), Key(3), RuntimeInspectable]
+    public PerformanceStat Lifetime = new PerformanceStat();
+
+    public override Behavior CreateInstance(EquippedItem item)
+    {
+        return new VapourDump(this, item);
+    }
+
+    public override Behavior CreateInstance(ConsumableItemEffect item)
+    {
+        return new VapourDump(this, item);
+    }
+}
+
+public class VapourDump : Behavior
+{
+    private VapourDumpData _data;
+    private bool _vented;
+
+    public VapourDump(VapourDumpData data, EquippedItem item) : base(data, item)
+    {
+        _data = data;
+    }
+
+    public VapourDump(VapourDumpData data, ConsumableItemEffect item) : base(data, item)
+    {
+        _data = data;
+    }
+
+    public override bool Execute(float dt)
+    {
+        if (_vented) return true;
+        _vented = true;
+        Entity.Zone.Vent(new VapourCloud
+        {
+            Body = new KinematicBody { Position = Entity.Position.xz, Velocity = Entity.Velocity },
+            Radius = Evaluate(_data.Radius),
+            Opacity = Evaluate(_data.Opacity),
+            Lifetime = Evaluate(_data.Lifetime),
+            Venter = Entity
+        });
+        return true;
+    }
+}

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

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

Assets/Scripts/ServerShared/Entity.cs

@@ -203,12 +203,10 @@ public abstract class Entity
             return presencePermitted;
         }), initialValue: true);
         
-        foreach (var item in Equipment)
-        foreach (var behavior in item.Behaviors)
-        {
-            if(behavior is IInitializableBehavior initializableBehavior)
-                initializableBehavior.Initialize();
-        }
+        // One initialiser for everything that computes targets here: gear and the effects still running, so a
+        // consumable active across a refit retargets to the new items exactly as gear does.
+        InitializeBehaviors(Equipment.SelectMany(item => item.Behaviors));
+        InitializeBehaviors(_activeConsumables.SelectMany(effect => effect.Behaviors));
         foreach(var entity in Zone.Entities)
         {
             EntityInfoGathered[entity] = 0;
@@ -860,9 +858,23 @@ public abstract class Entity
 
     public void ActivateConsumable(ConsumableItem item)
     {
-        _activeConsumables.Add(new ConsumableItemEffect(item, this));
+        var effect = new ConsumableItemEffect(item, this);
+        // The same hook Activate runs over Equipment: a behaviour that computes its targets there (StatModifier)
+        // would otherwise reach its second tick uninitialised.
+        InitializeBehaviors(effect.Behaviors);
+        _activeConsumables.Add(effect);
     }
 
+    private static void InitializeBehaviors(IEnumerable<Behavior> behaviors)
+    {
+        foreach (var behavior in behaviors.ToList())
+            if (behavior is IInitializableBehavior initializable)
+                initializable.Initialize();
+    }
+
+    // Derived, never written: true iff an active consumable effect carries a ThrottleLock.
+    public bool ThrottleLocked => _activeConsumables.Any(e => e.Behaviors.OfType<ThrottleLock>().Any());
+
     public ConsumableItemEffect FindActiveConsumable(ConsumableItemData data)
     {
         return _activeConsumables.FirstOrDefault(ac => ac.Data == data);
@@ -1448,11 +1460,16 @@ public abstract class Entity
             for (var i = 0; i < _activeConsumables.Count; i++)
             {
                 _activeConsumables[i].Update(delta);
-                if (_activeConsumables[i].RemainingDuration < 0)
+                if (_activeConsumables[i].RemainingDuration <= 0)
                 {
                     // Cut 2 Gate 1 fix (docs/stats-and-power-cut.md): an expired consumable dropped out of this
                     // list without ever telling the resolver, leaving its generation/cache/modifier entries
                     // reachable (keyed by this ConsumableItemEffect instance) for the rest of the process.
+                    // A StatModifier's attachments are keyed by its target items, not by the effect, so Forget alone
+                    // leaves a boost attached to its targets: dispose each behaviour first.
+                    foreach (var behavior in _activeConsumables[i].Behaviors)
+                        if (behavior is IDisposable disposable)
+                            disposable.Dispose();
                     Resolver.Forget(_activeConsumables[i]);
                     _activeConsumables.RemoveAt(i--);
                 }

Assets/Scripts/ServerShared/ItemManager.cs

@@ -183,6 +183,9 @@ public class ItemManager
             };
         }
 
+        if (design is ConsumableItemData)
+            return new ConsumableItem { Data = l.Design, Lot = lot };
+
         return new CompoundCommodity
         {
             Data = l.Design, Lot = lot

Assets/Scripts/ServerShared/Ship.cs

@@ -233,27 +233,29 @@ public class Ship : Entity
         if (_active && !_exitingWormhole && !_enteringWormhole)
         {
             RecalculateThrust();
+            // The lock replaces intent here, once; player and agent intent both pass through this one read.
+            var move = ThrottleLocked ? float2(0, 1) : MovementDirection;
             foreach (var thruster in _allThrusters) thruster.Axis = 0;
             var rightThrusterTorqueCompensation = abs(RightStrafeTotalTorque) / RightStrafeTorqueThrusters.Count;
             foreach (var thruster in _rightThrusters)
             {
                 var thrust = 0f;
-                thrust += MovementDirection.x;
+                thrust += move.x;
                 if (RightStrafeTorqueThrusters.Contains(thruster))
-                    thrust -= MovementDirection.x * (rightThrusterTorqueCompensation / (abs(thruster.Torque) * thruster.Thrust));
+                    thrust -= move.x * (rightThrusterTorqueCompensation / (abs(thruster.Torque) * thruster.Thrust));
                 thruster.Axis = thrust;
             }
             var leftThrusterTorqueCompensation = abs(LeftStrafeTotalTorque) / LeftStrafeTorqueThrusters.Count;
             foreach (var thruster in _leftThrusters)
             {
                 var thrust = 0f;
-                thrust += -MovementDirection.x;
+                thrust += -move.x;
                 if (LeftStrafeTorqueThrusters.Contains(thruster))
-                    thrust += MovementDirection.x * (leftThrusterTorqueCompensation / (abs(thruster.Torque) * thruster.Thrust));
+                    thrust += move.x * (leftThrusterTorqueCompensation / (abs(thruster.Torque) * thruster.Thrust));
                 thruster.Axis = thrust;
             }
-            foreach (var thruster in _forwardThrusters) thruster.Axis += MovementDirection.y;
-            foreach (var thruster in _reverseThrusters) thruster.Axis += -MovementDirection.y;
+            foreach (var thruster in _forwardThrusters) thruster.Axis += move.y;
+            foreach (var thruster in _reverseThrusters) thruster.Axis += -move.y;
 
             foreach (var thruster in _clockwiseThrusters) thruster.Axis += Turn;
             foreach (var thruster in _counterClockwiseThrusters) thruster.Axis += -Turn;

Assets/Scripts/ServerShared/StatResolver.cs

@@ -141,6 +141,9 @@ public class StatResolver
         {
             set.Scale.Remove(modifierKey);
             set.Constant.Remove(modifierKey);
+            // An entry with nothing attached is no entry: a modifier that is gone leaves no trace in the resolver.
+            if (set.Scale.Count == 0 && set.Constant.Count == 0)
+                _modifiers.Remove(entry);
         }
         _cache.Remove(entry);
     }

Assets/Scripts/ServerShared/VapourClouds.cs

@@ -0,0 +1,32 @@
+using CultMath;
+using static CultMath.math;
+using float2 = CultMath.float2;
+
+// A vented vapour cloud: a free-floating disc that thins every sensor sight line through it. Not an Entity,
+// never priced or rolled, never saved. Zone.Vent is the only adder and Zone's cloud step the only remover;
+// Zone.Obscuration is the one reader detection uses.
+public sealed class VapourCloud
+{
+    public FloatingBodyId Id;
+    public KinematicBody Body;
+    public double VentedAt;
+    public float Lifetime;
+    public float Radius;
+    // The opacity at the moment of venting; it fades linearly to nothing over Lifetime.
+    public float Opacity;
+    public Entity Venter;
+
+    // A cloud with no lifetime divides by zero; saturate maps the NaN and the infinity to nothing left.
+    public float OpacityAt(double now) =>
+        saturate(Opacity) * saturate(1f - (float) (now - VentedAt) / Lifetime);
+
+    // Whether the segment a-b reaches the disc: the closest point of the segment to the centre lies within the
+    // radius. A cloud past either end of the segment touches it only if it is near that end.
+    public bool Touches(float2 a, float2 b)
+    {
+        var ab = b - a;
+        var length2 = lengthsq(ab);
+        var t = length2 > 0f ? saturate(dot(Body.Position - a, ab) / length2) : 0f;
+        return lengthsq(Body.Position - (a + ab * t)) <= Radius * Radius;
+    }
+}

Assets/Scripts/ServerShared/VapourClouds.cs.meta

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

Assets/Scripts/ServerShared/Zone.cs

@@ -20,6 +20,10 @@ public class Zone
     // Laid mines, in lay order. Zone owns their existence: Lay is the one adder, the mine step the one remover,
     // and every removal is a blast. Runtime state, never saved.
     public ReactiveCollection<Mine> Mines = new ReactiveCollection<Mine>();
+
+    // Vented vapour clouds, in vent order. Zone owns their existence: Vent is the one adder, StepClouds the one
+    // remover, and Obscuration the one reader that detection uses. Runtime state, never saved.
+    public ReactiveCollection<VapourCloud> Clouds = new ReactiveCollection<VapourCloud>();
     public Dictionary<CultRecordKey, BodyData> Planets = new Dictionary<CultRecordKey, BodyData>();
     public Dictionary<CultRecordKey, Planet> PlanetInstances = new Dictionary<CultRecordKey, Planet>();
 
@@ -225,6 +229,7 @@ public class Zone
         foreach (var entity in Entities.ToArray()) entity.Update(deltaTime);
 
         StepMines(deltaTime);
+        StepClouds(deltaTime);
 
         // Cut 3: after every entity has had its chance to fire this tick, age and resolve the shots that
         // firing queued. A shot fired this tick with a flight time shorter than CommitHorizon commits and
@@ -238,6 +243,39 @@ public class Zone
         Mines.Add(mine);
     }
 
+    public void Vent(VapourCloud cloud)
+    {
+        cloud.Id = NextBodyId();
+        cloud.VentedAt = _time;
+        Clouds.Add(cloud);
+    }
+
+    // The fraction of a sight line's signal that survives the clouds between `a` and `b`: the product of
+    // (1 - opacity now) over every cloud whose disc the segment touches, so 1f when none does. Derived from the
+    // live clouds at each call and stored nowhere; Sensor.Gain is where it enters detection.
+    public float Obscuration(float2 a, float2 b)
+    {
+        var through = 1f;
+        for (var i = 0; i < Clouds.Count; i++)
+        {
+            var cloud = Clouds[i];
+            if (cloud.Touches(a, b)) through *= 1f - cloud.OpacityAt(_time);
+        }
+        return through;
+    }
+
+    // After StepMines: each cloud drifts as a KinematicBody on the zone's force, as a mine does, and is removed
+    // once its lifetime has run out. Nothing else removes a cloud.
+    private void StepClouds(float deltaTime)
+    {
+        var settings = _itemManager.GameplaySettings;
+        foreach (var cloud in Clouds.ToArray())
+        {
+            cloud.Body.Step(deltaTime, GetForce(cloud.Body.Position), settings);
+            if (cloud.VentedAt + cloud.Lifetime <= _time) Clouds.Remove(cloud);
+        }
+    }
+
     // After the entity loop and before FireControl.Step, in lay order: each mine drifts as a KinematicBody, is
     // triggered by the first eligible hull its armed disc touches, and detonates through FireControl.Detonate at
     // its trigger plus fuse delay or at its lifetime, whatever its layer does (ruling mine-owner-leash). The

docs/aetheria-release-map.md

@@ -7623,3 +7623,149 @@ retire-firing-arc r1, ships-addon-link-rows r1; link-rig-record r3; ships-addon-
 `mind-commit-0c23fa01...` (ships-addon-link-package r2, link-rig-presenter r2, link-calibre-judge r2, question
 `hardpoint-arc-caps`, withdrew question `calibre-arc-caps`) and `mind-commit-40788d58...` (ships-addon-link-package r3,
 r2's arm smoke pins fixed). context-pack read every anchor SAME at `acea1aa7`.
+
+## Vectored thruster rows
+
+Pass: Imagination (`imagination-aeth-vectoring`), session `self-2026-10-10-ag`. Body: `GameCult/Aetheria` origin/master
+`30d02719`; the allocator at `1fc98bdc` (branch `eureka/aetheria-release-thrust-allocator-core`, read-only, a fix
+batch in flight); the rig record at `562de34c` (branch `eureka/aetheria-release-link-rig-record`, Soul pass running);
+CultMath `BoundedLeastSquares` at CultLib origin/main `50512e6e`. One design owns follow-ups `vectored-thruster-rows`
+(operator: "if that dine and dash could tilt that vector for each row of thrusters it would be even more hyper
+maneuverable"; a gimbal per row, not per thruster) and `gimballed-thrusters`. Prior art:
+`docs/research/thrust-vectoring-prior-art.md` at `30d02719` (cited as VP, by section).
+
+### Body facts
+
+- **V1. A column is linear in the push direction.** The allocator's column is xy = push * thrust / mass and
+  z = `Torque` * thrust * `TorqueMultiplier` / mass (spec `cut-thrust-allocator.r1`, adds; `ThrustAllocator.cs:8-18`
+  at `1fc98bdc`). `Torque` is `-dot(normalize(toCenter), float2(1,0).Rotate(rotation))` (`Thruster.cs:62-71`), linear
+  in the direction vector. So a thruster tilted by angle a has column c(a) = cos a * c(0) + sin a * c(pi/2): two fixed
+  columns per thruster carry every tilt. This is VP 1.1's virtual-actuator trick, exact for Aetheria's planar plant.
+- **V2. BoundedLeastSquares has box bounds only** (`BoundedLeastSquares.cs`, CultLib `50512e6e`: `lo <= x <= hi`,
+  dense primal active set, iteration cap 100, warm start in `x`). A gimbal wedge |v| <= tan(theta) u is not a box
+  (VP 2). The design below never needs the wedge: the per-tick slew window in the row's own frame is narrow (3 deg at
+  90 deg/s and 30 Hz, 12 deg at 360 deg/s), so v is boxed by the sine of the window and the recovered angle is
+  clamped to the window and the gimbal. No CultMath capability is missing, so no cultlib-gaps follow-up.
+- **V3. The sim already has the data seam.** `HardpointData.FiringArc` (key 6) is the hardpoint's arc
+  (`ItemData.cs:567-569`); `EquippedItem.Hardpoint` gives a behaviour its hardpoint (`Entity.cs:1688`, read by
+  `FireControl.ArcFor`, `FireControl.cs:36-41`). `HardpointData` uses keys 0-6; `ThrusterData` keys 1-5
+  (`Thruster.cs:12-27`; `BehaviorData` owns key 0). At `562de34c` the judge refuses a `thruster-emitter` anchor on a
+  joint, naming follow-up `gimballed-thrusters` (`ShipAuthoring.cs:360-363`), and checks that weapon mounts on one
+  joint share `Rotation` and `FiringArc` and that the chain's yaw reach covers the arc (`:370-385`).
+- **V4. The gimbal is a sim fact.** By V1 the angle changes push and turn, which the allocator and the evasion
+  envelope read. In V6, fixed rows leave forward and reverse at E 0.361 on the small hull; tilting rows take both to
+  0.000. So the row angle, its limit and its slew are simulation state and stats (target invariant `sim-owns-facts`);
+  the joint only draws `Thruster.Angle` (rulings `rig-is-presentation`, `mount-arc-gun-traverse`).
+- **V5. Probe harness.** Scratch C# console at `scratchpad/imagination-aeth-vectoring/harness` (local commit
+  `b5162ab`, then a v2 that fixed M4's scoring and added M3c and M5), `Program.cs` plus a verbatim copy of
+  `BoundedLeastSquares.cs` from `50512e6e`, run on Yggdrasil through `ygg-verify.sh` (`dotnet run -c Release`, image
+  `mcr.microsoft.com/dotnet/sdk:10.0`), 2026-10-10, exit 0 both runs (`run1.log`, `run2.log` beside it). The core
+  solve copies `ThrustAllocator` at `1fc98bdc` exactly (weights 100 and 1000, L1 split error variables, ridge 0.1,
+  KKT 1e-12, cap 100); every method shares it and shares one demand scale (V7). Hulls: *small*, two mains (accel 10)
+  and two side rows of four (accel 2, pushing across the hull, gimbal +-45 deg); *large*, four mains and four rows of
+  eight (36 thrusters). 30 Hz, 90 ticks per intent from rows at 0, 12 intents (full strafes, forward, reverse, two
+  diagonals, full turns, forward plus turn, strafe plus half turn, two partial). E is the realized wrench's error
+  against the demand, normalised per axis by the box extreme. REF is a brute-force grid over both row angles
+  (37 x 37, no slew limit) with the fixed-column solve inside, minimum weighted error.
+- **V6. Results** (mean E over the 12 intents after 90 ticks; worst single solve's iterations; us per tick on
+  Yggdrasil):
+
+  | Method | small 90 deg/s | small 360 deg/s | large 90 deg/s | solves/tick | worst iters (large) | us/tick (large) |
+  |---|---|---|---|---|---|---|
+  | REF grid (static optimum, shared row angle) | 0.134 | 0.134 | n/a | 1369 | n/a | n/a |
+  | M0 fixed rows (today) | 0.298 | 0.298 | 0.310 | 1 | 95 | 36 |
+  | M1 row as one actuator: shared throttle, (u, v) in the row frame, slew-boxed | 0.142 | 0.138 | 0.133 | 1 | 20 | 3 |
+  | M2 cascade: per-thruster (u, v), one angle per row, re-solve | 0.137 | 0.131 | 0.131 | 2 | 95 | 267 |
+  | M3 angle step linearised at last tick's throttles, one solve | 0.201 | 0.196 | 0.215 | 1 | 95 | 74 |
+  | M3c as M3, idle rows linearised at throttle .25 | 0.138 | 0.136 | 0.132 | 1 | 100 (2 IterationLimit) | 79 |
+  | M5 M1's angle, then per-thruster re-solve | 0.142 | 0.138 | 0.131 | 2 | 95 | 44 |
+  | M4 per-thruster gimbals (no row constraint; upper bound) | 0.138 | 0.135 | 0.129 | 1 | 89 | 328 |
+
+  No method produced NaN. M1, M2, M3c, M4 and M5 reach E 0.000 on forward and reverse (M0 and M3: 0.361). The large
+  hull's 95-iteration solves are the fixed per-thruster solve itself (M0 is also 95): finding
+  `cut-thrust-allocator-core.s1.large-hull-degradation`, follow-up `allocator-large-hull`. M1 collapses each row to
+  two variables (12 on the large hull instead of 36) and stays at 20 iterations, which is the "group identical
+  columns" remedy that follow-up names, arrived at for free.
+- **V7. The demand scale must be the gimbal reach.** The allocator scales intent by box extremes it sums from the
+  columns it is given (`ThrustAllocator.cs:44-61`). With rows tilting, current-column extremes move every tick, so
+  "full forward" would change meaning as the rows swing. The probe scales by the reach: per thruster and half-axis,
+  the maximum of A cos a + B sin a over the gimbal (closed form: sqrt(A^2 + B^2) when atan2(B, A) lies inside the arc,
+  else the better end). Small hull: +y 31.3 (mains 20, eight row thrusters 2 sin 45 deg each), -y 11.3, +-x 8.0,
+  +-z 12.53. The same reach is the envelope's box (cut `envelope-from-columns`), so intent and evasion read one
+  geometry.
+- **V8. Zero thrust: hold the angle, but never linearise through the throttle.** Schedule strafe right, idle, strafe
+  left, forward, idle, reverse, 30 ticks each, both hulls, 90 deg/s. M1 and M5: every step within the window (3.00
+  deg max), idle drift 0.000 deg, idle throttle 0, no sign flips in the late half of any phase, and reverse ends at
+  -45/45 (correct). M2: one or two late sign flips, and 3 deg of idle drift on the large hull (its stage one aims
+  idle rows with v alone). M3 is trapped: a row at zero throttle has a zero angle column, so it never tilts, forward
+  stays at E 0.361 and reverse ends at 45/-45 (the wrong way). M3c unsticks it but chatters (15 late flips), fires
+  at full throttle while idle on the large hull and hits the cap. Holding the previous angle when the row's (u, v)
+  is near zero (|(u, v)| < 1e-6) is enough once (u, v) are free variables: v can aim an idle row without thrust, and
+  the box's overcount is useful there.
+
+### Model page rows
+
+| Kind | Identity | Lifecycle | Authority |
+|---|---|---|---|
+| Gimbal limit (`HardpointData.FiringArc`, key 6, on a `Thruster` hardpoint; question `vector-row-data-home`) | The hardpoint's mount id (`Transform`) on its hull. Full width in degrees, as for a gun; the row swings +-FiringArc/2 about `Rotation`. 0 is a fixed thruster; thrusters get no `GameplaySettings.FiringArc` fallback. | Authored per hull with the other hardpoint fields; Save or Package writes it; a package edit changes it on Continue (moves no cell). | The ship author. The judge requires every member of a row to share it and the row's joint chain to reach it. The thruster reads it at activation. |
+| Row (`HardpointData.Row`, new key 7, string) | Unique within its hull; empty means not in a row. A `Thruster` hardpoint with `FiringArc` > 0 and no `Row` is a row of one. | Authored per hull; renaming a row changes no save (no save names a row; ruling `no-save-compatibility-before-players`). | The ship author. Judge: only on `Thruster` hardpoints; members share `Rotation` and a `FiringArc` > 0. Never derived from a joint (ruling `rig-is-presentation`). |
+| Slew rate (`ThrusterData.Slew`, new key 6, `PerformanceStat`, deg/s) | A stat of the thruster design. | Authored per design; heat, durability and quality move it live like `Thrust`. A row slews at its slowest live member. | The gear designer, as a weapon's traverse is (ruling `mount-arc-gun-traverse`). |
+| Live row angle (`Thruster.Angle`, runtime) | The thruster behaviour; every member of a row holds the same value. Radians from the hardpoint's `Rotation`. | 0 at `Activate`; moves at most slew x dt per tick; held while the row is idle; never saved (a load restarts at 0). | `ThrustAllocator` decides it; `Ship.Update` is its one writer. `Execute`, the envelope and presentation read it. The rig draws it and never writes it. |
+| Row actuator (runtime) | The row, built at `Activate` from its members' hardpoints. | Rebuilt when the thruster set changes (the allocator's resize rule). A dead member's columns are zero, so the row keeps steering with the rest. | `ThrustAllocator` reads the summed along and across columns and the slew window, and decides one throttle and one angle step per row. |
+
+### Authority map
+
+- **Owner.** `ThrustAllocator` decides every fixed thruster's throttle and every row's throttle and angle step, in one
+  `BoundedLeastSquares` solve (question `vector-row-formulation`, recommended `shared-throttle-row`).
+- **Inputs.** Intent (unchanged); each fixed thruster's column; per row, the summed column along and across its live
+  angle and its slew window [max(-arc/2 - angle, -slew dt), min(arc/2 - angle, slew dt)]; the reach (V7).
+- **Outputs.** `Thruster.Axis` for every thruster (a row's members share the row's) and `Thruster.Angle` for every
+  row member, read by `Execute`, `PowerRequest`, the envelope and presentation.
+- **Derived.** The reach and the envelope (one helper); a row's summed columns; the slew window.
+- **No longer owners.** `Allocate` no longer sums its box extremes from the current columns; they come from the reach
+  helper. A joint, its limits and the IK pose decide nothing in the sim.
+- **Forbidden writers.** Any `Angle` write outside `Ship.Update`; any read of `ShipJoint`, `ShipAnchor.Joint` or a
+  Unity transform in `Thruster`, `Ship` or `ThrustAllocator`; a second throttle solve or fallback mixer; an angle step
+  linearised through last tick's throttles (M3, V8).
+- **Shared paths.** Player helm, agents, the throttle lock and tests reach rows only through intent.
+  `Thruster.Column(angle)` is the one geometry function `Execute`, the allocator and the envelope call.
+
+### Rationale
+
+- **Why one actuator per row.** M1 matches M5 (per-member throttles after the same angle) within 0.002 mean E on all
+  three sweeps, is within 0.008 of the static optimum, keeps the allocator's one solve (ruling
+  `one-weighted-solve-no-rotation-demand`; the thrust-allocator authority map forbids a second solve) and is the
+  cheapest in iterations and time. M2 is the most accurate (0.131) but doubles the variables, reaches 95 of 100
+  iterations on 36 thrusters and drifts idle rows. What M1 gives up is differential throttle inside a row: on these
+  hulls it measured nothing, and a row that needs it can be authored as two rows. The operator decides: question
+  `vector-row-formulation`.
+- **Why the limit is the hardpoint's arc and the slew the gear's.** It is ruling `mount-arc-gun-traverse` applied to
+  thrusters: how far a mount swings is ship authoring; how fast is the part's own stat. Reusing `FiringArc` adds no
+  field that the add-on, Studio and C4 must learn; its meaning (how far the mounted item may point from `Rotation`)
+  already fits. Question `vector-row-data-home` holds the alternatives.
+- **Why the envelope counts the whole gimbal, not the slew.** The envelope already ignores the time to swing the
+  hull (cut `envelope-from-columns` sums box extremes); counting slew time only for rows would be a second,
+  inconsistent time model. If the pace pass finds slow gimbals over-credited, slew time enters the envelope for hull
+  turn and rows together.
+- **Sequence.** Both cuts land after `thrust-allocator` and `envelope-from-columns`, whose `Ship.Update` wiring and
+  `RecalculateEnvelope` they change, and after `link-rig-record`, whose judge they extend. The rig and the add-on are
+  follow-up `vector-rows-presentation`: nothing authors a `Row` until the add-on does, so the record cut is inert
+  data until then.
+
+### Cut order
+
+1. `vector-rows-record` after `link-rig-record`, `thrust-allocator` and `envelope-from-columns`:
+   `HardpointData.Row`, `ThrusterData.Slew`, the judge's row rules, thruster anchors allowed on joints with the
+   reach check.
+2. `vector-rows-allocator` after `vector-rows-record`, `thrust-allocator-core`, `thrust-allocator` and
+   `envelope-from-columns`: rows as one actuator each in the solve, `Thruster.Angle`, `Column(angle)`, the reach
+   helper for demand and envelope. Its `Ship.cs` anchors are written against the merged wiring at Hands time
+   (the spec says where).
+
+### Admitted
+
+2026-10-10 (`imagination-aeth-vectoring`): receipt `mind-commit-2829a7e1...` (cut_specs `cut-vector-rows-record.r1`,
+`cut-vector-rows-allocator.r1`, questions `vector-row-formulation` and `vector-row-data-home`, follow-up
+`vector-rows-presentation`) and `mind-commit-e1337a9c...` (`cut-vector-rows-record.r2` superseding r1: its
+ShipValidationTests anchor named the wrong class). context-pack read every anchor SAME: record r2 at `562de34c`,
+allocator r1 at `1fc98bdc`.

docs/research/thrust-vectoring-prior-art.md

@@ -0,0 +1,131 @@
+# Prior art: control allocation with tilting / gimballed thrusters
+
+Serves the fork: vectored thruster rows in Aetheria (follow-ups `aetheria-release:follow_up:vectored-thruster-rows`, `aetheria-release:follow_up:gimballed-thrusters`). A thruster row tilts its thrust vector within a gimbal limit at a slew rate; the thrust allocator chooses the tilt; one gimbal per row, not per thruster.
+
+Eyes pass, 2026-10-10, session self-2026-10-10-ag. Facts with evidence pointers. No recommendation. Anything inferred is marked "(inferred)". Items marked [not retrieved] were seen only through search snippets or citations in other papers, not read in full.
+
+## 0. The allocator today (the thing the prior art is compared against)
+
+Source: `Assets/Scripts/ServerShared/ThrustAllocator.cs` at HEAD `1fc98bdc` of branch `eureka/aetheria-release-thrust-allocator-core` (read via `git show`).
+
+- Input: `ReadOnlySpan<float3> columns` (x starboard acceleration, y forward acceleration, z clockwise yaw rate per unit throttle), `float2 move`, `float turn`. Output: one throttle per thruster in [0,1].
+- One `BoundedLeastSquares.Solve` per call over n throttles plus 4 error variables (unwanted/missing translation per half-axis, linear cost). Yaw row weight 1000, translation rows weight 100, ridge 0.1 on each throttle. Variable bounds: throttles in [0,1], errors in [0, 2].
+- Columns are fixed inputs: the allocation matrix is constant with respect to the unknowns, so the problem is linear in the throttles.
+
+## 1. Question (a): standard formulations for allocation with tilting actuators
+
+### 1.1 Virtual actuators: force components as the linear unknowns, angle and magnitude recovered afterwards
+
+- Voliro hexacopter (Kamel, Verling et al., ETH, arXiv 1801.04581, section "D. Control allocation"). The allocation matrix is nonlinear in the tilt angles. The paper states a nonlinear least squares solve was judged too costly on the onboard computer and proposes "a variable transformation": each rotor's force is split into a vertical and a lateral component, F_v,i = c n_i^2 cos(alpha_i) and F_l,i = c n_i^2 sin(alpha_i) (eqs 16-17). The 12-vector of components maps linearly to the wrench by a constant matrix, solved by pseudo-inverse. Recovery: n_i^2 = (1/c) sqrt(F_v,i^2 + F_l,i^2) (eq 22), alpha_i = atan2(F_l,i, F_v,i) (eq 23). The paper reports several hundred Hz on a Pixhawk.
+- Same technique in the marine literature, named "extended thrust configuration" (Sørdalen 1997, Control Engineering Practice 5(9):1223-1231, [not retrieved]; described in Mukwege/Nguyen/Garone arXiv 2510.08119 intro and in Maneuvering-based Dynamic Thrust Allocation, arXiv 2507.18309, section 2: "separating the force components and using the rectangular configuration matrix is convenient as this leads to a constant configuration matrix"). In 2507.18309 fixed-direction thrusters stay in polar form (magnitude) while azimuth thrusters use rectangular components, in one allocation.
+- Mukwege/Nguyen/Garone (arXiv 2510.08119, sections 2-4) write the whole problem as d = M F with F in R^(3m) (three force components per thruster, M constant 6 x 3m) and treat the orientation as F_j / |F_j|.
+
+### 1.2 Nonlinear allocation, solved by sequential local linearisation
+
+- Johansen, Fossen, Berge, "Constrained nonlinear control allocation with singularity avoidance using sequential quadratic programming", IEEE TCST 12(1):211-216, 2004 [not retrieved; abstract and the description in 2510.08119 section 1.1 and 4]. Each sample: a convex QP approximating the nonlinear program; actuator rate and position constraints; a singularity penalty on 1/det(J(alpha) J(alpha)^T) added to the cost.
+- Per 2510.08119 section 4, the penalty (i) does not work when thrusters are fewer than the degrees of freedom (det is identically zero), and (ii) gives no systematic behaviour around zero demand d = 0. The same paper names the equality constraint d = J(alpha) T and the penalty as the source of non-convexity.
+- Ryll/Cuniato line and the ETH Voliro follow-ups [not retrieved in full]: a search result describes Cuniato et al. (IEEE T-RO) as a differential allocation including servo and propeller dynamics, claimed free of singularities.
+
+### 1.3 Sequential / cascaded (forces first, then angles)
+
+- TU Delft thesis on dual-axis tilt-rotor quadplanes (repository.tudelft.nl, search snippet only) reports a nonlinear SQP allocator and states that a cascaded scheme (linear then angular accelerations) was chosen over a combined one because of large roll and pitch changes. [not retrieved in full]
+- A 2021 tilt-rotor quadrotor paper (search snippet, not retrieved) splits the effectiveness matrix into two parts (yaw torque and forward velocity first, then all dynamics) and iterates to convergence.
+- Voliro's solution (1.1) is itself two-stage: linear solve for components, then closed-form angle recovery.
+
+### 1.4 Rate and gimbal limits entering the allocation
+
+- Per-tick bounds from current state and rate (box on the actuator variable): Tiltrotor NMPC (Nguyen/Garone et al., arXiv 2406.06130, section 4.1): "we use the current state of actuators and their rate of change to update u_min and u_max" every sample, and constrain the controller so its virtual command lies in the image h(u) of the admissible actuator box. There the unknowns are thrust and tilt angle themselves (u = thrust_i, tilt_i) with the rate-updated box; the paper's allocator in its experiments is a pseudo-inverse.
+- Mukwege et al. 2510.08119 section 4: thrust saturation as F_i magnitude bound, thrust rate as |F_i - F_i0| <= bound reusing the previous solution F_i0, pointing and angular-rate constraints as convex cones C_i with F_i in C_i (conic combination of 3 vectors, or half-space form A F <= b). Resulting problem class: QCQP at most. For real time it states thrust saturation can be rewritten as three box constraints per actuator (F_x, F_y, F_z min/max), "at the cost of extra conservativeness".
+- Marine DP (MARIN, search snippet [not retrieved]): physical limits modelled are saturation, azimuth turn rate and RPM change rate, solved with SQP.
+- Maneuvering-based Dynamic Thrust Allocation (arXiv 2507.18309, abstract and section 3.4): a nonlinear reference filter driven by a control Lyapunov/barrier function tracks the optimal allocation with rate limitation of the thruster forces; the optimal allocation itself is computed unconstrained in the manifold p + Q*lambda (particular solution plus nullspace).
+- Härkegård and active-set methods (Bodson & Frost, NASA, quoted in a search result [not retrieved]): Härkegård's active-set algorithms for constrained least-squares allocation; "Resolving actuator redundancy - optimal control vs. control allocation", Automatica 41(1):137-144, 2005 (bibliographic fact only, [not retrieved]). Dynamic allocation with rate limits as constraint on the increment is a standard formulation of this literature (inferred from the 2406.06130 and 2510.08119 descriptions; the Härkegård paper was not read).
+- Voliro paper states the limitation of the linear trick directly (section IV-C text near eq 23): "the tilting angles and the angular velocities are nonlinearly coupled. Therefore, it is difficult to constrain them separately. This means, that this allocation doesn't account for the slower dynamics of the tilting angles." Example given: hovering at 90 deg roll, two rotors on the vertical axis must "constantly rotate 180 back and forth at a high rate"; tilt servos cannot follow, so forces and moments appear in directions not commanded. The authors state this motivated a further step (text beyond the retrieved excerpt).
+
+## 2. Question (b): virtual-actuator trick inside a least-squares / QP allocator
+
+### Bound shapes
+
+- A real tilt limit is a cone (3D) or a wedge (2D) on the force vector: |F_lateral| <= tan(theta_max) * F_vertical, F_vertical >= 0. 2510.08119 section 4 states pointing constraints are "convex cones C_i", yielding at most a QCQP; the linear-programming-friendly approximation is a box on each component (eqs 40-42), explicitly conservative.
+- In a 2D plane with a one-sided (non-reversible) thruster, the cone degenerates to two half-spaces on (F_v, F_l) (inferred from the cone statement above; Aetheria's columns are planar and throttles are in [0,1]). Whether `BoundedLeastSquares` accepts general linear inequality constraints or only variable box bounds was not examined by this pass; the allocator file shows only variable bounds [lo, hi].
+- Marine azimuth with a full circle: the Valčić/Prpić-Oršić result is that removing a forbidden sector from the azimuth circle leaves a non-convex feasible region ("Pacman shape") causing large azimuth swings and slower allocation (CROSBI 899099 and related entries, search results only).
+
+### Conditioning
+
+- Mukwege et al. 2510.08119 section 1 and 3 state that pseudo-inverse allocations are "sensible to the singularities" and produce "discontinuous actuator orientations references"; because servos have finite turning rate, crossing a singularity leaves "a period of time where the system is not able to fulfill the demands." They note singular configurations are "also usually related to energy-efficient configurations."
+- The linear virtual formulation raises the number of unknowns from one scalar per actuator to two or three (Voliro: 12 variables for 6 rotors). Over-actuation (more unknowns than DOF) means the solution is not unique (Voliro section D; 2406.06130 section 1 mention of ill-conditioned effectiveness matrix).
+- 2510.08119 adds a rest-configuration nullspace term to the convex cost (q1 b(d) K_b^T F - q2 ||...||^2, eq 38) which they say preserves convexity and keeps a minimum force on each actuator; they present it as the fix for the orientation discontinuity.
+
+### Warm start
+
+- No source retrieved states warm-start behaviour of a bounded least-squares/QP solver specifically under virtual-actuator allocation. 2510.08119 section 4 states the rate constraint reuses the previous solution F_i0 as the centre of the rate box (so the previous solution is part of the constraint, not only an initial guess). Voliro: the pseudo-inverse is memoryless. Orbiter forum simplex thread (section 4): solve time 0-15 ms for 22 thrusters, no warm-start detail.
+
+### Singularity near zero thrust
+
+- Angle atan2(F_l, F_v) is undefined at F = 0 and discontinuous near it: Voliro eq 23; 2510.08119 intro and section 3 (Lipschitz constant of the orientation is bounded only if |F_j| stays above a minimum, their condition C2: |F_j + s_j(d)| >= epsilon_2, enforced by the nullspace smoothing term).
+- 2510.08119 section 5 numerical examples (marine vessel with 3 azimuth thrusters; quadcopter) report orientation jumps when the pseudo-inverse solution crosses the singular point, and smoothing removing them. Their Figure 4 text: "the smoothing action appears when a discontinuity in azimuth orientation is close."
+- The plain virtual-actuator formulation has the zero-thrust ambiguity because the unknown F carries the angle implicitly; the output angle command is a function of the solution. (Inferred from eqs 22-23 plus the above.)
+
+## 3. Question (c): games
+
+Retrieval for games was by web search of wiki and forum pages; no engine source code was read.
+
+- Kerbal Space Program: engines have a `ModuleGimbal` with configurable range (typically a few degrees; kerbal.wiki Part_modules example LV-909 shows about 4 degrees each way in pitch and yaw), per-axis response toggles (kOS docs: gimbal responds to pitch, yaw, roll controls separately; LIMIT suffix; LOCK snaps to zero), a response-speed field whose effect is unclear (a forum thread, topic 46553, reports no observable difference between speeds 1 and 100; a reply says the speed field is used only when `useGimbalResponseSpeed` is true). Roll participation of off-axis engines was added in 0.24 (forum summary). Gimbal acts only while the engine burns; RCS and reaction wheels cover the rest (forum posts). KerbCom Avionics mod added a solver balancing engine gimbals, reaction wheels and RCS (forum announcement; algorithm not retrieved). KSP's own internal allocation was not found in any retrieved source.
+- Space Engineers: without mods, thrust is applied through the grid's centre of mass so offset thrusters make no torque (Keen support thread "Realistic Thrusters // Thruster Torque & Thrust Allocation", forum answers). Vectoring is done by mounting thrusters on rotors/sub-grids and scripting (Whip's, Vector Thrust OS named by players). The "Realistic Thrusters" mod/suggestion is the only torque-from-offset treatment found.
+- Avorion: Directional Thruster block with nozzles on two opposing sides, aimed by rotating the block, affecting only that axis, 2.5x thrust along it (wiki; players report 3x); regular thrusters have nozzles on all six sides; thruster output scales against ship mass; turning authority comes from distance to centre of mass (wiki, developer post). No continuous gimbal found.
+- Starsector: movement stats only (wiki: acceleration, turn acceleration, max turn rate as hull-mod multipliers); flux does not gate movement. No thrust allocation.
+- Children of a Dead Earth: store/feature text says moment of inertia, delta-v and acceleration are computed; searches found no description of gimbals or RCS allocation. Nothing established.
+- Orbiter (simulator, not shipped game with gimbals evidence): forum "Simplex-based thruster control" (thread 25232) describes an RCS class using the simplex method on arbitrary thruster layouts "no groups", simultaneous rotation and translation, commands scaled linearly when out of reach; 0-15 ms on 22 thrusters; occasional instability with unrealistically large torques; no mention of gimbals. ESA ATV uses simplex-based jet selection precomputed into a lookup table (search result [not retrieved]).
+- No retrieved source describes a shipped game doing a physically allocated vectored thrust with an optimiser. (A negative result of limited searching, not proof of absence.)
+
+## 4. Question (d): shared-angle actuators (one gimbal per row)
+
+- No retrieved source formulates allocation for several thrusters sharing one tilt angle with individual magnitudes. This was searched directly (control allocation, shared tilt, common tilt, group of thrusters one gimbal) and returned nothing matching.
+- Nearest found: TU Delft thesis snippet on a quadcopter with a single gimbal-style common tilt (Zheng et al.): two extra servos and spherical joints tilt the whole rotor set so the combined thrust vector is steerable and thrust is attitude-independent. The retrieved excerpt does not describe the allocation. [not retrieved in full]
+- Structure of the problem as stated by the established formulations (inferred): with one common angle alpha per row, row member i produces force t_i (cos alpha, sin alpha). In virtual-actuator terms every member's component pair (F_v,i, F_l,i) must have the same ratio tan(alpha). The linear-component trick's advantage (angle free per actuator, constant matrix) is lost because the ratio equality across members is bilinear in (t_i, alpha); the formulation with per-thruster free components would overcount freedom. If the row's members have equal nominal directions, the row's total force and torque are (sum of t_i) and (sum of t_i * lever_i) (inferred), which makes the row's angle a single nonlinear variable shared by several linear throttles.
+- Related structural facts in sources: 2507.18309 section 2 mixes fixed-direction thrusters (polar form, magnitude only) and azimuth thrusters (rectangular form, two components) in one allocation; this covers per-thruster angle plus fixed thrusters, not shared angle.
+- Sequential treatment of coupled problems exists in the literature: the tilt-rotor papers' cascaded or iterated split (1.3). A row-shared angle solved as an outer scalar search with an inner bounded linear solve is not described in any retrieved source (inferred as one possible shape; no source).
+
+## 5. Converged / disagrees
+
+Converged (stated by two or more retrieved sources):
+
+1. Treating each tilting actuator as 2 or 3 linear force components with a constant allocation matrix, then recovering magnitude and angle by norm and atan2, is a standard approach: Voliro 1801.04581 (eq 16-23), Sørdalen extended thrust as cited in 2510.08119 and 2507.18309, Mukwege 2510.08119 (F in R^(3m)).
+2. The recovered angle is discontinuous or undefined near zero component magnitude: Voliro (eq 23 and the 90 degree roll example), 2510.08119 (intro, section 3, section 5), 2507.18309 (azimuth penalty motivation).
+3. Servo slowness is not represented by the linear trick alone: Voliro (explicit statement) and 2510.08119 (finite turning rate discussion) agree; solutions in the sources add a rate constraint (2510.08119 section 4), a rate-updated bound (2406.06130 section 4.1), a nullspace smoothing term (2510.08119), or a rate-limited reference filter (2507.18309).
+4. Rate limits enter as per-sample bounds centred on the previous actuator state or previous solution: 2406.06130 (u_min/u_max updated from current state and rate), 2510.08119 (|F_i - F_i0| <= bound).
+5. Tilt or pointing limits are cones in force space and convex; box approximations of the components are the cheap, conservative form: 2510.08119 (cone C_i, eqs 40-42).
+6. Redundancy yields non-unique solutions chosen by a secondary objective (energy, nullspace, rest configuration): Voliro, 2510.08119, 2507.18309, 2406.06130.
+
+Disagrees / differs across sources:
+
+1. Linear vs nonlinear: Voliro rejects nonlinear least squares for compute cost; the marine SQP line (Johansen et al. 2004, MARIN) accepts a local QP per sample with a singularity penalty; 2510.08119 states the penalty fails when the thruster count is below the DOF count and around d = 0.
+2. Where limits live: 2406.06130 puts the actuator box in the controller (NMPC) and uses a plain pseudo-inverse allocator; 2510.08119 puts constraints in the allocator QP/QCQP; 2507.18309 puts rate limitation in a downstream reference filter.
+3. Singularity handling: penalty on det(J J^T) (Johansen 2004) vs nullspace rest configuration (2510.08119) vs differential allocation avoiding the algebraic map (Cuniato, snippet only) vs forbidden-zone removal (marine; Valčić says it causes non-convexity and large swings and proposes modelling interaction as losses instead).
+4. Solvers: simplex/LP with scaling of out-of-reach commands (Orbiter thread) vs QP/active set (Härkegård, Bodson) vs SQP (Johansen, TU Delft) vs closed-form pseudo-inverse (Voliro, 2406.06130).
+5. Games: Space Engineers applies thrust through the centre of mass by default (no torque from offset); Orbiter and the ATV approach allocate by simplex from true positions; KSP gimbals are small-range controls fed by control inputs per axis. They do not agree on whether positional torque is physically computed.
+
+## 6. Sources
+
+Read in full or in relevant part (text extracted):
+- Kamel, Verling et al., "Voliro: An Omnidirectional Hexacopter With Tiltable Rotors", arXiv 1801.04581. https://arxiv.org/pdf/1801.04581
+- Mukwege, Nguyen, Garone, "General formulation of an analytic and Lipschitz continuous control allocation for thrust-vectored controlled rigid-bodies", arXiv 2510.08119v3 (Apr 2026). https://arxiv.org/pdf/2510.08119
+- Maneuvering-based Dynamic Thrust Allocation for Fully-Actuated Vessels, arXiv 2507.18309. https://arxiv.org/pdf/2507.18309
+- Nonlinear Model Predictive Control of Tiltrotor Quadrotors with Feasible Control Allocation, arXiv 2406.06130. https://arxiv.org/abs/2406.06130
+- Sorge, Ciresola, Michieletto, Cenedese, "Dynamic Control Allocation for Dual-Tilt UAV Platforms", arXiv 2604.05677 (text extracted, only keyword-checked; no claim above rests on it). https://arxiv.org/pdf/2604.05677
+- Constrained Dynamic Control Allocation in the Presence of Singularity and Infeasible Solutions, arXiv 1607.05209 (abstract only). https://arxiv.org/abs/1607.05209
+- Aetheria ThrustAllocator.cs, branch eureka/aetheria-release-thrust-allocator-core, commit 1fc98bdc.
+
+Cited, not retrieved (bibliographic or snippet only):
+- Johansen & Fossen, "Control allocation - A survey", Automatica 49(5):1087-1103, 2013, DOI 10.1016/j.automatica.2013.01.035. Full text not found (NTNU URLs returned HTML stubs).
+- Johansen, Fossen, Berge, IEEE TCST 12(1):211-216, 2004.
+- Sørdalen, "Optimal thrust allocation for marine vessels", Control Engineering Practice 5(9):1223-1231, 1997.
+- Härkegård & Glad, "Resolving actuator redundancy - optimal control vs. control allocation", Automatica 41(1):137-144, 2005; Härkegård active-set allocation as cited in Bodson & Frost (NASA NTRS 20100024149 appeared in search results).
+- Cuniato et al., IEEE T-RO, differential allocation for tiltable-rotor platforms (search summary).
+- Valčić & Prpić-Oršić, forbidden-zone handling in thrust allocation (CROSBI 838045, 899099).
+- MARIN, "An advanced thrust allocation algorithm for DP applications" (search result).
+- TU Delft thesis on dual-axis tilt-rotor quadplanes, https://repository.tudelft.nl/file/File_3e64f087-21b4-458c-8fc6-6ea6559a1bbe
+- KSP: https://kerbal.wiki/index.php/Part_modules, https://forum.kerbalspaceprogram.com/topic/46553-engine-gimbal-reaction-speed, https://ksp-kos.readthedocs.io/en/latest/structures/vessels/gimbal.html (the wiki Gimbal page was blocked by bot protection).
+- Space Engineers: https://support.keenswh.com/spaceengineers/pc/topic/45350-realistic-thrusters-thruster-torque-thrust-allocation
+- Avorion: https://avorion.fandom.com/wiki/Directional_Thruster
+- Starsector: https://starsector.wiki.gg/wiki/Auxiliary_Thrusters
+- Orbiter: https://orbiter-forum.com/threads/simplex-based-thruster-control.25232

tests/Aetheria.Shared.Tests/Aetheria.Shared.Tests.csproj

@@ -11,6 +11,8 @@
     <!-- AuthoredSettings (Unity Settings.asset YAML reader), so fixtures load the shipped gameplay settings
          instead of hand-copying them. -->
     <ProjectReference Include="..\..\tools\AetherDb\AetherDb.csproj" />
+    <!-- The player build's staging rules: Unity-free, owned by Assets/Editor, compiled here so the suite can prove them. -->
+    <Compile Include="..\..\Assets\Editor\PlayerStaging.cs" Link="PlayerStaging.cs" />
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.4.0" />
     <PackageReference Include="xunit" Version="2.9.3" />
     <PackageReference Include="xunit.runner.visualstudio" Version="3.1.5" />

tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs

@@ -116,7 +116,10 @@ public sealed class AetheriaStoresTests : IDisposable
     public void MissingCatalogGlobalIsLoud()
     {
         var empty = Path.Combine(_root, "empty.cc");
-        using (AetheriaStores.Open(empty, catalogWritable: true)) { }
+        // A catalog file that exists but lacks the global: the read-only open reaches the global check.
+        File.Copy(Catalog, empty);
+        using (var seed = AetheriaStores.Open(empty, catalogWritable: true))
+            Assert.True(seed.Commit(batch => batch.Remove(seed.RefOf(seed.GetGlobal<TestCatalogGlobal>()).Key)));
         var error = Assert.Throws<InvalidOperationException>(() => AetheriaStores.Open(empty));
         Assert.Contains("aetheria.tests.catalogglobal", error.Message);
         using (AetheriaStores.Open(Catalog)) { }
@@ -200,6 +203,23 @@ public sealed class AetheriaStoresTests : IDisposable
         Assert.Null(record);
     }
 
+    // A shipped player with no catalog must not boot into an empty game: a read-only open of a missing path throws
+    // naming the path, and does not create the file. A writable open still seeds an empty catalog.
+    [Fact]
+    public void AStoreRefusesAMissingCatalog()
+    {
+        var missing = Path.Combine(_root, "absent", "Aetheria.cc");
+
+        // FileNotFoundException, not the catalog-global check: that one also throws on a missing file whenever a global is registered.
+        var error = Assert.Throws<FileNotFoundException>(() => AetheriaStores.Open(missing));
+        Assert.Contains(missing, error.Message);
+        Assert.False(File.Exists(missing));
+        Assert.False(Directory.Exists(Path.GetDirectoryName(missing)));
+
+        using (var seeded = AetheriaStores.Open(missing, catalogWritable: true))
+            Assert.Empty(seeded.GetAll<Faction>());
+    }
+
     private static string Hash(string path) => Convert.ToHexString(SHA256.HashData(File.ReadAllBytes(path)));
 
     private static string[] SchemaNames(string path)

tests/Aetheria.Shared.Tests/ConsumableTests.cs

@@ -0,0 +1,266 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using CultMath;
+using GameCult.Caching;
+using Xunit;
+
+// A consumable is a cargo item with a timed effect (aetheria-release CS-R1). Its modifiers exist in the resolver
+// exactly while its effect is active: the host (Entity) initialises the effect's behaviours at activation and
+// disposes them at expiry, and ItemManager.CreateInstance is the one way a lot becomes a ConsumableItem.
+public sealed class ConsumableTests : IDisposable
+{
+    private readonly string _root = Path.Combine(Path.GetTempPath(), "aetheria-consumable-" + Guid.NewGuid().ToString("N"));
+    private string Catalog => Path.Combine(_root, "Aetheria.cc");
+    private static readonly int2 EngineCell = new int2(0, 0);
+    private static readonly int2 HoldCell = new int2(1, 1);
+
+    public ConsumableTests() => Directory.CreateDirectory(_root);
+    public void Dispose() => Directory.Delete(_root, true);
+
+    private sealed class Rig
+    {
+        public CultCache Cache;
+        public ItemManager Items;
+        public Ship Ship;
+        public EquippedItem Engine;
+        public PerformanceStat Thrust;
+        public ConsumableItemData Consumable;
+        public ConsumableItemData Other; // a second, unrelated non-stackable design
+        public Func<EquippableItem> NewEngine;
+        public CultRecordKey Key;
+        public CultRecordRef<Faction> Maker;
+
+        public ConsumableItem Mint(ConsumableItemData design = null) =>
+            Assert.IsType<ConsumableItem>(Items.CreateInstance(Items.CreateLot(design ?? Consumable, Maker, .5f)));
+        public EquippedCargoBay Hold => Ship.CargoBays.Single();
+        public int InCargo => Hold.Cargo.Keys.Count(i => i is ConsumableItem);
+    }
+
+    // A ship with a thruster (Thrust 10) and a hold; the consumable doubles ThrusterData.Thrust for one second.
+    private Rig Build(bool stackable = false)
+    {
+        var thrust = new PerformanceStat { Min = 10, Max = 10 };
+        var cache = AetheriaStores.Open(Catalog, catalogWritable: true);
+        cache.Upsert(new TestCatalogGlobal { Name = "Temperament" });
+        cache.Upsert(new Faction { Name = "Maker", ShortName = "MKR" });
+        var hullShape = new Shape(3, 3);
+        foreach (var cell in hullShape.AllCoordinates) hullShape[cell] = true;
+        var hullRef = cache.Upsert(new HullData
+        {
+            Name = "Skiff", HullType = HullType.Ship, Shape = hullShape, Durability = 10,
+            Hardpoints = { new HardpointData { Type = HardpointType.Sensors, Position = EngineCell, Shape = new Shape() } }
+        });
+        var engineRef = cache.Upsert(new GearData
+        {
+            Name = "Engine", Hardpoint = HardpointType.Sensors, Shape = new Shape(), Durability = 10,
+            Behaviors = { new ThrusterData { Thrust = thrust } }
+        });
+        var interior = new Shape(2, 1); // room for two consumables
+        foreach (var cell in interior.AllCoordinates) interior[cell] = true;
+        var holdRef = cache.Upsert(new CargoBayData { Name = "Hold", Shape = new Shape(), InteriorShape = interior, Durability = 10 });
+        var consumableRef = cache.Upsert(new ConsumableItemData
+        {
+            Name = "Overdrive", Duration = 1f, Stackable = stackable, Shape = new Shape(),
+            Behaviors =
+            {
+                new StatModifierData
+                {
+                    Stat = new StatReference { Target = nameof(ThrusterData), Stat = nameof(ThrusterData.Thrust) },
+                    Modifier = new PerformanceStat { Min = 2, Max = 2 },
+                    Type = StatModifierType.Multiplier
+                }
+            }
+        });
+        var otherRef = cache.Upsert(new ConsumableItemData { Name = "Flare", Duration = 1f, Shape = new Shape() });
+        cache.FlushAsync().Wait();
+
+        var items = new ItemManager(cache, new ProvenanceLedger(), RunSaveTests.TestSettings(), _ => { });
+        var makerRef = cache.RefOf(cache.GetByName<Faction>("Maker"));
+        EquippableItem Gear(EquippableItemData design) => (EquippableItem) items.CreateInstance(items.CreateLot(design, makerRef, .5f));
+        var zone = new Zone(items, new PlanetSettings(), new ZonePack(), new GalaxyZone { Name = "Test Zone", Owner = null }, null);
+        var ship = new Ship(items, zone, Gear(cache.Get(hullRef)), new EntitySettings());
+        Assert.True(ship.TryEquip(Gear(cache.Get(engineRef)), EngineCell));
+        Assert.True(ship.TryEquip(Gear(cache.Get(holdRef)), HoldCell));
+        zone.Entities.Add(ship);
+        ship.Activate();
+        var data = cache.Get(consumableRef);
+        return new Rig
+        {
+            Cache = cache, Items = items, Ship = ship, Thrust = thrust, Consumable = data, Other = cache.Get(otherRef),
+            NewEngine = () => Gear(cache.Get(engineRef)),
+            Key = items.ItemData.RefOf<ItemData>(data).Key,
+            Engine = ship.Equipment.Single(e => e.Data.Name == "Engine"),
+            Maker = makerRef
+        };
+    }
+
+    // Two ticks after activation the modifier has attached (the first tick executes it, the second applies it).
+    private static void Tick(Rig rig, int times, float dt)
+    {
+        for (var i = 0; i < times; i++) rig.Ship.Update(dt);
+    }
+
+    // The rule: a consumable's modifiers exist in the resolver exactly while its effect is active, never after.
+    // Observed at the resolved stat and at the resolver's modifier entry count, not at a flag.
+    [Fact]
+    public void AConsumableModifierBoostsUntilExpiry()
+    {
+        var rig = Build();
+        using var _ = rig.Cache;
+        var resolver = rig.Ship.Resolver;
+        Assert.Equal(10f, rig.Engine.Evaluate(rig.Thrust), 3);
+        var baseline = resolver.ModifierEntryCount;
+
+        rig.Ship.ActivateConsumable(rig.Mint());
+        Tick(rig, 2, .3f); // 0.4s of the 1s remain; the modifier has attached
+        Assert.Equal(20f, rig.Engine.Evaluate(rig.Thrust), 3);
+        Assert.True(resolver.ModifierEntryCount > baseline);
+
+        Tick(rig, 3, .3f); // 1.5s elapsed in all: the effect ran out on the fourth tick
+        Assert.Equal(10f, rig.Engine.Evaluate(rig.Thrust), 3);
+        Assert.Equal(baseline, resolver.ModifierEntryCount);
+    }
+
+    // A lot minted through the one production path is a ConsumableItem, and a hold holding it activates it.
+    [Fact]
+    public void ABoughtConsumableActivates()
+    {
+        var rig = Build();
+        using var _ = rig.Cache;
+        Assert.True(rig.Hold.TryStore(rig.Mint()));
+        Assert.Equal(1, rig.InCargo);
+
+        Assert.True(rig.Ship.TryActivateConsumable(rig.Consumable));
+        Assert.Equal(0, rig.InCargo);
+        Assert.NotNull(rig.Ship.FindActiveConsumable(rig.Consumable));
+    }
+
+    // CS-R1: a non-stackable design allows one active effect at a time, so its Duration is its cooldown.
+    [Fact]
+    public void ANonStackableConsumableRefusesASecondActivation()
+    {
+        var rig = Build();
+        using var _ = rig.Cache;
+        Assert.True(rig.Hold.TryStore(rig.Mint()));
+        Assert.True(rig.Hold.TryStore(rig.Mint()));
+
+        Assert.True(rig.Ship.TryActivateConsumable(rig.Consumable));
+        Assert.False(rig.Ship.TryActivateConsumable(rig.Consumable));
+        Assert.Equal(1, rig.InCargo);
+
+        Tick(rig, 5, .3f); // the first effect has run out
+        Assert.True(rig.Ship.TryActivateConsumable(rig.Consumable));
+        Assert.Equal(0, rig.InCargo);
+    }
+
+    // The expiry boundary: Duration 1 with 0.3 s ticks leaves 0.1 s after the third tick (still active) and
+    // -0.2 s after the fourth (gone). An expiry one tick early or one tick late changes one of these two reads.
+    [Fact]
+    public void AConsumableLivesForItsDurationAndNoLonger()
+    {
+        var rig = Build();
+        using var _ = rig.Cache;
+        rig.Ship.ActivateConsumable(rig.Mint());
+        Tick(rig, 3, .3f);
+        Assert.Equal(20f, rig.Engine.Evaluate(rig.Thrust), 3);
+        Tick(rig, 1, .3f);
+        Assert.Equal(10f, rig.Engine.Evaluate(rig.Thrust), 3);
+    }
+
+    // An effect runs for exactly its Duration: Duration 1 with 0.25 s ticks (exact in floats) executes its
+    // behaviours on four ticks and is gone when the fourth ends, not on a fifth.
+    [Fact]
+    public void AConsumableRunsForExactlyItsDurationInTicks()
+    {
+        var rig = Build();
+        using var _ = rig.Cache;
+        rig.Ship.ActivateConsumable(rig.Mint());
+        Tick(rig, 3, .25f);
+        Assert.NotNull(rig.Ship.FindActiveConsumable(rig.Consumable));
+        Assert.Equal(20f, rig.Engine.Evaluate(rig.Thrust), 3);
+        Tick(rig, 1, .25f); // the fourth tick spends the last of the Duration
+        Assert.Null(rig.Ship.FindActiveConsumable(rig.Consumable));
+        Assert.Equal(10f, rig.Engine.Evaluate(rig.Thrust), 3);
+    }
+
+    // CS-R1, the stackable side: a stackable design activates again while its first effect runs, and every
+    // multiplier on the stat multiplies.
+    [Fact]
+    public void TwoStackableConsumablesOverlapAndMultiply()
+    {
+        var rig = Build(stackable: true);
+        using var _ = rig.Cache;
+        Assert.True(rig.Hold.TryStore(rig.Mint()));
+        Assert.True(rig.Hold.TryStore(rig.Mint()));
+
+        Assert.True(rig.Ship.TryActivateConsumable(rig.Consumable));
+        Assert.True(rig.Ship.TryActivateConsumable(rig.Consumable));
+        Assert.Equal(0, rig.InCargo);
+        Tick(rig, 2, .3f);
+        Assert.Equal(40f, rig.Engine.Evaluate(rig.Thrust), 3);
+    }
+
+    // Two modifiers share one resolver entry, both attached. The first expires while the second still runs: the
+    // second's boost stays, and when it expires too nothing is left behind.
+    [Fact]
+    public void AnExpiringConsumableLeavesAnOverlappingOnesBoost()
+    {
+        var rig = Build(stackable: true);
+        using var _ = rig.Cache;
+        var resolver = rig.Ship.Resolver;
+        var baseline = resolver.ModifierEntryCount;
+        Assert.True(rig.Hold.TryStore(rig.Mint()));
+        Assert.True(rig.Hold.TryStore(rig.Mint()));
+
+        Assert.True(rig.Ship.TryActivateConsumable(rig.Consumable));
+        Tick(rig, 1, .3f);
+        Assert.True(rig.Ship.TryActivateConsumable(rig.Consumable));
+        Tick(rig, 2, .3f); // both attached: the first has 0.1 s left, the second 0.4 s
+        Assert.Equal(40f, rig.Engine.Evaluate(rig.Thrust), 3);
+
+        Tick(rig, 1, .3f); // the first ran out; the second's boost is still on the shared entry
+        Assert.Equal(20f, rig.Engine.Evaluate(rig.Thrust), 3);
+        Assert.True(resolver.ModifierEntryCount > baseline);
+
+        Tick(rig, 1, .3f); // and now the second
+        Assert.Equal(10f, rig.Engine.Evaluate(rig.Thrust), 3);
+        Assert.Equal(baseline, resolver.ModifierEntryCount);
+    }
+
+    // CS-R1: the cooldown is per design. A running effect of one design does not refuse another design.
+    [Fact]
+    public void ADesignsCooldownDoesNotBlockAnotherDesign()
+    {
+        var rig = Build();
+        using var _ = rig.Cache;
+        Assert.True(rig.Hold.TryStore(rig.Mint()));
+        Assert.True(rig.Hold.TryStore(rig.Mint(rig.Other)));
+
+        Assert.True(rig.Ship.TryActivateConsumable(rig.Consumable));
+        Assert.True(rig.Ship.TryActivateConsumable(rig.Other));
+        Assert.Equal(0, rig.InCargo);
+    }
+
+    // Docking: an effect still running when the entity deactivates, is refitted and activates again boosts the
+    // items now fitted, as gear modifiers do, not the thruster that was swapped out.
+    [Fact]
+    public void AConsumableActiveAcrossARefitBoostsTheNewItems()
+    {
+        var rig = Build();
+        using var _ = rig.Cache;
+        rig.Ship.ActivateConsumable(rig.Mint());
+        Tick(rig, 2, .3f);
+        Assert.Equal(20f, rig.Engine.Evaluate(rig.Thrust), 3);
+
+        rig.Ship.Deactivate();
+        Assert.NotNull(rig.Ship.TryUnequip(rig.Engine));
+        Assert.True(rig.Ship.TryEquip(rig.NewEngine(), EngineCell));
+        rig.Ship.Activate();
+        Tick(rig, 2, .1f); // 0.2 s more: the effect still has 0.2 s of its second
+        var fitted = rig.Ship.Equipment.Single(e => e.Data.Name == "Engine");
+        Assert.NotSame(rig.Engine, fitted);
+        Assert.Equal(20f, fitted.Evaluate(rig.Thrust), 3);
+    }
+}

tests/Aetheria.Shared.Tests/LoadoutTests.cs

@@ -760,11 +760,7 @@ public sealed class LoadoutTests : IDisposable
         var items = new ItemManager(cache, new ProvenanceLedger(), RunSaveTests.TestSettings(), _ => { });
         var hullItem = (EquippableItem) items.CreateInstance(items.CreateLot(hullData, maker, .5f));
         var ship = new Ship(items, null, hullItem, new EntitySettings());
-        // ItemManager.CreateInstance has no ConsumableItemData branch (it only special-cases EquippableItemData,
-        // falling back to CompoundCommodity otherwise); build the instance directly, as that method does for
-        // EquippableItem.
-        var consumableLot = items.CreateLot(consumableData, maker, .5f);
-        var consumableItem = new ConsumableItem { Data = cache.RefOf<ItemData>(consumableData), Lot = consumableLot };
+        var consumableItem = (ConsumableItem) items.CreateInstance(items.CreateLot(consumableData, maker, .5f));
         var effect = new ConsumableItemEffect(consumableItem, ship);
         effect.Update(5f); // half the duration elapsed -> progress .5 -> effectiveness .5 on a linear ramp
 

tests/Aetheria.Shared.Tests/PlayerStagingTests.cs

@@ -0,0 +1,101 @@
+using System;
+using System.IO;
+using System.Linq;
+using Xunit;
+
+// A player directory's GameData is exactly the catalog, Narrative/** and (when the repo has them) Mods/**.
+public sealed class PlayerStagingTests : IDisposable
+{
+    private readonly string _root = Path.Combine(Path.GetTempPath(), "aetheria-staging-" + Guid.NewGuid().ToString("N"));
+    private string Repo => Path.Combine(_root, "repo");
+    private string Player => Path.Combine(_root, "player");
+    private string Source(string relative) => Path.Combine(Repo, "GameData", relative);
+    private string Staged(string relative) => Path.Combine(Player, "GameData", relative);
+
+    public PlayerStagingTests()
+    {
+        Write(Source("Aetheria.cc"), "catalog-bytes");
+        Write(Source("Narrative/Main.ink"), "main");
+        Write(Source("Narrative/Quests/Deep/First.ink"), "first");
+        Write(Source("SoundbanksInfo.json"), "{}");
+        Write(Source("run.cc"), "a developer's run");
+        Write(Source("player.cc"), "a developer's settings");
+        Directory.CreateDirectory(Player);
+    }
+
+    public void Dispose() => Directory.Delete(_root, true);
+
+    [Fact]
+    public void StagesTheCatalogAndNarrativeFileForFile()
+    {
+        PlayerStaging.Stage(Repo, Player);
+
+        Assert.Equal("catalog-bytes", File.ReadAllText(Staged("Aetheria.cc")));
+        Assert.Equal("main", File.ReadAllText(Staged("Narrative/Main.ink")));
+        Assert.Equal("first", File.ReadAllText(Staged("Narrative/Quests/Deep/First.ink")));
+    }
+
+    [Fact]
+    public void StagesModsWhenTheRepoHasThemAndNoModsFolderWhenItDoesNot()
+    {
+        PlayerStaging.Stage(Repo, Player);
+        Assert.False(Directory.Exists(Staged("Mods")));
+
+        Write(Source("Mods/ship-a/ship.cc"), "ship");
+        Write(Source("Mods/ship-a/mesh/hull.glb"), "hull");
+        PlayerStaging.Stage(Repo, Player);
+
+        Assert.Equal("ship", File.ReadAllText(Staged("Mods/ship-a/ship.cc")));
+        Assert.Equal("hull", File.ReadAllText(Staged("Mods/ship-a/mesh/hull.glb")));
+    }
+
+    [Fact]
+    public void StagesNothingElseFromGameData()
+    {
+        PlayerStaging.Stage(Repo, Player);
+
+        var staged = Directory.GetFileSystemEntries(Path.Combine(Player, "GameData")).Select(Path.GetFileName).OrderBy(name => name).ToArray();
+        Assert.Equal(new[] { "Aetheria.cc", "Narrative" }, staged);
+    }
+
+    [Fact]
+    public void ReplacesWhatAnEarlierBuildLeftInGameData()
+    {
+        Write(Staged("Aetheria.cc"), "stale");
+        Write(Staged("run.cc"), "a played run");
+        Write(Staged("Mods/gone/ship.cc"), "removed mod");
+
+        PlayerStaging.Stage(Repo, Player);
+
+        Assert.Equal("catalog-bytes", File.ReadAllText(Staged("Aetheria.cc")));
+        Assert.False(File.Exists(Staged("run.cc")));
+        Assert.False(Directory.Exists(Staged("Mods")));
+    }
+
+    [Fact]
+    public void RefusesAMissingCatalogNamingItAndLeavesNoGameData()
+    {
+        File.Delete(Source("Aetheria.cc"));
+
+        var error = Assert.Throws<InvalidOperationException>(() => PlayerStaging.Stage(Repo, Player));
+
+        Assert.Contains("GameData/Aetheria.cc", error.Message);
+        Assert.False(Directory.Exists(Path.Combine(Player, "GameData")));
+    }
+
+    [Fact]
+    public void RefusesMissingNarrative()
+    {
+        Directory.Delete(Source("Narrative"), true);
+
+        var error = Assert.Throws<InvalidOperationException>(() => PlayerStaging.Stage(Repo, Player));
+
+        Assert.Contains("GameData/Narrative", error.Message);
+    }
+
+    private static void Write(string path, string text)
+    {
+        Directory.CreateDirectory(Path.GetDirectoryName(path));
+        File.WriteAllText(path, text);
+    }
+}

tests/Aetheria.Shared.Tests/StatResolverTests.cs

@@ -441,7 +441,7 @@ public sealed class StatResolverTests : IDisposable
         for (var i = 0; i < 20; i++)
         {
             var lot = items.Lots.Add(new Lot { Design = cache.RefOf<ItemData>(boosterData), Origin = new Attributed(), Quality = .5f, Roles = new List<RoleFill>() });
-            var consumableItem = new ConsumableItem { Data = cache.RefOf<ItemData>(boosterData), Lot = lot };
+            var consumableItem = Assert.IsType<ConsumableItem>(items.CreateInstance(lot));
             ship.ActivateConsumable(consumableItem);
 
             // Duration is 0.01s; one 1-second tick expires it and drives Entity.Update's expiry branch.
@@ -452,4 +452,132 @@ public sealed class StatResolverTests : IDisposable
         Assert.Equal(baselineCache, resolver.CacheEntryCount);
         Assert.Equal(baselineModifiers, resolver.ModifierEntryCount);
     }
+
+    // Ruling boost-stacking-multiply: every multiplier on one stat multiplies, with no stacking penalty, and every
+    // constant adds. The rig is the production path end to end: gear carrying StatModifierData is equipped on a ship
+    // beside a thruster, a consumable is minted through ItemManager.CreateInstance and activated on the ship, and
+    // the resolved value is read through EquippedItem.Evaluate. Nothing here calls AttachModifier by hand.
+    private sealed class ThrustRig
+    {
+        public CultCache Cache;
+        public ItemManager Items;
+        public Ship Ship;
+        public EquippedItem Engine;
+        public PerformanceStat Thrust;
+        public Func<ConsumableItem> Consumable; // null when the rig was built without one
+
+        public float Resolved => Engine.Evaluate(Thrust);
+        // Two ticks: the first executes every modifier, the second applies it (StatModifier.Update).
+        public void Tick(float dt) { for (var i = 0; i < 2; i++) Ship.Update(dt); }
+    }
+
+    private static StatModifierData ThrustModifier(StatModifierType type, float value) => new StatModifierData
+    {
+        Stat = new StatReference { Target = nameof(ThrusterData), Stat = nameof(ThrusterData.Thrust) },
+        Modifier = new PerformanceStat { Min = value, Max = value },
+        Type = type
+    };
+
+    // A Thrust-10 thruster and one gear per entry of `gear`, in that attach order, plus (optionally) a consumable
+    // whose single modifier is `consumable`. The hull has four hardpoints, so at most three gear modifiers.
+    private ThrustRig BuildThrustRig((StatModifierType Type, float Value)[] gear, (StatModifierType Type, float Value)? consumable = null)
+    {
+        var thrust = new PerformanceStat { Min = 10, Max = 10 };
+        var cache = AetheriaStores.Open(Catalog, catalogWritable: true);
+        cache.Upsert(new TestCatalogGlobal { Name = "Temperament" });
+        var hullShape = new Shape(3, 3);
+        foreach (var cell in hullShape.AllCoordinates) hullShape[cell] = true;
+        var cells = new[] { HardpointCell, SecondHardpointCell, FirstGunCell, SecondGunCell };
+        cache.Upsert(new HullData
+        {
+            Name = "Skiff", HullType = HullType.Ship, Shape = hullShape, Durability = 10,
+            Hardpoints = cells.Select(c => new HardpointData { Type = HardpointType.Sensors, Position = c, Shape = new Shape() }).ToList()
+        });
+        cache.Upsert(new GearData { Name = "Engine", Hardpoint = HardpointType.Sensors, Shape = new Shape(), Durability = 10, Behaviors = { new ThrusterData { Thrust = thrust } } });
+        for (var i = 0; i < gear.Length; i++)
+            cache.Upsert(new GearData { Name = "Boost" + i, Hardpoint = HardpointType.Sensors, Shape = new Shape(), Durability = 10, Behaviors = { ThrustModifier(gear[i].Type, gear[i].Value) } });
+        if (consumable != null)
+            cache.Upsert(new ConsumableItemData { Name = "Stim", Duration = 1f, Shape = new Shape(), Behaviors = { ThrustModifier(consumable.Value.Type, consumable.Value.Value) } });
+        cache.FlushAsync().Wait();
+
+        var items = new ItemManager(cache, new ProvenanceLedger(), Settings(), _ => { });
+        var zone = new Zone(items, new PlanetSettings(), new ZonePack(), new GalaxyZone { Name = "Test Zone", Owner = null }, null);
+        var ship = new Ship(items, zone, Mint(cache, items, cache.GetByName<HullData>("Skiff")), new EntitySettings());
+        Assert.True(ship.TryEquip(Mint(cache, items, cache.GetByName<GearData>("Engine")), cells[0]));
+        for (var i = 0; i < gear.Length; i++)
+        {
+            // A test gear has no authored heat response, so its thermal performance reads 0 and it would sit offline;
+            // the override is the entity's own switch for keeping a part running, not a stand-in for the rule.
+            var boost = Mint(cache, items, cache.GetByName<GearData>("Boost" + i));
+            boost.OverrideShutdown = true;
+            Assert.True(ship.TryEquip(boost, cells[i + 1]));
+        }
+        ship.OverrideShutdown = true;
+        zone.Entities.Add(ship);
+        ship.Activate();
+
+        Func<ConsumableItem> mint = null;
+        if (consumable != null)
+        {
+            var design = cache.GetByName<ConsumableItemData>("Stim");
+            mint = () => Assert.IsType<ConsumableItem>(items.CreateInstance(items.Lots.Add(
+                new Lot { Design = cache.RefOf<ItemData>(design), Origin = new Attributed(), Quality = .5f, Roles = new List<RoleFill>() })));
+        }
+        return new ThrustRig { Cache = cache, Items = items, Ship = ship, Engine = ship.Equipment.Single(e => e.Data.Name == "Engine"), Thrust = thrust, Consumable = mint };
+    }
+
+    // Two scales multiply: x1.2 and x1.25 on one stat resolve to base x1.5, and x1.1, x1.2, x1.25 to base x1.65,
+    // whatever order they attach in. Mutations at StatResolver.ScaleModifier: a sum of excesses reads 14.5 and
+    // 15.5, the strongest-only rule 12.5, a diminishing curve 14.67, and `result *= value * value` or
+    // `result *= value + 0.01f` (functions of the scale itself) read off 15.
+    [Theory]
+    [InlineData(new[] { 1.2f, 1.25f }, 15f)]
+    [InlineData(new[] { 1.25f, 1.2f }, 15f)]
+    [InlineData(new[] { 1.1f, 1.2f, 1.25f }, 16.5f)]
+    [InlineData(new[] { 1.25f, 1.1f, 1.2f }, 16.5f)]
+    [InlineData(new[] { 1.2f, 1.25f, 1.1f }, 16.5f)]
+    public void TwoScalesOnOneStatMultiply(float[] scales, float expected)
+    {
+        var rig = BuildThrustRig(scales.Select(s => (StatModifierType.Multiplier, s)).ToArray());
+        using var _ = rig.Cache;
+        Assert.Equal(10f, rig.Resolved, 3); // modifiers not yet applied
+        rig.Tick(.1f);
+        Assert.Equal(expected, rig.Resolved, 3);
+    }
+
+    // A gear modifier and a consumable modifier on one drive's Thrust share one entry and multiply: x1.2 gear and
+    // x1.5 consumable read x1.8, and when the consumable expires only the gear's x1.2 remains.
+    [Fact]
+    public void AConsumableBoostMultipliesWithGear()
+    {
+        var rig = BuildThrustRig(new[] { (StatModifierType.Multiplier, 1.2f) }, (StatModifierType.Multiplier, 1.5f));
+        using var _ = rig.Cache;
+        rig.Tick(.1f);
+        Assert.Equal(12f, rig.Resolved, 3); // gear alone
+
+        rig.Ship.ActivateConsumable(rig.Consumable());
+        rig.Tick(.1f); // 0.8s of the 1s remain
+        Assert.Equal(18f, rig.Resolved, 3);
+
+        rig.Tick(.5f); // the consumable's duration has run out
+        Assert.Equal(12f, rig.Resolved, 3);
+    }
+
+    // Constants add, and compose with scales through PerformanceStat.Evaluate: (base x scale) + constant. +3 and +4
+    // resolve as a constant of 7; with a x2 scale beside them the value is Evaluate's for scale 2 and constant 7,
+    // (10 x 2) + 7. Mutations at ConstantModifier: `result = Math.Max(result, value)` reads constant 4;
+    // `result += value * 2` reads constant 14.
+    [Theory]
+    [InlineData(new[] { 3f, 4f }, new float[0], 1f, 7f, 17f)]
+    [InlineData(new[] { 3f, 4f }, new[] { 2f }, 2f, 7f, 27f)]
+    public void TwoConstantsOnOneStatAdd(float[] constants, float[] scales, float expectedScale, float expectedConstant, float expected)
+    {
+        var rig = BuildThrustRig(constants.Select(c => (StatModifierType.Constant, c))
+            .Concat(scales.Select(s => (StatModifierType.Multiplier, s))).ToArray());
+        using var _ = rig.Cache;
+        rig.Tick(.1f);
+        Assert.Equal(expectedScale, rig.Ship.Resolver.ScaleModifier(rig.Engine, rig.Thrust), 3);
+        Assert.Equal(expectedConstant, rig.Ship.Resolver.ConstantModifier(rig.Engine, rig.Thrust), 3);
+        Assert.Equal(expected, rig.Resolved, 3);
+    }
 }

tests/Aetheria.Shared.Tests/ThrottleLockTests.cs

@@ -0,0 +1,274 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using CultMath;
+using GameCult.Caching;
+using Xunit;
+using static CultMath.math;
+
+// A ThrottleLock on an active consumable replaces the pilot's movement intent with full forward, read once at
+// the top of Ship.Update's active branch. Turn is untouched. Every observation is a thruster's Axis after a real
+// Ship.Update, with the effect started through Entity.ActivateConsumable.
+public sealed class ThrottleLockTests : IDisposable
+{
+    private readonly string _root = Path.Combine(Path.GetTempPath(), "aetheria-throttlelock-" + Guid.NewGuid().ToString("N"));
+    private string Catalog => Path.Combine(_root, "Aetheria.cc");
+
+    public ThrottleLockTests() => Directory.CreateDirectory(_root);
+    public void Dispose() => Directory.Delete(_root, true);
+
+    private static GameplaySettings Settings() => new GameplaySettings
+    {
+        DefaultEntitySettings = new EntitySettings(),
+        Tiers = new[] { new RarityTier { Name = "Common", Quality = .5f, Rarity = 0, Color = new float3(1, 1, 1) } },
+        QualityPriceModifier = new ExponentialLerp()
+    };
+
+    private static PerformanceStat Constant(float v) => new PerformanceStat { Min = v, Max = v };
+
+    private static EquippableItem Mint(CultCache cache, ItemManager items, ItemData design, ItemRotation rotation = ItemRotation.None) => new EquippableItem
+    {
+        Data = cache.RefOf<ItemData>(design),
+        Durability = design is EquippableItemData equippable ? equippable.Durability : 0,
+        Rotation = rotation,
+        Lot = items.Lots.Add(new Lot { Design = cache.RefOf<ItemData>(design), Origin = new Attributed(), Quality = .5f, Roles = new List<RoleFill>() })
+    };
+
+    private sealed class Fixture
+    {
+        public CultCache Cache;
+        public ItemManager Items;
+        public Ship Ship;
+        public ConsumableItemData Lock;
+        public Thruster Forward, Reverse, Clockwise;
+        public Thruster[] Right, Left; // pairs with opposing torque: a lone off-axis strafe thruster cancels its own torque
+
+        public void ActivateLock() => Ship.ActivateConsumable(new ConsumableItem
+        {
+            Data = Cache.RefOf<ItemData>(Lock),
+            Lot = Items.Lots.Add(new Lot { Design = Cache.RefOf<ItemData>(Lock), Origin = new Attributed(), Quality = .5f, Roles = new List<RoleFill>() })
+        });
+    }
+
+    // One thruster per intent direction, plus two reverse thrusters either side of the centre line, one of
+    // which has clockwise torque (the one Turn reaches). Thrusters are found by their item's rotation, as Ship
+    // sorts them.
+    private Fixture Build(float lockDuration)
+    {
+        var cache = AetheriaStores.Open(Catalog, catalogWritable: true);
+        cache.Upsert(new TestCatalogGlobal { Name = "Temperament" });
+        var hullShape = new Shape(5, 5);
+        foreach (var cell in hullShape.AllCoordinates) hullShape[cell] = true;
+        cache.Upsert(new HullData { Name = "Skiff", HullType = HullType.Ship, Shape = hullShape, Durability = 10, Mass = 1000 });
+        cache.Upsert(new GearData
+        {
+            Name = "Thruster", Hardpoint = HardpointType.Tool, Shape = new Shape(), Durability = 10,
+            MinimumTemperature = 0, MaximumTemperature = 1000, OptimalTemperature = 280, PlateauWidth = 400,
+            Behaviors = { new ThrusterData { Thrust = Constant(100), Visibility = Constant(0), Heat = Constant(0), EnergyUsage = Constant(0) } }
+        });
+        var lockData = new ConsumableItemData { Name = "Overdrive", Duration = lockDuration, Behaviors = { new ThrottleLockData() } };
+        cache.Upsert(lockData);
+        cache.FlushAsync().Wait();
+
+        var items = new ItemManager(cache, new ProvenanceLedger(), Settings(), _ => { });
+        var zone = new Zone(items, new PlanetSettings(), new ZonePack(), new GalaxyZone { Name = "Test Zone", Owner = null }, null);
+        var ship = new Ship(items, zone, Mint(cache, items, cache.GetByName<HullData>("Skiff")), new EntitySettings());
+        var gear = cache.GetByName<GearData>("Thruster");
+        Assert.True(ship.TryEquip(Mint(cache, items, gear, ItemRotation.Reversed), new int2(2, 1)));
+        Assert.True(ship.TryEquip(Mint(cache, items, gear, ItemRotation.None), new int2(1, 2)));
+        Assert.True(ship.TryEquip(Mint(cache, items, gear, ItemRotation.None), new int2(3, 2)));
+        // Strafe pairs sit either side of the centre line across the ship's length, so their torques oppose.
+        Assert.True(ship.TryEquip(Mint(cache, items, gear, ItemRotation.CounterClockwise), new int2(1, 1)));
+        Assert.True(ship.TryEquip(Mint(cache, items, gear, ItemRotation.CounterClockwise), new int2(1, 3)));
+        Assert.True(ship.TryEquip(Mint(cache, items, gear, ItemRotation.Clockwise), new int2(3, 1)));
+        Assert.True(ship.TryEquip(Mint(cache, items, gear, ItemRotation.Clockwise), new int2(3, 3)));
+        zone.Entities.Add(ship);
+        ship.Aim = float3(0, 0, 1);
+        ship.Activate();
+
+        var thrusters = ship.GetBehaviors<Thruster>().ToArray();
+        return new Fixture
+        {
+            Cache = cache, Items = items, Ship = ship, Lock = cache.GetByName<ConsumableItemData>("Overdrive"),
+            Forward = thrusters.Single(t => t.Item.EquippableItem.Rotation == ItemRotation.Reversed),
+            Right = thrusters.Where(t => t.Item.EquippableItem.Rotation == ItemRotation.CounterClockwise).ToArray(),
+            Left = thrusters.Where(t => t.Item.EquippableItem.Rotation == ItemRotation.Clockwise).ToArray(),
+            Reverse = thrusters.First(t => t.Item.EquippableItem.Rotation == ItemRotation.None && t.Torque <= 0),
+            Clockwise = thrusters.First(t => t.Item.EquippableItem.Rotation == ItemRotation.None && t.Torque > 0)
+        };
+    }
+
+    // Spec ALockedThrottleIgnoresIntent. Mutation: read MovementDirection in place of move at any of the six
+    // sites in Ship.Update and the matching assertion goes red.
+    [Fact]
+    public void ALockedThrottleIgnoresIntent()
+    {
+        var f = Build(100f);
+        using var _ = f.Cache;
+        f.ActivateLock();
+        Assert.True(f.Ship.ThrottleLocked);
+
+        foreach (var intent in new[] { float2(0, -1), float2(1, 0), float2(-1, 0) })
+        {
+            f.Ship.MovementDirection = intent;
+            f.Ship.Turn = 0;
+            f.Ship.Update(0.01f);
+            Assert.Equal(1f, f.Forward.Axis);
+            Assert.Equal(0f, f.Reverse.Axis);
+            Assert.All(f.Right, t => Assert.Equal(0f, t.Axis));
+            Assert.All(f.Left, t => Assert.Equal(0f, t.Axis));
+        }
+
+        // Turning stays with the pilot: the clockwise-torque thruster follows Turn while the lock holds.
+        f.Ship.MovementDirection = float2(0, -1);
+        f.Ship.Turn = 1;
+        f.Ship.Update(0.01f);
+        Assert.Equal(1f, f.Clockwise.Axis);
+        f.Ship.Turn = 0;
+        f.Ship.Update(0.01f);
+        Assert.Equal(0f, f.Clockwise.Axis);
+    }
+
+    // Spec TheLockEndsWithItsEffect. Mutation: make ThrottleLocked a latch (set on activation, never cleared)
+    // and the post-expiry reverse axis stays 0.
+    [Fact]
+    public void TheLockEndsWithItsEffect()
+    {
+        var f = Build(1f);
+        using var _ = f.Cache;
+        f.ActivateLock();
+        f.Ship.MovementDirection = float2(0, -1);
+        f.Ship.Update(0.5f);
+        Assert.Equal(0f, f.Reverse.Axis);
+
+        f.Ship.Update(2f); // runs past the Duration; the effect leaves at the end of this tick
+        Assert.False(f.Ship.ThrottleLocked);
+
+        f.Ship.Update(0.01f);
+        Assert.Equal(1f, f.Reverse.Axis);
+        Assert.Equal(0f, f.Forward.Axis);
+    }
+
+    // Spec AnUnlockedShipFollowsIntent. Mutation: replace the conditional by an unconditional float2(0, 1) and
+    // the reverse and strafe assertions go red.
+    [Fact]
+    public void AnUnlockedShipFollowsIntent()
+    {
+        var f = Build(1f);
+        using var _ = f.Cache;
+        Assert.False(f.Ship.ThrottleLocked);
+
+        f.Ship.MovementDirection = float2(0, -1);
+        f.Ship.Update(0.01f);
+        Assert.Equal(1f, f.Reverse.Axis);
+        Assert.Equal(0f, f.Forward.Axis);
+
+        f.Ship.MovementDirection = float2(1, 0);
+        f.Ship.Update(0.01f);
+        Assert.All(f.Right, t => Assert.Equal(1f, t.Axis));
+        Assert.All(f.Left, t => Assert.Equal(0f, t.Axis));
+        Assert.Equal(0f, f.Forward.Axis);
+
+        f.Ship.MovementDirection = float2(-1, 0);
+        f.Ship.Update(0.01f);
+        Assert.All(f.Left, t => Assert.Equal(1f, t.Axis));
+        Assert.All(f.Right, t => Assert.Equal(0f, t.Axis));
+
+        f.Ship.MovementDirection = float2(0, 1);
+        f.Ship.Update(0.01f);
+        Assert.Equal(1f, f.Forward.Axis);
+        Assert.Equal(0f, f.Reverse.Axis);
+    }
+
+    // Finding zero-stick-unpinned. Mutation: float2(0, length(MovementDirection)) as the locked intent. The lock
+    // supplies full forward whatever the stick's magnitude, including none and a short reverse push.
+    [Fact]
+    public void ALockedShipGetsFullForwardWhateverTheStickLength()
+    {
+        var f = Build(100f);
+        using var _ = f.Cache;
+        f.ActivateLock();
+        foreach (var intent in new[] { float2(0, 0), float2(.3f, .2f), float2(-.5f, -.5f) })
+        {
+            f.Ship.MovementDirection = intent;
+            f.Ship.Turn = 0;
+            f.Ship.Update(0.01f);
+            Assert.Equal(1f, f.Forward.Axis);
+            Assert.Equal(0f, f.Reverse.Axis);
+            Assert.All(f.Right, t => Assert.Equal(0f, t.Axis));
+            Assert.All(f.Left, t => Assert.Equal(0f, t.Axis));
+        }
+    }
+
+    // Finding ccw-turn-unpinned. Mutation: drop the counter-clockwise Turn. Turn in either sign reaches only the
+    // thrusters with torque of that sign, at full, while the lock holds forward.
+    [Fact]
+    public void ALockedShipTurnsBothWays()
+    {
+        var f = Build(100f);
+        using var _ = f.Cache;
+        f.ActivateLock();
+        var all = f.Ship.GetBehaviors<Thruster>().ToArray();
+        var cw = all.Where(t => t.Torque > 0 && t.Item.EquippableItem.Rotation == ItemRotation.None).ToArray();
+        var ccw = all.Where(t => t.Torque < 0 && t.Item.EquippableItem.Rotation == ItemRotation.None).ToArray();
+        Assert.NotEmpty(cw);
+        Assert.NotEmpty(ccw);
+        f.Ship.MovementDirection = float2(1, -1);
+        foreach (var turn in new[] { 1f, -1f })
+        {
+            f.Ship.Turn = turn;
+            f.Ship.Update(0.01f);
+            Assert.All(turn > 0 ? cw : ccw, t => Assert.Equal(1f, t.Axis));
+            Assert.All(turn > 0 ? ccw : cw, t => Assert.Equal(0f, t.Axis));
+            Assert.Equal(1f, f.Forward.Axis);
+        }
+    }
+
+    // Finding non-lock-consumable-unpinned. Mutation: any active consumable locks. A consumable without
+    // ThrottleLockData leaves the pilot's intent in force.
+    [Fact]
+    public void AConsumableWithoutTheLockDoesNotLock()
+    {
+        var f = Build(100f);
+        using var _ = f.Cache;
+        var plain = new ConsumableItemData { Name = "Plain", Duration = 100f };
+        f.Cache.Upsert(plain);
+        f.Ship.ActivateConsumable(new ConsumableItem
+        {
+            Data = f.Cache.RefOf<ItemData>(plain),
+            Lot = f.Items.Lots.Add(new Lot { Design = f.Cache.RefOf<ItemData>(plain), Origin = new Attributed(), Quality = .5f, Roles = new List<RoleFill>() })
+        });
+        Assert.False(f.Ship.ThrottleLocked);
+        f.Ship.MovementDirection = float2(0, -1);
+        f.Ship.Update(0.01f);
+        Assert.Equal(1f, f.Reverse.Axis);
+        Assert.Equal(0f, f.Forward.Axis);
+    }
+
+    // Finding lock-end-boundary-unpinned, finding lock-end-at-90pct-unpinned. Mutations: the lock ends at half
+    // Duration, at 0.8 or 0.9 of Duration, or one tick late. Duration 1 stepped in 0.25 s ticks (exact in
+    // floats) locks the axes on exactly four ticks (reverse stays 0), the effect is gone when the fourth ends,
+    // and the fifth tick follows the stick. The count scales with Duration: 2 s locks eight ticks.
+    [Theory]
+    [InlineData(1f, 4)]
+    [InlineData(2f, 8)]
+    public void TheLockEndsAtTheExactTickOfItsDuration(float duration, int lockedTicks)
+    {
+        var f = Build(duration);
+        using var _ = f.Cache;
+        f.ActivateLock();
+        f.Ship.MovementDirection = float2(0, -1);
+        for (var i = 0; i < lockedTicks; i++)
+        {
+            Assert.True(f.Ship.ThrottleLocked);
+            f.Ship.Update(.25f);
+            Assert.Equal(0f, f.Reverse.Axis);
+            Assert.Equal(1f, f.Forward.Axis);
+        }
+        Assert.False(f.Ship.ThrottleLocked);
+        f.Ship.Update(.25f);
+        Assert.Equal(1f, f.Reverse.Axis);
+        Assert.Equal(0f, f.Forward.Axis);
+    }
+}

tests/Aetheria.Shared.Tests/VapourCloudTests.cs

@@ -0,0 +1,431 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using CultMath;
+using GameCult.Caching;
+using GameCult.Caching.MessagePack;
+using MessagePack;
+using UniRx;
+using Xunit;
+using static CultMath.math;
+using float2 = CultMath.float2;
+using float3 = CultMath.float3;
+using int2 = CultMath.int2;
+
+// Vapour clouds in the sim (aetheria-release cut vapour-cloud, ruling vapour-cloud-obscuration): a VapourDump
+// behaviour vents a zone cloud that thins every sensor sight line through it, both ways, through Sensor.Gain's
+// one detection rule; a lock falls by the existing detection-threshold rule and nothing else. The scene is two
+// ships facing each other along z with a fixed visibility, so what a sensor gathers is a number the clouds
+// alone change: steady info is visibility x sensitivity / (distance x TargetInfoDecay), and visibility 100,
+// sensitivity 1, decay .5 puts it at .5 at range 400 (above the .1 threshold) and saturated at range 40.
+public sealed class VapourCloudTests : IDisposable
+{
+    private const float Dt = .05f;
+    private const float Threshold = .1f;
+    private readonly string _root = Path.Combine(Path.GetTempPath(), "aetheria-vapour-" + Guid.NewGuid().ToString("N"));
+    private readonly List<CultCache> _caches = new List<CultCache>();
+    private static readonly object Glow = new object();
+
+    public VapourCloudTests() => Directory.CreateDirectory(_root);
+
+    public void Dispose()
+    {
+        foreach (var c in _caches) c.Dispose();
+        Directory.Delete(_root, true);
+    }
+
+    private static PerformanceStat Constant(float v) => new PerformanceStat { Min = v, Max = v };
+
+    private static Shape Solid(int w, int h)
+    {
+        var shape = new Shape(w, h);
+        foreach (var cell in shape.AllCoordinates) shape[cell] = true;
+        return shape;
+    }
+
+    private sealed class Lab
+    {
+        public ItemManager Items;
+        public Zone Zone;
+        public Ship Observer;
+        public Ship Target;
+        public EquippedItem Dump;
+        public LockWeapon Lock;
+        public int Lot = 1;
+        public bool HoldTarget = true;
+    }
+
+    private Lab Build(float distance, float radius = 20f, float opacity = .9f, float lifetime = 1000f)
+    {
+        var settings = new GameplaySettings
+        {
+            DefaultEntitySettings = new EntitySettings(),
+            Tiers = new[] { new RarityTier { Name = "Common", Quality = .5f, Rarity = 0, Color = new float3(1, 1, 1) } },
+            QualityPriceModifier = new ExponentialLerp(),
+            TargetDetectionInfoThreshold = Threshold, TargetArmorInfoThreshold = .2f, TargetGearInfoThreshold = .8f,
+            TargetInfoDecay = .5f, VisibilityDecay = 0f,
+            FiringArc = 170, CommitHorizon = .5f, SchematicCellSize = 1f
+        };
+        var cache = AetheriaStores.Open(Path.Combine(_root, Guid.NewGuid().ToString("N") + ".cc"), catalogWritable: true);
+        _caches.Add(cache);
+        cache.Upsert(new TestCatalogGlobal { Name = "Temperament" });
+        cache.Upsert(new HullData
+        {
+            Name = "Hull", HullType = HullType.Ship, Shape = Solid(5, 5), Durability = 1000000, Mass = 1000,
+            Hardpoints = { new HardpointData { Type = HardpointType.Sensors, Position = new int2(0, 0), Shape = new Shape() } }
+        });
+        GearData Gear(string name, HardpointType hardpoint, BehaviorData behavior) => new GearData
+        {
+            Name = name, Hardpoint = hardpoint, Shape = new Shape(), Durability = 1,
+            MinimumTemperature = -1000, MaximumTemperature = 1000, OptimalTemperature = 0, PlateauWidth = 2000,
+            Behaviors = { behavior }
+        };
+        cache.Upsert(Gear("Eye", HardpointType.Tool, new SensorData
+        {
+            Sensitivity = Constant(1f),
+            SensitivityCurve = new BezierCurve { Keys = new[] { float4(0, 1, 0, 0), float4(1, 1, 0, 0) } },
+            PingBoost = Constant(.000004f), PingEnergy = Constant(0f), PingVisibility = Constant(5f),
+            PingRange = Constant(300f), PingCooldown = Constant(4f)
+        }));
+        cache.Upsert(Gear("Vent", HardpointType.Tool, new VapourDumpData
+        {
+            Radius = Constant(radius), Opacity = Constant(opacity), Lifetime = Constant(lifetime)
+        }));
+        cache.Upsert(Gear("LockGun", HardpointType.Sensors, new LockWeaponData
+        {
+            Damage = Constant(0), Range = Constant(1000), MinRange = Constant(0), Velocity = Constant(0),
+            Spread = Constant(0), DamageSpread = Constant(0), Penetration = Constant(0), Count = Constant(1),
+            BurstTime = Constant(0), Cooldown = Constant(1000),
+            DamageCurve = new BezierCurve { Keys = new[] { float4(0, 1, 0, 0), float4(1, 1, 0, 0) } },
+            LockSpeed = Constant(1), SensorImpact = Constant(1), LockAngle = Constant(170),
+            DirectionImpact = Constant(1), Decay = Constant(1)
+        }));
+        cache.FlushAsync().Wait();
+
+        var ledger = new ProvenanceLedger();
+        for (var i = 1; i <= 50; i++) ledger.Lots[i] = new Lot { Origin = new Attributed(), Quality = 1 };
+        var items = new ItemManager(cache, ledger, settings, _ => { });
+        var zone = new Zone(items, new PlanetSettings(), new ZonePack { Radius = 5000 }, new GalaxyZone { Name = "Vapour", Owner = null }, null);
+        var lab = new Lab { Items = items, Zone = zone };
+
+        EquippableItem Make(string name) => new EquippableItem
+        {
+            Data = items.ItemData.RefOf<ItemData>(items.ItemData.GetByName<GearData>(name)), Durability = 1, Lot = lab.Lot++
+        };
+        Ship NewShip()
+        {
+            var hull = items.ItemData.RefOf<ItemData>(items.ItemData.GetByName<HullData>("Hull"));
+            var ship = new Ship(items, zone, new EquippableItem { Data = hull, Durability = 1000000, Lot = lab.Lot++ }, new EntitySettings());
+            Assert.True(ship.TryEquip(Make("Eye")));
+            return ship;
+        }
+
+        lab.Observer = NewShip();
+        Assert.True(lab.Observer.TryEquip(Make("LockGun"), new int2(0, 0)));
+        lab.Target = NewShip();
+        var dump = Make("Vent");
+        Assert.True(lab.Target.TryEquip(dump));
+        lab.Dump = lab.Target.Equipment.Single(x => x.EquippableItem == dump);
+        // Held off until a test pulls the trigger: the dump vents on its first run.
+        lab.Dump.Enabled.Value = false;
+
+        zone.Entities.Add(lab.Observer);
+        zone.Entities.Add(lab.Target);
+        lab.Observer.Activate();
+        lab.Target.Activate();
+        lab.Observer.Position = float3(0, 0, 0);
+        lab.Observer.Aim = float3(0, 0, 1);
+        lab.Target.Position = float3(0, 0, distance);
+        lab.Target.Aim = float3(0, 0, -1);
+        lab.Observer.SetIff(lab.Target, true);
+        lab.Target.SetIff(lab.Observer, true);
+        zone.Update(0f);
+        lab.Lock = lab.Observer.Weapons.OfType<LockWeapon>().Single();
+        return lab;
+    }
+
+    // One tick: both ships stay where they were put, facing each other, each a fixed visibility to the other's sensor.
+    private static void Tick(Lab lab)
+    {
+        foreach (var ship in new[] { lab.Observer, lab.Target })
+        {
+            ship.VisibilitySources[Glow] = 100f;
+            if (ship != lab.Target || lab.HoldTarget) ship.Velocity = float2.zero;
+        }
+        lab.Observer.Direction = float2(0, 1);
+        lab.Target.Direction = float2(0, -1);
+        lab.Zone.Update(Dt);
+    }
+
+    private static void Run(Lab lab, int ticks)
+    {
+        for (var i = 0; i < ticks; i++) Tick(lab);
+    }
+
+    private static float Info(Ship watcher, Ship watched) => watcher.EntityInfoGathered[watched];
+
+    // The observer has settled on the target and holds a full lock on it: the state a cloud has to break.
+    private static void Establish(Lab lab)
+    {
+        Run(lab, 100);
+        Assert.True(Info(lab.Observer, lab.Target) > Threshold, "the observer never gathered the target");
+        Assert.Contains(lab.Target, lab.Observer.VisibleEnemies);
+        lab.Observer.SetTarget(lab.Target);
+        Run(lab, 100);
+        Assert.True(lab.Lock.IsLocked, "the observer never locked the target");
+        Assert.Empty(lab.Zone.Clouds);
+    }
+
+    private static void Vent(Lab lab)
+    {
+        lab.Dump.Enabled.Value = true;
+        for (var i = 0; i < 5 && lab.Zone.Clouds.Count == 0; i++) Tick(lab);
+        Assert.Single(lab.Zone.Clouds);
+    }
+
+    private static VapourCloud Hand(Zone zone, float2 at, float radius, float opacity, float lifetime = 1000f)
+    {
+        var cloud = new VapourCloud { Body = new KinematicBody { Position = at }, Radius = radius, Opacity = opacity, Lifetime = lifetime };
+        zone.Vent(cloud);
+        return cloud;
+    }
+
+    [Fact]
+    public void ACloudBreaksALockAtRange()
+    {
+        var lab = Build(400f);
+        Establish(lab);
+
+        Vent(lab);
+        var ticks = 0;
+        while (ticks++ < 600 && !lab.Observer.Target.Value.IsNone) Tick(lab);
+
+        Assert.True(lab.Observer.Target.Value.IsNone, "the cloud never broke the target");
+        Assert.True(Info(lab.Observer, lab.Target) < Threshold, $"info {Info(lab.Observer, lab.Target)} is above the threshold");
+        Run(lab, 3);
+        Assert.Equal(0f, lab.Lock.Lock);
+        Assert.DoesNotContain(lab.Target, lab.Observer.VisibleEnemies);
+    }
+
+    [Fact]
+    public void AStrongCloseSensorBurnsThrough()
+    {
+        var lab = Build(40f);
+        Establish(lab);
+        var before = Info(lab.Observer, lab.Target);
+
+        Vent(lab);
+        Run(lab, 600);
+
+        var after = Info(lab.Observer, lab.Target);
+        Assert.True(after < before - .2f, $"the cloud thinned nothing: {before} -> {after}");
+        Assert.True(after > Threshold, $"info {after} fell below the threshold");
+        Assert.Equal(lab.Target, lab.Observer.Target.Value.Entity);
+        Assert.True(lab.Lock.IsLocked);
+    }
+
+    [Fact]
+    public void TheCloudBlindsItsVenter()
+    {
+        var lab = Build(400f);
+        Run(lab, 100);
+        Assert.True(Info(lab.Target, lab.Observer) > Threshold, "the venter never gathered the observer");
+        Assert.Contains(lab.Observer, lab.Target.VisibleEnemies);
+
+        Vent(lab);
+        Run(lab, 300);
+
+        Assert.True(Info(lab.Target, lab.Observer) < Threshold);
+        Assert.DoesNotContain(lab.Observer, lab.Target.VisibleEnemies);
+        // (The observer updates before the venter in the tick that vents, so it is one tick behind.)
+        Assert.Equal(Info(lab.Observer, lab.Target), Info(lab.Target, lab.Observer), 3);
+    }
+
+    [Fact]
+    public void ACloudFadesAndIsRemoved()
+    {
+        var lab = Build(400f);
+        // Vented 3s into the zone's life: the fade runs from the vent, not from the zone's start.
+        for (var i = 0; i < 3; i++) lab.Zone.Update(1f);
+        var cloud = Hand(lab.Zone, float2(0, 0), 10f, .8f, lifetime: 10f);
+        var a = float2(-5, 0);
+        var b = float2(5, 0);
+        Assert.Equal(.2f, lab.Zone.Obscuration(a, b), 5);
+
+        for (var i = 0; i < 5; i++) lab.Zone.Update(1f);
+        Assert.Equal(.4f, cloud.OpacityAt(lab.Zone.Time), 5);
+        Assert.Equal(.6f, lab.Zone.Obscuration(a, b), 5);
+        Assert.Single(lab.Zone.Clouds);
+
+        for (var i = 0; i < 5; i++) lab.Zone.Update(1f);
+        Assert.Empty(lab.Zone.Clouds);
+        Assert.Equal(1f, lab.Zone.Obscuration(a, b));
+    }
+
+    [Fact]
+    public void ACloudDriftsWithItsVelocityUntilItFades()
+    {
+        var lab = Build(400f);
+        var cloud = new VapourCloud { Body = new KinematicBody { Position = float2(0, 0), Velocity = float2(10, 0) }, Radius = 5f, Opacity = .5f, Lifetime = 1000f };
+        lab.Zone.Vent(cloud);
+        Assert.Equal(.5f, lab.Zone.Obscuration(float2(0, -20), float2(0, 20)), 5);
+
+        lab.Zone.Update(1f);
+
+        // The launch velocity decays on the zone's launch drag, so it has moved most of the way and no further.
+        Assert.InRange(cloud.Body.Position.x, 5f, 9.9f);
+        Assert.Equal(1f, lab.Zone.Obscuration(float2(0, -20), float2(0, 20)));
+        Assert.Equal(.5f, lab.Zone.Obscuration(float2(cloud.Body.Position.x, -20), float2(cloud.Body.Position.x, 20)), 2);
+    }
+
+    [Fact]
+    public void ACloudWithNoLifetimeObscuresNothing()
+    {
+        var lab = Build(400f);
+        var cloud = Hand(lab.Zone, float2(0, 0), 10f, .8f, lifetime: 0f);
+        Assert.Equal(0f, cloud.OpacityAt(lab.Zone.Time));
+        Assert.Equal(1f, lab.Zone.Obscuration(float2(-5, 0), float2(5, 0)));
+    }
+
+    [Fact]
+    public void AnEffectVentsOnce()
+    {
+        var lab = Build(400f, radius: 17f, opacity: .7f, lifetime: 123f);
+        lab.HoldTarget = false;
+        Run(lab, 2);
+        lab.Target.Velocity = float2(3, 0);
+        VapourCloud vented = null;
+        float2 venterVelocity = float2.zero;
+        float2 venterAt = float2.zero;
+        float2 cloudVelocity = float2.zero;
+        float2 cloudAt = float2.zero;
+        using var sub = lab.Zone.Clouds.ObserveAdd().Subscribe(add =>
+        {
+            vented = add.Value;
+            cloudVelocity = add.Value.Body.Velocity;
+            cloudAt = add.Value.Body.Position;
+            venterVelocity = lab.Target.Velocity;
+            venterAt = lab.Target.Position.xz;
+        });
+
+        lab.Dump.Enabled.Value = true;
+        Run(lab, 100);
+
+        Assert.Single(lab.Zone.Clouds);
+        Assert.Same(vented, lab.Zone.Clouds.Single());
+        Assert.True(length(venterVelocity) > 0f, "the venter was not moving");
+        Assert.Equal(venterVelocity, cloudVelocity);
+        Assert.Equal(venterAt, cloudAt);
+        Assert.Same(lab.Target, vented.Venter);
+        // Each stat is the authored one, evaluated through the host.
+        Assert.Equal(17f, vented.Radius);
+        Assert.Equal(.7f, vented.Opacity);
+        Assert.Equal(123f, vented.Lifetime);
+    }
+
+    [Fact]
+    public void ACloudThinsOnlyTheSightLinesItTouches()
+    {
+        var lab = Build(400f);
+        var first = Hand(lab.Zone, float2(0, 0), 10f, .6f);
+        float Through(float2 a, float2 b) => lab.Zone.Obscuration(a, b);
+
+        Assert.Equal(.4f, Through(float2(-50, 0), float2(50, 0)), 5);
+        Assert.Equal(.4f, Through(float2(50, 0), float2(-50, 0)), 5);
+        // Passing wide of the centre but within the radius, neither end inside the disc.
+        Assert.Equal(.4f, Through(float2(-50, 9.9f), float2(50, 9.9f)), 5);
+        Assert.Equal(1f, Through(float2(-50, 10.1f), float2(50, 10.1f)));
+        // Ending inside the disc, and a point inside it (the observer inside its own cloud).
+        Assert.Equal(.4f, Through(float2(-50, 0), float2(5, 0)), 5);
+        Assert.Equal(.4f, Through(float2(3, 0), float2(3, 0)), 5);
+        Assert.Equal(1f, Through(float2(30, 0), float2(30, 0)));
+        // A segment that stops short of the disc, or starts past it, touches nothing even on the same line.
+        Assert.Equal(1f, Through(float2(-50, 0), float2(-20, 0)));
+        Assert.Equal(1f, Through(float2(20, 0), float2(50, 0)));
+
+        // Two clouds on one sight line multiply.
+        var second = Hand(lab.Zone, float2(30, 0), 5f, .5f);
+        Assert.NotEqual(first.Id, second.Id);
+        Assert.Equal(.2f, Through(float2(-50, 0), float2(50, 0)), 5);
+        Assert.Equal(.4f, Through(float2(-50, 0), float2(15, 0)), 5);
+    }
+
+    // Where the rule is decided: once the start-up seed has decayed away, the info a sensor settles at is what
+    // survives the cloud times what the open sight line settles at, in both directions.
+    [Fact]
+    public void TheGainIsScaledByWhatSurvivesTheCloud()
+    {
+        var clear = Build(400f);
+        var cloudy = Build(400f);
+        // Mid-way between them and clear of both: only the segment, not either end, touches it.
+        Hand(cloudy.Zone, float2(0, 200), 10f, .6f, lifetime: 1e6f);
+        Run(clear, 400);
+        Run(cloudy, 400);
+
+        Assert.True(Info(clear.Observer, clear.Target) > Threshold);
+        Assert.Equal(.4f, Info(cloudy.Observer, cloudy.Target) / Info(clear.Observer, clear.Target), 2);
+        Assert.Equal(.4f, Info(cloudy.Target, cloudy.Observer) / Info(clear.Target, clear.Observer), 2);
+    }
+
+    // A ping is gathered through the same rule. Settled, the tick that a ping reaches the target adds the ping gain
+    // in place of the passive one; that extra, in a lab with a cloud on the sight line, is what survives the
+    // cloud times the extra in the open (info is linear in the gain while nothing saturates).
+    [Fact]
+    public void ThePingGainIsScaledToo()
+    {
+        float PingExtra(Lab lab)
+        {
+            Run(lab, 400);
+            lab.Observer.Sensor.Ping();
+            var biggest = 0f;
+            var last = Info(lab.Observer, lab.Target);
+            for (var i = 0; i < 38; i++)
+            {
+                Tick(lab);
+                biggest = max(biggest, Info(lab.Observer, lab.Target) - last);
+                last = Info(lab.Observer, lab.Target);
+            }
+            return biggest;
+        }
+
+        var clear = Build(250f);
+        var cloudy = Build(250f);
+        Hand(cloudy.Zone, float2(0, 125), 10f, .6f, lifetime: 1e6f);
+
+        var open = PingExtra(clear);
+        Assert.True(open > .05f, $"the ping left no mark on the open trace ({open})");
+        Assert.Equal(.4f, PingExtra(cloudy) / open, 2);
+    }
+
+    // The chunk path reads the same rule: the passive rate toward a point is scaled by the same survivor fraction.
+    [Fact]
+    public void TheChunkRateIsScaledByTheSameFactor()
+    {
+        var lab = Build(100f);
+        var at = float2(0, 100);
+        var open = lab.Observer.Sensor.PassiveRate(100f, at);
+        Assert.True(open > 0f);
+
+        Hand(lab.Zone, float2(0, 50), 10f, .6f);
+        Assert.Equal(.4f, lab.Observer.Sensor.PassiveRate(100f, at) / open, 5);
+    }
+
+    // The dump's wire shape: BehaviorData union 42, its radius, opacity and lifetime at keys 1, 2 and 3.
+    [Fact]
+    public void TheDumpIsUnion42WithRadiusOpacityLifetimeAtKeys1To3()
+    {
+        var options = CultDocumentMessagePackSerialization.OptionsFor(typeof(ZonePack).Assembly);
+        var data = new VapourDumpData { Radius = Constant(1f), Opacity = Constant(2f), Lifetime = Constant(3f) };
+        var bytes = MessagePackSerializer.Serialize<BehaviorData>(data, options);
+
+        var reader = new MessagePackReader(bytes);
+        Assert.Equal(2, reader.ReadArrayHeader());
+        Assert.Equal(42, reader.ReadInt32());
+        Assert.Equal(4, reader.ReadArrayHeader());
+        reader.Skip();
+        Assert.Equal(1f, MessagePackSerializer.Deserialize<PerformanceStat>(ref reader, options).Min);
+        Assert.Equal(2f, MessagePackSerializer.Deserialize<PerformanceStat>(ref reader, options).Min);
+        Assert.Equal(3f, MessagePackSerializer.Deserialize<PerformanceStat>(ref reader, options).Min);
+    }
+}