From d8f1b51c8610aeaadc5e1792548c24c74e3a4881 Mon Sep 17 00:00:00 2001 From: Cristian Cerroni Date: Tue, 3 Nov 2026 17:38:48 -0500 Subject: [PATCH] Fix orbit camera mirroring by matching gameplay handedness --- docs/compatibility.md | 6 +++ docs/decisions.md | 6 +++ docs/orbit-camera.md | 38 +++++++++++++++++++ docs/progress.md | 12 ++++++ docs/rendering.md | 4 ++ docs/tasks.md | 3 ++ src/GamePort/Application/OrbitCamera.cs | 22 +++++++++++ src/GamePort/Program.cs | 8 ++-- .../GamePort.ProjectionTests.csproj | 1 + tests/GamePort.ProjectionTests/Program.cs | 29 ++++++++++++++ 10 files changed, 125 insertions(+), 4 deletions(-) create mode 100644 docs/orbit-camera.md create mode 100644 src/GamePort/Application/OrbitCamera.cs diff --git a/docs/compatibility.md b/docs/compatibility.md index 2bafbee..0082670 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -3,6 +3,12 @@ Compilation, native runtime, original behavior and full feature completion are separate evidence categories. **The game is not fully reconstructed/playable yet.** +Orbit inspector follow-up: corrected right-handed inspection view/perspective +to gameplay's positive-Z left-handed convention.36 camera/aspect cases and all +existing projection checks pass. Enabled-validation llvmpipe captures confirm +the removed horizontal reflection; lab gameplay captures are byte-identical. +Native/package evidence: orbit-camera.md. Native Windows remains unverified. + Rocketship impact follow-up: corrected first-material red-flash RGBA previously misapplied to ship scale.13 managed groups include actual wall contact plus130 frames of unchanged geometry, correct ship-only tint, recovery and repeated diff --git a/docs/decisions.md b/docs/decisions.md index 04bf0c2..fa5ead2 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -264,3 +264,9 @@ actual DLL renderer consumers now guard the contract. Use a ship-only red material flash with unit geometry; regress vertex positions as well as values. See gameplay/rocketship-impact-render.md. +45. **Keep inspection in the gameplay coordinate convention.** A right-handed + view/perspective pair can render a valid frame while mirroring a positive-Z + source scene relative to gameplay. OrbitCamera now owns the matching + left-handed view/projection; apply the shared Vulkan Y correction only once. + Regress screen right/up and depth across camera poses, not frame presence + alone. The modern inspector is separate from recovered original camera logic. diff --git a/docs/orbit-camera.md b/docs/orbit-camera.md new file mode 100644 index 0000000..e2f9c3d --- /dev/null +++ b/docs/orbit-camera.md @@ -0,0 +1,38 @@ +# Orbit camera handedness correction + +2026-11-03. User reports the world flips when using orbit inspection. +This is a modern camera bug; no new original-binary interpretation is needed. + +## Cause and correction + +Program used System.Numerics CreateLookAt/CreatePerspectiveFieldOfView for +inspection, both right-handed. Gameplay and source geometry use positive-Z +left-handed camera space. At the same eye/target/up, swapping the paired view +and perspective conventions reverses screen X. The old orbit view therefore +mirrored the world relative to gameplay. Vulkan's shared M22 viewport flip is +still required for screen Y; removing that would introduce another inversion. + +OrbitCamera now owns the inspector eye/view/projection calculation and uses +CreateLookAtLeftHanded/CreatePerspectiveFieldOfViewLeftHanded. The caller applies +the same single Vulkan Y correction as gameplay. Existing orbit positions, +elevation limits, zoom, field of view and depth range are retained. Gameplay, +scripted and Rocketship cameras keep their existing math. + +## Verification + +ProjectionTests covers36 combinations of four azimuths, three elevations and +three aspect ratios (4:3,16:9,21:9). Tests independently construct forward/right/up +vectors and verify centered target, screen directions, positive-Z forward and +Vulkan0..1 near/far depth. Existing all35 level clip mappings and actual outside +geometry regression also pass. Main .NET build passes. + +Before/after960×720 llvmpipe model captures show the horizontal reflection; +mirroring the old image matches the corrected view to under.0012 mean intensity +per RGB channel, versus2.68–4.77 without reflection. Both runs enable Vulkan +validation and report zero errors. Captures were inspected. The two-frame lab +gameplay readbacks before/after are byte-identical with the same copied assets. +Generated evidence: artifacts/orbit-camera/{projection.log,build.log,before.log, +after.log,comparison.log,comparison.png,gameplay-before.log,gameplay-after.log}. +The first test compile had an ambiguous target-typed Vector4 overload; specifying +Vector4 fixed it before validation. Package/native window results follow after +rebuild; native Windows remains a separate runtime check. diff --git a/docs/progress.md b/docs/progress.md index 77cf243..564b7a6 100644 --- a/docs/progress.md +++ b/docs/progress.md @@ -1,5 +1,17 @@ # Progress — 2026-11-03 +## Orbit camera reflection correction + +The modern inspector paired a right-handed view/perspective with source scenes +whose gameplay cameras use positive-Z left-handed space. This mirrored the world +on switching camera modes. OrbitCamera now supplies the matching left-handed +view/projection and retains the shared single Vulkan Y correction.36 camera/ +aspect matrix cases pass plus existing35-level projection checks. Before/after +GPU captures confirm the removed reflection; lab gameplay captures remain +byte-identical. Main build passes. Native/package evidence is recorded in +[orbit-camera.md](orbit-camera.md). This is a port camera fix, not new original +runtime evidence. + ## Rocketship wall-impact correction User Windows testing exposed wild ship scaling on wall hits. The initial port diff --git a/docs/rendering.md b/docs/rendering.md index 6bb3c30..15d4449 100644 --- a/docs/rendering.md +++ b/docs/rendering.md @@ -3,6 +3,10 @@ Original API and state maps: `analysis/graphics.md`. Mesh/material/texture formats: `file-formats.md`. Vulkan code: `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`. +Modern orbit inspection uses gameplay's positive-Z left-handed view/perspective +and the same single Vulkan viewport Y correction. The former right-handed pair +mirrored the scene when changing modes; regression and GPU proof: orbit-camera.md. + Default prepared LV1B view uses the GAM STARTEXP camera; positive-Z projection uses recovered FOV `0xAAA/16384*360` degrees, near 20, far 10000. Generic engine far default is 3200; other scene-specific overrides remain to be mapped. Camera diff --git a/docs/tasks.md b/docs/tasks.md index c5b85ba..c63f06a 100644 --- a/docs/tasks.md +++ b/docs/tasks.md @@ -46,6 +46,9 @@ compile, runtime and original-fidelity verification are separate. ## Immediate continuation +- [x] Correct orbit inspection's mirrored world: share gameplay handedness, + verify36 angle/elevation/aspect cases, GPU reflection and unchanged gameplay. + - [x] Correct user-reported Rocketship wall scaling: recover material RGBA consumer, replace geometry deformation with red damage flash, regress actual wall contact/per-vertex geometry/color through repeated impacts and expiry. diff --git a/src/GamePort/Application/OrbitCamera.cs b/src/GamePort/Application/OrbitCamera.cs new file mode 100644 index 0000000..4fcc2dd --- /dev/null +++ b/src/GamePort/Application/OrbitCamera.cs @@ -0,0 +1,22 @@ +using System.Numerics; + +namespace GamePort.Application; + +/// Inspection camera in the same positive-Z view space as gameplay. +/// Caller applies the Vulkan viewport Y flip to Projection exactly once. +public readonly record struct OrbitCamera(Vector3 Eye, Matrix4x4 View, Matrix4x4 Projection) +{ + public static OrbitCamera Create(Vector3 target, float radius, float angle, float elevation, float aspect) + { + if (!float.IsFinite(target.X) || !float.IsFinite(target.Y) || !float.IsFinite(target.Z) + || !float.IsFinite(radius) || radius < .01f || !float.IsFinite(angle) + || !float.IsFinite(elevation) || MathF.Abs(elevation) >= MathF.PI / 2 + || !float.IsFinite(aspect) || aspect <= 0) + throw new ArgumentOutOfRangeException(nameof(radius), "A finite orbit outside the poles and positive viewport are required"); + var eye = target + radius * new Vector3(MathF.Cos(elevation) * MathF.Sin(angle), + MathF.Sin(elevation), MathF.Cos(elevation) * MathF.Cos(angle)); + return new(eye, Matrix4x4.CreateLookAtLeftHanded(eye, target, Vector3.UnitY), + Matrix4x4.CreatePerspectiveFieldOfViewLeftHanded(MathF.PI / 3, aspect, + Math.Max(radius / 10000, .01f), radius * 20)); + } +} diff --git a/src/GamePort/Program.cs b/src/GamePort/Program.cs index 38ffc4b..ea589bc 100644 --- a/src/GamePort/Program.cs +++ b/src/GamePort/Program.cs @@ -1231,11 +1231,11 @@ internal static class Program if (keys.Contains(45) || keys.Contains(86)) radius *= MathF.Exp(dt); } radius = Math.Max(radius, 0.01f); - var eye = target + radius * new Vector3(MathF.Cos(elevation) * MathF.Sin(angle), - MathF.Sin(elevation), MathF.Cos(elevation) * MathF.Cos(angle)); + var orbit = OrbitCamera.Create(target,radius,angle,elevation,(float)renderer.Width / renderer.Height); + var eye = orbit.Eye; var view = originalCamera ? Matrix4x4.CreateLookAtLeftHanded(originalStart!.CameraPosition, originalStart.Position + new Vector3(0, 80, 0), Vector3.UnitY) - : Matrix4x4.CreateLookAt(eye, target, Vector3.UnitY); + : orbit.View; var renderEye = originalCamera ? originalStart!.CameraPosition : eye; var renderTarget = originalCamera ? originalStart!.Position + new Vector3(0,80,0) : target; if (simulation != null && !inspecting) @@ -1318,7 +1318,7 @@ internal static class Program viewportWidth: renderer.Width, viewportHeight: renderer.Height); var projection = gameplayProjection ? SceneProjection.CreateGameplay(level?.Code, (float)renderer.Width / renderer.Height) - : Matrix4x4.CreatePerspectiveFieldOfView(MathF.PI / 3, (float)renderer.Width / renderer.Height, Math.Max(radius / 10000, 0.01f), radius * 20); + : orbit.Projection; projection.M22 *= -1; if (animations != null) { diff --git a/tests/GamePort.ProjectionTests/GamePort.ProjectionTests.csproj b/tests/GamePort.ProjectionTests/GamePort.ProjectionTests.csproj index 4352f23..9de0b35 100644 --- a/tests/GamePort.ProjectionTests/GamePort.ProjectionTests.csproj +++ b/tests/GamePort.ProjectionTests/GamePort.ProjectionTests.csproj @@ -3,6 +3,7 @@ + diff --git a/tests/GamePort.ProjectionTests/Program.cs b/tests/GamePort.ProjectionTests/Program.cs index aa9c311..cc55c13 100644 --- a/tests/GamePort.ProjectionTests/Program.cs +++ b/tests/GamePort.ProjectionTests/Program.cs @@ -64,6 +64,35 @@ Require(recovered > 100, "Actual outside geometry must demonstrate the old arbit Console.WriteLine($"PASS actual LEV1 source view retains{recovered} vertices formerly beyond the incorrect3200 far plane"); Console.WriteLine("Projection recovery is statically verified; original-game visual comparison and per-layer/fog fidelity remain separate."); +//The modern inspector must preserve gameplay's screen directions instead of +//reflecting the original left-handed scene through a right-handed camera. +foreach(var aspect in new[]{4f/3,16f/9,21f/9}) +foreach(var angle in new[]{0,MathF.PI/2,MathF.PI,MathF.PI*1.5f}) +foreach(var elevation in new[]{-.7f,0,.7f}) +{ + var target=new Vector3(123,456,-789); + const float radius=600; + var orbit=OrbitCamera.Create(target,radius,angle,elevation,aspect); + var forward=Vector3.Normalize(target-orbit.Eye); + var right=Vector3.Normalize(Vector3.Cross(Vector3.UnitY,forward)); + var up=Vector3.Cross(forward,right); + var projection=orbit.Projection;projection.M22*=-1; + Vector3 Screen(Vector3 point) + { + var clip=Vector4.Transform(new Vector4(point,1),orbit.View*projection); + Require(clip.W>0,"Orbit target lies in front of positive-Z view"); + return new(clip.X/clip.W,clip.Y/clip.W,clip.Z/clip.W); + } + var center=Screen(target);var screenRight=Screen(target+right*40);var screenUp=Screen(target+up*40); + Require(MathF.Abs(center.X)<.00001f&&MathF.Abs(center.Y)<.00001f,"Orbit target stays centered"); + Require(screenRight.X>center.X&&screenUp.Y