SUNRISE STUDIO

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

pathholds
bundle.jsonthe bubbles in order, and the far tiles, sky, sounds, music, creatures and Director map
<bubble>/bubble.jsonone bubble: spawn points, statics, lights, entities, volumes, doors, squads and crossings
<bubble>/*.glb, *.pngfiles that bubble.json names, relative to the bubble folder
other filesfiles 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

  1. Choose New > Destination. See Create a destination from an installed one.
  2. In World Import Bundle, pick bundle.json to place every bubble, or one bubble.json to place that bubble’s statics only.
  3. 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.
  4. Optionally tick Remove host content, so only the bundle shows. See Remove host content.
  5. Press Create.
picked fileStudio places
bundle.jsonbundle 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.jsonthat 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.

fieldStudio makes
glba model with the glb’s materials; see Which surfaces import
lods, lod_distancesup to two coarser copies that take over at those distances
draw_distancethe distance past which it does not draw
collisionthe glb it collides with; absent, its own glb; false, none
surfaceone collision surface material tag for all its triangles
occluderfalse 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": true on 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.

fieldmeaning
pngthe grid; image row 0 is the +Y edge; a cell with red at 128 or more is blocked
originthe grid’s -X, -Y corner; its Z is the walls’ base
cellcell size in metres
heightwall 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

partStudio makes
a bubble’s lightsa copy of a stock local light at each position, with the stock light’s colour and range
sky in bundle.jsona sky ring around the horizon with the panorama PNG, in the first bubble
far in bundle.jsona 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 plays field 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.

fieldmeaning
slota device slot of the source activity, by its name there, such as d_lure
positionthe 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.

fieldmeaning
actionthe action that fires the event
framethe frame of that action, from 0, at 30 frames a second
sounda bundle sound by name, or an installed sound event tag
effectan installed entity tag spawned on the frame; give this or sound
detachedtrue 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.

fieldmeaning
namethe name an event’s sound uses
wava mono or stereo 16-bit PCM wav
likean installed sound event; the new sound keeps its volume, falloff and containers
variationsmore wavs, played in turn where the like event varies its sound
switchesa wav per switch value name, for a like event that picks its sound by a switch
max_distancehow 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.

fieldmeaning
triggera player trigger of the source activity that has a volume, by its name there, such as pt_left_town
positionwhere the middle of the volume’s floor goes
sizeoptional: a box of this width, depth and height
cornersoptional, in place of size: 3 to 15 corners of a convex floor, as x, y offsets from position, in order
heightwith corners: how far the volume reaches up
yawoptional: 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.

fieldmeaning
nameprintable ASCII, 1 to 128 characters, unique in the bundle
positionthe middle of the box’s floor
size[width, depth, height], each above 0
yawoptional: 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}.

  • H is the FNV-1 hash of BUBBLE:NAME: the bubble’s folder name as bundle.json lists it, and the spawn point’s name. WorldContent.BundleSpawnSet(bubble, name) computes it.
  • R is 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.

fieldmeaning
tothe bundle bubble on the other side
linetwo or more points of the border; this bubble lies on the left seen from above; Z is the ground height
widthmetres 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.

fieldmeaning
nameunique in the destination; a mission script names the squad by it
entityan installed combatant entity tag, or creature: and a bundle creature’s name
countmembers per placement, 1 to 64; 1 by default
positionwhere 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.

fieldmeaning
glba skinned glb with named animations; each skinned mesh may have its own base colour image
donorthe installed combatant entity whose behaviour the creature keeps
clipsbehaviour to animation name; idle is required; the others are locomotion, fire, melee, throw, flinch, evade, death, reaction, spawn and ability
scale, yawglb units to metres, and a turn so the creature faces the donor’s forward
bones, followthe 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, healthmultipliers of the donor’s gun damage and hit points
display_namethe name plate text; every language then reads it in English
grenades, attackfalse removes the grenade ability; melee empties the weapon loadout, so the creature only closes in and melees
projectile, projectile_speedan installed projectile the gun fires instead, and its speed
capsulethe 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.

fieldmeaning
trackslooping tracks: a name, a PCM16 wav, and optional loop_start and loop_end sample numbers
likean installed music event to copy; without it, Studio picks one the destination’s music sensors name
bubblesthe track each bubble plays
combatthe 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.