Following a person into a vehicle loses the person after disembark

[mayor-modder]

Problem

When following a person who enters a vehicle, the mod can switch to following the vehicle itself and fail to resume following the original person after they disembark.

Observed behavior

• Follow a person in first person.
• The person boards a car, train, or bus.
• The camera follows the vehicle while they are riding.
• After the person disembarks, the camera can remain attached to the vehicle.

Initial code evidence

EntityFollower.Filter() mutates CameraDataModel.FollowEntity from the user-selected person to CurrentTransport or CurrentVehicle. That appears to lose the distinction between the selected subject and the per-frame camera attachment target. The current disembark recovery relies on a narrow ResidentFlags.Disembarking check against LastFollowEntity, which can miss the handoff.

Likely files:

• EntityFollower.cs
• DataModels/CameraDataModel.cs
• Transformer/CameraTransformer.cs

Acceptance criteria

• The selected follow subject remains stable when a person enters a vehicle.
• The camera can attach to the ridden vehicle for position/rotation while preserving the person as the logical target.
• After disembark, the camera naturally resumes following the person.
• Follow behavior works for car, bus, train, and subway boarding/disembark scenarios.

[mayor-modder]

Investigation note

The current follow model appears to conflate two different concepts:

• the user-selected follow subject, such as a cim;
• the resolved camera attachment target, such as the vehicle that cim is currently riding.

The likely failure path is:

1. OrbitCameraController_FollowedEntityPatch.OnFollowChanged stores the selected entity in CameraDataModel.FollowEntity and also copies it to LastFollowEntity.
2. EntityFollower.TryGetPosition() calls Filter() every frame.
3. Filter() mutates CameraDataModel.FollowEntity when it sees TargetElement, CurrentTransport, CurrentVehicle, or current-building components.
4. When a followed cim boards a vehicle, FollowEntity becomes the vehicle. This bypasses OnFollowChanged, so follow-mode bookkeeping and scope do not get a clean transition event.
5. After that frame, GetFollowEntity() returns the vehicle to UI/PiP systems. The original cim only remains in LastFollowEntity.
6. Returning to the cim depends on catching ResidentFlags.Disembarking on LastFollowEntity. If that narrow flag is missed, the logical follow target remains the vehicle.

Relevant files:

• EntityFollower.cs: Filter() mutates CameraDataModel.FollowEntity.
• Transformer/CameraTransformer.cs: OnFollowChanged treats FollowEntity as the stable logical target and updates LastFollowEntity only when the orbit setter fires.
• MonoBehaviours/FirstPersonCameraController.cs: GetFollowEntity() exposes the mutated field to other systems.
• Systems/FirstPersonCameraActivatedUISystem.cs and Systems/FirstPersonCameraPIPSystem.cs: consumers currently call GetFollowEntity() and may need either the selected subject or the resolved camera target depending on behavior.

Hypothesis: issue #2 is caused by using one mutable FollowEntity field for both selected subject and resolved attachment target. The fix should preserve the selected subject separately, resolve a per-frame camera target without mutating that subject, and expose clear accessors for both semantics.

Potential fix shape:

• Add separate model state for the selected follow subject and the resolved camera target.
• Change EntityFollower from Filter() mutating model state to a pure-ish resolver that returns the best camera target for the current frame.
• Recompute scope/vehicle type from the resolved target, while preserving the selected subject for disembark recovery.
• Audit consumers of GetFollowEntity() and update each to use either selected subject or resolved target intentionally.

Docs context: the CS2 wiki describes entities as component containers and recommends classifying entities by component sets. That supports resolving a frame-local attachment target from components without overwriting the user-selected entity.