[FEATURE] Add managed jukebox state and control API

[ifBars]

What would you like to see?

Add a managed wrapper for placed jukeboxes that exposes their current state and common controls.

Useful members would include the track list/current track, play state, volume, shuffle, repeat mode, and safe operations such as play/pause, next, previous, volume changes, and selecting a track. State-change notifications would be useful for custom UI.

Why would this help?

Mods that add music-related UI, venues, or gameplay events currently need to access the native Jukebox and network state directly. A supported wrapper would make the existing jukebox behavior reusable without custom reflection or runtime-specific code.

Extra Context (Optional)

Keep the first version limited to existing game tracks and native jukebox behavior. Custom audio registration and new networked music payloads can be separate follow-up work. Controls should respect the game's existing server/authority rules.

[ifBars]

@Diffuin Research this issue and create an implementation plan.

[diffuin]

Implementation plan

Summary

Implement a dual-runtime managed wrapper in a new S1API.Audio surface. Both stripped branches expose the same native Jukebox state, controls, change callback, persistence data, and FishNet RPC seam. The wrapper should delegate all mutations to native methods, expose managed track/state snapshots, and avoid custom audio, save formats, or network payloads. IL2CPP delegate shape, track-ID semantics, volume bounds, prefab composition, and runtime authority behavior still require validation.

Design decisions

1. Propose S1API.Audio.Jukebox, JukeboxManager, JukeboxTrack, JukeboxState, and JukeboxRepeatMode. Expose strings, numeric values, enums, immutable snapshots, and GameObject/GUID lookup only; never expose AudioClip, native JukeboxState, FishNet types, or custom audio registration.
2. Use JukeboxManager.GetAll() to discover placed native Jukebox components and cache wrapper identity. Add Jukebox.FromGameObject() and GUID lookup so mods can resolve wrappers from placement events or persistent world identity without storing wrapper instances across scene reloads.
3. Forward controls to the native Jukebox methods and keep replication enabled internally. Adapt native onStateChanged into a per-wrapper managed event with copied state, and rely on the native JukeboxData/JukeboxLoader path for save/load behavior.

Implementation

1. Define the managed API contract — Add a documented, runtime-agnostic public surface for placed jukebox state and controls.
   • Add S1API/Audio/Jukebox.cs with managed state properties, Tracks, CurrentTrack, GUID or identity lookup, and per-instance OnStateChanged. (S1API/Audio/Jukebox.cs)
   • Add immutable JukeboxTrack and JukeboxState snapshots plus JukeboxRepeatMode values matching native None, RepeatQueue, and RepeatTrack values. (S1API/Audio/JukeboxTrack.cs, S1API/Audio/JukeboxState.cs, S1API/Audio/JukeboxRepeatMode.cs)
   • Add JukeboxManager.GetAll(), GetByGUID(), and wrapper caching for currently placed Jukebox components. (S1API/Audio/JukeboxManager.cs)
   • Expose TogglePlay, Previous, Next, ChangeVolume, SetVolume, ToggleShuffle, ToggleRepeatMode, ToggleSync, and PlayTrack without exposing the native replication flag or state object. (S1API/Audio/Jukebox.cs)
2. Implement the native bridge and lifecycle handling — Bind the managed API to the Mono and IL2CPP native components without leaking runtime-specific types or stale scene references.
   • Add aliased native access for ScheduleOne.ObjectScripts.Jukebox, copy TrackList metadata without AudioClip references, map currentTrack by native track identity, and preserve native repeat values. (S1API/Internal/Audio/JukeboxRuntime.cs)
   • Adapt onStateChanged with System.Action on Mono and the required Il2Cpp delegate conversion on IL2CPP; combine and remove callbacks without replacing native UI handlers. (S1API/Internal/Audio/JukeboxRuntime.cs, S1API/Entities/NPCMessaging.cs)
   • Make public mutators call the native control methods, pass replication enabled for absolute volume changes, and validate only track IDs and volume bounds confirmed from the native implementation. (S1API/Audio/Jukebox.cs, S1API/Internal/Audio/JukeboxRuntime.cs)
   • Prune destroyed wrappers and detach native callbacks during Main-scene cleanup so event handlers do not duplicate across load, unload, or save reload cycles. (S1API/Audio/JukeboxManager.cs, S1API/Internal/Lifecycle/SceneStateCleaner.cs)
3. Freeze the contract and document the limits — Add repository-local tests and user documentation for the new public surface and its compatibility boundary.
   • Add a compile fixture covering manager discovery, wrapper lookup, state properties, controls, and OnStateChanged subscription. (S1API.Tests/Audio/JukeboxApiCompileFixture.cs)
   • Add API compatibility tests for public signatures, immutable snapshot types, repeat enum numeric values, null/invalid input behavior, and absence of native game types from the public surface. (S1API.Tests/Audio/JukeboxApiCompatibilityTests.cs, S1API.Tests/Audio/JukeboxStateTests.cs)
   • Document lookup, state snapshots, control semantics, native-track-only scope, scene lifecycle, and the fact that authority and persistence remain native behavior. (S1API/docs/jukebox.md, S1API/docs/toc.yml, S1API/docs/modules-overview.md)
4. Validate both runtimes and native behavior — Verify compilation locally, then confirm lifecycle, authority, persistence, and event behavior in human-run game tests.
   • Run the repository restore, build, and contract tests for MonoMelon with local deployment disabled. (S1API.sln, S1API.Tests/S1API.Tests.csproj)
   • Repeat restore, build, and contract tests for Il2CppMelon, including generated-wrapper compilation of the delegate and collection adapters. (S1API.sln, S1API.Tests/S1API.Tests.csproj)
   • Inspect generated IL2CPP Jukebox signatures and confirm native track-ID semantics, volume bounds, callback shape, and control behavior before finalizing validation guards. (S1API/Internal/Audio/JukeboxRuntime.cs, S1API/Audio/Jukebox.cs)
   • Run human-only checks for placed-object discovery, event delivery, scene reload cleanup, save/load restoration, host/client convergence, authority rejection, and headless safety. (S1API/Audio/Jukebox.cs, S1API/Audio/JukeboxManager.cs)

Implementation gates

• What exact IL2CPP wrapper type represents Jukebox.onStateChanged, and does the generated Track[] expose the same members and collection behavior?
• Does native PlayTrack(trackID) use the TrackList index, and what volume range and clamping behavior should the managed SetVolume guard preserve?
• Does the native control implementation itself perform the required server/authority routing for every public control, especially SetVolume and PlayTrack, on both branches?

Evidence and validation

Evidence inspected

• Regular and beta stripped sources both define ScheduleOne.ObjectScripts.Jukebox with track metadata, mutable state fields, play/navigation/volume/shuffle/repeat/sync controls, onStateChanged, and network state methods: /data/references/s1-codearchiver-alternate/ScheduleOne-stripped/ObjectScripts/Jukebox.cs:20-101 and /data/references/s1-codearchiver-alternate-beta/ScheduleOne-stripped/ObjectScripts/Jukebox.cs:20-101.
• Native persistence already stores Jukebox.JukeboxState through JukeboxData and JukeboxLoader in both branches: /data/references/s1-codearchiver-alternate/ScheduleOne-stripped/Persistence/Datas/JukeboxData.cs:7-11 and /data/references/s1-codearchiver-alternate/ScheduleOne-stripped/Persistence/Loaders/JukeboxLoader.cs:6-12.
• S1API wraps placed world objects with cached managed instances, scans or resolves native objects, adapts callbacks, and clears scene-bound state: S1API/Storages/StorageManager.cs:18-85, S1API/Storages/StorageInstance.cs:345-371, S1API/Entities/NPCMessaging.cs:93-155, and S1API/Internal/Lifecycle/SceneStateCleaner.cs:57-119.
• The repository requires XML documentation, additive public APIs, compile/reflection compatibility fixtures, and separate MonoMelon and Il2CppMelon validation: AGENTS.md, CODING_STANDARDS.md, CONTRIBUTING.md, S1API.Tests/S1API.Tests.csproj:1-70, and S1API/S1API.csproj:10-48.

Validation performed

• Read issue [FEATURE] Add managed jukebox state and control API #221 and its available comments through the read-only GitHub broker.
• Read AGENTS.md, CODING_STANDARDS.md, CONTRIBUTING.md, and the required Schedule One modding, issue-planning, and human-writing guidance.
• Inspected repository wrapper, event, lifecycle, project, and test patterns, then compared the relevant Jukebox and persistence signatures in the regular and beta stripped sources.
• No repository files were changed, and no build or test command was run because this request is planning-only.

Runtime validation remaining

• Run dotnet restore, build, and test for both MonoMelon and Il2CppMelon using the repository's local game references.
• Verify the generated IL2CPP Jukebox wrapper, delegate conversion, Track[] access, Unity object discovery, and FishNet method behavior; Mono source alone cannot prove these details.
• Perform in-game or Play Mode checks for placed-jukebox discovery, native state notifications, event cleanup after scene reload, save/load restoration, volume and track-selection bounds, and repeat/shuffle behavior.
• Perform multiplayer and headless checks for host/client state convergence, native authority rules, replicated controls, and dedicated-server safety. No live runtime or end-to-end result is available from this planning pass.

Diffuin run details

• Model: gpt-5.6-luna
• Reasoning: xhigh (source-backed issue plan)
• Elapsed: 478s
• Codex thread: 019fe65b-c99d-72c0-8f87-603a4bab397a

---

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

[ifBars]

@Diffuin Open a PR to implement this consistent with the project coding standards and existing public APIs and internal utilities

[diffuin]

I opened #286