Carrot

Appearance

kids.kapish.audio.fmod ​

unity

Technical reference for the kids.kapish.audio.fmod Unity package -- FMOD Studio backend for Carrot.Audio.

Package Identity ​

  • Package name: kids.kapish.audio.fmod
  • Display name: Carrot.Audio.FMOD
  • Version: 0.1.0
  • Minimum Unity: 6000.0
  • License: MIT
  • Dependencies: kids.kapish.audio 0.1.0, com.fmod.unity 2.03.0

Assembly Structure ​

Carrot.Audio.Fmod (Runtime) ​

  • Path: Runtime/Carrot.Audio.Fmod.asmdef
  • Root namespace: Carrot.Audio.Fmod
  • References: Carrot, Carrot.Audio, FMODUnity
  • Engine references: Yes
  • Platforms: All

Currently contains only the FmodAudioBackend static class as a stub entry point.

Architecture ​

Backend Pattern ​

This package follows the backend pattern established by kids.kapish.audio: the core audio package defines abstract contracts (AudioEvent, AudioGroup, MusicPlayer), and backend packages provide concrete implementations for specific audio engines.

kids.kapish.audio.fmod will implement these contracts by delegating to FMOD Studio's runtime API via the com.fmod.unity plugin. This means game code only interacts with the Carrot.Audio API and never touches FMOD types directly -- swapping between Unity's built-in audio and FMOD becomes a package swap rather than a code rewrite.

Planned Type Map ​

The integration path documented in FmodAudioBackend.cs:

  • FmodAudioManager -- dispatches AudioEvent play/stop calls to FMOD's RuntimeManager. Manages FMOD system initialization and teardown.
  • FmodEventRef -- wraps FMOD event paths (event:/SFX/Explosion) or GUIDs. Provides serializable references that work with Unity's inspector.
  • FmodBankLoader -- handles FMOD bank loading. Banks can be loaded eagerly at startup, lazily per-scene, or via Addressables for streaming.
  • FmodMusicPlayer -- wraps FMOD's music system for adaptive music. Supports crossfades between tracks, vertical layering (intensity parameters), and stinger events.

FMOD Plugin Dependency ​

The com.fmod.unity package is distributed via FMOD's own scoped registry, not Unity's package manager. This means projects using this package must add FMOD's registry to their Packages/manifest.json. See the usage guide for installation details.

Key Design Decisions ​

  1. Stub-first. The package exists as scaffolding to establish the dependency graph and planned API surface before implementation. This lets other packages declare the dependency early and plan their integration.

  2. Backend swap, not abstraction layer. The package replaces the audio backend entirely rather than wrapping FMOD behind another abstraction. Carrot.Audio's contracts are the abstraction -- this package is one concrete implementation.

  3. Bank loading flexibility. The planned FmodBankLoader supports both FMOD's native bank loading and Addressables-based loading. This accommodates projects that use Addressables for all asset management as well as projects that prefer FMOD's own streaming.

Usage Guide ​

Practical guide to the kids.kapish.audio.fmod package -- FMOD Studio backend for Carrot.Audio.

Note: This package is currently a stub. The installation steps below are accurate, but the runtime API is not yet implemented. This guide documents the planned usage patterns.

Installation ​

1. Add FMOD's Scoped Registry ​

FMOD distributes its Unity plugin via a scoped registry. Add this to your project's Packages/manifest.json:

json
{
  "scopedRegistries": [
    {
      "name": "FMOD",
      "url": "https://fmod.github.io/unpm/",
      "scopes": ["com.fmod"]
    }
  ]
}

2. Add the Package Dependency ​

Add kids.kapish.audio.fmod to your project's or package's package.json:

json
{
  "dependencies": {
    "kids.kapish.audio.fmod": "0.1.0"
  }
}

This will pull in kids.kapish.audio and com.fmod.unity automatically.

3. Reference the Assembly ​

Add the assembly reference to your .asmdef:

json
{
  "references": ["Carrot.Audio.Fmod"]
}

Planned Usage ​

Once implemented, the FMOD backend will slot into the Carrot.Audio API transparently. The following examples show the intended usage patterns.

Registering the FMOD Backend ​

csharp
// At startup, register FMOD as the active audio backend
FmodAudioManager.Initialize();

Playing Events ​

Game code continues to use AudioEvent -- the FMOD backend resolves these to FMOD Studio events:

csharp
// AudioEvent references map to FMOD event paths like "event:/SFX/Explosion"
audioManager.Play(explosionEvent);

Bus/Group Control ​

AudioGroup maps to FMOD buses, giving sound designers mix control through FMOD Studio:

csharp
// Mute all SFX via the FMOD bus
audioManager.SetGroupVolume(sfxGroup, 0f);

Music ​

MusicPlayer delegates to FMOD's music system for adaptive audio:

csharp
// Crossfade to a new track -- FMOD handles the transition
musicPlayer.TransitionTo(battleMusic, fadeTime: 2f);

Bank Loading ​

FMOD audio data is organized into banks that must be loaded before playback:

csharp
// Load a bank for the current level
await bankLoader.LoadBankAsync("Level1.bank");

// Or via Addressables
await bankLoader.LoadBankFromAddressableAsync(level1BankId);

Carrot