mirror of https://github.com/isledecomp/isle-portable.git synced 2026-05-01 18:13:57 +00:00

* Add multiplayer extension

* Fix animation system to work when host is outside ISLE world

- Move TickHostSessions outside m_inIsleWorld gate so the host can
  coordinate animations from any world
- Load animation catalog early in HandleCreate so the host can
  coordinate before entering the ISLE world
- Use network-reported positions for remote player location detection
  instead of requiring spawned ROIs
- Always erase sessions at launch — the host's job ends when the
  animation starts; clients play and complete independently
- Replace BroadcastAnimComplete with locally-driven completion
  callbacks: host generates eventId at launch, clients cache
  completion JSON at start time, fire it when ScenePlayer finishes
- Make StopAnimation only do local cleanup (stop playback, cancel
  own interest, reset coordinator) without destroying the session
  host, so other players' sessions survive world transitions
- Broadcast state=0 in ResetAnimationState for full teardown paths
  (shutdown, reconnect, host migration) so clients aren't left with
  stale session state

* Fix use-after-free crash in ScenePlayer when remote player disconnects mid-animation

When a remote player's ROI is destroyed (disconnect, timeout, or respawn),
notify all active ScenePlayer instances to null out dangling references
before the ROI is freed. The animation engine already handles null ROI map
entries gracefully, so playback continues for remaining participants.

* Fix crash when performer's child ROIs are left dangling in ScenePlayer

NotifyROIDestroyed now walks the parent chain to also invalidate child
ROIs of the destroyed performer (head, limbs, etc.) that were placed
into the roiMap by BuildROIMap. The ancestor walk happens once; all
other fields are cleaned with simple pointer equality.

* Allow spectator to play click animation during scene playback

* Make PTATCAM track spectator ROI instead of camera in ScenePlayer

* Only regenerate emscripten version files when git state changes

Replace add_custom_target(ALL) with add_custom_command(OUTPUT) so the
version script only runs when .git/HEAD or the current branch ref file
changes, instead of on every build.

* Fix ROI name collision causing dangling pointers in NPC locomotion roiMaps

When ScenePlayer created cloned NPC ROIs for cooperative animations, it
renamed them to match the original character name and added them to the
ViewManager. This created a name collision: two ROIs with the same name.
The original game's AppendROIToScene searches by name and stops at the
first match, so if a locomotion BuildROIMap ran while the clone existed,
it could capture pointers to the clone's child ROIs. When the clone was
later destroyed (CleanupProps), those roiMap entries became dangling
pointers, crashing in AnimateWithTransform at roi.h:151 (SetVisibility).

Fix: use the alias mechanism (already supported by AnimUtils::BuildROIMap)
instead of renaming clones. Also unify all ROI name generation behind a
shared counter to prevent character manager key collisions.

2026-04-05 17:13:15 +02:00

3.9 KiB

Raw Blame History

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:

OnWorldEnabled fires (from LegoWorld::Enable, BEFORE SpawnPlayer)
ReinitForCharacter sets up the display ROI and marks m_active = true
Enter() fires OnActorEnter -- ROI is at stale position from previous session
PlaceActor sets ROI to correct spawn position
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:

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.
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.

3.9 KiB Raw Blame History