Place a World Import Bundle
A World Import Bundle is a folder of content made outside Studio, mostly glb files, with JSON files that say where each piece goes. Studio places it in a new destination when you create one. This page says what Studio makes from each part of a bundle.
The format is a draft and may change. src/SunriseStudio.World/Import/world-import-bundle.v1-draft.schema.json
in the Sunrise Studio source is the exact contract and describes every field. If this page and the
schema differ, the schema is right.
Lay out the bundle
| path | holds |
|---|---|
bundle.json | the bubbles in order, and the far tiles, sky, sounds, music, creatures and Director map |
<bubble>/bubble.json | one bubble: spawn points, statics, lights, entities, volumes, doors, squads and crossings |
<bubble>/*.glb, *.png | files that bubble.json names, relative to the bubble folder |
| other files | files that bundle.json names, relative to the bundle folder |
{
"bubbles": ["bubble_a", "bubble_b"],
"space": "shared",
"sky": { "panorama": "sky/dome.png" },
"sounds": [{ "name": "door_open", "wav": "sounds/door_open.wav", "like": "0x80F5D86D" }]
}
Lengths are metres and angles are degrees. Axes are the game’s: Z up. Export each glb from Blender
with +Y Up on; Studio reads it back as Z up, so a scene built Z up in Blender arrives unchanged.
Studio never converts units or axes. A quaternion is [x, y, z, w]. A yaw turns about +Z, and 0
faces +X. A tag is an installed tag in hex, with or without 0x.
Place it
- Choose New > Destination. See Create a destination from an installed one.
- In World Import Bundle, pick
bundle.jsonto place every bubble, or onebubble.jsonto place that bubble’s statics only. - Read the problems listed under the fields. Studio checks the bundle when you pick it and shows the first five. Create stays off until the bundle is valid.
- Optionally tick Remove host content, so only the bundle shows. See Remove host content.
- Press Create.
| picked file | Studio places |
|---|---|
bundle.json | bundle bubble 1 in the first kept bubble with states, bubble 2 in the second, and so on, then the bundle-wide parts; with more bundle bubbles than kept bubbles, Studio adds bubbles |
bubble.json | that bubble’s statics in the first kept bubble |
A problem is listed as file: path: message, for example bubble_a/bubble.json: statics[2].glb: missing. Some checks need the installed game and run only at import: a tag must be installed and
of the right kind, and a trigger, device slot or action name must exist.
Where each bubble lands
The first spawn point of a bundle bubble anchors it. Studio moves the whole bubble so that point lands on the first spawn point of its destination bubble, facing the same way.
With "space": "shared" in bundle.json, every bubble uses the first bubble’s space. The first
bubble’s first spawn point lands on the destination’s first spawn point, with no turn, and the
bubbles keep their places relative to each other. anchor picks another point to land there. Keep
the whole bundle inside the host map’s extents: the game draws nothing for a player far outside
them.
Statics
Each entry of a bubble’s statics is a glb placed at a position, rotation and scale.
| field | Studio makes |
|---|---|
glb | a model with the glb’s materials; see Which surfaces import |
lods, lod_distances | up to two coarser copies that take over at those distances |
draw_distance | the distance past which it does not draw |
collision | the glb it collides with; absent, its own glb; false, none |
surface | one collision surface material tag for all its triangles |
occluder | false keeps it out of the occlusion bake |
Distances are at the default field of view. Without them, Studio sets them from the mesh size.
A large static is cut into chunks of about 131 m, so its positions stay within a millimetre. Each chunk is its own model, and the chunks share placement lists of up to 512 rows. Statics in one package share a material when their textures, factors and alpha mode match.
A package holds 8,192 entries; the import starts a new package when one is full. The game crashes at sign-in when the named-tag data of a mod’s new packages passes about 2 MB in total. Studio writes only the names the game looks up, so this is rarely reached.
Collision, occlusion and nav meshes
Studio bakes each bubble after it places it.
- Collision. The statics and walls of a bundle bubble collide through one new collision entity in the bubble they land in. The bubble’s stock collision does not change. Each triangle takes the surface material and collision filter of the nearest stock triangle within 32 m, else the material installed collision uses most.
- Occlusion. A static’s closed meshes join the bubble’s occlusion as occluders. A mesh is closed when every edge belongs to exactly two triangles. Open meshes, such as terrain, never occlude.
- Nav mesh.
"nav": trueon a bubble bakes a nav mesh from its collision triangles, for enemies to find paths over.
To bake again after you change a bundle, choose Build > Bake collision and occlusion. It bakes
every placed bubble whose bubble.json or named files changed since its last bake. Build > Bake
all again bakes every one. The bake records live in bakes.json beside the project file.
Static collision internals has the format.
Invisible walls
A bubble’s permissions is a grid of invisible walls drawn as a PNG of square cells.
| field | meaning |
|---|---|
png | the grid; image row 0 is the +Y edge; a cell with red at 128 or more is blocked |
origin | the grid’s -X, -Y corner; its Z is the walls’ base |
cell | cell size in metres |
height | wall height in metres |
Each edge a blocked cell shares with an open cell, or with the grid border, becomes a wall. The
walls collide like the statics. A bubble with permissions needs statics, even an empty list.
Lights, sky and far tiles
| part | Studio makes |
|---|---|
a bubble’s lights | a copy of a stock local light at each position, with the stock light’s colour and range |
sky in bundle.json | a sky ring around the horizon with the panorama PNG, in the first bubble |
far in bundle.json | a far tile: stand-in geometry for distant bubbles |
A far tile keeps the triangles over the bubbles it covers, plus a margin, and sinks below the near
geometry. Every outdoor bubble ("kind": "outdoor") that does not stream the covered bubbles draws
it. So the tile shows from a distance, and the real bubble replaces it on entry. Each covered bubble
needs bounds.
Whether lights, far tiles and the sky show as intended in game is unverified. Native authoring profiles has the data each one writes.
Animated entities
Each entry of a bubble’s entities is a new animated entity built from a skinned glb.
- The glb holds one skinned mesh of one primitive, its armature, and named actions.
- Joint names are unique. A vertex takes up to four weights. The armature has at most 256 joints.
- Each action becomes a clip of its name, sampled at 30 frames a second.
- The entity loops the action its
playsfield names. Nothing switches clips. - One installed material draws it: a stock brown one, or the tag in
material. The glb’s own materials and textures are not imported. - Entities do not collide. The server does not know them.
To show and hide a part, weight it to its own joint and key that joint’s scale between 1 and 0.001 with stepped interpolation. Two parts keyed in turn give a blink.
Works in game: entities with up to 7 joints and 7 clips draw, animate and cast shadows.
Devices
An entity with a device field does not loop an action. A mission script moves it instead, such as
a door.
| field | meaning |
|---|---|
slot | a device slot of the source activity, by its name there, such as d_lure |
position | the action the slot’s position channel scrubs: 0 shows its first frame, 1 its last |
The script sets the slot’s position channel with set_channel. The device moves toward the value
at a fixed rate; the full range takes 10 seconds. Without a script it holds the action’s first
frame. A device has one moving channel: the power and lock channels move nothing, so put all the
motion in the one action. Studio gives the destination its own copy of the slot. Each slot drives
one entity, and only slots of the kept bubbles exist.
Works in game: a door opens and closes this way.
Events
An entity’s events make an action post a sound or spawn an effect on a frame.
| field | meaning |
|---|---|
action | the action that fires the event |
frame | the frame of that action, from 0, at 30 frames a second |
sound | a bundle sound by name, or an installed sound event tag |
effect | an installed entity tag spawned on the frame; give this or sound |
detached | true spawns the effect as its own object, which stays where it appeared |
A looping action fires its events on every pass. A device fires an event when its channel moves the action past the frame. Works in game: a detached effect appears at a looping entity and at a device door. Whether a sound plays is unverified.
Sounds
sounds in bundle.json adds sound events that entity events can name.
| field | meaning |
|---|---|
name | the name an event’s sound uses |
wav | a mono or stereo 16-bit PCM wav |
like | an installed sound event; the new sound keeps its volume, falloff and containers |
variations | more wavs, played in turn where the like event varies its sound |
switches | a wav per switch value name, for a like event that picks its sound by a switch |
max_distance | how far the sound carries, in metres |
Pick a like event that is used the way yours will be, such as a door sound for a door. The import
refuses a like event that has no container for the variations, switches or max_distance you
give. Audio internals has the bank
layout.
Trigger volumes
A bubble’s volumes moves player triggers of the source activity into the bubble.
| field | meaning |
|---|---|
trigger | a player trigger of the source activity that has a volume, by its name there, such as pt_left_town |
position | where the middle of the volume’s floor goes |
size | optional: a box of this width, depth and height |
corners | optional, in place of size: 3 to 15 corners of a convex floor, as x, y offsets from position, in order |
height | with corners: how far the volume reaches up |
yaw | optional: turns the floor about position |
With neither size nor corners, the volume keeps its own shape and only moves. Find a trigger on
the Triggers page of the World window. With size or corners, Studio writes a new shape, and the
trigger’s own volume must have a four-cornered floor (4 vertices on the Triggers page). Studio gives
the destination its own copy of the volume.
A mission script arms the trigger with fire_trigger and hears the player enter through
on_event_player_trigger. Works in game: a moved volume reports the player, and the script can
then open a door or teleport the player.
Doors
A bubble’s doors adds new box triggers, so you do not need a trigger of the source activity.
| field | meaning |
|---|---|
name | printable ASCII, 1 to 128 characters, unique in the bundle |
position | the middle of the box’s floor |
size | [width, depth, height], each above 0 |
yaw | optional: turns the box about position |
Each door is a player trigger slot door.<name> with its volume slot door.<name>.volume. Studio
adds objects of its own to hold them, 600 to an object. A trigger reports only after the script
arms it with fire_trigger, and then on every update while the player stays inside. So disarm it
on the first report. Arm a door once the client holds its region.
-- Each door's target: a region (8 * bubble row) and a spawn set hash.
local DOORS = {["route102:0"] = {region = 8 * 51, spawn_set_hash = 0x1234ABCD}}
return {
on_event_region_changed = function(context, state, event)
for name in pairs(DOORS) do context:slot("door." .. name):fire_trigger() end
end,
on_event_player_trigger = function(context, state, event)
local name = event.slot and event.slot.name:match("^door%.(.+)$")
local door = name and DOORS[name]
if door == nil then return end
event.slot:disarm_trigger()
context:teleport{region = door.region, spawn_set_hash = door.spawn_set_hash}
end,
}
Teleport targets
A spawn point with a name becomes its own spawn set in its bubble. A mission script moves the
player there with context:teleport{region = R, spawn_set_hash = H}.
His the FNV-1 hash ofBUBBLE:NAME: the bubble’s folder name asbundle.jsonlists it, and the spawn point’s name.WorldContent.BundleSpawnSet(bubble, name)computes it.Ris 8 times the destination bubble’s scenario row.
/* FNV-1, 32-bit, over the UTF-8 bytes. */
uint32_t h = 0x811C9DC5;
for (each byte b) { h *= 0x01000193; h ^= b; }
For example, bubble_a with a spawn point named arrival gives H = FNV-1("bubble_a:arrival").
Crossings
A crossing is a border two outdoor bubbles share. The player walks across it and the game switches
bubble on its own, with no teleport and no script. Use a door for an interior. Crossings need
"space": "shared", and both bubbles need bounds.
| field | meaning |
|---|---|
to | the bundle bubble on the other side |
line | two or more points of the border; this bubble lies on the left seen from above; Z is the ground height |
width | metres between the two switch lines, 4 or more; 8 by default |
List each pair once, in either bubble.
- Switching. Past half the width beyond the line, the game switches to the neighbour once it has loaded. Between the two switch lines neither side switches, so the player never flips back and forth.
- Streaming. Each bubble loads its neighbours’ statics and collision, so the other side is
there before the switch. Entities, lights, sky and spawn points stay in their own bubble. Do not
also list a crossing neighbour in
neighbours, or its statics draw twice. - Arrival. Each crossing gets one spawn set, the FNV-1 hash of
FROM:TO:crossing, with one point on each side.
The import refuses a bubble that would load more than 1,024 placement lists with all its neighbours, because the game crashes above that. Works in game: crossings switch both ways.
neighbours lists bundle bubbles that also draw this bubble’s statics, without a crossing.
Squads and creatures
A bubble’s squads adds new squads. Each squad copies one installed enemy, or a bundle creature.
| field | meaning |
|---|---|
name | unique in the destination; a mission script names the squad by it |
entity | an installed combatant entity tag, or creature: and a bundle creature’s name |
count | members per placement, 1 to 64; 1 by default |
position | where the squad spawns |
A mission script places a squad by its name, from the public instance, after the player arrives:
local squad = context:squad("wild_pooch")
squad:place{counts = squad:counts(), mode = ...}
Each bubble’s squads also
get a combat objective, the slot bundle_squads_<n>.objective, where n is the bubble’s place in
bubbles from 0. Its firing area is one box around the squads. A squad moves only inside the
firing area of an objective a script assigns it with assign_combat_objective. Whether squads move
over a baked nav mesh is unverified.
creatures in bundle.json builds enemies with their own skeleton, mesh, texture and clips over an
installed enemy, the donor. A creature keeps the donor’s behaviour, weapons, health and name
unless you change them. The donor’s own model, cape and gun do not draw.
| field | meaning |
|---|---|
glb | a skinned glb with named animations; each skinned mesh may have its own base colour image |
donor | the installed combatant entity whose behaviour the creature keeps |
clips | behaviour to animation name; idle is required; the others are locomotion, fire, melee, throw, flinch, evade, death, reaction, spawn and ability |
scale, yaw | glb units to metres, and a turn so the creature faces the donor’s forward |
bones, follow | the glb bones for the head, hands and feet, and donor rig points moved onto glb bones; hit shapes, the name plate and shots follow them |
damage, health | multipliers of the donor’s gun damage and hit points |
display_name | the name plate text; every language then reads it in English |
grenades, attack | false removes the grenade ability; melee empties the weapon loadout, so the creature only closes in and melees |
projectile, projectile_speed | an installed projectile the gun fires instead, and its speed |
capsule | the physical body: radius and height in metres; height at least 0.3 plus twice the radius |
Shots land on one box around the creature’s idle pose, so a creature has no head hits. A capsule radius of 1 can make the creature fall through the ground. Works in game: a creature placed by a squad stands at its position and fights.
Music
music in bundle.json is provisional; its shape may still change.
| field | meaning |
|---|---|
tracks | looping tracks: a name, a PCM16 wav, and optional loop_start and loop_end sample numbers |
like | an installed music event to copy; without it, Studio picks one the destination’s music sensors name |
bubbles | the track each bubble plays |
combat | the track that plays while a squad fights the player |
Studio writes a new music bank and event, and points every music sensor of the destination at them.
Track N is section N of each sensor, so a mission script picks a track with set_music_section.
bubbles and combat are checked but not applied yet. Whether the music plays in game is
unverified.
Landing zones
A bubble’s landings names Director landing zones on its named spawn points. map and planet in
bundle.json give the Director map and planet. New > Director entry reads them. See
Add the destination to the Director.
Limits
- A bundle goes into a new destination only. It cannot be placed into an installed map.
- Entities only loop one action or follow a device channel.
- A placed static can be moved but not copied or removed. See Open your destination.
- Unverified in game: lights, the sky, far tiles, sounds, music, and squads moving over a baked nav mesh.