A practical guide to turning a 3D space into a selectable venue in Tribe XR, using the Tribe modding documentation (README, Environments, Scenes, Composition and the two schema files). It covers what is possible, what isn't, how to convert a Unity or Blender project, and how to get it onto a headset, with a worked example at the end.
- What an environment mod is
- What you need
- Quick start
- Key environment settings
- Spawn points
- Back-wall visuals need passthrough mode
- Have fun with mixed reality
- Converting from Blender
- Converting from Unity
- Collision and walking
- Getting it onto a headset
- Restrictions at a glance
- Limits to plan around
- Troubleshooting
- Worked example: Tribe DJ Room
What an environment mod is
A mod is a folder of data: one mod.json manifest plus the GLB, PNG, JPEG and WAV files it names. Mods cannot run scripts, load native code or reference Unity or Unreal assets directly. The manifest only selects and configures features the app already has.
An environment mod (capability environment.scene/1) replaces the stock venue with your own scene. Players pick it in Visuals > Environments. A plain scene without environment is an overlay that decorates whatever venue is already loaded.
Unity projects and Blender scenes can both be converted into a Tribe mod, but not loaded directly. The geometry is exported to GLB, and everything else (placement, collision, lights, spawn points) is written as JSON. It works well with some know-how and within the limits below.
What you need
- The Tribe modding docs: README.rst, Environments.rst, Scenes.rst, Composition.rst and
mod.schema.json/composition.schema.json(give these to an AI assistant if you use one). - Blender 4.x (free) for exporting GLB, or a Unity project plus a way to export its meshes.
- A text editor for
mod.json. - A Quest headset, or the PC version for quick checks.
Quick start
- Create a folder for the package, for example
Mods/my-venue/. Asset files sit next tomod.jsonin the same folder (no subfolders). - Write
mod.json(minimal example below). - In Tribe, open Settings > Mods and press refresh. The package appears disabled; tick it.
- Open Visuals > Environments and select it.
- If something is wrong, the package card shows the error and the failing field.
Every feature you use must be listed in requires, or the package is rejected.
Key environment settings
Field | What it does |
backdrop | What sits behind your scene: none, passthrough (your real surroundings) or videoSphere (the app's 360° video). |
rigAnchor | Where the decks and mixer go in your venue: {"position": [X, Y, Z], "yaw": degrees}. |
spawns | Optional dj, mentor and spectator positions, at floor height. |
collision | Up to 64 boxes that players cannot pass through ( position, rotation, size). |
Coordinates: centimetres, X forward, Y right, Z up, rotations as [pitch, yaw, roll]. With the default rig anchor, the DJ stands 100 cm below the scene origin, so floors go at Z = -100.
Lighting: with backdrop: none nothing lights the rig or avatars, so add a steady booth light (about 5 candelas, roughly 1.7 m above the decks). Quest has no HDR, bloom or baked lighting, and a package can have at most 4 lights.
Spawn points
environment.spawns sets where people stand in your venue. Each spawn is a position in centimetres and a yaw (the direction they face), in the venue's own coordinates.
Spawn | Used for |
dj | The DJ. The position is the VR tracking origin at floor height; the player's height adjustment is added on top. Reapplied on selection, removal and recentering for rig-attached players. |
mentor | The mentor. Works the same way as dj. |
spectator | Spectators when they spawn, including late joiners. |
"spawns": {
"dj": {"position": [-6, 56, -100], "yaw": -90},
"mentor": {"position": [-6, -130, -100], "yaw": 90},
"spectator": {"position": [280, 240, 65], "yaw": -135}
}Any spawn you leave out keeps the app's normal position.
Back-wall visuals need passthrough mode
If you want Tribe's back-wall visuals in your venue, set "backdrop": "passthrough". The visuals wall only appears in passthrough venues. There is no manifest field for showing the app's visuals on your own geometry.
- Passthrough needs a headset that supports it. In multiplayer, a peer without passthrough sees the scene alone.
- Remove any sky sphere or enclosing dome in the passthrough version, otherwise it covers everything behind the scene.
- You don't need to cut holes in your room for the visuals wall: a complete, enclosed room works.
Have fun with mixed reality
Passthrough turns a venue into a mixed-reality space: your modelled room sits inside your real one. Anywhere the model has gaps, you see the real world.
- Windows onto your world: leave window openings without glass. With a skybox they show the sky; in a passthrough venue with no skybox they show your actual room. It's a really fun effect.
- Partial rooms: build only a booth, a floor, or a few walls and let passthrough fill in the rest.
- Openings and portals: leave arches, doors or skylights open on purpose.
- 360° video:
"backdrop": "videoSphere"keeps your scene in front of the app's 360° video environment instead. Video files are local to each player and not part of the mod.
Tip: keep two versions of the same venue (one with a skybox, one passthrough) with different ids, so both appear in the Environments list.
Converting from Blender
From README.rst (Exporting GLB from Blender):
- Model in metres. Join the parts of each object into one mesh (Object > Join).
- Apply transforms (Object > Apply > All Transforms). Tribe ignores glTF node transforms.
- Put the origin where the object should pivot.
- File > Export > glTF 2.0: format glTF Binary (.glb), Selected Objects, +Y Up on, Apply Modifiers on, UVs and normals on, materials exported, images Automatic. Compression, animation, shape keys and skinning off.
- A Blender position
(x, y, z)in metres lands at(y, x, z) × 100in Tribe's centimetres.
What carries over: base colour, metallic, roughness and emissive, with their textures. Normal maps are ignored.
Converting from Unity
Unity scenes can't be loaded, but their geometry can be converted. This takes some technical know-how. The general method:
- Export the meshes from Unity. Use an editor script or a glTF exporter to export every mesh in world space, and note the positions of spawn points and deck placeholders.
- Convert to GLB. Convert the meshes to Tribe's axes, merge them into a few GLB files (at most 8), and resize textures to 2048 px or less before embedding them.
- Rebuild colliders as boxes. Unity colliders don't carry over. Rebuild the floor, walls and furniture as collision boxes (at most 64).
- Place the rig. Use your deck placeholder's position as the
rigAnchor, and your spawn point as the spectator spawn. - Write
mod.jsonand test in the headset.
Things to know:
- Unity scripts, prefabs, Visual Scripting, shaders, lightmaps and lights don't transfer. Only meshes, textures and simple material colours do.
- Baked textures work best. If your textures already have lighting baked in, use unlit materials so they look the same without any lights.
- Watch texture import settings. A Unity texture with sRGB turned off displays brighter in Unity than in Tribe unless you adjust it.
- Coordinates differ. Unity is Y-up in metres; Tribe is Z-up in centimetres. Mapping: Tribe
(X, Y, Z) = (−z, −x, y) × 100from Unity(x, y, z). - Disabled objects aren't exported. Switch on anything you want to keep before exporting.
- Deck height matters. Stock decks sit 94 cm above the DJ's floor, so the desk top should be at about that height or the decks float.
Collision and walking
- Scene geometry never collides; only the collision boxes do. Collision from mesh shapes isn't supported, so curved walls and furniture are approximated with several rotated boxes (max 64).
- You can't walk around a modded venue. Navigation for moving around the venue isn't supported, and mods can't add a walking controller. Use spawn points (above) to choose where people stand.
Getting it onto a headset
On a headset, connect it to a computer:
- Connect the headset to your computer with a USB-C cable.
- On the computer, open the headset's storage and find Tribe's Mods folder:
Documents/Modsinside the app's files folder. Settings > Mods in the headset shows the exact path. - Copy the package folder into it, then press refresh in Settings > Mods.
Some devices' storage settings may restrict transfers.
Or import from Dropbox:
- Log in to Dropbox in Tribe's music browser.
- In that Dropbox, put each package in its own folder under
/Tribe/Mods/, for example/Tribe/Mods/my-venue/mod.json. - Press refresh in Settings > Mods. New packages are imported into the Mods folder, start disabled and work offline.
Dropbox rules:
- Only new package IDs are imported. A package whose
idis already installed is skipped, even if its version is newer. To bring in a changed package, give it a newid. - Deleting a package from Dropbox doesn't uninstall it.
- Package folders must be flat and contain only
mod.json, GLB, PNG, JPEG and WAV files with ASCII names. ZIP archives are not supported. - Limits: 64 packages, 128 files per package, 8 MiB per file, 64 MiB per package and 256 MiB per refresh.
- A failed import leaves installed packages unchanged.
On PC: put the package folder in the Mods folder (Documents/TribeXR/Mods on Windows) and press refresh in Settings > Mods, which also shows the folder path.
In multiplayer, mods are never transferred: every player needs the identical package installed and enabled.
Restrictions at a glance
Not supported in environment mods: walking or navigation around the venue, scripts or custom logic, Unity or Unreal assets loaded directly, collision from mesh shapes, baked lighting, sky systems, terrain, spot lights, normal maps, animated meshes (skins, morph targets, animations), loading other maps, and automatic sharing of mods between players.
Limits to plan around
Limit | Value |
Scene nodes per package | 128 |
Mesh files per package | 8 |
Mesh and texture data per package | 32 MiB |
Triangles | 500,000 (meshes × instances) |
GLB file size | 8 MiB, one merged mesh per file, up to 16 materials and 8 embedded images |
Textures | 2048 × 2048 px and 4 MiB each; power-of-two sizes recommended |
Collision boxes | 64 |
Lights | 4 per package |
Enabled packages | 16 |
These are validation limits, not performance guarantees. Always test on Quest, the slowest supported device.
Troubleshooting
- Package not listed: check the folder sits directly in the Mods folder and contains
mod.json, then press refresh. - Validation error: read the field named on the package card. Common causes: a capability missing from
requires, an unknown field, or a number out of range. - Decks floating or sunk: adjust the
rigAnchorZ or the table height (the DJ floor is always 100 cm below the rig anchor). - Room too dark: add the booth light, or use unlit materials with baked textures.
- Update not appearing via Dropbox: the ID is already installed. Give the package a new
idand import it again, or copy the updated folder over from a computer.
Worked example: Tribe DJ Room
- Source: the Tribe DJ Room Template Unity scene (9 room sections sharing one 8K baked atlas, wall canvases, DJ table, vaporwave sky sphere).
- Output: 4–5 GLB files (about 7 MB in total), 54 collision boxes, one booth light.
- Two versions: Tribe DJ Room (skybox,
backdrop: none) and Tribe DJ Room (Passthrough) (no skybox,backdrop: passthrough), which shows back-wall visuals and your real world through the windows.