[FEATURE] Expose managed NPC awareness events

[ifBars]

What would you like to see?

Expose the native NPC awareness callbacks through managed S1API events:

• drug dealing, general crime, petty crime, curfew violations, and suspicious players noticed
• gunshots and explosions heard
• hit by vehicle

Player and vehicle arguments should use existing S1API wrappers. Noise arguments should use a small read-only snapshot containing origin, range, type, source, and whether the origin is in the sewer.

Why would this help?

Law, stealth, ambient reaction, quest, and NPC behavior mods currently need native UnityEvents or Harmony patches to observe what an NPC notices.

Extra Context (Optional)

All eight native events still exist in current Mono and IL2CPP assemblies. Keep this API observation-only; it should not alter native NPC responses.

[ifBars]

@Diffuin Create an implementation plan for this issue

[diffuin]

Implementation plan

Summary

Add an additive, observation-only NPC awareness event surface and an immutable managed noise snapshot. Mono regular and beta source agree on all eight native callbacks; compilation remains the required proof that the generated IL2CPP wrappers support the same direct bridge.

Design decisions

1. Expose eight additive NPC events named after their native counterparts: OnNoticedDrugDealing, OnNoticedGeneralCrime, OnNoticedPettyCrime, OnNoticedPlayerViolatingCurfew, OnNoticedSuspiciousPlayer, OnGunshotHeard, OnExplosionHeard, and OnHitByCar.
2. Add a read-only NPCNoiseEvent snapshot with Origin, Range, Type, Source, and OriginInSewer. Use a managed NPCNoiseType enum so public signatures do not expose Schedule One types.
3. Bridge the existing native UnityEvents directly through the cross-runtime EventHelper. Convert player and vehicle arguments through existing wrappers, preserve nulls, and do not use reflection, patches, RPCs, or state changes.

Implementation

1. Define the public contract — Add documented, stable managed types and event signatures.
   • Create the read-only NPCNoiseEvent snapshot and NPCNoiseType enum with XML documentation for all five captured values. (S1API/Entities/NPCNoiseEvent.cs)
   • Replace the eight awareness TODOs with documented Action-based events using Player?, LandVehicle?, or NPCNoiseEvent as appropriate. (S1API/Entities/NPC.cs)
2. Bridge native awareness callbacks — Subscribe without changing native callback ownership or behavior.
   • Add per-NPC bridge bookkeeping that subscribes and unsubscribes each native UnityEvent through EventHelper while retaining delegate identity. (S1API/Entities/NPC.cs)
   • Copy noise fields synchronously into the snapshot, resolve Player from Player.All, and wrap LandVehicle directly without constructing fallback objects. (S1API/Entities/NPC.cs)
   • Keep callback delivery local to the native awareness invocation. Do not add save data, network messages, or native-response mutations. (S1API/Entities/NPC.cs)
3. Freeze meaningful managed behavior — Cover the new contract without simulating an unverified Unity runtime.
   • Test snapshot value capture, null Source handling, and managed noise-type conversion through internal test access. (S1API.Tests/Entities/NPCAwarenessApiTests.cs, S1API/Entities/NPCNoiseEvent.cs)
   • Add a compile-only caller fixture that subscribes and unsubscribes all eight event signatures. (S1API.Tests/Entities/NPCAwarenessApiTests.cs, S1API/Entities/NPC.cs)
   • Record the compatibility audit: all changes are additive, with no existing source, binary, behavioral, save, or network contract changed. (S1API/Entities/NPC.cs, S1API/Entities/NPCNoiseEvent.cs)
4. Validate both runtime targets — Prove compilation and identify the required human runtime matrix.
   • Restore, build, and run the S1API test suite for MonoMelon and Il2CppMelon without local deployment. (S1API.sln, S1API.Tests/S1API.Tests.csproj)
   • Run the documentation and target-branch ApiCompat gates used by CI. (S1API/S1API.csproj)
   • In human testing, trigger every callback on vanilla and custom NPCs in regular Mono and IL2CPP, verify wrapper and snapshot values, and confirm native reactions still occur. (S1API/Entities/NPC.cs)
   • In multiplayer, verify callbacks remain local to the peer executing native awareness and do not create replicated or saved state; also exercise an NPC after save/load. (S1API/Entities/NPC.cs)

Implementation gates

• The supplied Mono sources cannot prove the generated IL2CPP UnityEvent wrapper shape. Treat a successful Il2CppMelon build as the implementation gate before finalizing the direct bridge.

Evidence and validation

Evidence inspected

• S1API/Entities/NPC.cs already initializes all eight native awareness UnityEvents and contains matching TODOs for the missing managed events.
• Regular and beta stripped Mono sources declare the same five UnityEvent, two UnityEvent, and one UnityEvent fields on NPCAwareness.
• Both stripped NoiseEvent definitions expose origin, range, ENoiseType, source, and OriginInSewer; ENoiseType currently contains Footstep, Gunshot, and Explosion.
• AssetRipper prefab evidence shows NPCAwareness serializes these callback fields, including a vanilla hit-by-car reaction, so listeners can be added without replacing native responses.

Validation performed

• Read issue [FEATURE] Expose managed NPC awareness events #244 and its available comments through the read-only GitHub broker.
• Inspected the clean checkout with git status and git diff --check.
• Searched target-repository NPC, Player, vehicle, EventHelper, and test patterns.
• Inspected regular and beta stripped Mono declarations plus AssetRipper prefab serialization evidence.

Runtime validation remaining

• No restore, build, or unit test command was run because this is a read-only planning request.
• Compile and test both MonoMelon and Il2CppMelon after implementation to verify generated wrapper and delegate compatibility.
• Human in-game validation remains required for regular Mono, IL2CPP, multiplayer locality, native reaction preservation, and NPC save/load lifecycle behavior. No live runtime was available.

• 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: complexity (high); baseline source-backed technical request)
• Elapsed: 303s
• Codex thread: 019ff873-bc90-7a01-b740-67a366229313

---

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

[diffuin]

I opened #266