mirror of
https://github.com/isledecomp/isle-portable.git
synced 2026-05-03 11:04:04 +00:00
fe5ef4f9a5
* Fix 180-degree camera flip when exiting sub-worlds without cam anim When returning from sub-worlds (jukebox, hospital exterior, etc.) with 3rd person camera active, the camera/player flipped 180 degrees. This happened because SpawnPlayer calls Enter() → TurnAround() before PlaceActor(), and PlaceActor overwrites the ROI direction with the path's standard convention (z = forward). For spawn points with cam anims, OnCamAnimEnd corrected this, but spawn points with m_location=0 (like jukebox exterior) had no correction. Replace m_roiUnflipped with m_needsDirectionFlip flag that tracks world transitions. OnWorldEnabled sets the flag, and the first Tick after PlaceActor completes flips the ROI to backward-z and re-setups the camera. ReinitForCharacter now always flips the ROI direction, handling both Disable→Enable toggles and enabling 3rd person after a 1st-person spawn. https://claude.ai/code/session_01NQ9vy9Qr3aH6LNsRNLEEtY * Fix camera flip regressions for vehicle exit and world transitions The unconditional ROI flip in ReinitForCharacter caused a 180-degree flip when exiting vehicles (Enter's TurnAround follows and double-flips). Restore conditional flip using m_roiUnflipped, but now also set it in OnWorldEnabled (even when disabled) so cold-enabling 3rd person after a world transition correctly flips from PlaceActor's forward-z. Key changes: - Remove m_roiUnflipped clearing from OnActorEnter: Enter() is always followed by PlaceActor which overwrites the ROI, so clearing the flag prematurely caused the cold-enable case to miss the needed flip. - Add orbit camera override in OnActorEnter during world transitions (m_needsDirectionFlip && m_active) to suppress the 1st-person camera flash from Enter's TransformPointOfView. - Clear m_roiUnflipped in OnCamAnimEnd alongside m_needsDirectionFlip, since the cam anim's PlaceActor + flip handles the correction. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Defer orbit camera setup during world transition loading freeze Remove the premature SetupCamera call from OnActorEnter's world transition path. The stale orbit camera view (computed before PlaceActor runs) would freeze on screen during the ~500ms world load, appearing as a wrong-direction flash. The Tick correction after PlaceActor now handles the initial orbit camera setup at the correct position. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Skip orbit camera while cam anim is running to prevent actor glitch When a cam anim plays with 3rd-person camera active, ApplyOrbitCamera was fighting the cam anim each frame. If the cam anim was interrupted (space bar), its end handler read the ViewROI position — which was set by our orbit camera (elevated, behind player) — and placed the actor at that position, causing it to glitch into the air. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add documentation for ROI direction conventions and camera corrections Documents the forward-z vs backward-z conventions, all code paths that require direction correction, and the flags that coordinate them. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Refactor 3rd-person camera from backward-z to forward-z convention Switch the orbit camera to use forward-z (matching PlaceActor's native output), eliminating all FlipROIDirection/TurnAround corrections. The display clone flips to backward-z when syncing from the native ROI so character meshes face correctly. Use actor state (c_disabled) instead of m_animRunning to guard against cam anim conflicts, allowing the orbit camera to resume as soon as the player is released. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Reset orbit camera position on world re-entry Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Remove ShouldInvertMovement and update documentation * Remove header
98 lines
4.1 KiB
Markdown
98 lines
4.1 KiB
Markdown
# ROI Direction Conventions & Third-Person Camera
|
||
|
||
## Background: The Two Z-Axis Conventions
|
||
|
||
The game engine represents an actor's facing direction via the z-axis of its ROI
|
||
(Real-time Object Instance) local-to-world transform. Two opposite conventions
|
||
exist throughout the codebase:
|
||
|
||
| Convention | ROI z-axis points... | Used by |
|
||
|----------------|--------------------------|--------------------------------------------------------|
|
||
| **forward-z** | Toward visual forward | `PlaceActor` (with `m_cameraFlag=TRUE`), cam anim end |
|
||
| **backward-z** | Away from visual forward | After `Enter()`'s `TurnAround()`, vehicle ROIs |
|
||
|
||
Toggling between conventions is done by `IslePathActor::TurnAround` (or the
|
||
local `FlipMatrixDirection` helper): negate the z-axis and recompute the right
|
||
vector.
|
||
|
||
## Design Choice: Forward-Z
|
||
|
||
The third-person orbit camera uses **forward-z**, matching the convention that
|
||
`PlaceActor` naturally produces. This eliminates the need to flip the ROI
|
||
direction after every `PlaceActor` call.
|
||
|
||
`ComputeOrbitVectors` treats local Z+ as the character's visual forward and
|
||
places the camera at local −Z (behind the character), looking toward +Z.
|
||
|
||
## Engine Behavior
|
||
|
||
The engine's actor lifecycle:
|
||
|
||
```
|
||
Enter()
|
||
→ ResetWorldTransform(TRUE) sets m_cameraFlag = TRUE
|
||
→ TurnAround() flips to backward-z
|
||
→ TransformPointOfView() sets 1st-person camera
|
||
|
||
PlaceActor() resets to forward-z ← what we use
|
||
```
|
||
|
||
`PlaceActor` always produces forward-z (when `m_cameraFlag=TRUE`), which is
|
||
exactly what the orbit camera expects. No direction correction is needed after
|
||
`PlaceActor` runs.
|
||
|
||
## World Transition Timing
|
||
|
||
The one remaining complexity is timing during world transitions. The event order
|
||
is:
|
||
|
||
1. `OnWorldEnabled` fires (from `LegoWorld::Enable`, BEFORE `SpawnPlayer`)
|
||
2. `ReinitForCharacter` sets up the display ROI and marks `m_active = true`
|
||
3. `Enter()` fires `OnActorEnter` — ROI is at **stale position** from previous session
|
||
4. `PlaceActor` sets ROI to correct spawn position
|
||
5. First `Tick` — `ApplyOrbitCamera` sets the camera at the correct position
|
||
|
||
Between steps 3 and 5, the ROI position is stale. If we set up the orbit camera
|
||
in step 3, the stale view would freeze on screen during the ~500ms world load.
|
||
|
||
The `m_pendingWorldTransition` flag handles this: set in `OnWorldEnabled`,
|
||
it causes `OnActorEnter` and `ReinitForCharacter` to skip camera setup.
|
||
Cleared in the first `Tick` after `PlaceActor`, where `ApplyOrbitCamera`
|
||
naturally handles the camera. The orbit state (yaw, pitch, distance) is also
|
||
reset to defaults in `OnWorldEnabled`.
|
||
|
||
## Display Clone Direction
|
||
|
||
The native actor ROI is invisible in 3rd-person mode. A display clone renders
|
||
the character model instead. Character meshes face −z, so the clone needs
|
||
backward-z to look correct. When syncing the clone's transform from the native
|
||
ROI (which is in forward-z), `Tick` negates the z-axis and recomputes the right
|
||
vector — the same operation as `TurnAround`.
|
||
|
||
This also affects the right vector (X-axis): forward-z and backward-z produce
|
||
opposite right vectors. The orbit yaw input is negated to compensate, keeping
|
||
drag-right = camera-moves-right.
|
||
|
||
## Cam Anim Interaction
|
||
|
||
While a cam anim locks the player (`GetActorState() == c_disabled`), two
|
||
things protect the orbit camera:
|
||
|
||
1. **Tick guard**: `ApplyOrbitCamera` is skipped so it doesn't fight the cam
|
||
anim's `TransformPointOfView`. Without this, the cam anim end handler would
|
||
read our elevated orbit camera position and place the actor in the air.
|
||
|
||
2. **`OnCamAnimEnd`**: When the cam anim releases the player (first space bar
|
||
interruption or natural end), this callback calls `SetupCamera` to restore
|
||
the orbit camera.
|
||
|
||
After the first interruption, the actor state resets to `c_initial` and the
|
||
orbit camera resumes immediately — even if `m_animRunning` is still true for
|
||
background animations playing in the world.
|
||
|
||
## Network Direction
|
||
|
||
The network protocol sends forward-z direction (visual forward). Remote players
|
||
negate the received direction to backward-z for their ROI, since character meshes
|
||
face −z.
|