[FEATURE] Expose NPC vehicle entry and exit events

[ifBars]

What would you like to see?

Add managed NPC vehicle lifecycle events:

• OnEnterVehicle(LandVehicle vehicle)
• OnExitVehicle(LandVehicle vehicle)

Why would this help?

NPC behavior, quest, traffic, and vehicle mods need to react when an NPC enters or exits a vehicle. Today they must subscribe to native delegates directly.

Extra Context (Optional)

The native onEnterVehicle and onExitVehicle delegates still exist in Mono and IL2CPP, and S1API already has a LandVehicle wrapper. Preserve the native event timing and clean up runtime-specific delegate bridges safely.

[ifBars]

@Diffuin Create an implementation plan for this

[diffuin]

Implementation plan

Summary

Plan an additive NPC API that forwards the native vehicle callbacks through cached per-wrapper bridges and the existing LandVehicle conversion. The Mono field contract is confirmed, while the IL2CPP generated delegate shape and live callback timing require verification before merge.

Design decisions

1. Add public documented event Action members named OnEnterVehicle and OnExitVehicle to S1API.Entities.NPC. Dispatch each supplied native vehicle through new LandVehicle(nativeVehicle), matching the existing CurrentVehicle conversion path.
2. Use lazy, per-NPC cached native dispatchers. Mono subscribes directly; IL2CPP uses DelegateSupport.ConvertDelegate and Il2CppSystem.Delegate combine/remove so removal and teardown target the same delegate instance.
3. Do not add persistence, networking, reflection, Harmony patches, or fallback lookup. The managed events mirror native callback delivery, including its observer-side timing.

Implementation

1. Verify the runtime seam — Confirm the exact native contract before writing the dual-runtime bridge.
   • Inspect user-owned Mono and generated IL2CPP NPC wrappers for both delegate fields, their parameter types, and callback order relative to CurrentVehicle. (S1API/Entities/NPC.cs)
   • Confirm that the IL2CPP field can be combined and removed with a cached Il2CppSystem.Action. (S1API/Entities/NPC.cs)
2. Expose the managed events — Add the narrow public API and dispatch native arguments through S1API wrappers.
   • Add XML-documented OnEnterVehicle and OnExitVehicle events plus managed handler storage and native dispatch methods. (S1API/Entities/NPC.cs)
   • Create cached Mono and IL2CPP delegate bridges, subscribe only while handlers exist, and wrap the callback vehicle directly. (S1API/Entities/NPC.cs)
3. Clean up lifecycle hooks — Prevent retained delegates and duplicate callbacks across destruction or scene changes.
   • Detach both native bridges when the last managed handler is removed and from CleanupRuntimeHooks. (S1API/Entities/NPC.cs)
   • Run NPC runtime-hook cleanup before scene-state clearing destroys and removes NPC wrappers. (S1API/Internal/Lifecycle/SceneStateCleaner.cs)
   • Record the compatibility audit: the change is additive; existing source, binary, behavioral, save, and network contracts remain unchanged. (S1API/Entities/NPC.cs)
4. Validate both targets — Compile the public surface and confirm native timing in supported game runtimes.
   • Restore, build, and test MonoMelon and Il2CppMelon using the repository commands. (S1API.sln, S1API.Tests/S1API.Tests.csproj)
   • In Mono and IL2CPP, subscribe, enter, exit, unsubscribe, and destroy an NPC; verify one callback per native invocation and the vehicle argument. (S1API/Entities/NPC.cs)
   • On a host and remote client, verify native observer delivery without S1API-generated network messages or persisted event state. (S1API/Entities/NPC.cs)

Implementation gates

• The stripped Mono source establishes fields and method signatures but not invocation order. Inspect the generated IL2CPP wrapper and test whether each callback fires before or after CurrentVehicle changes, then document the observed native timing without altering it.

Evidence and validation

Evidence inspected

• Issue [FEATURE] Expose NPC vehicle entry and exit events #243 requests OnEnterVehicle(LandVehicle) and OnExitVehicle(LandVehicle) without changing native behavior.
• Regular and beta Mono stripped NPC declarations expose onEnterVehicle and onExitVehicle as Action; vehicle entry and exit are networked native methods.
• S1API.Entities.NPC already wraps CurrentVehicle with the internal LandVehicle constructor and contains TODOs for these two missing vehicle events.
• NPCMessaging and NPCRelationship retain converted IL2CPP delegates, remove the exact cached delegate, and expose cleanup through NPC.CleanupRuntimeHooks.

Validation performed

• Read the Schedule One modding, issue-planning, and clarity guidance.
• Inspected issue [FEATURE] Expose NPC vehicle entry and exit events #243, the relevant S1API wrappers and lifecycle cleanup, and regular/beta Mono stripped declarations.
• Checked the working tree and diff formatting; neither has local changes.
• No repository build ran because dotnet is unavailable in this environment.

Runtime validation remaining

• Run restore, build, and test for MonoMelon and Il2CppMelon after a .NET SDK and local game references are available.
• Human runtime validation is required for Mono and IL2CPP vehicle entry/exit timing, unsubscription, NPC destruction, scene transitions, and host/client observation.

• Create a pull request to implement this plan and close this issue when merged.

Diffuin run details

• Provider: codex
• Model: gpt-5.6-terra
• Reasoning: high (Luna advisor: risk (high); baseline source-backed technical request)
• Elapsed: 257s
• Codex thread: 019ff8df-42b8-7352-a4c2-131a9dfda389

---

AI notice: Generated with AI assistance and not guaranteed accurate. Verify findings and plans against the current source and runtime.

[diffuin]

I opened #267