Integration reference · [Satie documentation](/docs)

# Godot

## Godot 4 (the placement export)

Godot does not run the browser runtime. Satie exports the realized scene as one scene file (`satie.placement/v1`), one GDScript file and the takes, and Godot's own audio plays it: an AudioStreamPlayer3D per positioned voice, an AudioStreamPlayer per bed.

Files: `satie/scene.json`, `satie/audio/<take>`, `satie/satie.gd`. Add the loader as an autoload named `Satie` (in project.godot: `[autoload]` then `Satie="*res://satie/satie.gd"`); it starts with the game. Open the project once in the editor so the takes are imported for an exported build.

Describe the world to Satie exactly as for the web: satie_inspect_scene with the engine's own object names as ids and its own coordinates in metres (nothing is converted), then brief, compose, audit and realize. Then satie_export { engine, script, contractId, realizeId } (free): it returns the scene file's link, the loader's link, one download line per take and a README. Run the lines as they are; never transcribe the scene file.

Binding: a voice `at <id>` follows the object with that name (`find_child` under the current scene); when the name differs, `Satie.bind("door", $Door)`. A host nobody finds plays at its manifest position and the loader says so once in the log.

The game tells the sound what happens with the same five ideas as the web runtime: `Satie.fire("door_open", position)`, `Satie.host_event("crate", "drop")`, `Satie.set_host_surface("player", "gravel")` before the step that reads it, `Satie.signal_value("engine_load", 0.7)`, `Satie.state("combat")`. The events, signals and states section below applies as written; only the call names differ.

What the export carries: every voice's takes, host, position, level (Satie's level window, run by the loader), the inverse distance law, recurrence, event banks per surface, state gates and the `follow` bindings on volume, pitch and emission. A stated `occlusion` (or one bound to a signal) is played as its level cut only. What it does not: rooms and reverb, the occlusion muffle, walls worked out from geometry, per-voice DSP, movement paths, entities, the mixer and the live edit loop. The result lists what THIS scene loses in `notCarried`; tell the developer, and add the engine's own reverb zones where the room matters. To change the sound, compose again and export again.

Physical contacts: Godot's physics decides, Satie's law sounds it. When the manifest gives bodies and materials (see "Physical contacts" in the events section), the export also writes `satie/contacts.json`: the body table, each event's surfaces and the contact law's numbers. The loader finds each body's node by name (as it finds hosts), and for every `RigidBody3D` turns on `contact_monitor`, raises `max_contacts_reported` to at least 4 and reads its contacts from the physics server after each physics step: the change of the pair's velocity along the contact normal is the closing speed of an impact, the contact point's velocity the slide and the roll. Then the law, written in GDScript from the same numbers as the web runtime: nothing sounds under 1.8 m/s of closing speed or within 50 ms of the same body's last hit, the level is the square of the closing speed (full at 8.1 m/s), more than 4 impacts in one step merge into one per bank, a slide or a roll is a loop that rises with speed and releases 0.1 s after contact ends, and a material with no bank plays the default one and says so once. Do not fire `impact`, `<id>_slide` or `<id>_roll` by hand, and do not connect `body_entered` to a sound. The loader reads a step's contacts at the start of the next physics tick, so an impact sounds one tick (about 17 ms) after it happens.

What the physics does not say, the game says: `Satie.footstep("player", "gravel", foot_position, speed)` from the character controller or an animation track (the walker's speed over the ground sets the level), `Satie.land("player", "gravel", position, fall_speed)` when the scene has a `land` event, and for a vehicle `Satie.rolling("truck", "asphalt", travel_speed, wheel_surface_speed, skid_speed)` each physics tick it is on the ground. A thing the manifest does not list (the ground, a wall) says its material with `node.set_meta("satie_material", "concrete")`. A body spawned later: `Satie.watch_body("crate_2", node)` after `Satie.contact_body("crate_2", "wood")`. The signal `Satie.contact_hit(body, other, speed)` reports every impact over the gate for the game's own consequences. An event voice keeps four players, so impacts that overlap each keep their own level; `Satie.fire(event, position, surface, gain, body)` takes a level of its own too.

Occlusion from geometry: the loader casts rays through the physics space from the listener to each placed sound (the centre and eight points of its sphere, each sound about five times a second, staggered and eased) and lowers what is behind something by the blocking material's loss, on top of any `occlusion` the script states. Level only: this loader has no per-voice filter, so the muffle is not carried. `Satie.occlusion_mask` is the collision mask that blocks sound; `Satie.occlusion_probe = false` turns it off.

Godot plays through this GDScript loader, not Satie's native core, so the law exists here as a third copy held to the same numbers. Not heard by anyone yet in Godot: tell the developer to listen, and report what is off with satie_feedback.

Checked on 2026-11-12 by running the loader headless on Godot 4.5 with a 19-voice scene (loops, events, surface banks, signals, states, distance); not yet listened to on speakers or a headset. Tell the developer to listen once, and report what is off with satie_feedback.
