A practical guide to every Tribe XR mod type apart from venues: custom equipment and controllers, sample pads and drum kits, synths, VST3 instruments, keyboard mapping, audio-reactive scene overlays, deck waveform styles and a few smaller options. It is based on the Tribe modding documentation. For venues, see No access.
- Before you start
- Choosing the right mod type
- Equipment (compositions)
- Making equipment look right
- Routes and behaviours (logic)
- Sample pads and drum kits
- Synths
- VST3 instruments
- Keyboard mapping
- Audio-reactive scene overlays
- Waveform styles
- Smaller options
- Restrictions at a glance
- Limits to plan around
- Troubleshooting
Before you start
Every mod is a folder containing one mod.json manifest plus the GLB, PNG, JPEG and WAV files it names. Mods are data only: they can't run scripts or native code, and they only select and configure features the app already has.
- Asset files sit next to
mod.jsonin the same folder; subfolders aren't read. iduses lowercase letters, digits,.,_and-, with a creator prefix such asyourname.drum-pads. Don't change it after release.- Every feature you use must be listed in
requiresas a capability, or the package is rejected. - On PC, put the folder in
Documents/TribeXR/Mods(Windows). - On a headset, either connect it to a computer with a USB-C cable and copy the folder into Tribe's Mods folder (
Documents/Modsinside the app's files folder; Settings > Mods shows the exact path), or import it from Dropbox under/Tribe/Mods/after logging in to Dropbox in the music browser. Dropbox only imports package IDs that aren't already installed, and some devices' storage settings may restrict transfers. - Press refresh in Settings > Mods, then tick the package. Errors show on the package card with the failing field.
- In multiplayer, mods are never transferred. Every player needs the identical package (same
id,versionand files) installed and enabled.
The docs suggest giving an AI assistant the doc pages, both schema files and the generated binding-api.json port catalog from your Mods folder.
Choosing the right mod type
You want to make | Capability | Section |
Custom buttons, faders and knobs that control a deck | equipment.composition/1 | Equipment |
Logic: sequencers, LEDs that follow state, displays, mixer control | api.bindings/1 | Routes and behaviours |
Drum pads, loopers, one-shot players | audio.samples/1 | Sample pads and drum kits |
A playable synth | audio.synth/1 | Synths |
A controller for a VST3 instrument on your PC | audio.vst3/1 | VST3 instruments |
Computer-keyboard shortcuts for your buttons | none ( keyboard field) | Keyboard mapping |
Visuals that react to the music in any venue | scene.* | Audio-reactive scene overlays |
New deck waveform colours and shapes | waveform.style/2 | Waveform styles |
Custom synth sounds | audio.oscillators/1 | Synths |
Moving stock equipment, loading acid synth patterns | equipment.layout/1, audio.acidSequence/1 | Smaller options |
Equipment (compositions)
equipment.composition/1 builds selectable equipment from four kinds of pieces:
- Parts: decoration (cubes, cylinders, GLB meshes, and text with
api.bindings/1). - Controls: buttons, faders and knobs the performer touches.
- Behaviours: named app features such as a deck, a parameter or a synth. Each has ports, its named inputs and outputs.
- Connections: wires from a control event (
pressed,released,changed) to a behaviour's input port. Controls can also show feedback from an output port, such as a button that lights while a deck plays.
A composition is one of two kinds:
- Companion surface (no
audioOutput): attaches to a stock deck and controls it. The deck, its track and controls stay as they are. - Instrument (with
audioOutput): replaces the channel's device and sends its own audio to that mixer channel.
Example: a companion surface with a play button that lights while the deck plays, and a tempo fader.
Using it: enable the package, open Settings > Equipment > Select Equipment, choose it for a channel and confirm. For an instrument, also select LINE on that mixer input and raise its fader. Confirming an instrument destroys the previous device on that channel, including its loaded track.
Coordinates: centimetres from the performer's point of view: +X to the right, +Y toward the performer, +Z up. A companion at [0, 0, 0] overlaps its deck, so move it clear.
Key rules:
- Buttons emit
pressedandreleased; faders and knobs emitchangedwith a value from 0 to 1. Amin/maxon the connection maps that onto a range. - For ports whose minimum is above 1 (such as a clock's
bpm.set), give an explicitvalue. - Controls can't write to local (per-player) ports, except the mixer's personal monitoring ports. To change a part's appearance from a control, set a
parameterand route it to avisualbehaviour. - Each selected channel gets its own independent instance.
Making equipment look right
- Primitives take their surface from
color,metallic,roughness,emissiveandemissiveIntensity. GLB meshes keep their own materials unless you set one of these. - Values that match stock gear: dark panels 0.02–0.04, printed legends 0.5–0.65, white keys about 0.7, roughness 0.4–0.8 and no metal.
- A button with
feedbacklights its emissive layer by the feedback value. For a 0/1 source, set"min": 0, "max": 1or the LED stays half lit. - Every control prints its
labelon the panel in front of it. Uselegendto move, resize or hide it. - PC multiplies emissive by 4 so LEDs bloom; Quest has no bloom, so emissive 1 is full brightness there.
Modelling controls in Blender: export each case and control mesh as its own GLB. Put each control's origin at the centre of its base (a key can pivot at its back edge so it tips when pressed). Pass the mesh dimensions as size in centimetres with X and Y swapped (Blender Y is composition X). Make an LED's lit area the first material so emissive and feedback light it. Normal maps are ignored, so bake detail and legends into the base colour texture.
Routes and behaviours (logic)
api.bindings/1 adds routes, which wire one behaviour's output port to another's input port, independent of controls, plus extra behaviour types. The full port list for your version of the app is written to binding-api.json in the Mods folder at startup.
{"from": {"behavior": "macro", "port": "value"},
"to": {"behavior": "mixer", "port": "eq.high.set"},
"scale": -1, "offset": 1, "initial": true}Route field | Meaning |
from, to | Required output and input ports. |
event | change (default), rise or fall, with threshold (default 0.5). |
scale, offset | Payload is value × scale + offset, clamped to the target's range. |
value / valueFrom | A constant payload, or another output read when the event fires. |
gate | Only deliver while this output is above 0.5. |
initial | Also write once when the route starts. Use for displays and restored settings, not for actions. |
Behaviour | What it does |
deck | Transport, cues, loops, tempo, sync, hot cues 1–8 and memory cues on a stock deck. |
mixer | Reads and writes mixer controls: fader, trim, EQ, colour FX, crossfader, effects, sends, and personal cue and headphone levels. |
parameter | A shared number with a range; can be saved between sessions with persist. |
clock | A tempo grid that can follow the mixer's master tempo; drives sequences and sample quantisation. |
sequence | A list of up to 128 numbers stepped by a clock; steps can be muted at runtime (only the first 53 steps of a sequence). |
math | Add, subtract, multiply, divide, min, max, comparisons, and/or, modulo, round and bit. |
visual | Moves, scales, recolours, shows or hides a part, sets its glow, or changes a text part. |
signal | Music signals on each player: BPM, levels, EQ, playing state, crossfader and spectrum bands. |
lifecycle | Ready state, time since creation and channel. |
Routes run 30 times a second and right after control input, in dependency order. Cycles and self-routes are rejected, and there are no free-form expressions. This is a control-rate system, not a sample-accurate scheduler.
Sample pads and drum kits
audio.samples/1 adds the sample behaviour, which plays a WAV file from the package. With a clock and an audioOutput, sample voices make drum pads, loopers and one-shot players.
- Sample options:
gain,loop,chokeGroup(triggering one voice stops the other voices in the same group) andclockfor quantisation. - Quantising: with the clock's
quantizeon, triggers start on the next grid boundary (0.25, 0.5 or 1 beat). WithfollowMixer, the grid follows the mixer's sync master tempo. - Gated sounds: connect a button's
pressedtotriggerandreleasedtostop. - Overlapping hits: each sample behaviour has one voice, so add several behaviours using the same file.
- Audio output: every sample and synth must be listed once in
audioOutput.sources. Leave headroom when combining loud samples. - Sequenced patterns: with
api.bindings/1, route a clock'sstepinto asequence, and the sequence'seventinto a sample'strigger.
WAV files: 16-bit PCM, mono or stereo, 8–96 kHz, at most 10 seconds and 2 MiB each, 8 MiB of WAV per package. There is no pitch or rate control.
Synths
The synth behaviour (needs audio.synth/1 and api.bindings/1) is a 16-voice polyphonic synth.
Setting | Range | Default |
gain | 0–1 | 0.3 |
attack | 0.001–2 s | 0.01 |
release | 0.005–5 s | 0.2 |
cutoff | 20–20000 Hz | 8000 |
resonance | 0–1 | 0 |
envelope (filter opening per note) | 0–1 | 0 |
decay (filter envelope fall) | 0.02–4 s | 0.3 |
transpose | −48 to 48 semitones | 0 |
waveform | 0 (sine), 1 (triangle) or a custom oscillator name | 0 |
- Playing notes:
note.onandnote.off(MIDI note 0–127) for held notes;note.triggerfor a note lastinggateseconds;notes.offreleases everything. - Every setting also has a
.setinput, plusvelocityandgate. - Octave buttons: a parameter routed through
mathmultiply12 intotranspose.set. - At most 4 synths per composition.
Custom sounds (audio.oscillators/1): add up to 8 oscillators, each defined by harmonics (up to 64 sine amplitudes) or samples (exactly 32, 64, 128, 256 or 512 values for one cycle). On the waveform.set port, 0 is sine, 1 is triangle and your oscillators follow from 2.
"oscillators": [
{"id": "hollow", "harmonics": [1, 0, 0.333333, 0, 0.2]}
],
"waveform": "hollow"The bundled Studio Synth package is a full example: keys, knobs, faders, LED buttons, a step sequencer, octave transpose, saved settings, tempo sync, text displays and a keyboard profile.
VST3 instruments
audio.vst3/1 lets equipment play VST3 instrument plugins installed on your Windows PC. Audio goes to the mixer channel, so EQ, cue, fader, crossfader and recording work as normal.
- Install a VST3 instrument with its normal installer.
- In Settings > Mods, select Scan installed plugins.
- Select an instrument and Create equipment mod. This writes a package with one octave of keys, a GAIN knob, EDITOR, SAVE PRESET and PANIC buttons, and knobs for up to eight plugin parameters.
- Enable it, select it for a channel in Settings > Equipment > Select Equipment and set that mixer input to LINE.
- EDITOR opens the plugin's window on the desktop; SAVE PRESET stores its settings on that PC.
The generated mod.json is an ordinary composition you can edit. Plugins are referenced by the class ID from vst3-catalog.json, never a file path, and each vst3Parameter uses a parameter ID from the same catalog.
Keyboard mapping
The top-level keyboard field lets desktop players play an equipment mod's buttons from the computer keyboard. It needs no capability.
- Profiles:
singlewhen the equipment is the only focused device;leftandrightwhen two devices are focused. Give left and right different keys so both can be played at once. - Each profile maps up to 64 keys to button IDs (composition buttons or legacy synth controls).
- Key names are Unreal names:
A–Z,One–Zero,SpaceBar,BackSpace,Enter,Tab, punctuation such asCommaandLeftBracket, arrows andF1–F12.
How players use it (desktop mode): point at the equipment and press Ctrl+K (Command+K on Mac) to focus it. Press Ctrl+Shift+K on a second device for a two-device layout. Ctrl+K again unfocuses one device; Escape clears all. Holding a key holds the button.
Audio-reactive scene overlays
A scene without an environment section is an overlay: 3D objects added to whatever venue is loaded, which react to the music. Overlays appear as soon as the package is enabled and work in any session type.
- Nodes: stock shapes (group, cube, sphere, cylinder, plane, cone), GLB meshes, point lights and text, with materials, parent/child hierarchies, spinning and bobbing.
- Instances: draw up to 1024 copies of a node in a line, grid or ring in one draw call.
- Shaders:
glow(additive, for beams and halos) andled(opaque, for tubes and screens). - Motion: paths, random jitter, noise and per-second rates.
- Bindings: map a signal (beat, time, BPM, master or channel levels, faders, EQ, crossfader, spectrum bands) onto a property (position, rotation, scale, visibility, colour, glow, light, path progress). Shape them with waves, curves and attack/release smoothing.
Scenes aren't shared between players: each player builds the scene from their own copy and drives it from their own mixer, so matching packages react the same way.
Waveform styles
waveform.style/2 adds a named style to the Waveform button above each deck screen. Players pick it per channel; it changes the timeline, overview and mixer row.
- Start from the
modernorclassicpreset and override envelope, shading, normalisation, palette, colours, outline shape, amplitude, brightness, band gains, grid and cue opacity, and played dimming. - Styles are a local choice per player and channel. They never change audio, reload tracks or replicate to other players.
Smaller options
Equipment layout (equipment.layout/1): moves, rotates or scales existing stock devices (mixer or channel.0–channel.7). Solo sessions only.
"requires": ["equipment.layout/1"],
"equipment": [{"target": "mixer", "position": [0, -10, 0]}]Acid sequence (audio.acidSequence/1): loads up to 64 steps into the app's acid synth on one channel. Each step has a note (MIDI 48–96), a mode (note, rest or tie) and an optional accent. Solo sessions only.
Legacy synth device (device.polySynth/1): an older, simpler synth keyboard format. New instruments should use a composition with a synth behaviour instead.
Restrictions at a glance
Not supported in equipment mods: scripting, library browsing or track loading, live sample assignment, recording, slicing or time stretch, sample-accurate scheduling, jog and scratch gestures, waveform widgets, custom material graphs, audio input, and plugin effect inserts.
- Keyboard mapping is for the computer keyboard in desktop mode, and only for buttons: faders and knobs can't be mapped. Escape, Shift, Ctrl, Alt, Command, mouse buttons and gamepad inputs can't be mapped.
- VST3 works only on Windows and only in solo sessions. VST2, AU and CLAP plugins, 32-bit plugins, audio effects, sidechains, audio input, multi-output routing, the plugin window inside VR and shared presets aren't supported.
- Sample files have no pitch or rate control, and loops aren't seamless-loop edited.
- Equipment layout and acid sequences only apply in solo sessions.
- Multiplayer: mods are never transferred; every player needs the identical package.
Limits to plan around
Limit | Value |
Parts per composition | 128 |
Controls per composition | 128 |
Behaviours per composition | 64 |
Connections / routes | 256 each |
Audio sources | 16, at most 4 synths and 4 VST3 instruments |
Mesh files per package | 8 (shared with any scene) |
Meshes, textures and WAV per package | 32 MiB |
Triangles | 500,000 (text part 512, cube 12, cylinder 128) |
WAV files | 10 s and 2 MiB each, 8 MiB per package |
Scene nodes / bindings / lights | 128 / 256 / 4 per package |
Keyboard keys | 64 per profile |
Waveform style entries | 24 |
These are validation limits, not performance guarantees. Test on Quest, the slowest supported device.
Troubleshooting
- Equipment not in the list: enable the package in Settings > Mods, then look in Settings > Equipment > Select Equipment under the package name.
- No sound from an instrument: select LINE on that mixer input and raise its fader; check every sample and synth is listed once in
audioOutput.sources. - A control does nothing: Settings > Mods shows the package's last binding error, such as a missing track, a stock mixer control held by another player or an invalid value. Failed writes are reported, not silently ignored.
- LED stays half lit: set
"min": 0, "max": 1on the feedback. - Deck playback commands fail: the deck needs a track loaded.
- Saved parameters won't reset: increase the composition's
stateVersion. - Changes not picked up: press refresh in Settings > Mods. On a headset, Dropbox skips package IDs that are already installed, so copy the updated folder over from a computer or give it a new
id.