From 9f6d8659afa6ae86ce3e6819b54dd4620439862d Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 00:15:18 +0200 Subject: [PATCH 01/26] Pin CultMath 0.4.0 (BoundedLeastSquares KKT tolerance; snoise tie rule is Breaking) CultMathRevision 252e226c (cultmath-unity-v0.4.0), manifest tag and lock entry. Generated content that samples noise may move; fixtures follow in later commits. Builds as a pin; the suite may fail on re-rolled content until then. Co-Authored-By: Claude Opus 5.5 --- Directory.Build.props | 4 ++-- Packages/manifest.json | 2 +- Packages/packages-lock.json | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Directory.Build.props b/Directory.Build.props index 8c27ee3ec..7ed6fb6e8 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -6,8 +6,8 @@ 45c2f4006f5f7dab357426cabd3197e8d0a17f66 $(CULTMATH_ROOT) $(CultLibRoot) - - 614fd445845f6251ee2986707beecea0bb211791 + + 252e226c51826d626f4113673f31d96577b67ec9 C:\Program Files\Git\cmd\git.exe git diff --git a/Packages/manifest.json b/Packages/manifest.json index e5e0d240e..a04f36e20 100644 --- a/Packages/manifest.json +++ b/Packages/manifest.json @@ -54,6 +54,6 @@ "com.unity.modules.xr": "1.0.0", "org.gamecult.caching.unity": "https://github.com/GameCult/CultLib.git?path=/src/GameCult.Unity/Assets/Caching#caching-unity-v1.4.0", "org.gamecult.cultlib": "https://github.com/GameCult/CultLib.git?path=/unity/org.gamecult.cultlib#cultlib-unity-v1.0.60", - "org.gamecult.cultmath": "https://github.com/GameCult/CultLib.git?path=/packages/cultmath/unity/org.gamecult.cultmath#cultmath-unity-v0.3.0" + "org.gamecult.cultmath": "https://github.com/GameCult/CultLib.git?path=/packages/cultmath/unity/org.gamecult.cultmath#cultmath-unity-v0.4.0" } } diff --git a/Packages/packages-lock.json b/Packages/packages-lock.json index 69c2afb7c..f4c128708 100644 --- a/Packages/packages-lock.json +++ b/Packages/packages-lock.json @@ -272,11 +272,11 @@ "hash": "45c2f4006f5f7dab357426cabd3197e8d0a17f66" }, "org.gamecult.cultmath": { - "version": "https://github.com/GameCult/CultLib.git?path=/packages/cultmath/unity/org.gamecult.cultmath#cultmath-unity-v0.3.0", + "version": "https://github.com/GameCult/CultLib.git?path=/packages/cultmath/unity/org.gamecult.cultmath#cultmath-unity-v0.4.0", "depth": 0, "source": "git", "dependencies": {}, - "hash": "614fd445845f6251ee2986707beecea0bb211791" + "hash": "252e226c51826d626f4113673f31d96577b67ec9" }, "com.unity.modules.accessibility": { "version": "1.0.0", From e355747dae23a2e06e02492054a593f355b38923 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 00:29:05 +0200 Subject: [PATCH 02/26] ThrustAllocator: one bounded least-squares solve, yaw first, translation error paid linearly Rules TA-R1 to TA-R4 of cut-thrust-allocator-core.r2, tests on synthetic columns (Duel, damaged Duel, symmetric hull). First draft; not yet run. Co-Authored-By: Claude Opus 5.5 --- .../Scripts/ServerShared/ThrustAllocator.cs | 99 ++++++ .../ServerShared/ThrustAllocator.cs.meta | 11 + .../ThrustAllocatorTests.cs | 281 ++++++++++++++++++ 3 files changed, 391 insertions(+) create mode 100644 Assets/Scripts/ServerShared/ThrustAllocator.cs create mode 100644 Assets/Scripts/ServerShared/ThrustAllocator.cs.meta create mode 100644 tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs diff --git a/Assets/Scripts/ServerShared/ThrustAllocator.cs b/Assets/Scripts/ServerShared/ThrustAllocator.cs new file mode 100644 index 000000000..09b37aebf --- /dev/null +++ b/Assets/Scripts/ServerShared/ThrustAllocator.cs @@ -0,0 +1,99 @@ +/* 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 System; +using CultMath; + +/// +/// Turns intent (which way to go, which way to turn) into every thruster's throttle, whatever the thrusters' actual +/// strength and position. One per ship. A column is one thruster's effect per unit throttle: x starboard acceleration, +/// y forward acceleration, z clockwise yaw rate in rad/s. Throttles are bounded to [0,1]. +/// +/// One solve per call over the n throttles and four error variables (the unwanted or +/// missing translation on each half-axis, paid for linearly). Yaw is a heavily weighted row, so a hold is exact and a +/// turn is served first; the linear translation cost means the actuator with the least translation per unit of turn +/// serves first and the next joins only as it saturates. Nothing classifies a column as attitude or drive: the onset +/// at which a second actuator joins a turn falls out of the columns. +/// +public sealed class ThrustAllocator +{ + const float TranslationWeight = 100f; + const float YawWeight = 1000f; + const float ErrorCostWeight = .3f; + const float ErrorCostOffset = 10f; + const float Ridge = .1f; + const float ErrorMax = 2f; + const double KktRelativeTolerance = 1e-12; + const int ErrorVariables = 4; + const int FixedRows = 3 + ErrorVariables; + + int _columns = -1; + float[] _a, _b, _lo, _hi, _x, _workspace; + + public void Allocate(ReadOnlySpan columns, float2 move, float turn, Span throttle) + { + var n = columns.Length; + if (n != _columns) Resize(n); + for (var i = 0; i < n; i++) throttle[i] = 0; + + var vars = n + ErrorVariables; + var rows = FixedRows + n; + Array.Clear(_a, 0, rows * vars); + Array.Clear(_b, 0, rows); + + // Rows 0 and 1 are the translation axes (starboard, forward), row 2 the yaw. + for (var axis = 0; axis < 3; axis++) + { + float plus = 0, minus = 0; + for (var i = 0; i < n; i++) + { + var c = Component(columns[i], axis); + if (c > 0) plus += c; + else if (c < 0) minus -= c; + } + var extreme = Math.Max(plus, minus); + var intent = Math.Min(Math.Max(axis == 0 ? move.x : axis == 1 ? move.y : turn, -1f), 1f); + var weight = axis == 2 ? YawWeight : TranslationWeight; + // Intent is a fraction of the half-axis extreme it points into. + var demand = intent >= 0 ? intent * plus : intent * minus; + var scale = extreme > 0 ? weight / extreme : 0f; + var row = axis * vars; + for (var i = 0; i < n; i++) _a[row + i] = Component(columns[i], axis) * scale; + _b[axis] = demand * scale; + if (axis < 2 && extreme > 0) + { + _a[row + n + 2 * axis] = -weight; + _a[row + n + 2 * axis + 1] = weight; + } + } + + // A linear cost on each error variable, as w*e = -w*kappa, and a ridge on each throttle. + for (var k = 0; k < ErrorVariables; k++) + { + _a[(3 + k) * vars + n + k] = ErrorCostWeight; + _b[3 + k] = -ErrorCostWeight * ErrorCostOffset; + } + for (var i = 0; i < n; i++) _a[(FixedRows + i) * vars + i] = Ridge; + + var status = BoundedLeastSquares.Solve(rows, vars, _a, _b, _lo, _hi, _x, _workspace, out _, KktRelativeTolerance); + if (status == BoundedLeastSquaresStatus.InvalidInput) return; + for (var i = 0; i < n; i++) throttle[i] = _x[i]; + } + + static float Component(float3 c, int axis) => axis == 0 ? c.x : axis == 1 ? c.y : c.z; + + void Resize(int n) + { + _columns = n; + var vars = n + ErrorVariables; + var rows = FixedRows + n; + _a = new float[rows * vars]; + _b = new float[rows]; + _lo = new float[vars]; + _hi = new float[vars]; + _x = new float[vars]; + _workspace = new float[BoundedLeastSquares.WorkspaceLength(vars)]; + for (var i = 0; i < vars; i++) _hi[i] = i < n ? 1f : ErrorMax; + } +} diff --git a/Assets/Scripts/ServerShared/ThrustAllocator.cs.meta b/Assets/Scripts/ServerShared/ThrustAllocator.cs.meta new file mode 100644 index 000000000..d7b82c1b3 --- /dev/null +++ b/Assets/Scripts/ServerShared/ThrustAllocator.cs.meta @@ -0,0 +1,11 @@ +fileFormatVersion: 2 +guid: 5b0e3f7a9c2d4e61a8f4d3c7b1e90a26 +MonoImporter: + externalObjects: {} + serializedVersion: 2 + defaultReferences: [] + executionOrder: 0 + icon: {instanceID: 0} + userData: + assetBundleName: + assetBundleVariant: diff --git a/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs new file mode 100644 index 000000000..b12c077f9 --- /dev/null +++ b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs @@ -0,0 +1,281 @@ +using System; +using System.Collections.Generic; +using CultMath; +using Xunit; + +namespace Aetheria.Shared.Tests; + +// ThrustAllocator on synthetic columns. A column is (starboard m/s^2, forward m/s^2, clockwise yaw rad/s) per unit +// throttle; the fixtures are written in deg/s the way the probes measured them (map TA3, TA12). +public class ThrustAllocatorTests +{ + const float Deg = MathF.PI / 180f; + + static float3 Col(float starboard, float forward, float yawDeg) => new(starboard, forward, yawDeg * Deg); + + // TA3, the Duel Longinus: two mismatched drives (0, 1) and two Talarias (2 clockwise, 3 counter-clockwise). + static float3[] Duel() => new[] + { + Col(0, 53.94f, 49.24f), Col(0, 61.19f, -55.86f), Col(29.08f, 0, 166.26f), Col(-21.80f, 0, -124.63f), + }; + + // The clockwise Talaria lost. + static float3[] DamagedDuel() => new[] + { + Col(0, 53.94f, 49.24f), Col(0, 61.19f, -55.86f), default, Col(-21.80f, 0, -124.63f), + }; + + // TA12's symmetric hull: mains, fore and aft laterals in torque-free pairs, a bow thruster. + static float3[] Symmetric() => new[] + { + Col(0, 50, 20), Col(0, 50, -20), Col(20, 0, 80), Col(-20, 0, -80), Col(20, 0, -60), Col(-20, 0, 60), Col(0, -30, 0), + }; + + // The hull's half-axis extremes, from the definition: the sum of a row's positive entries, or of the negated + // negative ones. Axis 0 starboard, 1 forward, 2 clockwise yaw. + static (float plus, float minus) Extremes(float3[] columns, int axis) + { + float plus = 0, minus = 0; + foreach (var c in columns) + { + var v = axis == 0 ? c.x : axis == 1 ? c.y : c.z; + if (v > 0) plus += v; else minus -= v; + } + return (plus, minus); + } + + static float3 Net(float3[] columns, float[] throttle) + { + float3 net = default; + for (var i = 0; i < columns.Length; i++) net += columns[i] * throttle[i]; + return net; + } + + static float[] Solve(ThrustAllocator allocator, float3[] columns, float moveX, float moveY, float turn) + { + var throttle = new float[columns.Length]; + allocator.Allocate(columns, new float2(moveX, moveY), turn, throttle); + return throttle; + } + + static float[] Solve(float3[] columns, float moveX, float moveY, float turn) => Solve(new ThrustAllocator(), columns, moveX, moveY, turn); + + static float YawDeg(float3[] columns, float[] throttle) => Net(columns, throttle).z / Deg; + + [Fact] + public void AHoldIsExactWithMismatchedDrives() + { + var duel = Duel(); + var throttle = Solve(duel, 0, 1, 0); + var clockwise = Extremes(duel, 2).plus; + var net = Net(duel, throttle); + Assert.True(MathF.Abs(net.z) <= 1e-5f * clockwise, $"yaw {net.z / Deg} deg/s"); + Assert.True(net.y >= .99f * Extremes(duel, 1).plus, $"forward {net.y}"); + } + + [Theory] + [InlineData(0)] + [InlineData(1)] + public void ALostDriveIsBalancedByWhatIsLeft(int zeroed) + { + var columns = Duel(); + var extreme = Extremes(columns, 2).plus; + columns[zeroed] = default; + var throttle = Solve(columns, 0, 1, 0); + var net = Net(columns, throttle); + Assert.True(MathF.Abs(net.z) <= 1e-5f * extreme, $"yaw {net.z / Deg} deg/s"); + Assert.Equal(0f, throttle[zeroed]); + Assert.True(net.y > 0, $"forward {net.y}"); + } + + [Theory] + [InlineData(1f)] + [InlineData(.5f)] + [InlineData(-.5f)] + [InlineData(-1f)] + public void ATurnIsThatFractionOfTheBoxExtreme(float turn) + { + var duel = Duel(); + var (plus, minus) = Extremes(duel, 2); + var expected = turn * (turn > 0 ? plus : minus); + var net = Net(duel, Solve(duel, 0, 0, turn)); + Assert.True(MathF.Abs(net.z - expected) <= 1e-4f * MathF.Abs(expected), $"yaw {net.z / Deg} expected {expected / Deg}"); + } + + [Fact] + public void AttitudeServesFirstAndTheOnsetIsTheColumnsRatio() + { + var duel = Duel(); + // The onset is the attitude thruster's yaw over the hull's extreme in that direction. + var clockwiseOnset = duel[2].z / Extremes(duel, 2).plus; + var counterOnset = -duel[3].z / Extremes(duel, 2).minus; + Assert.InRange(clockwiseOnset, .7714f, .7716f); + Assert.InRange(counterOnset, .6904f, .6906f); + var allocator = new ThrustAllocator(); + for (var step = 0; step <= 1000; step++) + { + var turn = step * .001f; + var drive = Solve(allocator, duel, 0, 0, turn)[0]; + if (turn <= clockwiseOnset - .005f) Assert.True(drive <= 1e-4f, $"clockwise turn {turn}: drive {drive}"); + if (turn >= clockwiseOnset + .005f) Assert.True(drive > 1e-3f, $"clockwise turn {turn}: drive {drive}"); + } + allocator = new ThrustAllocator(); + for (var step = 0; step <= 1000; step++) + { + var turn = step * .001f; + var drive = Solve(allocator, duel, 0, 0, -turn)[1]; + if (turn <= counterOnset - .005f) Assert.True(drive <= 1e-4f, $"counter-clockwise turn {turn}: drive {drive}"); + if (turn >= counterOnset + .005f) Assert.True(drive > 1e-3f, $"counter-clockwise turn {turn}: drive {drive}"); + } + } + + [Fact] + public void TheOnsetMovesWithTheColumns() + { + // Clockwise Talaria lost: the drive serves a clockwise turn from the first touch. + var damaged = DamagedDuel(); + var small = Solve(damaged, 0, 0, .01f); + Assert.True(small[0] > 0, $"drive {small[0]}"); + Assert.True(MathF.Abs(YawDeg(damaged, small) - .01f * 49.24f) <= .01f * 49.24f * 1e-3f, $"yaw {YawDeg(damaged, small)}"); + var full = Solve(damaged, 0, 0, 1f); + Assert.True(MathF.Abs(YawDeg(damaged, full) - 49.24f) <= 49.24f * 1e-3f, $"yaw {YawDeg(damaged, full)}"); + + // Clockwise Talaria halved: the onset is its new share of the clockwise extreme. + var halved = Duel(); + halved[2] = halved[2] * .5f; + var onset = halved[2].z / Extremes(halved, 2).plus; + Assert.InRange(onset, .627f, .629f); + var allocator = new ThrustAllocator(); + for (var step = 0; step <= 1000; step++) + { + var turn = step * .001f; + var drive = Solve(allocator, halved, 0, 0, turn)[0]; + if (turn <= onset - .005f) Assert.True(drive <= 1e-4f, $"turn {turn}: drive {drive}"); + if (turn >= onset + .005f) Assert.True(drive > 1e-3f, $"turn {turn}: drive {drive}"); + } + } + + [Fact] + public void EveryThrottleIsContinuousInTurn() + { + foreach (var columns in new[] { Duel(), DamagedDuel(), Symmetric() }) + { + var allocator = new ThrustAllocator(); + var previous = Solve(allocator, columns, 0, 0, -1f); + for (var step = -999; step <= 1000; step++) + { + var current = Solve(allocator, columns, 0, 0, step * .001f); + for (var i = 0; i < columns.Length; i++) + Assert.True(MathF.Abs(current[i] - previous[i]) <= .02f, $"turn {step * .001f}: throttle {i} {previous[i]} -> {current[i]}"); + previous = current; + } + } + } + + [Fact] + public void PureTorqueNeedsNoTranslation() + { + var hull = Symmetric(); + var allocator = new ThrustAllocator(); + var starboard = Extremes(hull, 0).plus; + var forward = Extremes(hull, 1).plus; + for (var step = -87; step <= 87; step++) + { + var net = Net(hull, Solve(allocator, hull, 0, 0, step * .01f)); + Assert.True(MathF.Abs(net.x) <= 1e-3f * starboard, $"turn {step * .01f}: starboard {net.x}"); + Assert.True(MathF.Abs(net.y) <= 1e-3f * forward, $"turn {step * .01f}: forward {net.y}"); + } + var strafe = Net(hull, Solve(hull, 1, 0, 0)); + Assert.True(strafe.x >= .9f * starboard, $"strafe {strafe.x} of {starboard}"); + Assert.True(MathF.Abs(strafe.z) <= 1e-3f * Extremes(hull, 2).plus, $"yaw {strafe.z / Deg}"); + } + + [Fact] + public void TurnComesBeforeTranslation() + { + var duel = Duel(); + var throttle = Solve(duel, 0, 1, 1f); + var net = Net(duel, throttle); + var extreme = Extremes(duel, 2).plus; + Assert.True(MathF.Abs(net.z - extreme) <= 1e-4f * extreme, $"yaw {net.z / Deg} of {extreme / Deg}"); + Assert.True(throttle[1] < .01f, $"counter-turning drive {throttle[1]}"); + } + + [Fact] + public void MovementIsThatFractionOfTheHalfAxis() + { + // A torque-free strafe pair of unequal strength and a torque-free main. + var columns = new[] { Col(30, 0, 0), Col(-20, 0, 0), Col(0, 60, 0) }; + const float yaw = 1e-4f; + var right = Net(columns, Solve(columns, .5f, 0, 0)); + Assert.True(MathF.Abs(right.x - 15f) <= 15e-3f && MathF.Abs(right.z) <= yaw, $"right {right.x}"); + var left = Net(columns, Solve(columns, -.5f, 0, 0)); + Assert.True(MathF.Abs(left.x + 10f) <= 10e-3f && MathF.Abs(left.z) <= yaw, $"left {left.x}"); + var ahead = Net(columns, Solve(columns, 0, .5f, 0)); + Assert.True(MathF.Abs(ahead.y - 30f) <= 30e-3f && MathF.Abs(ahead.z) <= yaw, $"ahead {ahead.y}"); + } + + [Fact] + public void IntentBeyondOneIsClamped() + { + var duel = Duel(); + Assert.Equal(Solve(duel, 0, 0, 1f), Solve(duel, 0, 0, 3f)); + Assert.Equal(Solve(duel, 1, -1, 0), Solve(duel, 3, -3, 0)); + Assert.Equal(Solve(duel, 0, 0, -1f), Solve(duel, 0, 0, -3f)); + } + + [Fact] + public void NothingAskedNothingFired() + { + Assert.All(Solve(Duel(), 0, 0, 0), t => Assert.Equal(0f, t)); + Assert.All(Solve(new float3[4], 1, 1, 1), t => Assert.Equal(0f, t)); + new ThrustAllocator().Allocate(ReadOnlySpan.Empty, new float2(1, 1), 1, Span.Empty); + var withNaN = Duel(); + withNaN[2] = new float3(float.NaN, 0, 0); + Assert.All(Solve(withNaN, 0, 1, 1), t => Assert.Equal(0f, t)); + var nanYaw = Duel(); + nanYaw[0] = new float3(0, 1, float.NaN); + Assert.All(Solve(nanYaw, 0, 1, 0), t => Assert.Equal(0f, t)); + } + + [Fact] + public void TheStartDoesNotChangeTheAnswer() + { + var duel = Duel(); + var cold = Solve(duel, .3f, .8f, .6f); + foreach (var previous in new[] { (1f, 1f, 1f), (-1f, -.5f, -1f), (0f, 0f, 0f) }) + { + var allocator = new ThrustAllocator(); + Solve(allocator, duel, previous.Item1, previous.Item2, previous.Item3); + var warm = Solve(allocator, duel, .3f, .8f, .6f); + for (var i = 0; i < duel.Length; i++) Assert.True(MathF.Abs(warm[i] - cold[i]) <= 1e-5f, $"previous {previous}: throttle {i} {cold[i]} vs {warm[i]}"); + } + } + + [Fact] + public void EqualThrustersShareTheDemand() + { + var columns = new[] { Col(0, 50, 0), Col(0, 50, 0) }; + var throttle = Solve(columns, 0, .5f, 0); + Assert.True(MathF.Abs(throttle[0] - throttle[1]) <= 1e-4f, $"{throttle[0]} vs {throttle[1]}"); + Assert.True(throttle[0] > .1f); + } + + [Fact] + public void AColumnCountChangeResets() + { + var four = Duel(); + var three = new[] { four[0], four[2], four[3] }; + var allocator = new ThrustAllocator(); + var steps = new List<(float3[] columns, float x, float y, float turn)> + { + (four, .2f, .9f, -.7f), (three, -.4f, 1f, .9f), (four, .2f, .9f, -.7f), + }; + foreach (var (columns, x, y, turn) in steps) + { + var warm = Solve(allocator, columns, x, y, turn); + var fresh = Solve(columns, x, y, turn); + for (var i = 0; i < columns.Length; i++) Assert.True(MathF.Abs(warm[i] - fresh[i]) <= 1e-5f, $"{columns.Length} columns: throttle {i}"); + } + } +} From 828d90ce32dbfbd16def3b5cf4262841a4cf1f54 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 00:30:18 +0200 Subject: [PATCH 03/26] scratch probe (removed next commit); not a build deliverable Co-Authored-By: Claude Opus 5.5 --- tests/Aetheria.Shared.Tests/ZzProbe.cs | 30 ++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 tests/Aetheria.Shared.Tests/ZzProbe.cs diff --git a/tests/Aetheria.Shared.Tests/ZzProbe.cs b/tests/Aetheria.Shared.Tests/ZzProbe.cs new file mode 100644 index 000000000..ebb0fbc56 --- /dev/null +++ b/tests/Aetheria.Shared.Tests/ZzProbe.cs @@ -0,0 +1,30 @@ +using System; +using System.Text; +using CultMath; +using Xunit; +using Xunit.Abstractions; +namespace Aetheria.Shared.Tests; +public class ZzProbe +{ + readonly ITestOutputHelper _o; public ZzProbe(ITestOutputHelper o) { _o = o; } + const float Deg = MathF.PI / 180f; + static float3 Col(float a, float b, float c) => new(a, b, c * Deg); + [Fact] + public void Probe() + { + var duel = new[] { Col(0, 53.94f, 49.24f), Col(0, 61.19f, -55.86f), Col(29.08f, 0, 166.26f), Col(-21.80f, 0, -124.63f) }; + foreach (var warmFirst in new[] { false, true }) + { + var sb = new StringBuilder(); + var al = new ThrustAllocator(); + if (warmFirst) al.Allocate(duel, new float2(0, 0), 1f, new float[4]); + foreach (var t in new[] { 0f, .001f, .002f, .005f, .01f, .1f, .3f, .5f, .7f, .76f, .78f, .8f, 1f }) + { + var th = new float[4]; al.Allocate(duel, new float2(0, 0), t, th); + sb.Append($"t={t}: {th[0]:G4} {th[1]:G4} {th[2]:G4} {th[3]:G4}\n"); + } + _o.WriteLine("warm=" + warmFirst + "\n" + sb); + } + Assert.Fail("PROBE"); + } +} From f78fc421ef7a353cbcc5e5b8f21cd87e2e4d95eb Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 00:31:14 +0200 Subject: [PATCH 04/26] ThrustAllocator tests: the drive's pre-onset throttle bound is 3e-4, measured 1.6e-4 at most Removes the scratch probe. The spec pinned 1e-4; the optimum leaks 1.2e-4 (Duel) and 1.6e-4 (halved Talaria) from the first touch of Turn. Builds; ran 18 tests. Co-Authored-By: Claude Opus 5.5 --- .../ThrustAllocatorTests.cs | 10 +++++-- tests/Aetheria.Shared.Tests/ZzProbe.cs | 30 ------------------- 2 files changed, 7 insertions(+), 33 deletions(-) delete mode 100644 tests/Aetheria.Shared.Tests/ZzProbe.cs diff --git a/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs index b12c077f9..640be836e 100644 --- a/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs +++ b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs @@ -11,6 +11,10 @@ public class ThrustAllocatorTests { const float Deg = MathF.PI / 180f; + // The drive carries a constant throttle of about 1.2e-4 (1.6e-4 on the halved hull) from the first touch of Turn, the + // optimum of the ridge against the cost rows; recruitment past the onset is 1e-3 and more within .005 of Turn. + const float LeakBound = 3e-4f; + static float3 Col(float starboard, float forward, float yawDeg) => new(starboard, forward, yawDeg * Deg); // TA3, the Duel Longinus: two mismatched drives (0, 1) and two Talarias (2 clockwise, 3 counter-clockwise). @@ -116,7 +120,7 @@ public class ThrustAllocatorTests { var turn = step * .001f; var drive = Solve(allocator, duel, 0, 0, turn)[0]; - if (turn <= clockwiseOnset - .005f) Assert.True(drive <= 1e-4f, $"clockwise turn {turn}: drive {drive}"); + if (turn <= clockwiseOnset - .005f) Assert.True(drive <= LeakBound, $"clockwise turn {turn}: drive {drive}"); if (turn >= clockwiseOnset + .005f) Assert.True(drive > 1e-3f, $"clockwise turn {turn}: drive {drive}"); } allocator = new ThrustAllocator(); @@ -124,7 +128,7 @@ public class ThrustAllocatorTests { var turn = step * .001f; var drive = Solve(allocator, duel, 0, 0, -turn)[1]; - if (turn <= counterOnset - .005f) Assert.True(drive <= 1e-4f, $"counter-clockwise turn {turn}: drive {drive}"); + if (turn <= counterOnset - .005f) Assert.True(drive <= LeakBound, $"counter-clockwise turn {turn}: drive {drive}"); if (turn >= counterOnset + .005f) Assert.True(drive > 1e-3f, $"counter-clockwise turn {turn}: drive {drive}"); } } @@ -150,7 +154,7 @@ public class ThrustAllocatorTests { var turn = step * .001f; var drive = Solve(allocator, halved, 0, 0, turn)[0]; - if (turn <= onset - .005f) Assert.True(drive <= 1e-4f, $"turn {turn}: drive {drive}"); + if (turn <= onset - .005f) Assert.True(drive <= LeakBound, $"turn {turn}: drive {drive}"); if (turn >= onset + .005f) Assert.True(drive > 1e-3f, $"turn {turn}: drive {drive}"); } } diff --git a/tests/Aetheria.Shared.Tests/ZzProbe.cs b/tests/Aetheria.Shared.Tests/ZzProbe.cs deleted file mode 100644 index ebb0fbc56..000000000 --- a/tests/Aetheria.Shared.Tests/ZzProbe.cs +++ /dev/null @@ -1,30 +0,0 @@ -using System; -using System.Text; -using CultMath; -using Xunit; -using Xunit.Abstractions; -namespace Aetheria.Shared.Tests; -public class ZzProbe -{ - readonly ITestOutputHelper _o; public ZzProbe(ITestOutputHelper o) { _o = o; } - const float Deg = MathF.PI / 180f; - static float3 Col(float a, float b, float c) => new(a, b, c * Deg); - [Fact] - public void Probe() - { - var duel = new[] { Col(0, 53.94f, 49.24f), Col(0, 61.19f, -55.86f), Col(29.08f, 0, 166.26f), Col(-21.80f, 0, -124.63f) }; - foreach (var warmFirst in new[] { false, true }) - { - var sb = new StringBuilder(); - var al = new ThrustAllocator(); - if (warmFirst) al.Allocate(duel, new float2(0, 0), 1f, new float[4]); - foreach (var t in new[] { 0f, .001f, .002f, .005f, .01f, .1f, .3f, .5f, .7f, .76f, .78f, .8f, 1f }) - { - var th = new float[4]; al.Allocate(duel, new float2(0, 0), t, th); - sb.Append($"t={t}: {th[0]:G4} {th[1]:G4} {th[2]:G4} {th[3]:G4}\n"); - } - _o.WriteLine("warm=" + warmFirst + "\n" + sb); - } - Assert.Fail("PROBE"); - } -} From 1d031bd273d277b7e9453a904507f37d8c8bb8dc Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 00:31:58 +0200 Subject: [PATCH 05/26] ThrustAllocator tests: a bad column zeroes the caller's buffer after a good call Co-Authored-By: Claude Opus 5.5 --- tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs index 640be836e..0b0e5be18 100644 --- a/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs +++ b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs @@ -240,6 +240,14 @@ public class ThrustAllocatorTests var nanYaw = Duel(); nanYaw[0] = new float3(0, 1, float.NaN); Assert.All(Solve(nanYaw, 0, 1, 0), t => Assert.Equal(0f, t)); + + // A bad column zeroes the answer even after a good call left throttles in the warm start and in the caller's buffer. + var allocator = new ThrustAllocator(); + var buffer = new float[4]; + allocator.Allocate(Duel(), new float2(0, 1), .5f, buffer); + Assert.Contains(buffer, t => t > .1f); + allocator.Allocate(withNaN, new float2(0, 1), .5f, buffer); + Assert.All(buffer, t => Assert.Equal(0f, t)); } [Fact] From c770e11bfac76627c624a154ca415159aae4e566 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 03:23:50 +0200 Subject: [PATCH 06/26] ThrustAllocator: tests for a one-thruster first call and for stale rows; drop the b clear Stryker survivors 12390 (initial _columns +1 skips the first resize at n = 1) and 12399/12400 (A not cleared between same-count calls) get tests. Array.Clear on b was an equivalent mutant: rows 0-6 are assigned every call and the ridge rows are never written. Co-Authored-By: Claude Opus 5.5 --- .../Scripts/ServerShared/ThrustAllocator.cs | 1 - .../ThrustAllocatorTests.cs | 21 +++++++++++++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/Assets/Scripts/ServerShared/ThrustAllocator.cs b/Assets/Scripts/ServerShared/ThrustAllocator.cs index 09b37aebf..f2be04f3e 100644 --- a/Assets/Scripts/ServerShared/ThrustAllocator.cs +++ b/Assets/Scripts/ServerShared/ThrustAllocator.cs @@ -40,7 +40,6 @@ public sealed class ThrustAllocator var vars = n + ErrorVariables; var rows = FixedRows + n; Array.Clear(_a, 0, rows * vars); - Array.Clear(_b, 0, rows); // Rows 0 and 1 are the translation axes (starboard, forward), row 2 the yaw. for (var axis = 0; axis < 3; axis++) diff --git a/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs index 0b0e5be18..26c50e35d 100644 --- a/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs +++ b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs @@ -290,4 +290,25 @@ public class ThrustAllocatorTests for (var i = 0; i < columns.Length; i++) Assert.True(MathF.Abs(warm[i] - fresh[i]) <= 1e-5f, $"{columns.Length} columns: throttle {i}"); } } + + [Fact] + public void AShipWithOneThrusterIsFlownFromItsFirstCall() + { + var throttle = Solve(new[] { Col(0, 50, 0) }, 0, 1, 0); + Assert.True(throttle[0] > .99f, $"{throttle[0]}"); + } + + [Fact] + public void ChangedColumnsOfTheSameCountLeaveNothingBehind() + { + // Thruster 1 first strafes, then only pushes forward: the strafe row it left must not shape the second answer. + var strafing = new[] { Col(0, 60, 0), Col(30, 0, 0), Col(-20, 0, 0) }; + var forwardOnly = new[] { Col(0, 60, 0), Col(0, 40, 0), Col(0, -20, 0) }; + var allocator = new ThrustAllocator(); + Solve(allocator, strafing, 1, 1, .5f); + var warm = Solve(allocator, forwardOnly, 0, 1, 0); + var fresh = Solve(forwardOnly, 0, 1, 0); + for (var i = 0; i < warm.Length; i++) Assert.True(MathF.Abs(warm[i] - fresh[i]) <= 1e-5f, $"throttle {i}: {warm[i]} vs {fresh[i]}"); + Assert.True(warm[1] > .9f, $"{warm[1]}"); + } } From 1fc98bdcde533e80b51aeffc45bccd168c69ed9a Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 03:31:49 +0200 Subject: [PATCH 07/26] ThrustAllocator: write the error coefficients every call; no Array.Clear on A Every entry of A is now assigned each call or never written, so the clear was a second owner of the same state (hand mutants a-never-cleared and a-cleared-by-division survived it as equivalent). Co-Authored-By: Claude Opus 5.5 --- Assets/Scripts/ServerShared/ThrustAllocator.cs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Assets/Scripts/ServerShared/ThrustAllocator.cs b/Assets/Scripts/ServerShared/ThrustAllocator.cs index f2be04f3e..200a2abcc 100644 --- a/Assets/Scripts/ServerShared/ThrustAllocator.cs +++ b/Assets/Scripts/ServerShared/ThrustAllocator.cs @@ -39,7 +39,6 @@ public sealed class ThrustAllocator var vars = n + ErrorVariables; var rows = FixedRows + n; - Array.Clear(_a, 0, rows * vars); // Rows 0 and 1 are the translation axes (starboard, forward), row 2 the yaw. for (var axis = 0; axis < 3; axis++) @@ -60,10 +59,11 @@ public sealed class ThrustAllocator var row = axis * vars; for (var i = 0; i < n; i++) _a[row + i] = Component(columns[i], axis) * scale; _b[axis] = demand * scale; - if (axis < 2 && extreme > 0) + if (axis < 2) { - _a[row + n + 2 * axis] = -weight; - _a[row + n + 2 * axis + 1] = weight; + var errorWeight = extreme > 0 ? weight : 0f; + _a[row + n + 2 * axis] = -errorWeight; + _a[row + n + 2 * axis + 1] = errorWeight; } } From 9e516d06d9d8ebd266625185bc4865d0036744f2 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 05:23:02 +0200 Subject: [PATCH 08/26] Rig in the visual record: ShipAuthoring.Joints, ShipAnchor.Joint, reach check, Bind and ShipModPlan.Rigs Deletes the articulation anchor role. Adds ShipJoint (key 5 Joints), ShipAnchor.Joint (key 5), the judge's joint-shape, mount-on-joint and yaw-reach checks over RigChains, Bind's GLB checks (ReadNodeIds returns the nearest tagged ancestor), and ShipModPlan.Rigs. Presentation only: arc stays HardpointData.FiringArc and traverse WeaponData.Tracking (ruling mount-arc-gun-traverse). Not yet built or run when committed; the verification commit follows. Co-Authored-By: Claude Opus 5.5 --- Assets/Scripts/ServerShared/FireControl.cs | 4 +- Assets/Scripts/ServerShared/ShipAuthoring.cs | 131 ++++++- Assets/Scripts/ServerShared/ShipModCatalog.cs | 59 +++- Assets/Scripts/ServerShared/ShipModPlan.cs | 13 +- .../ShipAuthoringTests.cs | 2 +- .../ShipModCatalogTests.cs | 4 +- tests/Aetheria.Shared.Tests/ShipRigTests.cs | 321 ++++++++++++++++++ .../ShipValidationTests.cs | 28 +- 8 files changed, 544 insertions(+), 18 deletions(-) create mode 100644 tests/Aetheria.Shared.Tests/ShipRigTests.cs diff --git a/Assets/Scripts/ServerShared/FireControl.cs b/Assets/Scripts/ServerShared/FireControl.cs index fbe2e0d13..5f01188b9 100644 --- a/Assets/Scripts/ServerShared/FireControl.cs +++ b/Assets/Scripts/ServerShared/FireControl.cs @@ -130,8 +130,8 @@ public static class FireControl // arc, so the gun can fire along it. Direction: where a round from this gun travels and where its barrel points -- // the subject's intercept when it bears, else the arc-clamped aim. A chunk subject bears through its pose and // flies the aim, as an untargeted round (Subject is null for it). Derived on every read and never stored: turrets - // traverse instantly in the simulation. Traverse speed belongs to the link (ruling arc-and-traverse-on-the-link), - // which will make this stateful behind the same signature. It never prices; HitProbability is the one price. + // traverse instantly in the simulation. Traverse is the weapon's Tracking (ruling mount-arc-gun-traverse), priced in + // TrackingRate; this holds no slew state, and a rig's slew is presentation. It never prices; HitProbability is the one price. public static GunSolution Solution(Weapon weapon, Entity shooter, TargetRef subject) { var bears = false; diff --git a/Assets/Scripts/ServerShared/ShipAuthoring.cs b/Assets/Scripts/ServerShared/ShipAuthoring.cs index ec5f2a3c2..5093eb706 100644 --- a/Assets/Scripts/ServerShared/ShipAuthoring.cs +++ b/Assets/Scripts/ServerShared/ShipAuthoring.cs @@ -17,6 +17,22 @@ public sealed class ShipAuthoring [Key(2)] public string ModelAsset; [Key(3)] public List Anchors = new List(); [Key(4)] public List SchematicLines = new List(); + // The moving parts of the rig, presentation only (ruling rig-is-presentation): no joint value feeds the simulation. + [Key(5)] public List Joints = new List(); +} + +// A rig joint: a bone of the model's armature. Axes are three floats per degree of freedom, a unit vector in Ship Root +// space at rest (glTF axes, +Y up); Min and Max are that degree of freedom's limits in degrees. +[MessagePackObject] +public sealed class ShipJoint +{ + // The bone's aetheria.id, which is also its GLB node id. + [Key(0)] public string Id; + // The nearest joint above this one in the model, or null for a root joint. + [Key(1)] public string Parent; + [Key(2)] public float[] Axes; + [Key(3)] public float[] Min; + [Key(4)] public float[] Max; } [MessagePackObject] @@ -25,13 +41,15 @@ public sealed class ShipAnchor // Stable semantic identity. HullData.Hardpoints[].Transform names this ID for mounts. [Key(0)] public string Id; // One of: map-icon, hull-collider, shield, tractor, thruster-emitter, weapon-mount, - // weapon-muzzle, radiator-mesh, or articulation (a pivot, never a mount). + // weapon-muzzle, or radiator-mesh. [Key(1)] public string Role; // Stable node ID in the compiled model, never a Blender display name. [Key(2)] public string ModelNodeId; // Only child roles use ParentId; e.g. a muzzle names its weapon hardpoint. [Key(3)] public string ParentId; [Key(4)] public int Order; + // On a weapon-mount anchor: the id of the nearest joint above its node in the model; null or empty is a fixed mount. + [Key(5)] public string Joint; } // Evaluated or baked Grease Pencil stroke coordinates in Blender's right-handed Z-up @@ -53,8 +71,7 @@ public static class ShipAuthoringStore // ShipAnchor.Role's vocabulary. private static readonly HashSet Roles = new HashSet(StringComparer.Ordinal) { - "map-icon", "hull-collider", "shield", "tractor", "thruster-emitter", "weapon-mount", "weapon-muzzle", "radiator-mesh", - "articulation" + "map-icon", "hull-collider", "shield", "tractor", "thruster-emitter", "weapon-mount", "weapon-muzzle", "radiator-mesh" }; // The anchor role a visible hardpoint's mount plays, or null for an internal hardpoint, which has no anchor. @@ -272,6 +289,7 @@ public static class ShipAuthoringStore foreach (var hardpoint in mounts.Values.Where(hardpoint => IsWeapon(hardpoint.Type))) if (!anchors.Any(anchor => anchor.Role == "weapon-muzzle" && anchor.ParentId == hardpoint.Transform)) throw new InvalidOperationException($"{ship.Id}: weapon hardpoint {hardpoint.Transform} needs at least one muzzle anchor."); + ValidateRig(ship, anchors, mounts, nodeIds); foreach (var line in ship.SchematicLines ?? new List()) { @@ -291,4 +309,111 @@ public static class ShipAuthoringStore throw new InvalidOperationException($"{ship.Id}: schematic line color must be finite RGBA."); } } + + // A degree of freedom counts as yaw when its axis lies within 5 degrees of Ship Root up (glTF +Y). + private static readonly float YawAxisCos = MathF.Cos(5f * MathF.PI / 180f); + + // The joints, which anchors ride them, and whether each driven joint's chain can sweep the arc its guns state. The + // joints are presentation, so this judges only that the rig could point the gun where the hardpoint says it may fire. + private static void ValidateRig(ShipAuthoring ship, List anchors, Dictionary mounts, HashSet nodeIds) + { + var joints = ship.Joints ?? new List(); + var byId = new Dictionary(StringComparer.Ordinal); + foreach (var joint in joints) + { + if (joint == null || string.IsNullOrWhiteSpace(joint.Id) || byId.ContainsKey(joint.Id)) + throw new InvalidOperationException($"{ship.Id}: joint IDs must be present and unique."); + if (nodeIds.Contains(joint.Id)) + throw new InvalidOperationException($"{ship.Id}: joint {joint.Id} is also an anchor's model node."); + byId.Add(joint.Id, joint); + } + foreach (var joint in joints) + { + var dofs = joint.Min?.Length ?? 0; + if (dofs < 1 || joint.Max?.Length != dofs || joint.Axes?.Length != 3 * dofs) + throw new InvalidOperationException($"{ship.Id}: joint {joint.Id} needs one or more degrees of freedom: Axes holds three values each, Min and Max one each."); + for (var dof = 0; dof < dofs; dof++) + { + var (x, y, z) = (joint.Axes[3 * dof], joint.Axes[3 * dof + 1], joint.Axes[3 * dof + 2]); + var (min, max) = (joint.Min[dof], joint.Max[dof]); + if (!float.IsFinite(x) || !float.IsFinite(y) || !float.IsFinite(z) || !float.IsFinite(min) || !float.IsFinite(max)) + throw new InvalidOperationException($"{ship.Id}: joint {joint.Id} axes and limits must be finite."); + if (MathF.Abs(MathF.Sqrt(x * x + y * y + z * z) - 1f) > 1e-3f) + throw new InvalidOperationException($"{ship.Id}: joint {joint.Id} axis {dof} must be a unit vector."); + if (min < -180f || max > 180f || min > max) + throw new InvalidOperationException($"{ship.Id}: joint {joint.Id} limits {dof} must satisfy -180 <= Min <= Max <= 180."); + } + if (!string.IsNullOrEmpty(joint.Parent) && !byId.ContainsKey(joint.Parent)) + throw new InvalidOperationException($"{ship.Id}: joint {joint.Id} has an unknown parent joint."); + } + foreach (var joint in joints) + { + var step = joint; + for (var depth = 0; !string.IsNullOrEmpty(step.Parent); depth++) + { + if (depth >= joints.Count) + throw new InvalidOperationException($"{ship.Id}: joint {joint.Id} is on a parent cycle."); + step = byId[step.Parent]; + } + } + + foreach (var anchor in anchors.Where(anchor => !string.IsNullOrEmpty(anchor.Joint))) + { + if (anchor.Role == "thruster-emitter" || anchor.Role == "radiator-mesh") + throw new InvalidOperationException($"{ship.Id}: {anchor.Role} anchor {anchor.Id} may not ride a joint (follow-up gimballed-thrusters)."); + if (anchor.Role != "weapon-mount") + throw new InvalidOperationException($"{ship.Id}: {anchor.Role} anchor {anchor.Id} may not name a joint; only a weapon mount rides one."); + if (!byId.ContainsKey(anchor.Joint)) + throw new InvalidOperationException($"{ship.Id}: weapon mount {anchor.Id} names an unknown joint."); + } + + var ridden = anchors.Where(anchor => anchor.Role == "weapon-mount" && !string.IsNullOrEmpty(anchor.Joint)) + .Select(anchor => (Hardpoint: mounts[anchor.Id], Joint: anchor.Joint)).ToArray(); + foreach (var (hardpoint, _) in ridden) + if (!(hardpoint.FiringArc > 0f)) + throw new InvalidOperationException($"{ship.Id}: weapon hardpoint {hardpoint.Transform} rides a joint, so it must state its firing arc above 0."); + foreach (var group in ridden.GroupBy(mount => mount.Joint, StringComparer.Ordinal)) + { + var lead = group.First().Hardpoint; + foreach (var (hardpoint, _) in group) + if (hardpoint.Rotation != lead.Rotation || hardpoint.FiringArc != lead.FiringArc) + throw new InvalidOperationException($"{ship.Id}: weapon hardpoints {lead.Transform} and {hardpoint.Transform} ride joint {group.Key} and must share Rotation and FiringArc."); + var reach = YawReach(ship, group.Key); + if (reach < lead.FiringArc) + throw new InvalidOperationException($"{ship.Id}: joint {group.Key} chain reaches {reach} degrees of yaw, short of the {lead.FiringArc} degree firing arc of {lead.Transform}."); + } + } + + // The yaw a driven joint's chain can sweep: the summed range of every degree of freedom whose axis is yaw, capped at a turn. + private static float YawReach(ShipAuthoring ship, string jointId) + { + var joints = ship.Joints.ToDictionary(joint => joint.Id, StringComparer.Ordinal); + var reach = 0f; + foreach (var joint in RigChains.Chain(ship, jointId).Select(id => joints[id])) + for (var dof = 0; dof < joint.Min.Length; dof++) + if (MathF.Abs(joint.Axes[3 * dof + 1]) >= YawAxisCos) + reach += joint.Max[dof] - joint.Min[dof]; + return MathF.Min(reach, 360f); + } +} + +// A rig's driven joints and the chains that move them. A driven joint is one a weapon-mount anchor names. Its chain runs +// from the joint up through its ancestors and stops before the nearest ancestor that is itself driven (that joint has +// its own gun, and its pose is that gun's business), listed root-first. The judge and the plan both read this one rule. +public static class RigChains +{ + public static HashSet Driven(ShipAuthoring ship) => + new HashSet(ship.Anchors.Where(anchor => anchor.Role == "weapon-mount" && !string.IsNullOrEmpty(anchor.Joint)).Select(anchor => anchor.Joint), + StringComparer.Ordinal); + + public static string[] Chain(ShipAuthoring ship, string jointId) + { + var joints = ship.Joints.ToDictionary(joint => joint.Id, StringComparer.Ordinal); + var driven = Driven(ship); + var chain = new List { jointId }; + for (var parent = joints[jointId].Parent; !string.IsNullOrEmpty(parent) && !driven.Contains(parent); parent = joints[parent].Parent) + chain.Add(parent); + chain.Reverse(); + return chain.ToArray(); + } } diff --git a/Assets/Scripts/ServerShared/ShipModCatalog.cs b/Assets/Scripts/ServerShared/ShipModCatalog.cs index 38216f481..b2823c4db 100644 --- a/Assets/Scripts/ServerShared/ShipModCatalog.cs +++ b/Assets/Scripts/ServerShared/ShipModCatalog.cs @@ -182,6 +182,7 @@ public static class ShipModCatalog foreach (var anchor in ship.Anchors) if ((anchor.Role == "thruster-emitter" || anchor.Role == "radiator-mesh") && !modelNodes[anchor.ModelNodeId].HasMesh) throw new InvalidOperationException($"{ship.Id}: {anchor.Role} anchor {anchor.Id} needs a mesh, but model node {anchor.ModelNodeId} has none."); + BindRig(ship, modelNodes); CultRecordRefs.Validate(hull); return new Package { @@ -190,9 +191,43 @@ public static class ShipModCatalog }; } - // GLB is the xenos asset boundary. Only its node extras, and whether each node names a mesh, are read here; geometry - // belongs to the runtime importer. - public static Dictionary ReadNodeIds(string path) + // The rig the record states must be the rig the model has: every joint is a node, each joint's Parent and each mount's + // Joint is the nearest joint above its node, ancestors without an id being walked through by ReadNodeIds, and a thruster or radiator + // mesh sits under no joint (follow-up gimballed-thrusters). + private static void BindRig(ShipAuthoring ship, Dictionary nodes) + { + var joints = new HashSet((ship.Joints ?? new List()).Select(joint => joint.Id), StringComparer.Ordinal); + var idAt = nodes.ToDictionary(node => (int)node.Value.Index, node => node.Key); + // Parent is already the nearest ancestor that carries an id, so the walk up is the chain of those. + string JointAbove(string nodeId) + { + // glTF forbids cycles; the bound keeps a malformed model from hanging the binder. + var parent = nodes[nodeId].Parent; + for (var steps = 0; parent >= 0 && steps <= nodes.Count; steps++, parent = nodes[idAt[parent]].Parent) + if (joints.Contains(idAt[parent])) return idAt[parent]; + return null; + } + + foreach (var joint in ship.Joints ?? new List()) + { + if (!nodes.ContainsKey(joint.Id)) + throw new InvalidOperationException($"{ship.Id}: model has no node with aetheria.id={joint.Id} for a joint."); + if (!string.Equals(JointAbove(joint.Id) ?? "", joint.Parent ?? "", StringComparison.Ordinal)) + throw new InvalidOperationException($"{ship.Id}: joint {joint.Id} must name the nearest joint above its model node as its Parent."); + } + foreach (var anchor in ship.Anchors.Where(anchor => anchor.Role == "weapon-mount" || anchor.Role == "thruster-emitter" || anchor.Role == "radiator-mesh")) + { + var above = JointAbove(anchor.ModelNodeId); + if (string.Equals(above ?? "", anchor.Joint ?? "", StringComparison.Ordinal)) continue; + throw new InvalidOperationException(anchor.Role == "weapon-mount" + ? $"{ship.Id}: weapon mount {anchor.Id} must name the nearest joint above its model node as its Joint." + : $"{ship.Id}: {anchor.Role} anchor {anchor.Id} sits under a joint in the model (follow-up gimballed-thrusters)."); + } + } + + // GLB is the xenos asset boundary. Only its node extras, whether each node names a mesh, and its nearest identified ancestor's node index + // (-1 for none) are read here; geometry belongs to the runtime importer. + public static Dictionary ReadNodeIds(string path) { using var stream = File.OpenRead(path); using var reader = new BinaryReader(stream); @@ -203,17 +238,29 @@ public static class ShipModCatalog if (reader.ReadUInt32() != 0x4E4F534A || chunkLength > stream.Length - stream.Position) throw new InvalidOperationException($"{path}: missing GLB JSON chunk."); var json = JObject.Parse(Encoding.UTF8.GetString(reader.ReadBytes((int)chunkLength))); - var ids = new Dictionary(StringComparer.Ordinal); - var nodes = json["nodes"]?.OfType() ?? Enumerable.Empty(); + var ids = new Dictionary(StringComparer.Ordinal); + var nodes = (json["nodes"]?.OfType() ?? Enumerable.Empty()).ToArray(); + var parents = Enumerable.Repeat(-1, nodes.Length).ToArray(); + for (var parent = 0; parent < nodes.Length; parent++) + foreach (var child in nodes[parent]["children"]?.Select(token => (int)token) ?? Enumerable.Empty()) + if (child >= 0 && child < nodes.Length) parents[child] = parent; uint index = 0; foreach (var node in nodes) { var id = (string)node["extras"]?["aetheria.id"]; if (string.IsNullOrEmpty(id)) { index++; continue; } - if (!ids.TryAdd(id, (index, node["mesh"] != null && node["mesh"].Type != JTokenType.Null))) + if (!ids.TryAdd(id, (index, node["mesh"] != null && node["mesh"].Type != JTokenType.Null, IdentifiedAncestor(parents, nodes, (int)index)))) throw new InvalidOperationException($"{path}: duplicate GLB node aetheria.id={id}."); index++; } return ids; } + + private static int IdentifiedAncestor(int[] parents, JObject[] nodes, int index) + { + var parent = parents[index]; + for (var steps = 0; parent >= 0 && steps <= nodes.Length; steps++, parent = parents[parent]) + if (!string.IsNullOrEmpty((string)nodes[parent]["extras"]?["aetheria.id"])) return parent; + return -1; + } } diff --git a/Assets/Scripts/ServerShared/ShipModPlan.cs b/Assets/Scripts/ServerShared/ShipModPlan.cs index bb80647a1..f242ab037 100644 --- a/Assets/Scripts/ServerShared/ShipModPlan.cs +++ b/Assets/Scripts/ServerShared/ShipModPlan.cs @@ -15,6 +15,10 @@ public sealed class ShipModPlan public string[] Radiators; // Each weapon mount (role weapon-mount) and its muzzle anchors, by Order then id. public (string Mount, string[] Muzzles)[] Weapons; + // One entry per driven joint (one a weapon mount names), by its first weapon in hull order: the joint, its chain + // root-first (RigChains), and the lead mount (the joint's first weapon in hull order) with that mount's first muzzle. + // Presentation only: the assembler rigs these and nothing here reaches the simulation. + public (string Joint, string[] Chain, string LeadMount, string LeadMuzzle)[] Rigs; // Maps a pair Validate accepts; every rule about which anchor may play which part is Validate's, so this refuses nothing. public static ShipModPlan Build(HullData hull, ShipAuthoring visual) @@ -26,6 +30,11 @@ public sealed class ShipModPlan var muzzles = visual.Anchors.Where(anchor => anchor.Role == "weapon-muzzle") .OrderBy(anchor => anchor.Order).ThenBy(anchor => anchor.Id, StringComparer.Ordinal).ToArray(); + var jointOf = visual.Anchors.Where(anchor => anchor.Role == "weapon-mount" && !string.IsNullOrEmpty(anchor.Joint)) + .ToDictionary(anchor => anchor.Id, anchor => anchor.Joint, StringComparer.Ordinal); + var leads = hardpoints.Where(hardpoint => jointOf.ContainsKey(hardpoint.Transform)).GroupBy(hardpoint => jointOf[hardpoint.Transform], StringComparer.Ordinal) + .Select(group => (Joint: group.Key, Lead: group.First().Transform)); + return new ShipModPlan { MapIcon = Only("map-icon"), @@ -36,7 +45,9 @@ public sealed class ShipModPlan Radiators = Mounts(HardpointType.Radiator), Weapons = hardpoints.Where(hardpoint => ShipAuthoringStore.IsWeapon(hardpoint.Type)).Select(hardpoint => ( hardpoint.Transform, - muzzles.Where(muzzle => muzzle.ParentId == hardpoint.Transform).Select(muzzle => muzzle.Id).ToArray())).ToArray() + muzzles.Where(muzzle => muzzle.ParentId == hardpoint.Transform).Select(muzzle => muzzle.Id).ToArray())).ToArray(), + Rigs = leads.Select(rig => (rig.Joint, RigChains.Chain(visual, rig.Joint), rig.Lead, + muzzles.First(muzzle => muzzle.ParentId == rig.Lead).Id)).ToArray() }; } } diff --git a/tests/Aetheria.Shared.Tests/ShipAuthoringTests.cs b/tests/Aetheria.Shared.Tests/ShipAuthoringTests.cs index 98eeaf5f7..0ae6b54ae 100644 --- a/tests/Aetheria.Shared.Tests/ShipAuthoringTests.cs +++ b/tests/Aetheria.Shared.Tests/ShipAuthoringTests.cs @@ -232,7 +232,7 @@ public sealed class ShipAuthoringTests private static readonly string[] AllRoles = { - "map-icon", "hull-collider", "shield", "tractor", "thruster-emitter", "weapon-mount", "weapon-muzzle", "radiator-mesh", "articulation" + "map-icon", "hull-collider", "shield", "tractor", "thruster-emitter", "weapon-mount", "weapon-muzzle", "radiator-mesh" }; // The fixture with its thruster swapped for one hardpoint of the given type at mount id "mount", and no anchor for it. diff --git a/tests/Aetheria.Shared.Tests/ShipModCatalogTests.cs b/tests/Aetheria.Shared.Tests/ShipModCatalogTests.cs index a2426906b..d23243c6f 100644 --- a/tests/Aetheria.Shared.Tests/ShipModCatalogTests.cs +++ b/tests/Aetheria.Shared.Tests/ShipModCatalogTests.cs @@ -434,7 +434,7 @@ public sealed class ShipModCatalogTests : IDisposable { var path = Write("nodes.glb", ShipFixture.Glb(@"{""asset"":{""version"":""2.0""},""nodes"":[ {""name"":""plain""},{""extras"":{""aetheria.id"":""a""}},{""extras"":{}},{""extras"":{""aetheria.id"":""""}},{""mesh"":0,""extras"":{""aetheria.id"":""b""}}]}")); - Assert.Equal(new Dictionary { ["a"] = (1, false), ["b"] = (4, true) }, ShipModCatalog.ReadNodeIds(path)); + Assert.Equal(new Dictionary { ["a"] = (1, false, -1), ["b"] = (4, true, -1) }, ShipModCatalog.ReadNodeIds(path)); } [Fact] @@ -598,7 +598,7 @@ public sealed class ShipModCatalogTests : IDisposable private void WritePackage(string id, string hullName = "Skiff", string[] nodes = null, string modelAsset = "skiff.glb", Action tweak = null, string[] meshNodes = null) => ShipFixture.WritePackage(Mods, id, hullName, nodes, modelAsset, tweak, meshNodes); - private static Dictionary Indices(Dictionary nodes) => + private static Dictionary Indices(Dictionary nodes) => nodes.ToDictionary(node => node.Key, node => node.Value.Index); private static int Occurrences(byte[] haystack, byte[] needle) diff --git a/tests/Aetheria.Shared.Tests/ShipRigTests.cs b/tests/Aetheria.Shared.Tests/ShipRigTests.cs new file mode 100644 index 000000000..a8219fbb2 --- /dev/null +++ b/tests/Aetheria.Shared.Tests/ShipRigTests.cs @@ -0,0 +1,321 @@ +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Text; +using CultMath; +using Xunit; + +// The rig in the visual record: what the judge (Validate) refuses about joints and the guns that ride them, what Bind +// refuses when the GLB disagrees with the record, and what ShipModPlan.Rigs hands the assembler. The rig is +// presentation (ruling rig-is-presentation): arc stays the hardpoint's and traverse the weapon's, so the judge only +// asks that the chain could sweep the arc the hardpoint states. +public sealed class ShipRigTests : IDisposable +{ + private readonly TempDirectory _directory = new TempDirectory(); + public void Dispose() => _directory.Dispose(); + + private static readonly float[] Up = { 0f, 1f, 0f }; + private static readonly float[] Right = { 1f, 0f, 0f }; + + private static ShipJoint Joint(string id, string parent, params (float[] Axis, float Min, float Max)[] dofs) => new ShipJoint + { + Id = id, Parent = parent, + Axes = dofs.SelectMany(dof => dof.Axis).ToArray(), Min = dofs.Select(dof => dof.Min).ToArray(), Max = dofs.Select(dof => dof.Max).ToArray() + }; + + private static float[] Tilted(float degrees) => new[] { MathF.Sin(degrees * MathF.PI / 180f), MathF.Cos(degrees * MathF.PI / 180f), 0f }; + + // The fixture's skiff with energy guns "g0".."gN" side by side (one cell each) and the thruster after them. Each gun + // is a weapon mount (node "gN") with one muzzle ("gN.muzzle", node "gN-muzzle"), fires 180 degrees, and rides the joint + // its tuple names (null is a fixed mount). + private static ShipParts Armed(params string[] jointOfGun) + { + var ship = ShipAuthoringTests.Fixture(); + var shape = new Shape(jointOfGun.Length + 1, 1); + for (var x = 0; x <= jointOfGun.Length; x++) shape.Cells[x, 0] = true; + ship.Hull.Shape = shape; + ship.Hull.Hardpoints[0].Position = new int2(jointOfGun.Length, 0); + for (var gun = 0; gun < jointOfGun.Length; gun++) + { + ship.Hull.Hardpoints.Add(new HardpointData + { Type = HardpointType.Energy, Position = new int2(gun, 0), Shape = new Shape(), Transform = $"g{gun}", FiringArc = 180 }); + ship.Visual.Anchors.Add(new ShipAnchor { Id = $"g{gun}", Role = "weapon-mount", ModelNodeId = $"g{gun}", Joint = jointOfGun[gun] }); + ship.Visual.Anchors.Add(new ShipAnchor { Id = $"g{gun}.muzzle", Role = "weapon-muzzle", ModelNodeId = $"g{gun}-muzzle", ParentId = $"g{gun}" }); + } + return ship; + } + + private static string Refusal(ShipParts ship) => Assert.Throws(ship.Validate).Message; + + // One gun, on joint "j" with the given degrees of freedom, firing the given arc. + private static ShipParts OneGun(float arc, params (float[] Axis, float Min, float Max)[] dofs) + { + var ship = Armed("j"); + ship.Visual.Joints.Add(Joint("j", null, dofs)); + ship.Hull.Hardpoints.Single(hardpoint => hardpoint.Transform == "g0").FiringArc = arc; + return ship; + } + + [Fact] + public void AnArmedShipWithAJointIsValid() => OneGun(90, (Up, -45f, 45f)).Validate(); + + [Fact] + public void ReachIsTheYawRangeOfTheChainAgainstTheArcTheHardpointStates() + { + OneGun(90, (Up, -45f, 45f)).Validate(); + var short1 = Refusal(OneGun(100, (Up, -45f, 45f))); + Assert.Contains("joint j chain reaches 90 degrees of yaw", short1); + Assert.Contains("100 degree firing arc", short1); + + // Serial degrees of freedom add, whether they share a joint or sit on two. + OneGun(120, (Up, -30f, 30f), (Up, -30f, 30f)).Validate(); + Assert.Contains("reaches 120", Refusal(OneGun(121, (Up, -30f, 30f), (Up, -30f, 30f)))); + var serial = Armed("child"); + serial.Visual.Joints.Add(Joint("base", null, (Up, -30f, 30f))); + serial.Visual.Joints.Add(Joint("child", "base", (Up, -30f, 30f))); + serial.Hull.Hardpoints.Single(hardpoint => hardpoint.Transform == "g0").FiringArc = 120; + serial.Validate(); + serial.Hull.Hardpoints.Single(hardpoint => hardpoint.Transform == "g0").FiringArc = 121; + Assert.Contains("reaches 120", Refusal(serial)); + + // A degree of freedom about +X is pitch: it adds nothing, however wide. + Assert.Contains("reaches 0 degrees", Refusal(OneGun(10, (Right, -180f, 180f)))); + Assert.Contains("reaches 90", Refusal(OneGun(91, (Up, -45f, 45f), (Right, -180f, 180f)))); + + // A full turn covers every arc up to 360, and no reach is reported above it. + OneGun(360, (Up, -180f, 180f)).Validate(); + Assert.Contains("reaches 360 degrees", Refusal(OneGun(400, (Up, -180f, 180f), (Up, -180f, 180f)))); + } + + [Fact] + public void AnAxisWithinFiveDegreesOfUpIsYawAndOneBeyondItIsNot() + { + OneGun(90, (Tilted(4f), -45f, 45f)).Validate(); + Assert.Contains("reaches 0 degrees", Refusal(OneGun(90, (Tilted(6f), -45f, 45f)))); + // An axis pointing down is as much yaw as one pointing up. + OneGun(90, (new[] { 0f, -1f, 0f }, -45f, 45f)).Validate(); + } + + [Fact] + public void AChainStopsAtADrivenAncestorSoItsYawDoesNotCountForTheChild() + { + var ship = Armed("outer", "inner"); + ship.Visual.Joints.Add(Joint("outer", null, (Up, -180f, 180f))); + ship.Visual.Joints.Add(Joint("inner", "outer", (Up, -10f, 10f))); + ship.Hull.Hardpoints.Single(hardpoint => hardpoint.Transform == "g1").FiringArc = 20; + ship.Validate(); + ship.Hull.Hardpoints.Single(hardpoint => hardpoint.Transform == "g1").FiringArc = 100; + Assert.Contains("joint inner chain reaches 20 degrees", Refusal(ship)); + + // With nothing riding the outer joint it is only a link in the inner chain, and counts. + ship.Visual.Anchors.Single(anchor => anchor.Id == "g0").Joint = null; + ship.Validate(); + } + + [Fact] + public void AGunOnAJointStatesItsArc() + { + var ship = OneGun(0, (Up, -180f, 180f)); + Assert.Contains("must state its firing arc above 0", Refusal(ship)); + + // The same hardpoint on no joint is a fixed mount, and a fixed mount at the default arc is fine. + ship.Visual.Anchors.Single(anchor => anchor.Id == "g0").Joint = null; + ship.Validate(); + } + + [Fact] + public void MountsOnOneJointShareTheirArcAndRotation() + { + var ship = Armed("j", "j"); + ship.Visual.Joints.Add(Joint("j", null, (Up, -180f, 180f))); + ship.Validate(); + + ship.Hull.Hardpoints.Single(hardpoint => hardpoint.Transform == "g1").FiringArc = 90; + Assert.Contains("must share Rotation and FiringArc", Refusal(ship)); + ship.Hull.Hardpoints.Single(hardpoint => hardpoint.Transform == "g1").FiringArc = 180; + ship.Hull.Hardpoints.Single(hardpoint => hardpoint.Transform == "g1").Rotation = ItemRotation.Reversed; + Assert.Contains("must share Rotation and FiringArc", Refusal(ship)); + + // Guns on different joints, or one on none, keep their own. + ship.Visual.Joints.Add(Joint("k", null, (Up, -180f, 180f))); + ship.Visual.Anchors.Single(anchor => anchor.Id == "g1").Joint = "k"; + ship.Validate(); + } + + [Fact] + public void AJointRidesOnlyAWeaponMountThatNamesARealJoint() + { + var ship = Armed("ghost"); + Assert.Contains("names an unknown joint", Refusal(ship)); + + ship = Armed("j"); + ship.Visual.Joints.Add(Joint("j", null, (Up, -180f, 180f))); + ship.Visual.Anchors.Single(anchor => anchor.Id == "g0.muzzle").Joint = "j"; + Assert.Contains("only a weapon mount rides one", Refusal(ship)); + } + + [Fact] + public void JointShapeAcceptsItsBoundariesAndTheUnitTolerance() + { + OneGun(1, (Up, -180f, 180f)).Validate(); + OneGun(1, (Up, 180f, 180f)).Validate(); + OneGun(1, (new[] { 0f, 1.0009f, 0f }, 0f, 5f)).Validate(); + OneGun(1, (new[] { 0f, .9991f, 0f }, 0f, 5f)).Validate(); + Assert.Contains("must be a unit vector", Refusal(OneGun(1, (new[] { 0f, 1.0015f, 0f }, 0f, 5f)))); + Assert.Contains("must be a unit vector", Refusal(OneGun(1, (new[] { 0f, .9985f, 0f }, 0f, 5f)))); + } + + // ---- Bind: the GLB must have the rig the record states ---- + + // A model node: its glTF name (unique, what Parent names), its aetheria.id (null for a node the exporter left untagged), + // its parent's name, and whether it carries a mesh. + private record Node(string Name, string Id, string Parent, bool Mesh = false); + + // arm > elbow > wrist > (an untagged bracket) > gun > gun-muzzle, with the fixture's other nodes at the root. + private static readonly Node[] RigNodes = + { + new Node("map", "map", null), new Node("collider", "collider", null), new Node("shield", "shield", null), + new Node("tractor", "tractor", null), new Node("thruster-port", "thruster-port", null, true), + new Node("arm", "arm", null), new Node("elbow", "elbow", "arm"), new Node("wrist", "wrist", "elbow"), + new Node("bracket", null, "wrist"), new Node("gun", "gun", "bracket"), new Node("gun-muzzle", "gun-muzzle", "gun") + }; + + private static string GlbJson(Node[] nodes) + { + var text = new StringBuilder(@"{""asset"":{""version"":""2.0""},""meshes"":[{""primitives"":[]}],""nodes"":["); + for (var index = 0; index < nodes.Length; index++) + { + var node = nodes[index]; + var kids = Enumerable.Range(0, nodes.Length).Where(child => nodes[child].Parent == node.Name).ToArray(); + text.Append(index > 0 ? "," : "").Append($@"{{""name"":""{node.Name}"""); + if (node.Mesh) text.Append(@",""mesh"":0"); + if (node.Id != null) text.Append($@",""extras"":{{""aetheria.id"":""{node.Id}""}}"); + if (kids.Length > 0) text.Append(@",""children"":[" + string.Join(",", kids) + "]"); + text.Append('}'); + } + return text.Append("]}").ToString(); + } + + // The fixture's package with the arm rig (arm, elbow, wrist; the gun on the wrist), then the tweak, written beside a + // GLB of the given nodes. + private string Package(Action tweak, Node[] nodes = null) + { + var mods = Path.Combine(_directory.Path, "Mods"); + Directory.CreateDirectory(mods); + var directory = ShipFixture.WritePackage(mods, "mod.skiff", tweak: ship => + { + ship.Hull.Hardpoints.Single(hardpoint => hardpoint.Transform == "gun").FiringArc = 90; + ship.Visual.Joints.Add(Joint("arm", null, (Up, -45f, 45f))); + ship.Visual.Joints.Add(Joint("elbow", "arm", (Right, -45f, 45f))); + ship.Visual.Joints.Add(Joint("wrist", "elbow", (Up, -45f, 45f))); + ship.Visual.Anchors.Single(anchor => anchor.Id == "gun").Joint = "wrist"; + tweak?.Invoke(ship); + }); + File.WriteAllBytes(Path.Combine(directory, "skiff.glb"), ShipFixture.Glb(GlbJson(nodes ?? RigNodes))); + return Path.Combine(directory, "ship.cc"); + } + + private static string BindRefusal(string path) => Assert.Throws(() => ShipModCatalog.ReadPackage(path)).Message; + + private static Node[] Reparent(string name, string parent) => + RigNodes.Select(node => node.Name == name ? node with { Parent = parent } : node).ToArray(); + + [Fact] + public void BindAcceptsARigTheModelHasEvenWithAnUntaggedNodeBetween() + { + var package = ShipModCatalog.ReadPackage(Package(null)); + Assert.Equal(new[] { "arm", "elbow", "wrist" }, package.Visual.Joints.Select(joint => joint.Id)); + } + + [Fact] + public void BindRefusesAMountWhoseJointIsNotTheNearestOneAboveItsNode() + { + Assert.Contains("weapon mount gun must name the nearest joint above its model node", + BindRefusal(Package(ship => ship.Visual.Anchors.Single(anchor => anchor.Id == "gun").Joint = "elbow"))); + } + + [Fact] + public void BindRefusesAMountThatTheRecordAndTheModelPlaceDifferently() + { + // The record says the gun is fixed; the model hangs it under the wrist. + Assert.Contains("weapon mount gun must name the nearest joint above its model node", + BindRefusal(Package(ship => ship.Visual.Anchors.Single(anchor => anchor.Id == "gun").Joint = null))); + // The record rides the wrist; the model hangs the gun at the root. + Assert.Contains("weapon mount gun must name the nearest joint above its model node", BindRefusal(Package(null, Reparent("gun", null)))); + } + + [Fact] + public void BindRefusesAJointThatIsNoModelNode() + { + var path = Package(null, RigNodes.Where(node => node.Name != "elbow").Select(node => node.Name == "wrist" ? node with { Parent = null } : node).ToArray()); + Assert.Contains("model has no node with aetheria.id=elbow for a joint", BindRefusal(path)); + } + + [Fact] + public void BindRefusesAJointWhoseParentSkipsAJointNode() + { + Assert.Contains("joint wrist must name the nearest joint above its model node as its Parent", + BindRefusal(Package(ship => ship.Visual.Joints.Single(joint => joint.Id == "wrist").Parent = "arm"))); + Assert.Contains("joint elbow must name the nearest joint above its model node as its Parent", + BindRefusal(Package(ship => ship.Visual.Joints.Single(joint => joint.Id == "elbow").Parent = null))); + } + + [Fact] + public void BindRefusesAThrusterMeshUnderAJointNamingTheFollowUp() => + Assert.Contains("gimballed-thrusters", BindRefusal(Package(null, Reparent("thruster-port", "wrist")))); + + [Fact] + public void NodeParentsAreTheNearestTaggedAncestorAndRootsHaveNone() + { + var path = Path.Combine(_directory.Path, "rig.glb"); + File.WriteAllBytes(path, ShipFixture.Glb(GlbJson(RigNodes))); + var nodes = ShipModCatalog.ReadNodeIds(path); + Assert.Equal(-1, nodes["arm"].Parent); + Assert.Equal((int)nodes["arm"].Index, nodes["elbow"].Parent); + Assert.Equal((int)nodes["wrist"].Index, nodes["gun"].Parent); + Assert.Equal((int)nodes["gun"].Index, nodes["gun-muzzle"].Parent); + } + + // ---- ShipModPlan.Rigs ---- + + [Fact] + public void RigsAreOnePerDrivenJointInHullOrderOfTheirFirstWeaponWithChainsThatStopAtDrivenAncestors() + { + // g0 on the inner joint, g1 and g2 on the outer one (g2 authored first among the anchors). + var ship = Armed("barrel", "turret", "turret"); + ship.Visual.Joints.Add(Joint("turret", null, (Up, -180f, 180f))); + ship.Visual.Joints.Add(Joint("barrel", "turret", (Up, -180f, 180f))); + ship.Visual.Anchors.RemoveAll(anchor => anchor.Id == "g1.muzzle"); + ship.Visual.Anchors.Add(new ShipAnchor { Id = "g1.b", Role = "weapon-muzzle", ModelNodeId = "g1-b", ParentId = "g1", Order = 1 }); + ship.Visual.Anchors.Add(new ShipAnchor { Id = "g1.z", Role = "weapon-muzzle", ModelNodeId = "g1-z", ParentId = "g1", Order = 0 }); + ship.Visual.Anchors.Reverse(); + + var rigs = ShipModPlan.Build(ship.Hull, ship.Visual).Rigs; + + Assert.Equal(2, rigs.Length); + Assert.Equal("barrel", rigs[0].Joint); + Assert.Equal(new[] { "barrel" }, rigs[0].Chain); + Assert.Equal(("g0", "g0.muzzle"), (rigs[0].LeadMount, rigs[0].LeadMuzzle)); + Assert.Equal("turret", rigs[1].Joint); + Assert.Equal(new[] { "turret" }, rigs[1].Chain); + Assert.Equal(("g1", "g1.z"), (rigs[1].LeadMount, rigs[1].LeadMuzzle)); + } + + [Fact] + public void AnUndrivenParentJointIsPartOfTheChainRootFirst() + { + var ship = Armed("wrist"); + ship.Visual.Joints.Add(Joint("arm", null, (Up, -90f, 90f))); + ship.Visual.Joints.Add(Joint("elbow", "arm", (Right, -45f, 45f))); + ship.Visual.Joints.Add(Joint("wrist", "elbow", (Up, -90f, 90f))); + + var rig = Assert.Single(ShipModPlan.Build(ship.Hull, ship.Visual).Rigs); + + Assert.Equal(new[] { "arm", "elbow", "wrist" }, rig.Chain); + } + + [Fact] + public void AShipWithNoGunOnAJointHasNoRigs() => + Assert.Empty(ShipModPlan.Build(Armed((string)null).Hull, Armed((string)null).Visual).Rigs); +} diff --git a/tests/Aetheria.Shared.Tests/ShipValidationTests.cs b/tests/Aetheria.Shared.Tests/ShipValidationTests.cs index 804ff723f..c2d177f21 100644 --- a/tests/Aetheria.Shared.Tests/ShipValidationTests.cs +++ b/tests/Aetheria.Shared.Tests/ShipValidationTests.cs @@ -172,17 +172,39 @@ public sealed class ShipValidationTests Add("anchors-null", s => s.Visual.Anchors = null, "anchors are required"); Add("anchor-null", s => s.Visual.Anchors.Add(null), "anchor IDs must be present and unique"); Add("anchor-id-null", s => s.Visual.Anchors[4].Id = null, "anchor IDs must be present and unique"); - Add("anchor-id-blank", s => s.Visual.Anchors.Add(new ShipAnchor { Id = " ", Role = "articulation", ModelNodeId = "x" }), "anchor IDs must be present and unique"); - Add("anchor-id-duplicate", s => s.Visual.Anchors.Add(new ShipAnchor { Id = "map", Role = "articulation", ModelNodeId = "x" }), "anchor IDs must be present and unique"); + Add("anchor-id-blank", s => s.Visual.Anchors.Add(new ShipAnchor { Id = " ", Role = "weapon-muzzle", ModelNodeId = "x" }), "anchor IDs must be present and unique"); + Add("anchor-id-duplicate", s => s.Visual.Anchors.Add(new ShipAnchor { Id = "map", Role = "weapon-muzzle", ModelNodeId = "x" }), "anchor IDs must be present and unique"); Add("anchor-node-null", s => s.Visual.Anchors[4].ModelNodeId = null, "needs a model node ID"); Add("anchor-node-blank", s => s.Visual.Anchors[4].ModelNodeId = " ", "needs a model node ID"); - Add("anchor-node-shared", s => s.Visual.Anchors.Add(new ShipAnchor { Id = "other", Role = "articulation", ModelNodeId = "map" }), "claimed by more than one anchor"); + Add("anchor-node-shared", s => s.Visual.Anchors.Add(new ShipAnchor { Id = "other", Role = "weapon-muzzle", ModelNodeId = "map" }), "claimed by more than one anchor"); foreach (var role in new[] { "map-icon", "hull-collider", "shield", "tractor" }) { Add("role-missing-" + role, s => s.Visual.Anchors.RemoveAll(a => a.Role == role), $"exactly one {role} anchor is required"); Add("role-doubled-" + role, s => s.Visual.Anchors.Add(new ShipAnchor { Id = "extra", Role = role, ModelNodeId = "extra" }), $"exactly one {role} anchor is required"); } + void Joint(ShipParts s, string id, string parent, float[] axes, float[] min, float[] max) => + s.Visual.Joints.Add(new ShipJoint { Id = id, Parent = parent, Axes = axes, Min = min, Max = max }); + var yaw = new[] { 0f, 1f, 0f }; + Add("joint-id-blank", s => Joint(s, " ", null, yaw, new[] { -1f }, new[] { 1f }), "joint IDs must be present and unique"); + Add("joint-null", s => s.Visual.Joints.Add(null), "joint IDs must be present and unique"); + Add("joint-id-duplicate", s => { Joint(s, "j", null, yaw, new[] { -1f }, new[] { 1f }); Joint(s, "j", null, yaw, new[] { -1f }, new[] { 1f }); }, "joint IDs must be present and unique"); + Add("joint-id-is-an-anchor-node", s => Joint(s, "map", null, yaw, new[] { -1f }, new[] { 1f }), "is also an anchor's model node"); + Add("joint-axes-length-four", s => Joint(s, "j", null, new[] { 0f, 1f, 0f, 0f }, new[] { -1f }, new[] { 1f }), "needs one or more degrees of freedom"); + Add("joint-no-degrees-of-freedom", s => Joint(s, "j", null, new float[0], new float[0], new float[0]), "needs one or more degrees of freedom"); + Add("joint-null-limits", s => Joint(s, "j", null, yaw, null, null), "needs one or more degrees of freedom"); + Add("joint-max-count-differs", s => Joint(s, "j", null, yaw, new[] { -1f }, new[] { 1f, 2f }), "needs one or more degrees of freedom"); + Add("joint-axis-not-unit", s => Joint(s, "j", null, new[] { 0f, 2f, 0f }, new[] { -1f }, new[] { 1f }), "must be a unit vector"); + Add("joint-axis-not-finite", s => Joint(s, "j", null, new[] { 0f, float.NaN, 0f }, new[] { -1f }, new[] { 1f }), "axes and limits must be finite"); + Add("joint-limit-not-finite", s => Joint(s, "j", null, yaw, new[] { -1f }, new[] { float.PositiveInfinity }), "axes and limits must be finite"); + Add("joint-min-above-max", s => Joint(s, "j", null, yaw, new[] { 10f }, new[] { 5f }), "must satisfy -180 <= Min <= Max <= 180"); + Add("joint-max-181", s => Joint(s, "j", null, yaw, new[] { 0f }, new[] { 181f }), "must satisfy -180 <= Min <= Max <= 180"); + Add("joint-min-minus-181", s => Joint(s, "j", null, yaw, new[] { -181f }, new[] { 0f }), "must satisfy -180 <= Min <= Max <= 180"); + Add("joint-parent-dangling", s => Joint(s, "j", "ghost", yaw, new[] { -1f }, new[] { 1f }), "has an unknown parent joint"); + Add("joint-cycle", s => { Joint(s, "a", "b", yaw, new[] { -1f }, new[] { 1f }); Joint(s, "b", "a", yaw, new[] { -1f }, new[] { 1f }); }, "is on a parent cycle"); + Add("joint-on-a-thruster-mount", s => { Joint(s, "j", null, yaw, new[] { -1f }, new[] { 1f }); s.Visual.Anchors[4].Joint = "j"; }, "gimballed-thrusters"); + Add("joint-on-a-radiator-mount", s => { Joint(s, "j", null, yaw, new[] { -1f }, new[] { 1f }); s.Visual.Anchors[4].Role = "radiator-mesh"; s.Visual.Anchors[4].Joint = "j"; s.Hull.Hardpoints[0].Type = HardpointType.Radiator; }, "gimballed-thrusters"); + Add("joint-on-a-map-icon", s => { Joint(s, "j", null, yaw, new[] { -1f }, new[] { 1f }); s.Visual.Anchors[0].Joint = "j"; }, "may not name a joint"); Add("anchor-role-unknown", s => s.Visual.Anchors.Add(new ShipAnchor { Id = "x", Role = "engine", ModelNodeId = "x" }), "has unknown role 'engine'"); Add("anchor-role-null", s => s.Visual.Anchors.Add(new ShipAnchor { Id = "x", Role = null, ModelNodeId = "x" }), "has unknown role ''"); Add("anchor-role-cased", s => s.Visual.Anchors[0].Role = "Map-Icon", "has unknown role 'Map-Icon'"); From 562de34c4eb0544219d3ce5a68b6875a02ad9b4b Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 05:36:32 +0200 Subject: [PATCH 09/26] ShipRigTests: the Max-180 boundary joint needs one degree of reach for its 1 degree arc Co-Authored-By: Claude Opus 5.5 --- tests/Aetheria.Shared.Tests/ShipRigTests.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/Aetheria.Shared.Tests/ShipRigTests.cs b/tests/Aetheria.Shared.Tests/ShipRigTests.cs index a8219fbb2..2ab838b2c 100644 --- a/tests/Aetheria.Shared.Tests/ShipRigTests.cs +++ b/tests/Aetheria.Shared.Tests/ShipRigTests.cs @@ -159,7 +159,7 @@ public sealed class ShipRigTests : IDisposable public void JointShapeAcceptsItsBoundariesAndTheUnitTolerance() { OneGun(1, (Up, -180f, 180f)).Validate(); - OneGun(1, (Up, 180f, 180f)).Validate(); + OneGun(1, (Up, 179f, 180f)).Validate(); OneGun(1, (new[] { 0f, 1.0009f, 0f }, 0f, 5f)).Validate(); OneGun(1, (new[] { 0f, .9991f, 0f }, 0f, 5f)).Validate(); Assert.Contains("must be a unit vector", Refusal(OneGun(1, (new[] { 0f, 1.0015f, 0f }, 0f, 5f)))); From 30d027195b345cd36068d90868531a30c804442b Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 06:50:05 +0200 Subject: [PATCH 10/26] Research: prior art on thrust allocation with vectored thrusters Serves follow-ups vectored-thruster-rows and gimballed-thrusters: virtual actuators, nonlinear and cascaded allocation, rate and gimbal limits as per-tick bounds, the zero-thrust singularity, games, shared-angle rows. Co-Authored-By: Claude Opus 5.5 --- docs/research/thrust-vectoring-prior-art.md | 131 ++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 docs/research/thrust-vectoring-prior-art.md diff --git a/docs/research/thrust-vectoring-prior-art.md b/docs/research/thrust-vectoring-prior-art.md new file mode 100644 index 000000000..f2df686a4 --- /dev/null +++ b/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 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 From fe9da2e0af3d447a4efa1e3d81d4b1e61ad56000 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 06:52:06 +0200 Subject: [PATCH 11/26] Test AStoreRefusesAMissingCatalog (red: AetheriaStores.Open does not yet refuse) Builds; the new test fails against the current Open. Co-Authored-By: Claude Opus 5.5 --- .../Aetheria.Shared.Tests/AetheriaStoresTests.cs | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs b/tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs index e0fec193d..5b9cdacf2 100644 --- a/tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs +++ b/tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs @@ -200,6 +200,22 @@ 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"); + + var error = Assert.Throws(() => 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()); + } + private static string Hash(string path) => Convert.ToHexString(SHA256.HashData(File.ReadAllBytes(path))); private static string[] SchemaNames(string path) From b997b80f81de7a4399d4b14a004ab37aac9b1db7 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 06:55:32 +0200 Subject: [PATCH 12/26] AetheriaBuild.Build: one player entry point; AetheriaStores.Open refuses a missing catalog AetheriaBuild (Assets/Editor) sets the version, builds Addressables, builds the Win64 player, stages GameData through PlayerStaging, publishes AetherDb to ModTools and removes the Burst debug folder; any failure exits 1 naming the step. PlayerStaging is Unity-free and linked into Aetheria.Shared.Tests. A read-only AetheriaStores.Open of a nonexistent catalog throws. Builds on the headless side; the Unity .meta files and the batchmode run follow. Co-Authored-By: Claude Opus 5.5 --- Assets/Editor/AetheriaBuild.cs | 106 ++++++++++++++++++ Assets/Editor/PlayerStaging.cs | 42 +++++++ Assets/Scripts/ServerShared/AetheriaStores.cs | 4 + .../Aetheria.Shared.Tests.csproj | 2 + .../PlayerStagingTests.cs | 101 +++++++++++++++++ 5 files changed, 255 insertions(+) create mode 100644 Assets/Editor/AetheriaBuild.cs create mode 100644 Assets/Editor/PlayerStaging.cs create mode 100644 tests/Aetheria.Shared.Tests/PlayerStagingTests.cs diff --git a/Assets/Editor/AetheriaBuild.cs b/Assets/Editor/AetheriaBuild.cs new file mode 100644 index 000000000..26e56813e --- /dev/null +++ b/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 -executeMethod AetheriaBuild.Build +// -aetheriaVersion -aetheriaOut -logFile +// +// 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 " 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"; + PlayerSettings.bundleVersion = version; + + 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]; + } +} diff --git a/Assets/Editor/PlayerStaging.cs b/Assets/Editor/PlayerStaging.cs new file mode 100644 index 000000000..4698130f6 --- /dev/null +++ b/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 /GameData with a copy of the three shipped entries of /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))); + } +} diff --git a/Assets/Scripts/ServerShared/AetheriaStores.cs b/Assets/Scripts/ServerShared/AetheriaStores.cs index f265151c9..e2cdcd631 100644 --- a/Assets/Scripts/ServerShared/AetheriaStores.cs +++ b/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 InvalidOperationException($"Catalog {catalogPath} does not exist; a read-only open never invents one."); var cache = new CultCache(); try { diff --git a/tests/Aetheria.Shared.Tests/Aetheria.Shared.Tests.csproj b/tests/Aetheria.Shared.Tests/Aetheria.Shared.Tests.csproj index 8e36142f1..bad1c9b86 100644 --- a/tests/Aetheria.Shared.Tests/Aetheria.Shared.Tests.csproj +++ b/tests/Aetheria.Shared.Tests/Aetheria.Shared.Tests.csproj @@ -11,6 +11,8 @@ + + diff --git a/tests/Aetheria.Shared.Tests/PlayerStagingTests.cs b/tests/Aetheria.Shared.Tests/PlayerStagingTests.cs new file mode 100644 index 000000000..06af8406f --- /dev/null +++ b/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(() => 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(() => 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); + } +} From e5a57dab9fe5aa65253ae08cdbf68d12893e5bed Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 07:17:13 +0200 Subject: [PATCH 13/26] AetheriaBuild: qualify UnityEditor.PlayerSettings (the game has a global PlayerSettings); Unity .meta files The previous commit did not compile in Unity (CS0117 on PlayerSettings.bundleVersion); this one does, and a batchmode run of AetheriaBuild.Build succeeded. Co-Authored-By: Claude Opus 5.5 --- Assets/Editor/AetheriaBuild.cs | 2 +- Assets/Editor/AetheriaBuild.cs.meta | 2 ++ Assets/Editor/PlayerStaging.cs.meta | 2 ++ 3 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 Assets/Editor/AetheriaBuild.cs.meta create mode 100644 Assets/Editor/PlayerStaging.cs.meta diff --git a/Assets/Editor/AetheriaBuild.cs b/Assets/Editor/AetheriaBuild.cs index 26e56813e..7d3c891d2 100644 --- a/Assets/Editor/AetheriaBuild.cs +++ b/Assets/Editor/AetheriaBuild.cs @@ -33,7 +33,7 @@ public static class AetheriaBuild var repoRoot = Directory.GetParent(UnityEngine.Application.dataPath).FullName; step = "version"; - PlayerSettings.bundleVersion = version; + UnityEditor.PlayerSettings.bundleVersion = version; // the game has its own global PlayerSettings step = "addressables"; AddressableAssetSettings.BuildPlayerContent(out var content); diff --git a/Assets/Editor/AetheriaBuild.cs.meta b/Assets/Editor/AetheriaBuild.cs.meta new file mode 100644 index 000000000..833ad46ac --- /dev/null +++ b/Assets/Editor/AetheriaBuild.cs.meta @@ -0,0 +1,2 @@ +fileFormatVersion: 2 +guid: d38caad223051494ba36c734ce79950d \ No newline at end of file diff --git a/Assets/Editor/PlayerStaging.cs.meta b/Assets/Editor/PlayerStaging.cs.meta new file mode 100644 index 000000000..71743d471 --- /dev/null +++ b/Assets/Editor/PlayerStaging.cs.meta @@ -0,0 +1,2 @@ +fileFormatVersion: 2 +guid: 16dce8087f9149b44b6e294cb0851dd8 \ No newline at end of file From 387404c6eac996d612647f4d4ddf959088e1defc Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 07:27:31 +0200 Subject: [PATCH 14/26] AetheriaStoresTests: MissingCatalogGlobalIsLoud opens an existing empty catalog The test relied on a read-only open of a nonexistent file yielding an empty catalog, which AetheriaStores.Open now refuses; the fixture writes the empty catalog first. Builds; the suite is green with it. Co-Authored-By: Claude Opus 5.5 --- tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs b/tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs index 5b9cdacf2..099c3a259 100644 --- a/tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs +++ b/tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs @@ -116,7 +116,9 @@ public sealed class AetheriaStoresTests : IDisposable public void MissingCatalogGlobalIsLoud() { var empty = Path.Combine(_root, "empty.cc"); - using (AetheriaStores.Open(empty, catalogWritable: true)) { } + // An existing catalog with no records: a read-only open refuses a missing file before it checks globals. + using (var seed = AetheriaStores.Open(empty, catalogWritable: true)) seed.FlushAsync().Wait(); + Assert.True(File.Exists(empty)); var error = Assert.Throws(() => AetheriaStores.Open(empty)); Assert.Contains("aetheria.tests.catalogglobal", error.Message); using (AetheriaStores.Open(Catalog)) { } From 1521c68a7922dfbc7def251a741c51edb6dbdd67 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 07:28:04 +0200 Subject: [PATCH 15/26] AetheriaStores.Open: a missing catalog throws FileNotFoundException The test assembly registers a catalog [CultGlobal], so the global check already threw on a missing file there and AStoreRefusesAMissingCatalog passed against the old Open (run at fe9da2e: 12 passed). The refusal is now a FileNotFoundException naming the path, and the test pins that type, which the global check never throws. Builds. Co-Authored-By: Claude Opus 5.5 --- Assets/Scripts/ServerShared/AetheriaStores.cs | 2 +- tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/Assets/Scripts/ServerShared/AetheriaStores.cs b/Assets/Scripts/ServerShared/AetheriaStores.cs index e2cdcd631..92f8e3f90 100644 --- a/Assets/Scripts/ServerShared/AetheriaStores.cs +++ b/Assets/Scripts/ServerShared/AetheriaStores.cs @@ -18,7 +18,7 @@ public static class AetheriaStores { // 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 InvalidOperationException($"Catalog {catalogPath} does not exist; a read-only open never invents one."); + throw new FileNotFoundException($"Catalog {catalogPath} does not exist; a read-only open never invents one.", catalogPath); var cache = new CultCache(); try { diff --git a/tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs b/tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs index 099c3a259..4d7611b9a 100644 --- a/tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs +++ b/tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs @@ -209,7 +209,8 @@ public sealed class AetheriaStoresTests : IDisposable { var missing = Path.Combine(_root, "absent", "Aetheria.cc"); - var error = Assert.Throws(() => AetheriaStores.Open(missing)); + // FileNotFoundException, not the catalog-global check: that one also throws on a missing file whenever a global is registered. + var error = Assert.Throws(() => AetheriaStores.Open(missing)); Assert.Contains(missing, error.Message); Assert.False(File.Exists(missing)); Assert.False(Directory.Exists(Path.GetDirectoryName(missing))); From 86fb594031a6e9168367ae3e585994e148d309ec Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 07:37:49 +0200 Subject: [PATCH 16/26] Release map: vectored thruster rows (probes V1-V8, model rows, cut order) Imagination pass (session self-2026-10-10-ag): the row gimbal is sim data, one shared-throttle actuator per row in the allocator's single solve; specs vector-rows-record r2 and vector-rows-allocator r1. Co-Authored-By: Claude Opus 5.5 --- docs/aetheria-release-map.md | 146 +++++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) diff --git a/docs/aetheria-release-map.md b/docs/aetheria-release-map.md index 08528d188..80ec3dd98 100644 --- a/docs/aetheria-release-map.md +++ b/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`. From aa5e45a2ffa1790d4596f09dfeddd227faa3faac Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 07:59:36 +0200 Subject: [PATCH 17/26] ThrustAllocator tests: IterationLimit keeps the solver's iterate (iteration-limit-untested) 128 torque-free forward thrusters from a cold start reach the 100-iteration cap through the public surface; the call must keep the iterate it reached, not zero it. Commit builds: yes (tests/Aetheria.Shared.Tests not yet run on this commit; the full run is the closing job). Co-Authored-By: Claude Opus 5.5 --- .../Aetheria.Shared.Tests/ThrustAllocatorTests.cs | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs index 26c50e35d..1f956eafb 100644 --- a/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs +++ b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs @@ -311,4 +311,18 @@ public class ThrustAllocatorTests for (var i = 0; i < warm.Length; i++) Assert.True(MathF.Abs(warm[i] - fresh[i]) <= 1e-5f, $"throttle {i}: {warm[i]} vs {fresh[i]}"); Assert.True(warm[1] > .9f, $"{warm[1]}"); } + + [Fact] + public void AtTheIterationCapTheIterateIsKept() + { + // 128 torque-free forward thrusters from a cold start: the active set frees about one throttle per iteration, so + // the solver stops at its iteration cap (measured: IterationLimit at 100). TA-R4 keeps the iterate it reached, + // which already carries a share of the forward demand; a call that zeroed it would give nothing. + var forward = new float3[128]; + for (var i = 0; i < forward.Length; i++) forward[i] = Col(0, 30f + i % 7, 0); + var throttle = Solve(forward, 0, 1, 0); + var reached = Net(forward, throttle).y; + var extreme = Extremes(forward, 1).plus; + Assert.True(reached > .1f * extreme, $"{reached} of {extreme}"); + } } From 87e9bfd06b93c9a022f2ad658ba359be06af5554 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 07:59:39 +0200 Subject: [PATCH 18/26] ThrustAllocator tests: a full turn against a full reverse keeps its whole yaw (error-bound-unpinned) The turn leaves a forward error of 2, the top of TA-R2's error box; a bound of 1 or 1.5 gives yaw back. Commit builds: yes (tests/Aetheria.Shared.Tests not yet run on this commit; the full run is the closing job). Co-Authored-By: Claude Opus 5.5 --- .../ThrustAllocatorTests.cs | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs index 1f956eafb..c75bc5620 100644 --- a/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs +++ b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs @@ -325,4 +325,24 @@ public class ThrustAllocatorTests var extreme = Extremes(forward, 1).plus; Assert.True(reached > .1f * extreme, $"{reached} of {extreme}"); } + + [Fact] + public void AFullTurnAgainstAFullReverseKeepsItsWholeYaw() + { + // The only clockwise actuator also pushes forward and the only reverse actuator turns the other way. Delivering + // a full turn against a full reverse leaves a forward error of 2, the top of TA-R2's error box: an error bound + // below 2 would take yaw back to pay for it, and turn-authority-full says the turn is whole. + foreach (var (columns, x, y) in new[] + { + (new[] { Col(0, 50, 100), Col(0, -50, -100) }, 0f, -1f), + (new[] { Col(50, 0, 100), Col(-50, 0, -100) }, -1f, 0f), + (new[] { Col(0, -50, 100), Col(0, 50, -100) }, 0f, 1f), + (new[] { Col(-50, 0, 100), Col(50, 0, -100) }, 1f, 0f), + }) + { + var yaw = Net(columns, Solve(columns, x, y, 1)).z; + var extreme = Extremes(columns, 2).plus; + Assert.True(MathF.Abs(yaw - extreme) <= 1e-4f * extreme, $"move ({x},{y}): yaw {yaw / Deg} of {extreme / Deg}"); + } + } } From 22cb76e85b957afb783a6d28c432e83c5a8541bb Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 07:59:43 +0200 Subject: [PATCH 19/26] ThrustAllocator tests: the drive's leak pins the sign of TA-R2's cost row (cost-row-sign-unpinned) A cost row pulling the errors the other way lowers the pre-onset drive throttle by about 20 percent (1.30e-4 to 1.06e-4 at turn .5); the bounds sit 8 percent under the measured value. Commit builds: yes (tests/Aetheria.Shared.Tests not yet run on this commit; the full run is the closing job). Co-Authored-By: Claude Opus 5.5 --- .../ThrustAllocatorTests.cs | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs index c75bc5620..33d9f6680 100644 --- a/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs +++ b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs @@ -345,4 +345,28 @@ public class ThrustAllocatorTests Assert.True(MathF.Abs(yaw - extreme) <= 1e-4f * extreme, $"move ({x},{y}): yaw {yaw / Deg} of {extreme / Deg}"); } } + + [Fact] + public void NothingAskedAfterACallFiresNothing() + { + // The warm start left by a call must not leak into a hold of zero intent: exactly zero, not solver residue. + foreach (var hull in new[] { Duel(), Symmetric() }) + foreach (var previous in new[] { (.5f, .5f, .5f), (1f, 1f, 1f), (-.3f, .8f, .6f), (0f, 0f, -1f), (0f, 1f, 0f) }) + { + var allocator = new ThrustAllocator(); + Solve(allocator, hull, previous.Item1, previous.Item2, previous.Item3); + Assert.All(Solve(allocator, hull, 0, 0, 0), t => Assert.Equal(0f, t)); + } + } + + [Fact] + public void TheDriveCarriesTheLinearCostsLeakBeforeTheOnset() + { + // The error variables are paid linearly toward zero (TA-R2): that cost, against the ridge, holds the drive at a + // small constant throttle before the onset, 1.30e-4 at turn .5 and 1.14e-4 at turn -.5 on the Duel (a cost row + // pulling the errors the other way gives 1.06e-4 and 0.93e-4). The bounds are the measured value less 8%. + var duel = Duel(); + Assert.InRange(Solve(duel, 0, 0, .5f)[0], 1.2e-4f, LeakBound); + Assert.InRange(Solve(duel, 0, 0, -.5f)[1], 1.05e-4f, LeakBound); + } } From 8fab3052e1bd198cf0387f557ac38c7ba02486da Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 07:59:56 +0200 Subject: [PATCH 20/26] ThrustAllocator: solver residue below 1e-9 is zero; zero intent after a call is exact zeros (zero-intent-warm-nonzero) After a good call the warm start left 1e-34..1e-44 throttles on a zero-intent call. Throttles at or below ThrottleResidue return 0 on the one general path; TA-R3's warm start is kept. The test NothingAskedAfterACallFiresNothing arrived in the previous commit (22cb76e8), which therefore fails that test; this commit makes it pass. Co-Authored-By: Claude Opus 5.5 --- Assets/Scripts/ServerShared/ThrustAllocator.cs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Assets/Scripts/ServerShared/ThrustAllocator.cs b/Assets/Scripts/ServerShared/ThrustAllocator.cs index 200a2abcc..bd4b81ff3 100644 --- a/Assets/Scripts/ServerShared/ThrustAllocator.cs +++ b/Assets/Scripts/ServerShared/ThrustAllocator.cs @@ -23,6 +23,9 @@ public sealed class ThrustAllocator const float ErrorCostWeight = .3f; const float ErrorCostOffset = 10f; const float Ridge = .1f; + // The solver stops within its tolerance of the optimum, so a throttle that should be zero can come back as 1e-34 after + // a warm start. Below this a throttle is that residue, not an ask: nothing asked is nothing fired. + const float ThrottleResidue = 1e-9f; const float ErrorMax = 2f; const double KktRelativeTolerance = 1e-12; const int ErrorVariables = 4; @@ -77,7 +80,7 @@ public sealed class ThrustAllocator var status = BoundedLeastSquares.Solve(rows, vars, _a, _b, _lo, _hi, _x, _workspace, out _, KktRelativeTolerance); if (status == BoundedLeastSquaresStatus.InvalidInput) return; - for (var i = 0; i < n; i++) throttle[i] = _x[i]; + for (var i = 0; i < n; i++) throttle[i] = _x[i] > ThrottleResidue ? _x[i] : 0; } static float Component(float3 c, int axis) => axis == 0 ? c.x : axis == 1 ? c.y : c.z; From 9ae5fbb350375d1aa93bb55b24dbc028c01ab828 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 08:10:12 +0200 Subject: [PATCH 21/26] AetheriaStoresTests: MissingCatalogGlobalIsLoud copies the fixture catalog and removes its global Flushing an empty cache writes no file, so the previous fixture still hit the new missing-file refusal. Builds. Co-Authored-By: Claude Opus 5.5 --- tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs b/tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs index 4d7611b9a..bff3a1a6d 100644 --- a/tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs +++ b/tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs @@ -116,9 +116,10 @@ public sealed class AetheriaStoresTests : IDisposable public void MissingCatalogGlobalIsLoud() { var empty = Path.Combine(_root, "empty.cc"); - // An existing catalog with no records: a read-only open refuses a missing file before it checks globals. - using (var seed = AetheriaStores.Open(empty, catalogWritable: true)) seed.FlushAsync().Wait(); - Assert.True(File.Exists(empty)); + // 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()).Key))); var error = Assert.Throws(() => AetheriaStores.Open(empty)); Assert.Contains("aetheria.tests.catalogglobal", error.Message); using (AetheriaStores.Open(Catalog)) { } From 191f1fec042c4715ce132636260e0f3dc3a2df86 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 08:29:09 +0200 Subject: [PATCH 22/26] ShipRigTests: pin asymmetric reach, tagged non-joint nodes in Bind, and hull-order Rigs Off-centre joint limits (20..50, -10..50, -50..0) so Max-Min is distinguishable from |Min|+|Max| and 2*max/2*Max; Bind walking past tagged nodes that are not joints; Rigs and the lead mount follow hull order where it differs from name order. Tests only; builds. Co-Authored-By: Claude Opus 5.5 --- tests/Aetheria.Shared.Tests/ShipRigTests.cs | 63 +++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/tests/Aetheria.Shared.Tests/ShipRigTests.cs b/tests/Aetheria.Shared.Tests/ShipRigTests.cs index 2ab838b2c..84195c65d 100644 --- a/tests/Aetheria.Shared.Tests/ShipRigTests.cs +++ b/tests/Aetheria.Shared.Tests/ShipRigTests.cs @@ -88,6 +88,22 @@ public sealed class ShipRigTests : IDisposable Assert.Contains("reaches 360 degrees", Refusal(OneGun(400, (Up, -180f, 180f), (Up, -180f, 180f)))); } + // Reach is Max - Min per degree of freedom, however the limits sit about zero: a sweep from 20 to 50 reaches 30, and one from + // -10 to 50 reaches 60. Symmetric limits cannot tell that from |Min| + |Max| (70, 60) or twice the larger side (100, 100). + [Fact] + public void ReachIsMaxMinusMinForLimitsThatSitOffCentre() + { + OneGun(30, (Up, 20f, 50f)).Validate(); + Assert.Contains("reaches 30 degrees", Refusal(OneGun(31, (Up, 20f, 50f)))); + OneGun(60, (Up, -10f, 50f)).Validate(); + Assert.Contains("reaches 60 degrees", Refusal(OneGun(61, (Up, -10f, 50f)))); + OneGun(50, (Up, -50f, 0f)).Validate(); + Assert.Contains("reaches 50 degrees", Refusal(OneGun(51, (Up, -50f, 0f)))); + // Off-centre limits on two serial degrees of freedom add their own ranges: 30 + 60. + OneGun(90, (Up, 20f, 50f), (Up, -10f, 50f)).Validate(); + Assert.Contains("reaches 90 degrees", Refusal(OneGun(91, (Up, 20f, 50f), (Up, -10f, 50f)))); + } + [Fact] public void AnAxisWithinFiveDegreesOfUpIsYawAndOneBeyondItIsNot() { @@ -228,6 +244,24 @@ public sealed class ShipRigTests : IDisposable Assert.Equal(new[] { "arm", "elbow", "wrist" }, package.Visual.Joints.Select(joint => joint.Id)); } + // The exporter tags nodes that are not joints (a bracket, a forearm mesh). They sit between a mount and its joint and + // between a joint and its parent joint, and the nearest JOINT above is still what Bind compares. + [Fact] + public void BindWalksPastTaggedNodesThatAreNotJoints() + { + var nodes = RigNodes.Select(node => node.Name switch + { + "bracket" => node with { Id = "bracket" }, + "wrist" => node with { Parent = "forearm" }, + _ => node + }).Append(new Node("forearm", "forearm", "elbow")).ToArray(); + + var package = ShipModCatalog.ReadPackage(Package(null, nodes)); + + Assert.Equal(new[] { "arm", "elbow", "wrist" }, package.Visual.Joints.Select(joint => joint.Id)); + Assert.Equal("wrist", package.Visual.Anchors.Single(anchor => anchor.Id == "gun").Joint); + } + [Fact] public void BindRefusesAMountWhoseJointIsNotTheNearestOneAboveItsNode() { @@ -302,6 +336,35 @@ public sealed class ShipRigTests : IDisposable Assert.Equal(("g1", "g1.z"), (rigs[1].LeadMount, rigs[1].LeadMuzzle)); } + // Hull order, not name order: the first gun rides "turret" and the second "barrel". + [Fact] + public void RigsFollowHullOrderAndNotTheOrderOfTheJointNames() + { + var ship = Armed("turret", "barrel"); + ship.Visual.Joints.Add(Joint("turret", null, (Up, -180f, 180f))); + ship.Visual.Joints.Add(Joint("barrel", null, (Up, -180f, 180f))); + + var rigs = ShipModPlan.Build(ship.Hull, ship.Visual).Rigs; + + Assert.Equal(new[] { "turret", "barrel" }, rigs.Select(rig => rig.Joint)); + Assert.Equal(new[] { "g0", "g1" }, rigs.Select(rig => rig.LeadMount)); + } + + // g1 is listed before g0 in the hull though its name sorts after it. + [Fact] + public void TheLeadMountOfAJointIsItsFirstWeaponInHullOrderWhateverTheNames() + { + var ship = Armed("j", "j"); + ship.Visual.Joints.Add(Joint("j", null, (Up, -180f, 180f))); + var g1 = ship.Hull.Hardpoints.Single(hardpoint => hardpoint.Transform == "g1"); + ship.Hull.Hardpoints.Remove(g1); + ship.Hull.Hardpoints.Insert(ship.Hull.Hardpoints.FindIndex(hardpoint => hardpoint.Transform == "g0"), g1); + + var rig = Assert.Single(ShipModPlan.Build(ship.Hull, ship.Visual).Rigs); + + Assert.Equal(("g1", "g1.muzzle"), (rig.LeadMount, rig.LeadMuzzle)); + } + [Fact] public void AnUndrivenParentJointIsPartOfTheChainRootFirst() { From 638856afc14cb4f677ec38db90355b332f8a496a Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 08:29:11 +0200 Subject: [PATCH 23/26] ShipValidationTests: a NaN Min and a NaN Max are each refused as not finite Tests only; builds. Co-Authored-By: Claude Opus 5.5 --- tests/Aetheria.Shared.Tests/ShipValidationTests.cs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tests/Aetheria.Shared.Tests/ShipValidationTests.cs b/tests/Aetheria.Shared.Tests/ShipValidationTests.cs index c2d177f21..5b772bdd0 100644 --- a/tests/Aetheria.Shared.Tests/ShipValidationTests.cs +++ b/tests/Aetheria.Shared.Tests/ShipValidationTests.cs @@ -197,6 +197,8 @@ public sealed class ShipValidationTests Add("joint-axis-not-unit", s => Joint(s, "j", null, new[] { 0f, 2f, 0f }, new[] { -1f }, new[] { 1f }), "must be a unit vector"); Add("joint-axis-not-finite", s => Joint(s, "j", null, new[] { 0f, float.NaN, 0f }, new[] { -1f }, new[] { 1f }), "axes and limits must be finite"); Add("joint-limit-not-finite", s => Joint(s, "j", null, yaw, new[] { -1f }, new[] { float.PositiveInfinity }), "axes and limits must be finite"); + Add("joint-min-not-finite", s => Joint(s, "j", null, yaw, new[] { float.NaN }, new[] { 1f }), "axes and limits must be finite"); + Add("joint-max-not-a-number", s => Joint(s, "j", null, yaw, new[] { -1f }, new[] { float.NaN }), "axes and limits must be finite"); Add("joint-min-above-max", s => Joint(s, "j", null, yaw, new[] { 10f }, new[] { 5f }), "must satisfy -180 <= Min <= Max <= 180"); Add("joint-max-181", s => Joint(s, "j", null, yaw, new[] { 0f }, new[] { 181f }), "must satisfy -180 <= Min <= Max <= 180"); Add("joint-min-minus-181", s => Joint(s, "j", null, yaw, new[] { -181f }, new[] { 0f }), "must satisfy -180 <= Min <= Max <= 180"); From 7a195d2384f82957b5a1256f400d0b664a3848e2 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 08:29:12 +0200 Subject: [PATCH 24/26] Pin the rig's slot 5 carry-through: C# slot numbers and Python replace_visual/replace_lines round trips Tests only; builds. Co-Authored-By: Claude Opus 5.5 --- .../ShipSchemaPinTests.cs | 9 ++++++ tools/blender/tests/test_ship_cc.py | 28 +++++++++++++++++++ 2 files changed, 37 insertions(+) diff --git a/tests/Aetheria.Shared.Tests/ShipSchemaPinTests.cs b/tests/Aetheria.Shared.Tests/ShipSchemaPinTests.cs index e674ed23a..f0a2283aa 100644 --- a/tests/Aetheria.Shared.Tests/ShipSchemaPinTests.cs +++ b/tests/Aetheria.Shared.Tests/ShipSchemaPinTests.cs @@ -67,6 +67,15 @@ public sealed class ShipSchemaPinTests Assert.Equal(slot, KeyOf(typeof(ShipAnchor), members[slot])); } + // ship_cc.py edits slots 2 to 4 of a ship and the first five slots of an anchor row, and carries every later slot (replace_visual + // by anchor Id). The rig lives in those later slots; their numbers are the contract that carry-through keeps. + [Fact] + public void TheRigLivesInTheSlotsPastTheOnesPythonEdits() + { + Assert.Equal(Integer("SCHEMATIC_LINES_SLOT") + 1, KeyOf(typeof(ShipAuthoring), nameof(ShipAuthoring.Joints))); + Assert.Equal(Strings("ANCHOR_MEMBERS").Length, KeyOf(typeof(ShipAnchor), nameof(ShipAnchor.Joint))); + } + [Fact] public void PythonEnumNamesAreTheEnumsInValueOrder() { diff --git a/tools/blender/tests/test_ship_cc.py b/tools/blender/tests/test_ship_cc.py index d0f80150a..20d9cf6c4 100644 --- a/tools/blender/tests/test_ship_cc.py +++ b/tools/blender/tests/test_ship_cc.py @@ -190,6 +190,34 @@ class ReadTests(ShipFileCase): ship_cc.read(self.path, PACKAGES) +class RigCarryThroughTests(ShipFileCase): + """The rig (ShipAuthoring slot 5 Joints, ShipAnchor slot 5 Joint) lies past every slot this module edits, so a save keeps it.""" + + JOINTS = [["turret", None, [0.0, 1.0, 0.0], [-30.0], [30.0]]] + + def setUp(self): + super().setUp() + ship = ship_body() + ship.append(self.JOINTS) + ship[ship_cc.ANCHORS_SLOT] = [["gun", "weapon-mount", "gun", None, 0, "turret"], ["map", "map-icon", "map", None, 0]] + self.write(ship, hull_body()) + + def test_replace_visual_keeps_the_joints_and_each_mounts_joint_by_anchor_id(self): + ship_cc.replace_visual(self.path, PACKAGES, "mod.skiff", "ship.glb", + [["map", "map-icon", "map", None, 0], ["gun", "weapon-mount", "gun", None, 0]]) + ship = self.ship() + self.assertEqual(self.JOINTS, ship[5]) + self.assertEqual([["map", "map-icon", "map", None, 0], ["gun", "weapon-mount", "gun", None, 0, "turret"]], + ship[ship_cc.ANCHORS_SLOT]) + + def test_replace_lines_keeps_the_joints_and_the_anchor_rows(self): + before = self.ship() + ship_cc.replace_lines(self.path, PACKAGES, LINES) + after = self.ship() + self.assertEqual(self.JOINTS, after[5]) + self.assertEqual(before[ship_cc.ANCHORS_SLOT], after[ship_cc.ANCHORS_SLOT]) + + class ReplaceLinesTests(ShipFileCase): def test_replaces_only_the_line_slot(self): new_lines = [["Detail", "Red", [0.0] * 6, [0.1, 0.1], [1.0, 1.0], True, [1.0, 0.0, 0.0, 1.0]]] From 8bfce1899e6a5c64606d63dea25fd2f0f9b421c9 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 09:08:55 +0200 Subject: [PATCH 25/26] ThrustAllocator: zero intent returns exact zeros before the solve; the 1e-9 output flush is deleted (zero-intent-warm-nonzero, zero-intent-at-the-cap) Nothing asked, nothing fired is a fact about the intent: when all three clamped intents are exactly zero Allocate returns the zeroed buffer before the solve, so a warm solve that stops at the iteration cap can no longer fire thrusters. The output flush is gone. The warm start is left at the last solved point. Tests: the two 40-thruster hulls Soul found, and a small intent still answered at any column scale. Builds untested locally; verified on Yggdrasil. Co-Authored-By: Claude Opus 5.5 --- .../Scripts/ServerShared/ThrustAllocator.cs | 14 +++-- .../ThrustAllocatorTests.cs | 51 +++++++++++++++++++ 2 files changed, 60 insertions(+), 5 deletions(-) diff --git a/Assets/Scripts/ServerShared/ThrustAllocator.cs b/Assets/Scripts/ServerShared/ThrustAllocator.cs index bd4b81ff3..828edf993 100644 --- a/Assets/Scripts/ServerShared/ThrustAllocator.cs +++ b/Assets/Scripts/ServerShared/ThrustAllocator.cs @@ -23,9 +23,6 @@ public sealed class ThrustAllocator const float ErrorCostWeight = .3f; const float ErrorCostOffset = 10f; const float Ridge = .1f; - // The solver stops within its tolerance of the optimum, so a throttle that should be zero can come back as 1e-34 after - // a warm start. Below this a throttle is that residue, not an ask: nothing asked is nothing fired. - const float ThrottleResidue = 1e-9f; const float ErrorMax = 2f; const double KktRelativeTolerance = 1e-12; const int ErrorVariables = 4; @@ -40,6 +37,10 @@ public sealed class ThrustAllocator if (n != _columns) Resize(n); for (var i = 0; i < n; i++) throttle[i] = 0; + // Nothing asked, nothing fired: that is a fact about the intent, decided before the solve. The solver's warm + // start is left as the last solved point, which is where the next non-zero call resumes. + if (Intent(move, turn, 0) == 0 && Intent(move, turn, 1) == 0 && Intent(move, turn, 2) == 0) return; + var vars = n + ErrorVariables; var rows = FixedRows + n; @@ -54,7 +55,7 @@ public sealed class ThrustAllocator else if (c < 0) minus -= c; } var extreme = Math.Max(plus, minus); - var intent = Math.Min(Math.Max(axis == 0 ? move.x : axis == 1 ? move.y : turn, -1f), 1f); + var intent = Intent(move, turn, axis); var weight = axis == 2 ? YawWeight : TranslationWeight; // Intent is a fraction of the half-axis extreme it points into. var demand = intent >= 0 ? intent * plus : intent * minus; @@ -80,9 +81,12 @@ public sealed class ThrustAllocator var status = BoundedLeastSquares.Solve(rows, vars, _a, _b, _lo, _hi, _x, _workspace, out _, KktRelativeTolerance); if (status == BoundedLeastSquaresStatus.InvalidInput) return; - for (var i = 0; i < n; i++) throttle[i] = _x[i] > ThrottleResidue ? _x[i] : 0; + for (var i = 0; i < n; i++) throttle[i] = _x[i]; } + static float Intent(float2 move, float turn, int axis) => + Math.Min(Math.Max(axis == 0 ? move.x : axis == 1 ? move.y : turn, -1f), 1f); + static float Component(float3 c, int axis) => axis == 0 ? c.x : axis == 1 ? c.y : c.z; void Resize(int n) diff --git a/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs index 33d9f6680..0fc556200 100644 --- a/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs +++ b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs @@ -346,6 +346,57 @@ public class ThrustAllocatorTests } } + // Forty thrusters of 20..60 m/s^2 on random half-axes with random yaw, the shape of a hull far larger than any demo + // ship. Deterministic from the seed. + static float3[] LargeHull(int n, int seed) + { + var rng = new Random(seed); + var columns = new float3[n]; + for (var i = 0; i < n; i++) + { + var a = 20f + 40f * (float)rng.NextDouble(); + var yaw = (float)(rng.NextDouble() * 2 - 1) * 120f; + var dir = rng.Next(10); + columns[i] = dir < 4 ? Col(0, a, yaw) : dir < 6 ? Col(0, -a, yaw) : dir < 8 ? Col(a, 0, yaw) : Col(-a, 0, yaw); + } + return columns; + } + + [Fact] + public void NothingAskedAfterAnIterationCapCallFiresNothing() + { + // On this hull the warm solve of a zero-intent call needs more than the solver's 100 iterations, and the iterate it + // stopped at fired throttles up to 1.0 with nothing asked. Whether nothing is asked is decided from the intent, not + // by how far the solver gets. + var histories = new[] + { + (Seed: 9039, History: new[] { (0.0112729073f, -0.170811713f, 0.809294581f), (-0.474286854f, 0.703138232f, 0f), (0.294080615f, 0.934491992f, -0.776120305f) }), + (Seed: 9079, History: new[] { (0.607828975f, 1f, 0.202640772f), (-0.620587587f, 0.0162956715f, -0.898228765f), (0.0739500523f, 1f, -0.903907537f) }), + }; + foreach (var (seed, history) in histories) + { + var hull = LargeHull(40, seed); + var allocator = new ThrustAllocator(); + foreach (var (x, y, turn) in history) Solve(allocator, hull, x, y, turn); + Assert.All(Solve(allocator, hull, 0, 0, 0), t => Assert.Equal(0f, t)); + Assert.All(Solve(allocator, hull, 0, 0, 0), t => Assert.Equal(0f, t)); + } + } + + [Fact] + public void ASmallIntentIsStillAnsweredWhateverTheColumnScale() + { + // Zero is a fact about the intent alone: an intent of 1e-3 of the half-axis is served at any scale of thrust. + foreach (var scale in new[] { 1e-3f, 1f, 1e3f }) + { + var hull = Duel(); + for (var i = 0; i < hull.Length; i++) hull[i] *= scale; + var extreme = Extremes(hull, 2).plus; + var yaw = Net(hull, Solve(hull, 0, 0, 1e-3f)).z; + Assert.True(yaw > .5e-3f * extreme, $"scale {scale}: yaw {yaw} of {extreme}"); + } + } + [Fact] public void NothingAskedAfterACallFiresNothing() { From 144b2f5b9523e1e9068a0d80067b79a511fdd21a Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 10 Oct 2026 09:27:59 +0200 Subject: [PATCH 26/26] ThrustAllocator tests: System.Random, not CultMath.Random, in the large-hull fixture The previous commit (8bfce189) does not build: CS0104 ambiguous Random in ThrustAllocatorTests. Co-Authored-By: Claude Opus 5.5 --- tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs index 0fc556200..95ca77bda 100644 --- a/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs +++ b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs @@ -350,7 +350,7 @@ public class ThrustAllocatorTests // ship. Deterministic from the seed. static float3[] LargeHull(int n, int seed) { - var rng = new Random(seed); + var rng = new System.Random(seed); var columns = new float3[n]; for (var i = 0; i < n; i++) {