Fixed Camera Authoring (proposal)¶
Status: unimplemented as of 2026-04-24. Write-up of pain we hit during "The Monitor" jam game so the next time someone needs N fixed cameras in a scene, the authoring path is a single click in Godot, not three rounds of PSX-frame math debugging.
What we hit¶
Authoring the 4 CCTV camera positions for monitor.tscn cost roughly an
afternoon of debugging purely in coordinate-conversion gotchas:
-
Camera.SetPositiontakes raw PSX coords. Mesh verts get/GteScalingand Y/Z flipped at export (PSXMesh.cs:221-226), but Lua camera coords pass through unchanged (luaapi.cpp:1536-1545). Authoring a cam at the Godot-world position next to a mesh dropped the cam 60 units away from the geometry. Everything renders fine — just way off-screen. Seeproject_camera_lua_coord_frame.mdmemory. -
Camera.LookAtis a no-op stub. The runtime reads the target vector, computes nothing useful, and returns. The IDE brief shipped describing it as a working API. Workaround was hand-computingpitch = atan2(Δy, h)/πandyaw = atan2(Δx, Δz)/π. Seeproject_camera_lookat_stub.md. -
Pitch sign is inverted vs intuition. psyqo's
rotXmatrix (pcsx-redux-main/src/mips/psyqo/src/soft-math.cpp:32) makes positive pitch tilt the camera up in PSX-Y-down world space. The naturalatan2(dy_psx, h)/πformula gives the opposite of the right answer when the cam sits above the floor and you want it to look down at the floor. Spent the bulk of the debugging session on a black-screen feed because the floor was projected tosy=225— one pixel inside the bottom CRT bezel. Seeproject_camera_pitch_sign.md. -
No editor preview of the runtime camera frustum. A Godot
Camera3Dnode can show a preview gizmo — but it shows the Godot projection, not the PSX one. There's no way to confirm framing without exporting and running PCSX-Redux. Each iteration was 30+ seconds.
These are 4 separate paper cuts that compound. Doing the math on paper with a clear head is mostly tractable. Doing it twice while three other things are also broken is brutal.
What we want¶
A PS1FixedCamera Node3D that authors place visually in Godot world space
and configure with normal Godot conventions (look at a target, set FOV).
The exporter bakes presets into the splashpack with the conversion +
correct sign math built in. Lua just says "use preset N" or "use preset
'hallway'."
Authoring shape¶
# PS1FixedCamera.cs (Tool-mode, lives next to PS1Room.cs)
[ExportGroup("Identity")]
[Export] public string PresetName { get; set; } = "";
[ExportGroup("Aim")]
// Optional Node3D the cam looks at. If unset, exporter uses the cam's
// own -Z basis (Godot convention) so authors can rotate the node in the
// editor and see a live frustum gizmo.
[Export] public Node3D LookAtTarget { get; set; }
[ExportGroup("Projection")]
[Export(PropertyHint.Range, "1,1024,1")] public int ProjectionH { get; set; } = 120;
[ExportGroup("Behavior")]
// Optional shake to fire on Camera.LoadPreset, in raw fp12 + frame count.
[Export] public int LoadShakeIntensity { get; set; } = 80;
[Export] public int LoadShakeFrames { get; set; } = 4;
The node renders a wireframe frustum gizmo using ProjectionH directly so
the author can see in the Godot viewport exactly what the cam will see at
runtime — same FOV, same aspect.
Exporter¶
SceneCollector.CollectCameras(...) walks the tree for PS1FixedCamera
nodes. For each, it computes:
pos_psx = (gtx.X / GteScaling, -gtx.Y / GteScaling, -gtx.Z / GteScaling)
if LookAtTarget != null:
target_psx = same conversion applied to LookAtTarget.GlobalPosition
delta = target_psx - pos_psx
horiz = sqrt(delta.x^2 + delta.z^2)
yaw_pi = atan2(delta.x, delta.z) / π
pitch_pi = -atan2(delta.y, horiz) / π # ← negate to fix the sign
else:
# Read Godot Camera3D-style basis. Godot looks -Z; PSX looks +Z;
# that's the Y/Z flip handling the orientation.
fwd_godot = -gtx.basis.Z
fwd_psx = (fwd_godot.x, -fwd_godot.y, -fwd_godot.z)
yaw_pi = atan2(fwd_psx.x, fwd_psx.z) / π
pitch_pi = -atan2(fwd_psx.y, sqrt(fwd_psx.x^2 + fwd_psx.z^2)) / π
Bake (pos_psx, pitch_pi, yaw_pi, projH, presetName, shakeIntensity,
shakeFrames) into a new CameraPresetRecord. Bump splashpack version,
add a cameraPresetOffset + cameraPresetCount to the header, append a
CameraPresetRecord[] block.
Runtime (psxsplash side)¶
A new Camera.LoadPreset(name_or_index) Lua API:
int LuaAPI::Camera_LoadPreset(lua_State* L) {
psyqo::Lua lua(L);
if (!s_sceneManager) return 0;
const CameraPresetRecord* preset = nullptr;
if (lua.isString(1)) {
preset = s_sceneManager->findCameraPresetByName(lua.toString(1));
} else if (lua.isNumber(1)) {
preset = s_sceneManager->getCameraPreset((int)lua.toNumber(1));
}
if (!preset) return 0;
auto& cam = s_sceneManager->getCamera();
cam.SetPosition(preset->posX, preset->posY, preset->posZ);
cam.SetRotation(preset->pitch, preset->yaw, {0});
cam.SetH(preset->projH);
if (preset->shakeFrames > 0) {
psyqo::FixedPoint<12> intensity;
intensity.value = preset->shakeIntensity;
cam.Shake(intensity, preset->shakeFrames);
}
return 0;
}
Author code shrinks dramatically¶
Today (~30 lines for FEEDS table with manual conversion + sign-corrected pitch/yaw + ShakeRaw):
FEEDS = {
{ name = "HALLWAY", camPos = Vec3.new(-20, -0.625, 0.25),
pitch = 0.03, yaw = 0, projH = 120 },
-- … 3 more entries with hand-computed PSX coords …
}
local function switchToFeed(n)
local feed = FEEDS[n]
Camera.SetPosition(feed.camPos)
Camera.SetRotation(Vec3.new(feed.pitch, feed.yaw, 0))
Camera.SetH(feed.projH)
Camera.ShakeRaw(80, 4)
-- …
end
After:
local FEED_PRESETS = { "hallway", "storage", "parking", "back_room" }
local function switchToFeed(n)
Camera.LoadPreset(FEED_PRESETS[n])
-- …
end
The author authored the 4 cameras in the 3D viewport with Godot's normal gizmo + preview flow. Zero PSX-frame math. Zero pitch-sign gotchas. The black-screen-because-floor-is-one-pixel-below-bezel debugging episode does not happen.
Migration path¶
- Land
PS1FixedCamera.csalongsidePS1Room.cs/PS1Camera.cs. Tool-mode, gizmo, no runtime side yet. - Exporter: add
CollectCameras+CameraPresetRecordwriter behind a feature flag. Bump splashpack version when the writer side ships. - Runtime: add
Camera.LoadPreset+ the splashpack reader changes in psxsplash. Could land as a single PR;psxsplash-improvements.mdhas the upstream channel discussion. - Migration: for
monitor.tscn, replace theFEEDStable with 4PS1FixedCameranodes + a 4-entry array of preset names. Validate parity against the current hand-tuned framing before deleting the conversion math fromfeed_manager.lua.
Until then¶
Document the gotchas everywhere a fresh user is likely to look:
- docs/projects/the-monitor/the-monitor-ide-brief.md ← already patched (2026-04-24)
- docs/api-showcase.md if/when it covers Camera APIs
- docs/lua-ps1-cheatsheet.md ← TODO add a "fixed CCTV cams" recipe block
- Tool memories: project_camera_lua_coord_frame.md,
project_camera_lookat_stub.md, project_camera_pitch_sign.md
Out of scope¶
- Cutscene-driven camera tracks — already covered by
PS1Cutscene/PS1Camerabaked tracks (those go through the exporter's coordinate conversion, no manual math required). Fixed cameras are specifically for runtime-switchable preset selection (CCTV games, classic survival horror Resident-Evil-style fixed-cam, dialogue framing presets, etc.). - Smooth camera blends between presets — interesting but separate. V1 is "snap to preset on Camera.LoadPreset"; smooth blends can come later.