SteelSpeaker

3D speaker mod for PEAK that plays audio in-game, attaches to the player/host’s hip, and supports live in‑game tuning of the mount position/rotation. Built with BepInEx 5 + .NET Standard 2.1.

Features

• 3D positional audio that follows a visible speaker attached to the hip
• Host/local attach: defaults to host (Photon master); falls back to local if unresolved
• Live mount tuning overlay (F6) to adjust offsets; saves to BepInEx config
• AssetBundle prefab loader for your model with shader fallbacks for visibility
• Dev hotkeys for quick audio testing (F8/F9) and a debug cube (F7)

Player Install (r2modman)

• Plugin DLL: <ProfileFolder>\BepInEx\plugins\SteelSpeaker\com.github.coleman71803.SteelSpeaker.dll
• AssetBundle: <ProfileFolder>\BepInEx\plugins\SteelSpeaker\AssetBundles\speakerbundle
  • Fallback names: steelspeaker, speakerbundle.bundle, steelspeaker.bundle
• Test audio file: <ProfileFolder>\BepInEx\plugins\SteelSpeaker\Audio\test.mp3

In r2modman: PEAK → your profile → Settings → Browse profile folder to locate <ProfileFolder>.

Build & Deploy

• Build Release: dotnet build SteelSpeaker/SteelSpeaker.sln -c Release
• Output DLL: SteelSpeaker/artifacts/bin/SteelSpeaker/release/com.github.coleman71803.SteelSpeaker.dll
• Optional auto‑deploy: copy SteelSpeaker/Config.Build.user.props.template → SteelSpeaker/Config.Build.user.props and set
  • PeakGameRootDir and/or PeakPluginsDir (point PeakPluginsDir to your r2modman profile’s BepInEx/plugins/)

Controls

• F8: play test.mp3 on the speaker
• F9: stop playback
• F6: toggle mount tuner overlay
• F7: spawn a small debug cube at the mount for visibility sanity‑check

Tuner keys (when F6 is active):

• Move: J/L = X −/+, I/K = Z +/−, U/O = Y +/−
• Rotate: H/N = Yaw −/+, Y/G = Pitch −/+, T/B = Roll −/+
• Step size: +/- (range ≈ 0.0025 → 0.2)
• Save: S (writes current values to BepInEx config)

Configuration

• File: BepInEx\config\com.github.coleman71803.SteelSpeaker.cfg
• Keys:
  • Mount offsets: PosX, PosY, PosZ, RotX, RotY, RotZ
  • General: InitialAttachDelaySeconds (default 15)

The speaker reads these values when attaching so you can tweak live (F6), save (S), and keep across runs.

AssetBundle

• Loader path: <ProfileFolder>\BepInEx\plugins\SteelSpeaker\AssetBundles\speakerbundle
  • Fallbacks: steelspeaker, .bundle variants
• Prefab name inside bundle: Speaker3D (case‑sensitive)
  • If not found directly, the loader scans bundle assets and loads the one ending with speaker3d.prefab
• Rendering pipeline note:
  • PEAK uses Built‑in RP. If your model uses URP/HDRP shaders, the mod attempts a runtime Standard/Diffuse fallback for visibility (may look flatter). For best visuals, set materials to Built‑in (Standard/Lit) in Unity before building the bundle (StandaloneWindows64).

Logs & Troubleshooting

• Log file: <ProfileFolder>\BepInEx\LogOutput.log
• Expected diagnostics:
  • Loaded bundle: “Loaded AssetBundle: …\speakerbundle”
  • Prefab chosen: “Using asset '…speaker3d.prefab' from bundle.” (if not exact Speaker3D)
  • Visual info: “EnsureVisual/AttachToTarget: renderers=N, shader=…; bounds=…”
• If invisible:
  • Press F7 to spawn a debug cube to confirm attach point
  • Ensure prefab root is active; convert materials to Built‑in RP; confirm bundle name/path

Project Layout

• Core
  • src/SteelSpeaker/Plugin.cs – Entry; logging, config init, dev hosts
  • src/SteelSpeaker/Managers/AudioManager.cs – Minimal local file playback (.ogg/.wav/.mp3)
• Speaker & Assets
  • src/SteelSpeaker/Prefabs/BundleLoader.cs – Load speakerbundle, locate Speaker3D
  • src/SteelSpeaker/Prefabs/SpeakerBehavior.cs – Singleton; host/local hip attach; diagnostics & shader fixups
• Interaction & Dev
  • src/SteelSpeaker/Interaction/SpeakerInteractable.cs – Pickup/drop scaffolding (to integrate with native Interaction)
  • src/SteelSpeaker/Dev/devHotkeys.cs – F8/F9 test audio; uses BepInEx.Paths.PluginPath
  • src/SteelSpeaker/Dev/MountOffsetTuner.cs – F6 overlay; live offset tuning; F7 debug cube
• Config & Docs
  • src/SteelSpeaker/Config/ModConfig.cs – BepInEx config entries
  • spec/steel-speaker-reqs.md – Requirements brief
  • game-apis/targets.md – Place decompiled target signatures and notes here
  • ReferenceMaterial/*.cs – Decompiled PEAK snippets to guide integration

Developer Notes

• Attach strategy
  • On scene load, waits InitialAttachDelaySeconds, then attaches to:
    • Host (Photon master) if resolvable, else local
    • Hip bone via Character.GetBodypart(BodypartType.Hip) (falls back to player root if needed)
  • Keeps speaker parented and periodically re‑asserts attach across scene changes
• Visual safety
  • Enables renderers, sets scale to 1, matches player layer, attempts shader fallback if URP/HDRP detected
  • F7 debug cube is available to verify mount regardless of prefab rendering
• Positional audio
  • Reuses prefab AudioSource if present; else adds one with 3D settings (spatialBlend=1, logarithmic rolloff)
• r2modman support
  • Uses BepInEx.Paths.PluginPath to resolve all paths under the active profile

Thunderstore Packaging

• Build package: dotnet build -c Release -target:PackTS -v d
• Output: SteelSpeaker/artifacts/thunderstore/

Roadmap

• YouTube/queue: yt‑dlp/ffmpeg integration and caching
• Native interaction: implement IInteractible/IInteractibleConstant and patch into PEAK’s Interaction flow (E/hold‑E)
• Backpack clip: visual‑only attachment to backpack sockets (no slot usage)
• Network sync: host‑authoritative play/stop/queue broadcast to clients

Credits & License

• Built with BepInEx 5 and Photon PUN (via game)
• See LICENSE for license details