Fix orbit camera mirroring by matching gameplay handedness

This commit is contained in:
UnixNight committed 2026-11-03 17:38:48 -05:00
1 parent 1b679c641a
commit d8f1b51c86
10 files changed
+125 -4

No files matched your search

+6
View File
@@ -3,6 +3,12 @@
Compilation, native runtime, original behavior and full feature completion are Compilation, native runtime, original behavior and full feature completion are
separate evidence categories. **The game is not fully reconstructed/playable yet.** 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 Rocketship impact follow-up: corrected first-material red-flash RGBA previously
misapplied to ship scale.13 managed groups include actual wall contact plus130 misapplied to ship scale.13 managed groups include actual wall contact plus130
frames of unchanged geometry, correct ship-only tint, recovery and repeated frames of unchanged geometry, correct ship-only tint, recovery and repeated
+6
View File
@@ -264,3 +264,9 @@
actual DLL renderer consumers now guard the contract. Use a ship-only red 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. material flash with unit geometry; regress vertex positions as well as values.
See gameplay/rocketship-impact-render.md. 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.
+38
View File
@@ -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.
+12
View File
@@ -1,5 +1,17 @@
# Progress — 2026-11-03 # 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 ## Rocketship wall-impact correction
User Windows testing exposed wild ship scaling on wall hits. The initial port User Windows testing exposed wild ship scaling on wall hits. The initial port
+4
View File
@@ -3,6 +3,10 @@
Original API and state maps: `analysis/graphics.md`. Mesh/material/texture formats: Original API and state maps: `analysis/graphics.md`. Mesh/material/texture formats:
`file-formats.md`. Vulkan code: `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`. `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 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 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 far default is 3200; other scene-specific overrides remain to be mapped. Camera
+3
View File
@@ -46,6 +46,9 @@ compile, runtime and original-fidelity verification are separate.
## Immediate continuation ## 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 - [x] Correct user-reported Rocketship wall scaling: recover material RGBA
consumer, replace geometry deformation with red damage flash, regress actual consumer, replace geometry deformation with red damage flash, regress actual
wall contact/per-vertex geometry/color through repeated impacts and expiry. wall contact/per-vertex geometry/color through repeated impacts and expiry.
+22
View File
@@ -0,0 +1,22 @@
using System.Numerics;
namespace GamePort.Application;
/// <summary>Inspection camera in the same positive-Z view space as gameplay.
/// Caller applies the Vulkan viewport Y flip to Projection exactly once.</summary>
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));
}
}
+4 -4
View File
@@ -1231,11 +1231,11 @@ internal static class Program
if (keys.Contains(45) || keys.Contains(86)) radius *= MathF.Exp(dt); if (keys.Contains(45) || keys.Contains(86)) radius *= MathF.Exp(dt);
} }
radius = Math.Max(radius, 0.01f); radius = Math.Max(radius, 0.01f);
var eye = target + radius * new Vector3(MathF.Cos(elevation) * MathF.Sin(angle), var orbit = OrbitCamera.Create(target,radius,angle,elevation,(float)renderer.Width / renderer.Height);
MathF.Sin(elevation), MathF.Cos(elevation) * MathF.Cos(angle)); var eye = orbit.Eye;
var view = originalCamera var view = originalCamera
? Matrix4x4.CreateLookAtLeftHanded(originalStart!.CameraPosition, originalStart.Position + new Vector3(0, 80, 0), Vector3.UnitY) ? 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 renderEye = originalCamera ? originalStart!.CameraPosition : eye;
var renderTarget = originalCamera ? originalStart!.Position + new Vector3(0,80,0) : target; var renderTarget = originalCamera ? originalStart!.Position + new Vector3(0,80,0) : target;
if (simulation != null && !inspecting) if (simulation != null && !inspecting)
@@ -1318,7 +1318,7 @@ internal static class Program
viewportWidth: renderer.Width, viewportHeight: renderer.Height); viewportWidth: renderer.Width, viewportHeight: renderer.Height);
var projection = gameplayProjection var projection = gameplayProjection
? SceneProjection.CreateGameplay(level?.Code, (float)renderer.Width / renderer.Height) ? 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; projection.M22 *= -1;
if (animations != null) if (animations != null)
{ {
@@ -3,6 +3,7 @@
<ItemGroup> <ItemGroup>
<Compile Include="Program.cs"/> <Compile Include="Program.cs"/>
<Compile Include="../../src/GamePort/Application/SceneProjection.cs"/> <Compile Include="../../src/GamePort/Application/SceneProjection.cs"/>
<Compile Include="../../src/GamePort/Application/OrbitCamera.cs"/>
<Compile Include="../../src/GamePort/Assets/*.cs"/> <Compile Include="../../src/GamePort/Assets/*.cs"/>
</ItemGroup> </ItemGroup>
</Project> </Project>
+29
View File
@@ -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($"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."); 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<center.Y,"Orbit preserves gameplay right/up after Vulkan viewport flip");
var inView=Vector3.Transform(target,orbit.View);
Require(MathF.Abs(inView.Z-radius)<.001f,"Orbit view uses gameplay positive-Z forward");
var near=Screen(orbit.Eye+forward*.06f);var far=Screen(orbit.Eye+forward*12000);
Require(MathF.Abs(near.Z)<.003f&&MathF.Abs(far.Z-1)<.00001f,"Orbit near/far retain Vulkan0..1 depth");
}
Console.WriteLine("PASS orbit uses gameplay handedness/right/up/depth across36 camera poses and aspect ratios");
void Bytes(int address, string expected) void Bytes(int address, string expected)
{ {
var bytes = Convert.FromHexString(expected); var bytes = Convert.FromHexString(expected);