Integration reference · [Satie documentation](/docs)

# SATIE portable core in Unity

Two C# files over the core's C interface. Nothing here schedules, mixes or decides
a level: the native core does, the same code Godot and the offline renderer run.

- `SatieCore.cs`: the native calls (`SatieNative`), the manifest as plain classes,
  and `SatieSession`, which turns names into the core's commands (`Event`, `Signal`,
  `State`, `MoveHost`, `Listener`, `SetHostSurface`) and pulls audio (`Render`). It
  uses no UnityEngine type, so the .NET conformance test compiles and runs this
  exact file.
- `SatieCoreBehaviour.cs`: the Unity component. It loads the bundle and manifest,
  gives Unity's audio callback (`OnAudioFilterRead`) to the core, binds hosts to
  objects by name, and sends the listener and host positions every frame. The game
  calls the static `SatieCore` (`Fire`, `HostEvent`, `SetHostSurface`, `Signal`,
  `State`, `Bind`).

## What is verified, and what is not

Verified on 2026-11-12 (macOS arm64, .NET 9, the core built with AppleClang):

- `tests/Conformance`: `SatieSession` runs `packages/satie-core/tests/host_script.json`
  against the native library. The commands it issues are byte-identical to the
  TypeScript session's for the same script, the audio it pulls through P/Invoke
  (in odd block sizes) is bit-identical to `satie_render_scene` for that trace, the
  command struct is 48 bytes, and a bundle that does not match its manifest is
  refused. Run by `tests/placement.test.ts` when `SATIE_CORE_LIBRARY` and
  `SATIE_RENDER_SCENE` are set.
- `tests/CompileCheck`: both files compile at C# 7.3 against a stub of the
  UnityEngine API they touch, warnings as errors.
- Object output through P/Invoke (the ambient stream and the summed voice streams)
  is bit-identical to the native renderer's, in the same conformance run.

Run in the Unity editor on 2026-11-13 (Unity 6000.0.85f2, macOS arm64, the cabin
scene, an automated Play that measured `AudioListener` output):

- The scripts compile with no errors, the scene loads and plays through object
  output with 0 errors, 0 rejected commands and 0 dropped voices. Silent at rest
  (every signal rests at 0), about -23 dBFS RMS with the four loop signals at 1.
- The mixer's audition: every volume at -12 dB moved the output by about -11 dB;
  every sound muted gave silence; a solo left only the soloed sound above -80 dB.
- Save wrote the expected `satie.edits/v1` lines, and `Reload` with the files on
  disk returned true, kept the signals and kept playing.

Checked on 2026-11-14 (the assembled package, installed by the real `npx` line into
a scratch project, opened by Unity 6000.0.85f2 in batch mode on macOS):

- Each native library is imported for its own platform only (macOS, Windows x64 and
  Linux x64 for the editor and standalone on their own OS, Android arm64 for
  Android), read back through `PluginImporter`.
- The macOS library built on the CI runner loads in the editor and answers ABI 4;
  the component and the mixer window compile under their assembly definitions; the
  cabin renders through `SatieSession` inside the editor at -24.7 dBFS RMS with
  every signal at 1.

Not verified: by ear (whether sounds come from their places, clicks, the StereoMix
output), a Play session with the installed package (the Play run of 2026-11-13 used
hand-copied files and the old demo boot), a device build, and the mixer window
driven by hand. The Windows, Linux and Android libraries were built and
symbol-checked on their runners, and have not run in a game. There is no iOS,
WebGL or console library.

## Physics-mediated sound (2026-11-18, core ABI 7)

- `SatieContacts` (in `SatieCore.cs`, no UnityEngine type): wraps the core's contact layer
  (`satie/contacts.h`) and hands its decisions to `SatieSession`: an impact becomes
  `EventAt(name, bankKey, x, y, z, gain, body)` (`SATIE_TRIGGER_GAIN`), a slide or a roll
  becomes `Signal`. `SatieSession.Occlusion(source, amount, through)` sends a measured
  occlusion. With a library older than ABI 7, `SatieContacts.Available` is false,
  `EventLevelled` sends a plain trigger and `Occlusion` sends nothing.
- `SatiePhysics.cs`: `SatieBody` (forwards `OnCollisionEnter` and `OnCollisionStay`) and
  `SatiePhysics` (registers the bodies of `scene.contacts.json`, steps the layer after each
  physics step through `WaitForFixedUpdate`, takes `Footstep`, `Land` and `Rolling` from the
  game, and probes occlusion with `Physics.Linecast` by the table's numbers). The law and
  every number of it live in the core; this file measures and reports.

Verified on 2026-11-18 (macOS arm64, .NET 9): `tests/ContactsCheck` drives `SatieContacts`
against a library built from the tree (a crate dropped at 6 m/s reaches the queue as kind
10 on the wood-hard bank at (6 / 8.13)^2 from its body; two bodies in one step both sound
inside one cooldown; a drag raises and releases its loop's control; zero bytes allocated
over 600 physics steps) and against the ABI 4 library in `tests/fixtures`. `tests/CompileCheck`
compiles `SatiePhysics.cs` at C# 7.3 against API stubs. The batch-mode editor run and its
result are in `docs/specs/020-physics-mediated-sound/spec.md`.

Run in the editor on 2026-11-18 (Unity 6000.0.85f2, macOS arm64, batch mode, the assembled
package 0.1.1, an automated Play): the package compiled with no error or warning, the library
answered ABI 7, `SatiePhysics` started by itself and bound the crate and the floor by name; a
crate released 3 m up gave one impact at 7.65 m/s, fired once and reported for both bodies; a
wall between the ears and a placed loop gave it an occlusion of 0.576; 0 commands rejected.

Not verified: slides, rolls, footsteps and wheels inside a playing Unity scene, the level at
the output, and all of it by ear. The Windows, Linux and Android libraries are still ABI 4
(`package/Plugins/plugins.json` lists them under `stale`): there the scene plays as before
and contacts are silent, and the Console says so once.

## Install

A developer never copies these files. `satie_export { engine: "unity" }` returns one
line, run from the Unity project root:

    npx -y https://www.satie.world/unity/<version>/satie-unity.tgz --from '<link>'

It writes `Satie/` (the script, samples.json, the contract), copies the Unity package
into `Packages/world.satie.unity`, downloads the takes and compiles the scene into
`Assets/Resources/SatieCore`. On Play, a `Satie` object with `SatieCoreBehaviour`
starts by itself when the scene has none (`SatieCoreBehaviour.Boot`) and stays
across scene changes; a bound object that is destroyed is looked for again by name.

How the package is made:

- `package/`: what only the package has (its `package.json`, README, the two assembly
  definitions, and `Plugins/` with the native libraries and `plugins.json`).
- `scripts/build-unity-package.mts` (the last step of `npm run build`) assembles
  `Runtime/` and `Editor/` from the C# files here, writes a `.meta` file for
  everything (ids derived from the path, each library set to its own platform),
  bundles the command (`scripts/satie-unity/cli.mts`) and packs
  `dist/unity/<version>/satie-unity.tgz`, which the deploy serves.
- The native libraries are built on each platform's runner by
  `.github/workflows/unity-plugins.yml` (Windows x64 with the static C runtime, macOS
  universal, Linux x64, Android arm64 with 16 KB pages). After the core's source
  changes, `packages/satie-core/tests/unity-package.test.ts` fails until
  `npx tsx scripts/unity-plugins.mts` has rebuilt and downloaded them and the result
  is committed. While the workflow cannot run, `npx tsx scripts/unity-plugins.mts --local`
  builds this machine's library (macOS: universal) and records the others under `stale`
  with the ABI each really has. To build one by hand: `cmake -S packages/satie-core -B build/core
  -DSATIE_BUILD_SHARED=ON -DCMAKE_BUILD_TYPE=Release && cmake --build build/core
  --target satie_core_shared`.
- Bump `version` in `package/package.json` and `UNITY_PACKAGE_VERSION` in
  `packages/satie-mcp/export.ts` together when the package changes; the command
  replaces an installed package only when the version differs.

## Who gives a sound its direction

`SatieCoreBehaviour.output` chooses, before the scene loads:

- **EngineSpatializer** (default). The core decides what sounds and how loud; every
  positioned voice plays on its own child AudioSource, placed where the core says,
  so Unity's panning or the project's spatializer plugin (Project Settings, Audio)
  gives it its direction. Beds play on the component's own source. Each voice source
  plays a clip of ones and its filter multiplies by the voice, which works whether
  Unity pans before the filter or a plugin spatializes after it
  (`spatializePostEffects`). Unity's own rolloff is flat: distance is the core's.
- **StereoMix.** The core's finished stereo mix on one source, panned by the core.

`SatieSession` has the same two paths without Unity: `Render`, or `EnableObjects`
then `RenderObjects`, `CopyVoice`, `CopyAmbient` and `Voices`. The conformance test
holds both to the native renderer bit for bit.

The output is delayed by the limiter's lookahead (`SatieSession.LatencyFrames`, 2 ms).
Rooms ring and stated occlusion muffles, both done by the core; walls worked out from room geometry are not.

## A scene you can hear without building one

`SatieCoreDemo.cs` builds a test scene on Play from the compiled scene's manifest:
a marker per host, a camera with the ears, and the behaviour. It draws nothing in
the Game view (its first version drew a panel there; Mateo rejected it on
2026-11-13): the scene is played and mixed from the mixer window, and the ears are
the camera, moved like any object. Add it to an empty object in an empty scene; it
no longer starts by itself (since 2026-11-14 the behaviour does, without markers or
a camera, which is what a game wants). The scene is silent until its signals are raised.

## The mixer (Window > Satie > Mixer)

`Editor/SatieMixerWindow.cs` is the Satie mixer inside the Unity editor. It is a
view: nothing about a sound is decided in it.

- **Sounds.** One row per sound: its level now, a volume in whole decibels, mute
  and solo, and Play on a sound that answers an event, with one more button per
  surface it has takes for. Volume, mute and solo are an
  audition through the core's monitor gain (`SATIE_MONITOR`, ABI 4), so beds are
  covered like placed sounds.
- **Signals and state.** A slider per signal and a button per state, sent through
  the same calls the game makes.
- **Scene view.** A dot where each sound is, swelling with its level; clicking a dot
  or a row selects the other and the object the sound is bound to. A place no game
  object holds can be dragged, which is written as a `move`.
- **Save changes** appends `satie.edits/v1` lines to `.satie/authoring/edits.jsonl`
  at the project root: the log the browser mixer writes (`packages/satie-runtime/EDITS.md`).
  The coding agent applies it with `satie_apply_edits`, exports and compiles again.
  A level line carries the step since the last Save, since this window does not
  know the absolute level a reader could use to skip a line it already applied.
- **Reload while playing.** When the two compiled scene files change on disk during
  Play, the window loads them into the running core (`SatieCoreBehaviour.Reload`):
  signals, the state and bound objects carry over, and the audition starts again
  from "as written" because the new scene has the saved decisions in it.

With the test scene (`SatieCoreDemo`), the head of the window also has the switch
between Unity's direction and the core's stereo mix.

## The loop from Save to a changed scene

The same command is the whole round trip on one machine, with no server and no model.
In the Unity project:

    npx -y https://www.satie.world/unity/<version>/satie-unity.tgz --watch

or from this repository, against any scene folder (a web game's `public/satie`):

    npx tsx scripts/satie-unity/cli.mts --scene <game>/public/satie --unity <Unity project> --watch

Each pass applies the mixer's log to `scene.satie` through the same `applyEdits` as
`satie_apply_edits` and moves the log aside as `edits.applied-<time>.jsonl` (so no
line is applied twice), builds the placement scene (the same `buildExport` as
`satie_export`), saves the takes once under `.satie/takes`, compiles the bundle and
writes the pair into `Assets/Resources/SatieCore`. Decoding needs ffmpeg: the one on
the path, `FFMPEG_PATH`, or the `ffmpeg-static` package npm installs with the command.

Run on 2026-11-13 against a copy of the cabin with Unity playing: a volume of -6 dB
and a mute were saved in the window; nine seconds later the running scene had
reloaded with `spl 65 -> 59` and the muted bed gone (18 sources), signals kept, the
fire's measured peak 5.3 dB lower, 0 errors.

With a native library older than ABI 4 the window still lists the scene, with levels
and volume off.
