diff --git a/Assets/Editor/AetheriaBuild.cs b/Assets/Editor/AetheriaBuild.cs new file mode 100644 index 000000000..7d3c891d2 --- /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"; + UnityEditor.PlayerSettings.bundleVersion = version; // the game has its own global PlayerSettings + + step = "addressables"; + AddressableAssetSettings.BuildPlayerContent(out var content); + if (!string.IsNullOrEmpty(content.Error)) throw new InvalidOperationException("Addressables build reported an error: " + content.Error); + + step = "player"; + Directory.CreateDirectory(output); + var scenes = EditorBuildSettings.scenes.Where(scene => scene.enabled).Select(scene => scene.path).ToArray(); + if (scenes.Length == 0) throw new InvalidOperationException("EditorBuildSettings has no enabled scene"); + var report = BuildPipeline.BuildPlayer(new BuildPlayerOptions + { + scenes = scenes, + locationPathName = Path.Combine(output, "Aetheria.exe"), + target = BuildTarget.StandaloneWindows64, + options = BuildOptions.None, + }); + if (report.summary.result != BuildResult.Succeeded || report.summary.totalErrors != 0) + throw new InvalidOperationException($"BuildPlayer ended {report.summary.result} with {report.summary.totalErrors} errors"); + + step = "gamedata"; + PlayerStaging.Stage(repoRoot, output); + + step = "aetherdb"; + Publish(repoRoot, Path.Combine(output, "ModTools")); + + step = "burst"; + var burst = Path.Combine(output, "Aetheria_BurstDebugInformation_DoNotShip"); + if (Directory.Exists(burst)) Directory.Delete(burst, true); + + Debug.Log($"AetheriaBuild OK {version} {output}"); + } + catch (Exception error) + { + Debug.LogError($"AetheriaBuild FAILED at {step}: {error.GetType().Name}: {error.Message}"); + EditorApplication.Exit(1); + return; + } + EditorApplication.Exit(0); + } + + private static void Publish(string repoRoot, string modTools) + { + var info = new ProcessStartInfo("dotnet") + { + Arguments = $"publish tools/AetherDb -c Release -r win-x64 --self-contained -p:PublishSingleFile=true -o \"{modTools}\"", + WorkingDirectory = repoRoot, + UseShellExecute = false, + RedirectStandardOutput = true, + RedirectStandardError = true, + }; + using (var process = Process.Start(info)) + { + var errors = process.StandardError.ReadToEndAsync(); + var text = process.StandardOutput.ReadToEnd(); + process.WaitForExit(); + if (process.ExitCode != 0) + throw new InvalidOperationException($"dotnet publish exited {process.ExitCode}:\n{text}\n{errors.Result}"); + } + if (!File.Exists(Path.Combine(modTools, "AetherDb.exe"))) + throw new InvalidOperationException("dotnet publish produced no ModTools/AetherDb.exe"); + } + + private static string Argument(string name) + { + var args = Environment.GetCommandLineArgs(); + var at = Array.IndexOf(args, name); + if (at < 0 || at + 1 >= args.Length) throw new InvalidOperationException(name + " is required"); + return args[at + 1]; + } +} 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 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/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 diff --git a/Assets/Scripts/ServerShared/AetheriaStores.cs b/Assets/Scripts/ServerShared/AetheriaStores.cs index b335e3442..479f917d9 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; @@ -18,6 +19,9 @@ public static class AetheriaStores public static CultCache Open(string catalogPath, string runPath = null, string playerPath = null, bool catalogWritable = false, CultDocumentRegistry registry = null) { + // A read-only open of an absent catalog would hydrate an empty game; a shipped player missing its catalog stops here. + if (!catalogWritable && !File.Exists(catalogPath)) + throw new FileNotFoundException($"Catalog {catalogPath} does not exist; a read-only open never invents one.", catalogPath); var cache = new CultCache(registry); try { 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 13fcd587f..b997add7f 100644 --- a/Assets/Scripts/ServerShared/ShipModCatalog.cs +++ b/Assets/Scripts/ServerShared/ShipModCatalog.cs @@ -183,6 +183,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 { @@ -191,9 +192,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); @@ -204,17 +239,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/Assets/Scripts/ServerShared/ThrustAllocator.cs b/Assets/Scripts/ServerShared/ThrustAllocator.cs new file mode 100644 index 000000000..828edf993 --- /dev/null +++ b/Assets/Scripts/ServerShared/ThrustAllocator.cs @@ -0,0 +1,105 @@ +/* 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; + + // 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; + + // 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 = 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; + 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) + { + var errorWeight = extreme > 0 ? weight : 0f; + _a[row + n + 2 * axis] = -errorWeight; + _a[row + n + 2 * axis + 1] = errorWeight; + } + } + + // 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 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) + { + _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/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", 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`. 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 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/AetheriaStoresTests.cs b/tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs index e0fec193d..bff3a1a6d 100644 --- a/tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs +++ b/tests/Aetheria.Shared.Tests/AetheriaStoresTests.cs @@ -116,7 +116,10 @@ public sealed class AetheriaStoresTests : IDisposable public void MissingCatalogGlobalIsLoud() { var empty = Path.Combine(_root, "empty.cc"); - using (AetheriaStores.Open(empty, catalogWritable: true)) { } + // A catalog file that exists but lacks the global: the read-only open reaches the global check. + File.Copy(Catalog, empty); + using (var seed = AetheriaStores.Open(empty, catalogWritable: true)) + Assert.True(seed.Commit(batch => batch.Remove(seed.RefOf(seed.GetGlobal()).Key))); var error = Assert.Throws(() => AetheriaStores.Open(empty)); Assert.Contains("aetheria.tests.catalogglobal", error.Message); using (AetheriaStores.Open(Catalog)) { } @@ -200,6 +203,23 @@ public sealed class AetheriaStoresTests : IDisposable Assert.Null(record); } + // A shipped player with no catalog must not boot into an empty game: a read-only open of a missing path throws + // naming the path, and does not create the file. A writable open still seeds an empty catalog. + [Fact] + public void AStoreRefusesAMissingCatalog() + { + var missing = Path.Combine(_root, "absent", "Aetheria.cc"); + + // FileNotFoundException, not the catalog-global check: that one also throws on a missing file whenever a global is registered. + var error = Assert.Throws(() => 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) 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); + } +} 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 1fe18a4e6..755fc20b9 100644 --- a/tests/Aetheria.Shared.Tests/ShipModCatalogTests.cs +++ b/tests/Aetheria.Shared.Tests/ShipModCatalogTests.cs @@ -446,7 +446,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] @@ -610,7 +610,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..84195c65d --- /dev/null +++ b/tests/Aetheria.Shared.Tests/ShipRigTests.cs @@ -0,0 +1,384 @@ +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)))); + } + + // 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() + { + 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, 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)))); + 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)); + } + + // 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() + { + 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)); + } + + // 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() + { + 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/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/tests/Aetheria.Shared.Tests/ShipValidationTests.cs b/tests/Aetheria.Shared.Tests/ShipValidationTests.cs index 804ff723f..5b772bdd0 100644 --- a/tests/Aetheria.Shared.Tests/ShipValidationTests.cs +++ b/tests/Aetheria.Shared.Tests/ShipValidationTests.cs @@ -172,17 +172,41 @@ 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-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"); + 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'"); diff --git a/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs new file mode 100644 index 000000000..95ca77bda --- /dev/null +++ b/tests/Aetheria.Shared.Tests/ThrustAllocatorTests.cs @@ -0,0 +1,423 @@ +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; + + // 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). + 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 <= LeakBound, $"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 <= LeakBound, $"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 <= LeakBound, $"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)); + + // 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] + 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}"); + } + } + + [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]}"); + } + + [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}"); + } + + [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}"); + } + } + + // 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 System.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() + { + // 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); + } +} 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]]]