Build downloadable theme parks for the real world.

The DreamPark SDK is a Unity 6 project on GitHub. Clone it, open it, set a content ID, build your attraction, script gameplay in Lua, and publish from the editor — your build downloads to DreamPark headsets from there.

Best practices

Read this first — it's the short list that separates attractions that thrive in real spaces from ones that don't:

• Write gameplay in Lua. XLua exposes Unity's API through the CS namespace, LuaBehaviour covers the lifecycle and physics hooks you'd use in a MonoBehaviour — and Lua ships over-the-air, instantly. New C# has to be manually reviewed and waits for a future app release. Scripting in Lua.
• Build for hand tracking and physical movement. Guests walk around a real room with their hands. Don't design around controllers, keyboard input, or stationary play — none of that exists in a DreamPark play space.
• Design for 5 to 60 minute sessions. Most attractions sit somewhere in that range. Long onboarding, slow tutorials, and complex menus are friction in a setting where guests are paying for time.
• Whatever ships has to just work. Guests can't reset, restart, or troubleshoot. Test on a real Quest 3S or Quest 3 before publishing.
• Keep builds lean. Use the Optimization tools and Manage Third Party Assets to strip out anything you're not using. Every megabyte downloads to every headset.
• No undisclosed data collection. Don't build your own analytics, telemetry or tracking into an attraction.

Overview

DreamPark is a mixed-reality theme park platform. It turns real spaces into fully virtual attractions — hours of entertainment for visitors carrying nothing but a Quest 3 headset. No wearables, no controllers, no installed hardware per attraction.

What makes that work is the part no one else does: attractions from different developers run side by side in the same space. An operator sets up and manages their whole lineup in minutes from a simple mobile app, mixing your attraction with everyone else's. Your build downloads to the headset, runs there, and earns you a share of DreamPark's revenue, split by how much guests play it.

The SDK is the framework you use to build those attractions. It's a complete Unity 6 project — clone it, open it, and your content lives under Assets/Content/. Everything else in the project is platform plumbing that keeps your build compatible with DreamPark: headsets, hand tracking, the in-game DreamBand UI, payment kiosks, networking, and so on. The SDK is released alongside the main DreamPark app and you pull updates when we ship them.

Quick start

1. Clone the SDK from GitHub — https://github.com/Future-Circus/dreampark-sdk (clone command above). The repo is public. Run git lfs install first, then open the folder in Unity 6000.3.23f1 via Unity Hub → Add.
2. Set your content ID. Once packages have resolved, a setup popup asks you to pick a unique identifier for your game (e.g. CoinCollector). This renames the starter folder under Assets/Content/ for you.
3. Sign in: DreamPark → Sign In. Enter your email, then the 6-digit code we send you. There's no separate sign-up — the first code you verify creates the account.
4. Open Assets/[StartHere].unity — it opens by itself the first time the project comes up, with the Meta camera rig, hand tracking, passthrough and occlusion already wired. Press Play — you're in the starter scene. (Want a different scene on launch? DreamPark → Startup Scene...)
5. Create your attraction. Drop an AttractionTemplate, pick a size, drag in props. More below.
6. Script gameplay in Lua with LuaBehaviour — the same hooks as a MonoBehaviour, and it releases instantly. More below.
7. Test on a Quest. Put a Quest 3S or Quest 3 in Developer Mode, connect over Quest Link (USB-C data cable) or Air Link, accept the prompts in the headset, press Play, and check passthrough and hand tracking work.
8. Publish. Open DreamPark → Content Uploader, fill in name/description/logo, click Upload Release, write release notes, then Start · All in the launch window. More below.
9. Play it. Open the DreamPark iOS app (private TestFlight beta — email aidan@dreampark.app for an invite) and turn on Experimental Mode in your park settings. New uploads show up there right away.

Requirements

• Unity 6000.3.23f1. The SDK is pinned to this exact version so local, CLI and release builds use the same toolchain. If Unity Hub says "Editor version not found", install that exact editor.
• Unity build support modules: Android (with its OpenJDK and Android SDK & NDK sub-modules) and iOS — the uploader builds both on every release and neither can be switched off. Add Mac and Windows build support too: those editor targets are on by default in the upload window and are required for an official release.
• Git LFS. The SDK's art, audio, models and native plugins live in LFS. Run git lfs install before cloning — without it the clone appears to work but every binary arrives as a text placeholder. Already cloned without it? Open the project and run DreamPark → Troubleshooting → Check Git LFS — it finds the placeholders and downloads the real files (the SDK also checks when the project opens).
• A DreamPark developer account for the Content Uploader and publishing. Sign-in is passwordless: enter your email, then the 6-digit code we send you — verifying it creates the account if you don't have one. Developer program details here.
• Git. You'll clone the SDK from GitHub.
• A Meta Quest 3S or Quest 3 in Developer Mode, plus a USB-C data cable (not charge-only) for Quest Link.
• macOS or Windows for development.

Project structure

The project is one Unity 6 solution. Everything you build lives under Assets/Content/<your-content-id>/; everything else is the SDK and Unity itself. Hover the highlighted rows to see what each core piece does.

Your content is made of three pieces: a persistent Player, your Attractions (A_*.prefab), and their Props (P_*.prefab). Multiple content folders can coexist in one project — each is its own independent package, and the Content Uploader's dropdown picks which one to publish. Two names are reserved and can't be published: Sample, and the template placeholder before you rename it.

The template ships a Player.prefab and a starter Attraction.prefab. For fuller examples, open Assets/Content/Sample/ — a complete worked project with two attractions (A_TestAttraction and A_DreamSequence), five props, its own scene and the Lua behind them.

Set your content ID

The first time you open the project, the Content ID Setup popup walks you through picking a unique identifier for your attraction. The ID:

• Must start with a letter
• Can contain letters and numbers only — no dashes, spaces, underscores or dots
• Must be between 2 and 64 characters

The popup renames the starter folder from the template placeholder to Assets/Content/<your-id>/ and keeps Unity GUIDs intact so nothing in the scene breaks. Pick something short and final — this is the canonical ID used to publish your game. If you're signed in, the popup also checks that no other developer already owns the name.

If the popup comes back, the template folder YOUR_GAME_HERE is still on disk. Rename or delete it (see Troubleshooting).

Create your first Attraction

Open Assets/[StartHere].unity. The Meta camera rig, hand tracking, passthrough and occlusion are already wired up, along with your Player.prefab, a starter Attraction.prefab and a few [EXAMPLE] objects. Build here, and don't delete the building blocks.

An Attraction is a prefab with an AttractionTemplate component on its root (naming convention: A_MyAttraction.prefab). The template auto-attaches a GameArea (the playable boundary that detects guests — and measures the playtime your revenue share is based on) and a MusicArea (an audio zone). Drop one into the scene, then pick a size from the inspector. Sizes are given in feet and run Micro (14×16 ft) → Boutique → Small → Square → Medium → Large → Jumbo (120×150 ft), plus MallCorridor (30×260 ft) for long thin spaces and Custom for anything else.

The Attraction template can auto-generate the floor mesh for you, so you don't have to model it yourself unless you want to. (There's also a generateCeiling toggle in the inspector — it's legacy and does nothing now. Ceilings are handled globally by the player rig's depth-mask plane rather than per attraction, so you can ignore it.) When it's ready, save it as a prefab under Assets/Content/<your-id>/Prefabs/ — a transparent preview tile is generated automatically for every attraction, so it shows up in the app with tile art. To refresh one after you change the prefab, run DreamPark → Troubleshooting → Regenerate Level Previews. Open A_TestAttraction under Assets/Content/Sample/Prefabs/ to see a working example.

Create your first Prop

Props are interactive bits between attractions — they let operators fill tight hallways with collectable coins, or add environmental detail around core attractions. A Prop is a prefab with a PropTemplate component on its root (naming convention: P_MyProp.prefab), which carries a calibration Y-offset so the prop sits correctly on the floor in real spaces.

Props also work inside your attractions: drag a prop prefab in, position it, and it's hooked in. Behind the scenes the SDK rebuilds the floor gap mesh and re-bakes the NavMesh (what any NavMeshAgent enemies path on) when you change the attraction or its props — you don't manage that yourself. Preview tiles are generated for props too.

The bundled Sample ships five example props under Assets/Content/Sample/Prefabs/ — P_DreamPortal, P_Enemy, P_Pit, P_TestPoint and P_TestProp. Open them to see how working props are put together, and copy them into your own folder to build from.

How your content gets addressed

You never assign addressable addresses or labels — the SDK stamps them from your prefabs every time it processes your content folder, and hand-editing them in the Addressables window will be overwritten. It's worth knowing the shape, though, because it explains one confusing failure:

The backend classifies your content by that address, not by the file name. Anything with a Levels/ address is an attraction; anything with a Props/ address is a prop. The A_ and P_ prefixes are still the convention and still worth following for your own sanity, but they aren't what's checked.

So if an attraction doesn't show up in the Attractions browser after a publish, the thing to check is the component on the prefab root — an AttractionTemplate is what produces a Levels/ address in the first place. Renaming the file won't fix it.

Customize your Player

Player.prefab (under Assets/Content/<your-id>/Prefabs/) is the root player object, already placed and wired into the starting scene. It persists across attractions, so anything you attach to it survives scene loads. Use it for things that belong to the guest and should outlive a single attraction — hand-held tools, damage effects, per-player audio — attached as LuaBehaviours. Title-wide rules, progression and shared state go in your Game Manager when your title runs as a package. How the rig is built and loaded: The Player rig.

Next SDK Putting a blaster, wand, sword or phone in the guest's hand? Read Hand-held objects first — the hand's axes on a headset aren't what the Editor used to show, and dp.hold does the mounting for you.

Hand-held objects New in the next SDK release

Blasters, wands, swords, torches, phones, balls — anything a guest holds. This is the one part of a DreamPark game where the Editor and the headset used to disagree: a prop hung under the hand with no rotation looked right in Play mode and came out rolled 90° on a Quest, top pointing out of the back of the hand and handle sticking out of the palm. Three shipped games hit it. The fix is a convention for authoring the prop and one Lua call that mounts it.

The hand frame on the headset

Your rig's hand nodes (HandTracker on LeftHand / RightHand / BothHands, and the RemoteRig hands) follow the OpenXR wrist joint. Its axes are the same for both hands, which is exactly why one rotation can't be right for both:

The origin is the wrist. A prop lands on one of two targets, in metres: the fist centre (the power-grip axis under the middle finger) at (−0.007, −0.033, 0.081) right / (+0.007, −0.033, 0.081) left, or the palm surface at (0, −0.022, 0.064) for both hands. DreamPark is hand-tracking only — never design a prop around controllers, whose anchor has different axes.

Author the prop: Grip, Muzzle and friends

prefabMyBlaster       root: the object. No hand rotation baked in, scale 1
├── Model       the art. Import-axis fixes (rotation, scale, offset) live HERE
├── Grip        lands on the fist centre. +Z = where the fingers point, +Y = the thumb side
├── PalmGrip    instead of Grip, for things resting on the open palm (phone, tray, ball)
├── GripLeft    optional: what the left hand uses instead (PalmGripLeft for palm props)
├── Grip2       optional: where the off hand holds a two-handed prop
└── Muzzle      barrel tip or emitter. +Z = the shot direction (skip it if nothing shoots)

• The Grip pose is the hold. The mount maths never changes — the Grip lands on the fist centre with its +Z along the fingers and +Y on the thumb side — so a gun, a wand and a sword differ only in where their Grip sits and how it's turned. See the archetypes below.
• Never use a negative scale to mirror a prop for the left hand. It breaks colliders, particle shapes, lighting and transform.right. The mount is a rotation, so anything symmetric left-to-right (guns, swords, wands, balls) needs nothing; anything with a face toward the palm (a phone screen, a shield, a watch face) gets a GripLeft / PalmGripLeft, normally the same point rolled 180° about its +Z.
• Recoil, kick and spin go on Model, in the prop's own axes. The mount owns the root.

Archetypes: the hold is data in the Grip

Grip rotations are Unity Euler angles for the right hand; positions are in the prop's normalised frame (+Z forward, +Y up). Device-proven holds were approved on a Quest; derived ones were computed from Meta's hand data and haven't been confirmed on a device yet — render them and try them.

Hold it from Lua

lua-- blaster.lua.txt, on the blaster prop
-- @var model transform

function start()
    dp.hold(self.gameObject, 'active')   -- whichever hand is in use; re-mounts when that changes
end

function fire()
    local origin, dir = dp.muzzle(self.gameObject)   -- read it on every shot, never cache it
    spawn_bolt(origin, dir)
    kick(model)                                      -- recoil goes on Model, never on the root
end

• What other players see mounts itself. Put the remote copy under RemoteRig/RightHand, RemoteRig/LeftHand or RemoteRig/Hand (see RemoteRig). Any object with a Grip child directly under one of those is mounted for that side automatically — Hand follows that player's active hand. No script on the copy.
• The template's … Handheld Pivot children are re-posed to the Grip pose: right (−0.007, −0.033, 0.081), Euler (0, 0, 90); left (0.007, −0.033, 0.081), Euler (0, 0, −90). A Player.prefab copied from an older template still has the old pose — (±0.022, −0.019, 0.1), Euler (0, −90, −98.6) — which points a barrel up along the thumb. Re-pose it, or skip the pivot and use dp.hold, which works under any hand node.

The Editor now matches the headset

The Scene-view Simulator and the AI Playtester pose both hands in the device wrist frame — a relaxed pistol grip pointing where you look — so a correct mount looks correct in Play mode. Older SDKs copied the head's rotation onto both hands, so a correct mount looked rolled 90° and a "fixed" one was wrong on the headset. If your Lua compensated for that, remove the compensation, or gate it so it still runs on an older SDK:

lualocal old_editor_hands = dp.editor_hand_frame == nil or dp.editor_hand_frame() ~= 'device'

Play mode is still only a first look. The render and a device test below are the acceptance test.

HandheldKit

An editor tool for getting any imported model — FBX, GLB, Blender, Meshy, Asset Store — into the convention. It's a builder, Tools/Builders/Handheld/HandheldKit.cs, run through the Unity CLI (Tools/agent/u.sh run_script --file Tools/Builders/Handheld/HandheldKit.cs --entry HandheldKit.<Fn> --args '[…]'):

Check it — both hands, every time

1. HandheldKit.Validate passes on the prop.
2. HandheldKit.Render with both — and look at every view. Gun: the fist rides the lower handle, body above the knuckles. Wand: the shaft runs out between thumb and index, leaning toward the thumb. Sword or axe: the handle goes through the fist, the blade or head sits above the thumb. Palm: the face is visible from the palm side.
3. HandheldKit.ValidateRig passes on your Player.prefab.
4. The Hand-held props pre-upload check (handheld-convention) comes back clean, or each finding is explained.
5. Play mode: no Lua errors, the right prop showing in the right hand, the Muzzle firing forward.
6. On a Quest: both hands, pointing at something, with a second player watching you. The bar is "it feels like it's in my hand".

The full reference — the measurements, flipVisual setups, and what each hold was proven on — is HANDHELD.md at the root of the SDK repo.

Scripting in Lua

Write your gameplay in Lua. All of it. The SDK is built around XLua, and the gameplay you'd write in a MonoBehaviour you can write in a LuaBehaviour:

• XLua exposes Unity's API through the CS namespace. CS.UnityEngine.Vector3.up, CS.UnityEngine.Time.deltaTime, CS.UnityEngine.Object.Instantiate(prefab). Call methods with : (self.transform:Rotate(v)), and use GetComponent(typeof(CS.UnityEngine.Renderer)) instead of generics. Two limits on headsets: the app blocks file, network, reflection and threading APIs, plus Resources and PlayerPrefs (save data goes in storage); and a Unity type the app hasn't compiled a wrapper for can work in the Editor but fail on a headset. The uploader flags blocked types.
• Lifecycle and physics hooks are plain functions. awake, start, update, fixedupdate, lateupdate, onenable, ondisable, ondestroy; ontriggerenter/exit/stay(other) and oncollisionenter/exit/stay(collision); onapplicationpause/onapplicationfocus. DreamPark adds onready() (the world is placed and enabled), onzoneenter()/onzoneexit() (the guest entered or left this attraction), onlayout(frame_id, scale, footprint)Next SDK (the attraction's applied layout frame — 'base', 'minimum' or a custom id —, its frame scale and its footprint in metres, both Vector2 x/z; sent once after start() and again whenever the app re-fits the attraction), and onnet/onmessage for networking. Define only what you use — undefined hooks cost nothing. Do positional or cross-object work in start() or onready(), not awake(), which runs before the object is placed.
• Component access works as you'd expect — self.transform, self.gameObject, self:GetComponent(...) — plus inspector-injected references (GameObjects, AudioClips, other scripts) that appear as variables in your script.
• Lua releases instantly. Scripts are data, not compiled code — they push over-the-air to live headsets without an app rebuild. Guests pick up new behavior on their next session.

Add a LuaBehaviour component to any GameObject and point it at a .lua.txt file under Content/<YourGame>/Scripts/:

lua-- coin.lua.txt: a spinning coin any hand can collect
local rotateSpeed = 90  -- degrees / sec

function update()
    self.transform:Rotate(CS.UnityEngine.Vector3.up * rotateSpeed * CS.UnityEngine.Time.deltaTime)
end

function ontriggerenter(other)
    if dp.is_player(other) then
        sparkle:Play()          -- injected ParticleSystem
        scoreManager.add(1)     -- injected LuaBehaviour on the Player
        CS.UnityEngine.Object.Destroy(self.gameObject)
    end
end

Declare inspector fields with a comment at the top of the script: -- @var name type [default]. Types: gameobject, transform, component, script, audioclip, material, sprite, texture, vector3, color, float, int, bool, string and list (a list of GameObjects). Defaults apply to numbers, bools and strings; everything else is set in the Inspector. An injected script arrives as that script's Lua scope, so you call its functions directly. Picking a script auto-adds its fields, and ↻ Sync from Lua rebuilds the list while keeping existing values.

Use dp.is_player(other) to test for the guest, and don't hand-roll it. It checks rig ancestry first — anything under the PlayerRig is the player whatever its tag or layer say — and falls back to the Player tag and layer. The version creators tend to write, other.tag == "Player" or other.gameObject.layer == LayerMask.NameToLayer("Player"), is already wrong against our own rig: the shipped Player.prefab's colliders are Untagged on the Default layer, so that test misses the guest entirely. There is also no Hand tag at all. In oncollisionenter(collision), pass collision.collider — a Collision itself always returns false. Tags are for prop-to-prop dispatch, from the roster in the project's Tags & Layers.

The dp API

dp is a global table in every Lua script — nothing to require, nothing to find. It exists so that the handful of things every attraction needs (where is the guest, which attraction am I in, who else is here) don't each get hand-rolled into a slightly different pcall around CS.*.

Three of its branches have their own sections: dp.profile, dp.storage (and each script's own storage), and dp.score for leaderboards. The rest is here.

The guest

dp.is_player is the one to use rather than a tag or layer test — Scripting in Lua explains why the hand-written version is wrong against our own rig.

Finding your way around

Reaching another script shouldn't require knowing its C# component type. These walk the hierarchy for you, and reading a scope boots that script if it hasn't run yet — so a cross-script reference never depends on Awake ordering.

Session & players

Full detail in Players in the park and Coordinates & the park frame; this is the index.

Hand-held props New in the next SDK release

All of it in Hand-held objects. On an app older than the release these new functions are nil; test for them (if dp.shared_state then) when a title must run on both.

Third-party assets

You'll bring in art packs, audio libraries, shaders, plugins, and the like from the Asset Store or external sources. Park them in your content folder's ThirdPartyLocal/ — it's stripped from builds, so it's a safe staging area to experiment. If an import lands elsewhere, Assets → DreamPark → Move to ThirdPartyLocal relocates it, and DreamPark → Relocate ALL stray packages to ThirdPartyLocal sweeps every vendor folder that landed at the root of Assets/. Note that despite what a few places still claim, this folder is not gitignored — keep it out of your commits yourself.

When you're actually using a third-party asset, move it into your content folder so it ships with your build. Don't shuffle files by hand — the SDK ships a tool that does it for you:

menuDreamPark → Manage Third Party Assets

This tool — ThirdParty Sync — looks for anything in your project that references a file in your content folder's ThirdPartyLocal/, follows those references and their dependencies, and moves them into Assets/Content/<your-id>/ThirdParty/. If a referenced script belongs to a package's assembly, it brings the rest of that assembly's scripts too, so the code still compiles. It preserves Unity GUIDs so prefab and scene references don't break. The same sync runs automatically every time you upload, and the window has an Auto-sync on Play toggle, so you can let it handle the move if you'd rather not think about it.

Why bother? Anything in ThirdPartyLocal/ doesn't ship in your build. Anything in your content folder's ThirdParty/ does. The sync tool draws that line cleanly.

Materials & shaders

DreamPark is mixed reality. Every pixel of virtual geometry has to be clipped by the guest's real room — their hands, their furniture, the walls — using Meta's Depth API. That integration lives in the shader, which makes shader choice a correctness requirement rather than an art preference.

Use one of these three for every material you ship:

Never ship Standard, URP-Lit, URP-Unlit, or a marketplace or asset-pack shader. They compile fine and they look fine in the Editor. The failure only appears on a headset, in passthrough, where the object refuses to be occluded and draws straight over the guest's hands and furniture.

Opaque materials must have Alpha Clipping on

This is not a default and not a preference — it's enforced, and it's the one that catches everybody.

The occlusion subgraph drives its result into the fragment's alpha. A Transparent surface consumes that alpha through its blend, so occlusion just works. An Opaque surface has nothing downstream that reads alpha — the clip is the only consumer. With Alpha Clipping off, the occlusion value is computed, written, and thrown away, and the material renders at full opacity over the real world.

There are also three pieces of state, and any of them can disagree. _AlphaClip is the float the inspector draws; _ALPHATEST_ON is the keyword that actually selects the clipping variant; _alphaClipping is the threshold, and at 0 it clips nothing, so clipping can be "on" in both of the others and still throw occlusion away. Assigning a shader to an existing material carries over same-named floats and the old keyword set, so a converted material routinely lands with one on and the other off — including the case where the toggle reads ON in the inspector while the shader isn't clipping at all. Never test just one: DreamParkMaterialRules.IsSatisfied(mat) checks all three, and it's what the upload gate uses.

Two smaller things worth knowing:

• There is no _Cutoff. That's URP Lit's name, and a Shader Graph doesn't get one for free. The clip threshold is _alphaClipping (0–1, default 0.5) on the Universal shader; on Unlit it's a fixed 0.5. The repair raises a threshold of 0 to 0.5, and keeps one you set yourself.
• _opacity and _baseColor.a are dead weight on an Opaque material until clipping is on — then they're live. The SDK's repair resets them to 1 as part of enabling clipping, so turning it on fixes occlusion and changes nothing else about how the material looks.

You mostly won't have to do this by hand

Several layers keep the rule true, so the usual experience is that it's simply already correct:

• The DreamPark shader inspector re-establishes it on every repaint — switch Alpha Clipping off on an Opaque material and it snaps back.
• A material postprocessor repairs any .mat on import, which covers script-created and hand-edited materials.
• DreamPark → Optimization → Material Optimizer... converts the materials in a folder you pick onto the right shaders, with per-row review, and applies the rule as it converts.
• DreamPark → Troubleshooting → Fix Opaque Materials Missing Alpha Clipping sweeps every material already in your project in one pass — import-time repair only reaches materials that get re-imported.
• The pre-upload checks are the backstop, and they block the upload rather than warning.

TextMesh Pro text Next SDK

TextMesh Pro's own shaders have no occlusion, so world-space text used to draw over the guest's hands. The SDK now ships occluded twins — DreamPark/TextMeshPro/Distance Field and DreamPark/TextMeshPro/Mobile/Distance Field — with the same properties and inspector, which render identically off-headset. The SDK's default fonts already use them. A font material of yours on a stock TMP shader shows up as a Materials without Meta Occlusion warning with a one-click fix, or fix them all with DreamPark → Troubleshooting → Use Occluded TextMesh Pro Shaders. On the new app, world-space text inside your attractions is also moved onto the occluded shader when it loads; HUD text on your Player rig and screen-space UI are left alone.

Scrolling textures, transparency and what the checks scan Next SDK

• Scroll or tile a texture from Lua on DreamPark-Unlit or DreamPark-UniversalShader: _baseTex is the main texture with tiling and offset, so mat.mainTextureOffset = CS.UnityEngine.Vector2(t, 0) works — no need to switch to DreamPark/Particles.
• Transparent never writes depth. Both graphs default Depth Write to Auto; the Material Optimizer sets it on every conversion and takes Opaque/Transparent from the source. Untextured sources convert with an empty texture slot (not the grey checker), so the colour you set is the colour you get.
• The occlusion checks now look everywhere a material can draw: mesh and skinned renderers, particle systems (and their trails), materials you inject into a LuaBehaviour, and your Sequence's Start, Overlay and Game Over levels.

Packages: Arena, Sequence & Adventure

Every play space is a different shape. You don't ship a park — you ship packages: three ways the app can turn your title into something playable in whatever space an operator scanned, automatically, without losing what you authored (the order things happen in, where the game starts and ends, which pieces it can't live without).

All three are authored in one place — DreamPark → Content Uploader → Packages — from the same library of Attractions and Props, and all three share your Game Manager and your Player.

Arena and Adventure are optional; every title needs a valid Sequence to upload. An Adventure you haven't finished (no Start Point or no End Point) is simply left out of the upload — never shipped broken, and never in your way.

Why packages matter

• Your title plays everywhere. An operator picks your title; the app measures the space and builds the right package. You never hand-place anything for a particular space.
• Your intent survives. A loose pile of attractions has no order, no start, no finish and no idea which pieces matter. A package carries all of that.
• There's always a playable answer. If an Adventure's required pieces don't fit, the app falls back to your Sequence — the real game in one room — or, if that can't fit either, your Arena, instead of scattering random props.
• One set of rules. The same Game Manager and Player run under all three, so your Lua doesn't care which one the guest got.
• Sequences stream. Only the level on screen is loaded, plus the next one warming in the background, so a 30-attraction game fits in a bedroom.

The Packages panel

The Content Uploader has a Park Assets section — your reusable library of every Attraction and Prop, where you can also create Groups of reusable sets — and a Packages section with three tabs: Arena · Sequence · Adventure. Each tab shows a GAME MANAGER card, a PLAYER card, the organizer for that format and a ▶ Test … in Park Simulator button.

Placing something in a package doesn't move it — a placement is a reference, so the same asset or Group can appear more than once. Your choices are saved as small .dreampark-*.json files in your content folder; commit them. (For historical reasons .dreampark-sequence.json holds the Adventure and .dreampark-dream-sequence.json holds the Sequence — don't rename them.) Testing or uploading compiles the packages into a runtime recipe for you (and bakes any attraction's shrink/grow variants that need it) — there's nothing to generate by hand, and no "Dream Sequence" prefab to maintain.

Arena

Arena is the instant package. Every Attraction and Prop is automatically sorted into a size: its smallest footprint, in whole feet, short side × long side. When the app builds an Arena it goes through the scanned floor one free rectangle at a time, takes the largest size that fits, and places that size's first entry. Big spaces get your attractions; the gaps left over get your small props.

• Everything is in by default, including assets you add later.
• Drag cards within a size to set priority — the first card is that size's pick. Make it something that explains itself at a glance; it's often the first thing anyone sees of your title.
• Drag a card onto another size's header to override its measured size — say, to offer an attraction only in rooms comfortably bigger than it. Right-click → Use Measured Size undoes it.
• Right-click → Exclude from Arena anything that can't stand alone. It stays in Park Assets and your other packages, and right-clicking the dimmed card → Include in Arena brings it back.
• The panel lists recommended square-size gaps — every square from 1 × 1 ft up to the long side of your largest size that doesn't have a size of its own (a 2 × 3 doesn't count as 2 × 2). A small prop at each gap means no scanned corner is ever left empty.

Arena entries are alternatives, so none of them is ever "required". If an entry isn't available on the device, the app moves to the next one in that size. If no size fits anywhere, nothing is placed. The first card is the default pick, not a guarantee — an operator can re-roll a space to deal it a different entry. Only AttractionTemplates and Props with an authored footprint are candidates, and the Sequence's Start, Overlay and Game Over levels never are.

Sequence

The Sequence is your whole game, playable in one room. The room is authored at 12 × 18 ft and shrinks or grows within the limits of the levels in it. The guest starts on your Start Level; your attractions then stream in one at a time, in the same room, with a particle transition covering every swap, until your Game Over Level. A persistent Overlay Level sits over every ordinary level for navigation and HUD.

The Sequence tab shows, top to bottom: the Game Manager and Player; the START LEVEL and OVERLAY LEVEL; your attractions and Groups in order (drag to reorder, drop from Park Assets to add); and the GAME OVER LEVEL.

Levels are numbered slots

What can play in a Sequence

An Attraction plays if its authored size — or its smallest (shrink) size — fits 12 × 18 ft, either way round. Anything that doesn't is shown dimmed and skipped. Props never play as Sequence levels. An attraction marked Game Requires Attraction that can't fit blocks the upload rather than silently disappearing.

How the room is sized

• The Sequence's smallest possible room is set by its least-shrinkable level — including the Start, Overlay and Game Over levels. One big fixed object on your Start Level makes the whole game need a bigger room. Build decoration from Props so the shrink bake can pull it in.
• In any room, each level is packed between its own shrink and grow limits, rotated if it fits better that way, and never stretched past its grow limit — spare floor stays empty rather than distorting your meshes and colliders.
• Debug overlays and helper visuals that draw the layout shouldn't count toward it. Keep one out of the shrink/grow bake by putting [nopack] in its object's name, or — for a script-drawn overlay — a -- @packing-ignore comment in the Lua script on that objectNext SDK. Either covers the object and everything under it. (Names containing gizmo are still skipped, as before.)
• The room keeps one calibrated floor; each level inherits its grade and keeps its own cutouts (pits, lava…).

Transitions

A level change plays the transition for at least 2.5 s and swaps the level at the end of it, once the next level has downloaded and been checked for fit. For the raw dp.load_level the newest request wins; the default Game Manager's load_level instead refuses a new request while one is still in progress. If the next level can't load or can't fit, the guest stays where they are and dp.on_level_failed fires.

Editing Start, Overlay & Game Over

The first time you open the Sequence tab, the SDK generates three prefabs in Assets/Content/<your-id>/DreamSequence/: Start Level, Overlay Level and Game Over Level. They're yours. Click a card to find the prefab, open it in Prefab Mode and edit it like any attraction. Each is an AttractionTemplate set to Custom 12 × 18 ft, with a Sequence Floor Border that follows the room's edge as it packs.

Start Level — your title screen

It ships with a START button on the floor at the centre of the room. Stepping on it plays a press animation and a click, ignores re-presses for about two seconds, and calls your Game Manager's start_game() — by default, the first attraction.

• Brand it. Title, logo, mascot, set dressing. A Start Level that's just a button in an empty room makes a finished game look broken.
• Move or restyle the button with prefab-instance overrides. Keep its LuaBehaviour and its action = start injection.
• Replace it with a portal, a lever, anything with a trigger:

lua-- my-start-portal.lua.txt
local armed = true
function ontriggerenter(other)
    if not armed or not dp.is_player(other) then return end
    armed = false
    local gm = dp.game_manager()
    if gm ~= nil and gm.start_game ~= nil then gm.start_game() end
end

To change what "start" means — jump to a hub, pick a random first level — edit start_game in the Game Manager, not the button.

Overlay Level — navigation & HUD

It ships with elevator-style BACK and FORWARD buttons on the room's left edge (they call the Game Manager's previous_level() and next_level()) and the Default Level Transition effect. The Overlay is visible over your attractions and hidden on the Start and Game Over levels; it has no floor of its own and sits on whatever level is showing.

• It persists across level swaps — the right home for a scoreboard, a timer, or a level counter built from dp.current_level_index() and dp.levels().
• Delete the navigation if your game advances itself (objectives, an exit portal per level, a timer).
• Take control of its visibility with dp.overlay_auto_visibility(false) and dp.show_overlay(true|false).

Game Over Level — your ending

It ships empty, and an empty Game Over never forces a bigger room. Add a scorecard, credits, a thank-you, and a way to play again:

lua-- replay-button.lua.txt (a trigger on the Game Over Level)
function ontriggerenter(other)
    if dp.is_player(other) and dp.button_press() then
        local gm = dp.game_manager()
        if gm ~= nil and gm.load_level ~= nil then gm.load_level(1) end  -- back to Start
    end
end

Rules for all three

• Leave the size at Custom 12 × 18 ft — the SDK resets any other size.
• Your edits are safe. The SDK's upgrades to these prefabs run once each; removing the default button won't bring it back. Delete a prefab entirely and it's regenerated with the defaults.
• Avoid naming anything in these prefabs LevelFloor, 12 ft × 18 ft Level Floor or Game Over Backdrop — those names are cleaned up automatically.
• Override, don't edit, the shared SDK prefabs. The default start button, elevator controls, transition and border live under Assets/DreamPark/ and are replaced when you update the SDK. Change them on the instance, or build your own in your content folder.

Adventure

An Adventure spreads your game across the space. You set a clear Start Point, the attractions and Groups in the order the guest should meet them, and a required End Point. The app lays them out along a walking route through the scanned park — Start first, End last, each attraction facing the one before it — and everything stays deployed; the guest walks between them.

• Drop an attraction on START POINT and one on END POINT. Both are required — an Adventure missing either one is left out of your upload until you finish it.
• Attractions, Props and Groups can all go in between, and repeats are fine — each placement is its own occurrence. Hidden placements aren't deployed.
• Tick Game Requires Attraction on pieces the game can't function without.
• Placement is all-or-nothing: if a required piece doesn't fit or won't load, the app plays your Sequence instead — or your Arena, if the Sequence can't fit either.
• In an Adventure, dp.load_level(slot) doesn't hide anything — it moves the package's "current stop" and fires dp.on_level_loaded, so your Game Manager can track progress along the route.

The Game Manager

The Game Manager is your game's brain: one persistent prefab that holds your title's rules, progression and state, shared by Arena, Sequence and Adventure. It isn't a spatial container — nothing is parented under it and it never affects room size.

The Content Uploader creates both once and never overwrites them. The prefab carries a LuaBehaviour, a NetId (so every player in a session shares navigation) and OptimizedAFIgnore (so it's never culled for distance).

• It's created once per package, before any attraction starts, and survives every level change.
• It only exists when your title runs as a package. Attractions placed on their own have no Game Manager, so dp.game_manager() returns nil — always check.

What the default script does

It keeps every player on the same level by syncing through its NetId. That's why the buttons call the Game Manager's load_level: the raw dp.load_level is local to one headset.

Customizing it

Rewrite those functions however you like; buttons and portals don't care how you decide. A random order with no repeats:

lualocal played = {}
function next_level()
    local pool = {}
    for slot = 2, dp.level_count() - 1 do          -- attractions only
        if not played[slot] then pool[#pool + 1] = slot end
    end
    if #pool == 0 then return load_level(dp.level_count()) end  -- Game Over
    local pick = pool[math.random(#pool)]
    if load_level(pick) then played[pick] = true; return true end
    return false                                 -- busy; try again later
end

A hub built from Groups:

luafunction enter_world(name)
    for _, g in ipairs(dp.groups()) do          -- { id, name, sourceId, count }
        if g.name == name then return load_level(0, g.id) end
    end
    return false
end

Keep run state — score, flags, which worlds are cleared — here, where it survives level changes. The manager isn't inside an attraction, so use game-scope storage explicitly: dp.storage.game('YourGame').max('high_score', score). Attractions reach it with dp.game_manager().

Game Manager, Player or attraction?

The Player rig

Player.prefab is the guest's body in your game. A PlayerRig on the root, and tracked children:

• One rig per game. In a package it's created once, before gameplay, outside every attraction, and survives every level change — switching between your Sequence and Adventure keeps the same rig. Placed on their own, your attractions spawn it with the first one that loads.
• Only the rig of the game the guest is standing in is shown; walking into someone else's attraction swaps to theirs.
• Keep it named Player.prefab, one per content folder, never inside an attraction. The PLAYER card in the uploader says Player Required until it exists.
• Don't look parts up by name or tag — use dp.player(), dp.head(), dp.hand(side), and dp.is_player(collider), and convert anything you send over the network with dp.to_park(dp.head().position) / dp.to_park_dir(dp.head().forward).

Package API reference

These live on dp in every script and always answer for the package that script belongs to — there's no global "current package", because a park can hold several titles.

Unsubscribe what you subscribe — the package holds on to your function:

lualocal function on_loaded(slot) print('now playing ' .. tostring(dp.levels()[slot])) end
function onready()   dp.on_level_loaded(on_loaded) end
function ondestroy() dp.off_level_loaded(on_loaded) end

dp.level_error() is one of invalid-or-inactive-slot, download-or-load-failed, room-fit-failed, spawn-failed, presentation-failed, missing-loader, load-exception or spawn-exception, and nil before any failure (each new valid request resets it).

Outside a package, dp.level_count() and dp.current_level_index() return 0, dp.levels() and dp.groups() return nil, dp.load_level returns false and every dp.is_*() is false. In an Arena or Adventure, dp.on_level_loaded fires immediately, and a groupId can be the placed Group's id or, when unambiguous, its library sourceId.

Game Storage API

Every guest who plays your attraction gets a small per-player save file scoped to your content ID. High scores, coins, checkpoints, unlock flags, best lap times — that's what it's for. It is deliberately not a blob store: think tens of keys, not megabytes of JSON.

There are two scopes:

• Attraction scope (the default) — keyed to the individual attraction the script lives under. Two attractions in the same content ID each get their own high_score.
• Game scope — storage.game.*. Shared across every attraction you ship under one content ID. Use it for currency, account-wide progress, and cross-attraction unlocks.

The storage variable

You don't import anything or pass IDs around. Every LuaBehaviour gets a storage variable injected automatically, already bound to the attraction it lives in — the SDK walks up the hierarchy to the nearest GameArea, PropTemplate, or LevelTemplate to work out the scope.

luastorage.get("checkpoint", 0)        -- synchronous read, with a default
storage.set("checkpoint", 3)        -- string (≤1 KB) / number / bool only
storage.increment("shots_fired", 1) -- returns the new value
storage.max("high_score", score)    -- set-if-greater — high scores
storage.min("best_time", lapTime)   -- set-if-lower — best times
storage.delete("temp_flag")

storage.game.increment("coins", 5)  -- same ops, game-wide scope
storage.game.get("coins", 0)

storage.isReady()                   -- has the server snapshot landed?
storage.onReady(function() end)     -- fires once it has (reads work before it)

storage.setProgress(62)             -- one overall "how far along" number per title (0–100 by convention)
storage.getProgress(0)
storage.gameId, storage.attraction  -- the scope this proxy resolved to

For scripts that live outside any attraction — park-wide systems on Player.prefab, for instance — there's no attraction to bind to. Use the explicit game-scope accessor instead; the injected storage there warns once and no-ops:

lualocal s = dp.storage.game("yourContentId")
s.increment("coins", 5)

Reads are instant, writes are batched

Reads come out of a local cache synchronously — gameplay never waits on a callback to show a high score. The snapshot loads lazily on first access; onReady tells you when the player's real values have arrived, and reads before that return your defaults. For a guest who never pairs, onReady never fires — there's no server data to wait for — so use it to refresh a display, never to gate the start of a round.

Writes are debounced (~2s) and coalesced into batched requests, so calling increment every frame is fine. Always prefer increment / max / min over read-compare-set. Those three ops are applied server-side, which makes them race-safe: a max("high_score", 50) from this headset can never clobber an 80 the same guest set on another headset five minutes ago.

Values and limits

Values must be a string (≤ 1024 bytes), a finite number, or a boolean. No nested tables, no arrays, no nil. If you need structure, encode it into separate keys — the caps are per-key-count, so a handful of flat keys is cheaper than one giant JSON string.

Oversized or malformed writes fail locally with a console warning before they ever hit the network — set returns false, numeric ops return 0. Watch the Unity console during testing; a silent no-op is always accompanied by a warning telling you which cap you hit.

Guests can delete their data — design for it

Game storage belongs to the guest, not to your attraction. They can delete any of it, at any time, without telling you — individual keys from their adventure log, a whole game's save from their profile, or everything when they delete their account. That is a deliberate platform guarantee and it is not going away, so treat it as a normal runtime condition rather than an edge case.

In practice this means one rule: every read must survive its key being gone.

• Always pass a default. storage.get("level", 1), never storage.get("level") followed by arithmetic. A deleted key reads as your default, exactly like a first-time player.
• Never treat "has data" as "has permission". If a guest deletes the key that recorded they finished the tutorial, they see the tutorial again. That's correct and survivable. If instead it strips an item they paid DreamPoints for, that's a bug you built — keep entitlements in their inventory, which is a separate system with its own rules.
• Don't split one fact across several keys. Deletion is per-key, so a guest can remove quest_stage while quest_reward_claimed survives. If those two disagree, your quest is stuck. Prefer one key that fully describes a state over several that only make sense together.
• A returning player can look brand new. Your "welcome back" path and your first-run path should both lead somewhere sensible, because either can fire for the same guest on consecutive visits.

The good news is that the defaults-everywhere style this pushes you toward is the same style that makes solo play, offline play, and unpaired guests work. If your attraction handles a fresh player well, it already handles a deletion well.

Worked example

The SDK ships this as Assets/DreamPark/Samples/GameStorage/storage_high_score.lua.txt:

lua-- @var coinValue int 1

local score = 0

function awake()
    -- Reads work immediately (cache / defaults). onReady fires once the
    -- player's persisted values have actually arrived from the server.
    storage.onReady(function()
        local best  = storage.get("high_score", 0)
        local coins = storage.game.get("coins", 0)
        CS.UnityEngine.Debug.Log(string.format("best=%d coins=%d", best, coins))
    end)
end

-- Call once per coin pickup.
function addCoin()
    score = score + (coinValue or 1)
    -- coins are a GAME-scope currency — shared across this game's attractions
    storage.game.increment("coins", coinValue or 1)
end

-- Call when the run ends.
function finishRun()
    -- set-if-greater: safe even if this profile is mid-session on another
    -- headset with a better score.
    local best = storage.max("high_score", score)
    storage.increment("runs_played", 1)
    score = 0
end

REST reference

You shouldn't need these from inside an attraction — the Lua API is the supported surface — but they're what GameStorageAPI calls under the hood, and they're useful if you're building companion tooling:

Auth is the platform API key (or an SDK preview key in the editor) plus an X-Headset-Id header. The player's identity is resolved server-side from the headset binding — a user ID never appears in the URL, and clients can't address another player's data.

Profile API

dp.profile is the read side of the guest's DreamPark identity: who they are, what they own, and how many DreamPoints they're carrying. It's available globally in every Lua script.

Readers return plain Lua tables, so you can index them directly:

luafunction start()
    dp.profile.onReady(function()
        local wand = dp.profile.getItemByType("wand")
        if wand then
            equip(wand.itemId, wand.modelUri)
        end

        if dp.profile.hasBadge("beta_tester") then
            showSecretDoor()
        end

        local ach = dp.profile.getAchievement("throw_100")
        if ach then
            progressBar.value = ach.progress / ach.maxValue
        end
    end)
end

Height-aware ergonomics. Author reachable controls and eye-level targets for the 68-inch reference, then scale them per guest: targetY = floorY + (authoredY - floorY) * dp.profile.getHeightFactor(). Height is a local presentation value, so every player sees the same networked object at their own reachable height without moving it for anyone else. Drop-in sample: Assets/DreamPark/Samples/ProfileAPI/height.lua.txt.

An inventory entry looks like this:

Achievements, badges & items

Three different reward shapes, and picking the right one matters more than the API does:

Step 1 — define them in the catalog

Achievements, badges and items are declared in the developer portal before you can award them. Awarding an ID that doesn't exist in the catalog won't error, but the reward will show up unnamed and without art everywhere it's displayed.

From your content's page in the developer portal, use the tabs:

url/developer/content/<your-content-id>/achievements
/developer/content/<your-content-id>/badges
/developer/content/<your-content-id>/items

Each entry needs an ID — letters, numbers, _ and -, up to 80 characters. This is the string you'll pass from Lua, so pick it carefully; it's permanent.

Fields you can set:

Step 2 — award them from Lua

luadp.profile.awardAchievement("beat_the_boss")  -- one-shot: marks it COMPLETE
dp.profile.awardAchievement("throw_100", 1)   -- incremental: ADDS 1 progress
dp.profile.awardBadge("axe_master")           -- idempotent
dp.profile.awardItem("wizardsway_coin", 5)    -- stacks: amount goes 5, 10, 15…
dp.profile.awardItem("wizardsway_wand")       -- one-of-a-kind (see "Stacks" below)
dp.profile.awardUniqueItem("relic")           -- a new unique item every call

dp.profile.removeItem("wizardsway_wand", 1)   -- decrement the stack
dp.profile.removeBadge("axe_master")

The semantics differ per kind, and this is the part worth internalising:

Picking the right item shape

Items come in three shapes, and the distinction is worth getting right up front because it's awkward to change once guests own things:

luaif storage.get("got_relic", false) == false then
    dp.profile.awardItem("relic", 1)
    storage.set("got_relic", true)
end

The SDK ships drop-in scripts for all three under Assets/DreamPark/Samples/ProfileAPI/ — achievement.lua.txt, badge.lua.txt and item.lua.txt. Each exposes its ID as an inspector field and a trigger() entry point, so you can wire an award to a collision or an EasyEvent chain without writing any code.

What happens when you award something

• The guest gets a notification — on the first unlock only, and only for guests with a real (non-anonymous) account playing a production build.
• It lands in their adventure log for that visit, and may be lifted into the park's public activity feed when the visit ends.
• Achievements, badges and items all grant profile XP — 400 XP per completed achievement, 250 per badge, 100 per inventory entry (per entry, not per stack size). That feeds the guest's DreamPark level and rank title. Partial progress is worth nothing until the achievement completes, so a maxValue: 10 achievement pays out once, on the call that reaches 10 — and because completion is sticky, that XP never comes back off.
• Nothing grants DreamPoints automatically. If you want a reward to pay out points, call addDreamPoints yourself — see below.

When your writes actually reach the profile

A player walking around a DreamPark space hasn't opted into every attraction installed there. So the SDK holds your profile and save-data writes until the player physically enters one of your attractions — the first time they step into one of your GameAreas, everything you've queued is sent, in order, and every later write goes straight through for the rest of their visit.

Walking back out doesn't close it again. It's a one-time entry, not a presence check, and it lasts until the guest's identity changes. Save data waits for one of your attractions specifically; profile awards wait for the first attraction of any game. At most 64 writes are held per game and the oldest are dropped past that, so a loop that writes before entry loses data.

This is almost always invisible, because the natural place to award something is inside the attraction the guest is standing in. It matters in two cases:

• Park-wide scripts on Player.prefab. A system that grants a welcome item on start() will hold that grant until the guest reaches one of your attractions. That's the intended behaviour — but if you were counting on it landing immediately, it won't.
• Editor testing without a GameArea. Testing a lone prop in an empty scene means there's nothing to walk into, so editor sessions open the gate automatically. Set ContentGate.AutoOpenInEditor = false if you want to exercise the real device behaviour.

Reads are never gated — dp.profile lookups and storage.get work from the moment your script runs. Only writes wait.

Scores & the Adventure Log

Every DreamPark play session produces an Adventure — a timeline of what the guest did, shown on their profile afterwards, summarised in their recap email, and distilled into the park's public activity feed. Scores are the headline act in that timeline.

A key is score-like if its name contains score, best, record or streak (case-insensitive). So high_score, coins_best and win_streak all qualify; coins and checkpoint don't.

Name your main score score or high_score and the row reads clean: New high score of 2,450 in Carnival Axe Throw. Any other score-like key gets appended as a dimmed qualifier — coins_best renders … (Coins Best) — which is right for a secondary metric and wrong for your headline number.

How score rows are highlighted

Score rows get treatment no other event type gets:

• A star icon and a distinct accent colour in the timeline, so scores read as scores at a glance.
• Attraction preview art. Score rows and attraction discoveries are the only rows that carry the attraction's preview render — the auto-generated tile of the attraction the score was set in, alongside its real catalog name. (Item and achievement rows show their own icons.)
• They're shareable. A guest can mint a score row into a public share page with its own OG card and URL.
• Top billing in the park feed. When a visit ends, the platform distils it down to a handful of notable moments for the park's public activity feed. Score rows rank first — above achievements, badges, attraction discoveries and items. One per attraction makes the cut.

Personal bests get their own treatment

Rows from a max write are flagged as a personal best and worded that way everywhere; score rows from increment or set aren't:

Within a single attraction, a personal-best row always outranks a plain score row in the feed — even one with a higher number. Another reason to write your headline score with max.

Getting the copy right

Three things you control determine whether these rows read well:

• Name your headline score score or high_score so it renders without a qualifier, and write it with max.
• Keep score writes in attraction scope — that's the default, so just don't reach for storage.game here. The attraction binding is what supplies the preview art and the real attraction name. Game-scope (storage.game) writes are credited to whichever attraction the player is standing in; a write made outside every attraction renders without art and without the "in <attraction>" clause.
• Write the score once, at the end of a run. Every max call is a candidate row. Writing per frame or per point produces a wall of noise in the guest's timeline, and only one of those rows will survive into the park feed anyway.

lua-- The whole high-score integration, in one line at the end of a run.
function onRunComplete(finalScore)
    storage.max("high_score", finalScore)
end

Leaderboards

storage.max keeps one player's personal best. To rank players against each other, use dp.score. It's a separate, global namespace, and every call is a network round trip — nothing is cached, because someone else's submit can change the board at any moment. Results come back in a callback as (ok, result).

lua-- At the end of a run: report the value; the server decides if it's a best.
dp.score.submit(storage.gameId, "high_score", finalScore, storage.attraction, "desc",
    function(ok, r) if ok and r.global and r.global.improved then celebrate() end end)

-- Top 10 at this park, anyone.
dp.score.fetchLeaderboard(storage.gameId, "high_score",
    { attraction = storage.attraction, thisParkOnly = true, limit = 10 },
    function(ok, board)
        if not ok then return end
        for _, e in ipairs(board.entries) do
            print(e.rank, e.displayName or "Guest", e.score, e.isMe)
        end
    end)

-- This player's own best (no board scan).
dp.score.fetchMine(storage.gameId, "high_score", { attraction = storage.attraction },
    function(ok, mine) if ok and mine.hasScore then print(mine.score) end end)

storage.gameId and storage.attraction are the scope the injected storage resolved to, so you don't hard-code either.

• A board is (content ID, metric, optional attraction). Metrics follow the storage key rules. Each submit updates the global best and, when the player is in a known park, their best at that park. Each is written only if it improves.
• Direction locks on the first write. Pass "asc" for times (lower wins); the default is "desc". A later submit in the other direction is rejected.
• fetchLeaderboard options: attraction, thisParkOnly, friendsOnly, limit (default 25, max 100). friendsOnly needs a claimed account — guests have no friend list. Guest rows come back with displayName = nil.
• Same gating as other writes. Submits wait for the guest to enter an attraction, and are rate limited per guest.
• Current limits: no paging (one page of up to 100), no day/week/month windows (everything is all-time), no total count, and no rank in fetchMine. Ranks are positions in the page you fetched.
• Leaderboard submits don't create Adventure Log rows. Keep writing storage.max("high_score", …) as well if you want the timeline moment.

For a live scoreboard among guests in the same room right now, build it on the multiplayer relay instead.

DreamPoints

DreamPoints are the platform-wide currency — earned across the whole park, spent on real rewards. Your attraction can mint and charge them:

lualocal balance = dp.profile.getDreamPoints()

dp.profile.addDreamPoints(50, "boss_defeated")
dp.profile.spendDreamPoints(20, "revive")

Both calls are gated identically. Points only move when all three of these hold:

• Running on a headset, in the DreamPark app. The Unity editor — whether on an SDK preview key or otherwise — never moves real points.
• The attraction is approved. Experimental content can't award or spend.
• The guest has a claimed account. Anonymous guests can't hold DreamPoints at all — on a headset their add and spend requests are refused outright rather than no-oped.
• The player is standing in one of your attractions. The server checks approval against the attraction the guest is in, so award and spend points from inside your attractions — a script on Player.prefab firing between attractions no-ops.

Miss the headset, approval or attraction gate and the call still succeeds with the balance unchanged, so your logic runs the same everywhere. Things that do behave differently even when fully live:

• A spend can be refused for insufficient balance. That's a real failure, not a no-op — so never hand over what they bought on the strength of the call returning. Refresh the profile and confirm the balance moved.
• Awards are capped. Past the per-guest daily cap (25,000 points per UTC day) you get the same successful no-op. A single grant over 10,000 points fails outright, and bursts of calls are rate limited. Treat a granted point as something to verify rather than assume.

Because points are real economic value across every attraction in the chain, treat minting as something you tune deliberately rather than sprinkle. Talk to us if you're planning a design where points are the core loop.

Testing player data in the editor

All of the above works in the Unity editor without a headset. Sign in first:

menuDreamPark → Sign In
DreamPark → Profile → Bind to Logged-In User

That runs the same pairing flow a real headset uses and issues a preview key, valid for an hour, scoped to your own account. Storage, profile reads, and item/achievement/badge awards all hit the real backend against your own profile — so you're testing the actual code path, not a mock.

Also under DreamPark → Profile: Dump Cache to Console to inspect the loaded snapshot, Clear Identity to simulate an unbound guest, and one-click test award actions.

If the preview key expires mid-session, re-run Bind to Logged-In User. If awards seem to vanish, check the Unity console first — every rejected write logs the reason.

Multiplayer

Players in a DreamPark space are standing in the same physical room. Shared experiences — co-op puzzles, competitive arenas, props that react for everyone at once — are the obvious thing to build, and the SDK is set up so that you can build them without running any infrastructure at all.

How sessions work

When your attraction starts up, each headset spends a few seconds listening for an existing session on the local network. If it hears one, it joins. If it hears silence, it starts hosting — and the next headset to boot finds it. There's no lobby, no room code, and nothing for the guest or the operator to do.

Where one is installed, a DreamBox kiosk may act as the relay instead. Headsets prefer it and migrate automatically, and the behaviour is identical either way — your gameplay can't tell which kind of host it's talking to, and shouldn't try.

Under the hood every device is a client of one relay, and the host headset is a client of its own. That's a deliberate design choice: the relay does no parsing, keeps no state, and makes no decisions — it just rebroadcasts every message to everyone else, reliably and in order. Nothing about your game lives on the host, which is why losing the host costs a short hitch — about a second when it leaves cleanly, a few seconds when it simply disappears — and nothing else.

Headset-hosted sessions are scoped, so groups don't merge by accident: public-SDK builds sit on a separate channel from production builds, and peer sessions are further scoped by park. A DreamBox, or the local dev relay, is shared infrastructure — every build on the network joins it, whatever its channel or park.

Net IDs

A network message has to arrive at the right object. When headset A says "this crate is now red," headset B needs to know which of its crates that means. That's what a Net ID is: a number that identifies the same object on every device in the session.

Add the NetId component to any GameObject you want to network. You don't assign the number — it's derived deterministically from where the object sits in the hierarchy, so every device computes the same value independently. There's no ID negotiation, no handshake, and no server handing out handles.

The rules that make IDs stable

You mostly don't need to think about this, but it explains the two mistakes people make:

• Inside a spawned attraction, the hash walks up the hierarchy and stops at the attraction's spawn boundary, mixing in a key derived from park data that's identical on every client. Everything below that boundary comes from your prefab, so it matches everywhere. Don't reorder siblings inside a networked prefab between builds — sibling index is part of the hash, so shuffling children changes IDs.
• Objects placed at a scene root hash on their name only, because root ordering differs between the editor and device builds. Give scene-placed networked props unique names. Two objects called Crate at the root will collide.
• (Clone) suffixes are stripped, so instantiation timing can't shift a hash.
• If you need to pin an ID by hand — an object whose hierarchy genuinely differs between editor and device — set explicitId on the component to any non-zero number. Inside an attraction it only needs to be unique within that prefab (the SDK mixes in the instance's scope, so two copies of the attraction don't collide); on a scene-placed object it's used as-is and must be unique in the park. Set it on the shared prefab, not per instance.

What changes in the next SDK New in the next SDK release

• Every spawn boundary is scoped, Sequences included. Arena and Adventure attractions already were. Now the Dream Sequence root, its Start, Overlay and Game Over levels, every streamed level, and the Game Manager get a park-stable scope too. On older apps they don't, which is why an object inside a Sequence level could hash differently on two headsets — and why some titles pinned explicitIds there.
• Every id mixes in your content ID, hashed or explicit, so two titles in one park can't collide even if both picked the same number.
• Don't set explicitId on attraction content at all. Its one remaining use is a bus on Player.prefab — a cross-attraction bus no scope covers. Most networked attractions need a single NetId, hashed, on the attraction's manager object: dp.shared_state needs none, and dp.net_body attaches its own.
• A collision keeps the first holder. The second object waits and takes the id over only when the first is destroyed.
• Session protocol 2. Because ids change, apps on the old and new scheme ignore each other's sessions rather than join one where nothing arrives.

When IDs don't line up

Two warnings in the Unity console tell you exactly what went wrong, and they're worth recognising on sight:

Messages that arrive before their object's script is listening are buffered (up to 32 per object) and delivered once it is, so you don't have to worry about startup races.Next SDK In the next SDK a buffered message expires after 5 seconds — stale state is worse than none.

Sending & receiving messages

Put a NetId and a LuaBehaviour on the same GameObject and the messaging API wires itself up. Nothing to import, no manager object to find:

lua-- Send a Lua table. Unity values convert themselves.
net_send("color", { tint = CS.UnityEngine.Color.red })

-- Receive: declare this at file scope. It fires on every OTHER device.
function onmessage(kind, payload)
    if kind == "color" then apply(payload.tint) end
end

That's the typed wire, and it's the one to reach for. net_send(kind, table) takes a Lua table, and onmessage(kind, payload) hands you the fields back — already unwrapped, so there's no envelope to remember and no JSON to build by hand.

What makes it worth using isn't the brevity, it's the coordinate handling: every Vector3, Quaternion, Transform and Color converts automatically, and positions cross the wire park-local — which is the difference between a shared object appearing in the same place on every headset and appearing two metres away. See Coordinates & the park frame; it's the bug this exists to prevent.

Next SDK In the next SDK, points sent from inside an attraction also travel relative to the attraction, which survives two headsets whose park calibration differs slightly. Nothing changes in your code — see Attraction-relative positions.

The envelope (string form)

This is the single most common thing to get wrong, so it's worth being explicit. Your payload is wrapped before it goes on the wire, and onnet receives the whole envelope, not just your fields:

json{"type":"color","payload":{"netId":2847193021,"r":1,"g":0,"b":0}}

So read t.payload.r, never t.r. And because type lives on the envelope, that's where you dispatch:

luafunction onnet(payload)
    local ok, t = pcall(function() return json_parse(payload) end)
    if not ok or t == nil then return end

    local p = t.payload
    if p == nil then return end

    if t.type == "color" then
        apply_color(p.r, p.g, p.b)
    elseif t.type == "door" then
        set_door_open(p.open)
    end
end

Four things to know about delivery

• You don't receive your own messages. The relay sends to everyone except the sender. So apply the change locally as well as broadcasting it — the "optimistic local apply" pattern you'll see in every sample. This also means a solo guest still gets working gameplay with nobody else in the room.
• Routing is by Net ID, not by event type or by script. Every receiver on that object gets every kind of message sent to it. If one object handles several kinds, branch on the kind argument (onmessage) or on t.type (onnet) yourself.
• Delivery is reliable and ordered. Messages arrive, and they arrive in the order you sent them. There's no unreliable or unordered option, which means there's no fire-and-forget channel for high-frequency state — budget accordingly. A lost packet briefly holds up everything behind it, so send absolute values, not deltas.
• Sends before the session is up are queued (up to 64, for 5 seconds), so a hello at startup still arrives. If the timing matters — a join window, a state request — run it from dp.on_connected(fn).
• net_send exists whenever the object has a NetId, from awake() on (not at file scope). With no networking client it quietly runs single-player. Keep a guard for objects without a NetId, and ask dp.relay().connected if you need to know a message really went out:

luaif net_send then net_send("color", body) end

A complete working prop

Condensed from the SDK's own sample at Assets/DreamPark/Samples/Multiplayer/lua_touch_color_switch.lua.txt (which adds a few inspector knobs and an oncollisionenter path) — touch a prop with your hand and it changes colour on every headset in the room. That's the whole multiplayer surface area in about thirty lines:

lua-- @var cooldownSeconds float 0.3

local UE = CS.UnityEngine
local renderer = nil
local lastFire = -999

function start()
    pcall(function()
        renderer = self.gameObject:GetComponent(typeof(UE.Renderer))
    end)
end

local function apply_color(r, g, b)
    if renderer == nil then return end
    pcall(function()
        renderer.material.color = UE.Color(r, g, b, 1)
    end)
end

local function on_touched()
    -- Two hand colliders shouldn't double-fire.
    local now = UE.Time.time
    if now - lastFire < cooldownSeconds then return end
    lastFire = now

    local r, g, b = math.random(), math.random(), math.random()

    -- Optimistic local apply — the relay never echoes our own message back.
    apply_color(r, g, b)

    -- Broadcast to everyone else. Queued briefly if the session isn't up yet; solo still works.
    if net_send then
        net_send("color", string.format('{"r":%.2f,"g":%.2f,"b":%.2f}', r, g, b))
    end
end

function ontriggerenter(other)
    if dp.is_player(other) then on_touched() end
end

function onnet(payload)
    local ok, t = pcall(function() return json_parse(payload) end)
    if not ok or t == nil then return end
    local p = t.payload
    if p == nil or p.r == nil then return end
    apply_color(p.r, p.g, p.b)
end

Coordinates & the park frame

Unity world space is not the same on two headsets. Each Quest puts its tracking origin wherever it happened to boot, so transform.position means something different on every device in the room. Send one of those numbers over the relay and the receiver applies it in their world — the room lines up, the shared object doesn't, and the other player ends up standing two metres from where they really are.

The fix is a shared frame. A park is QR-calibrated into park-local space, which is identical on every headset. Attractions and props live in it.

If you use the typed wire, this is already handled: net_send(kind, table) converts every Vector3 on the way out and back on the way in, and dp.peers() hands you Transforms that are already correct in your own world. You only need the helpers below when you're formatting your own JSON.

luafunction onready()
    local head = dp.head()                -- this headset's world space
    if head == nil or not net_send then return end
    net_send("look", { at = head.position, dir = dp.dir(head.forward) })  -- typed wire makes it park-local
end

Two things that catch people out:

• awake() is too early. The rig isn't parented or stamped yet, so dp.park() isn't there. Do this work in onready().
• Anything you draw for a peer must be park-local. Remote bodies, name tags, projectiles, AI proxies. Logic about your own body — a hit test against your own hands — can stay in world space, because it never leaves your headset.

In editor Play mode with no park in the scene, all of these are the identity transform, so desk testing behaves normally.

Attraction-relative positions New in the next SDK release

Park-local space is shared only as well as two headsets' QR calibrations agree, and in a real room they're off by a few centimetres and a degree or two. For anything that lives in an attraction — a boss, a ball, a target on the wall — what has to match is its place relative to the attraction. So in the next SDK, that's what goes on the wire.

• Typed net_send(kind, table) does it for you. Every point, direction, rotation and pose is encoded relative to the sending script's attraction (the nearest Attraction or Sequence level above it) and park-local beside it. Receivers inside the attraction use the first; older apps read the second, so the message still decodes everywhere. A script outside any attraction — a Player.prefab bus — stays park-local.
• dp.shared_state and dp.net_body use the same frame, so a stored Vector3 or a prop's pose means the same spot in the attraction on every headset.
• Hand-packed numbers — the string form of net_send and onnet — go through these helpers instead of dp.to_park:

Inside a script, go defaults to the script's own object; pass another object to use its attraction.

lua-- string form: pack the numbers yourself
local p = dp.to_attraction(muzzle.position)
net_send("shot", string.format('{"x":%.3f,"y":%.3f,"z":%.3f}', p.x, p.y, p.z))

function onnet(raw)
    local t = json_parse(raw).payload
    spark_at(dp.from_attraction(CS.UnityEngine.Vector3(t.x, t.y, t.z)))
end

Players in the park

You never send player positions. The SDK already streams every headset's head and both hands — park-local, dead-banded, rate-limited and smoothed on arrival. Reading other players costs nothing, and you never send poses yourself. The stream does share your headset's relay allowance (up to about 12 messages a second while moving), so on a headset-hosted session plan on roughly 45 a second for your own traffic.Next SDK In the next SDK the platform's own services share the headset too, and your share is 24 a second — see The send budget.

luafor _, p in ipairs(dp.peers()) do
    -- p.head / p.left / p.right are Transforms in THIS headset's world
    look_at(p.head.position)
end

A peer entry carries:

What other players see of you — RemoteRig

Put a child named RemoteRig in your Player.prefab. Whatever is inside it is your avatar: the SDK clones that subtree onto every other headset and drives it from your tracked body. Children named Head, LeftHand, RightHand and Hand follow automatically.

Lua scripts inside a RemoteRig run only on the clones other people are looking at, with peer_id injected — so tinting a remote player by their team is a couple of lines:

luafunction onready()
    local p = dp.peer(peer_id)
    if p and p.state and p.state.team then
        set_tint(p.state.team)
    end
end

There are no ownership components, no authority flags and no roles to configure — the clone simply isn't you. Clones are built from each viewer's own copy of your Player.prefab, so they appear on headsets running the same game; others just see the name tag. The SDK strips networking and tracking components from the clone but keeps your colliders, which is how local projectiles hit remote players.

Leader, clock & shared randomness New in the next SDK release

Before a multiplayer game can do anything interesting it needs three things: someone who decides, a clock everyone agrees on, and dice that roll the same on every headset. Games used to build all three by hand, and most of the bugs lived there. In the next SDK the platform runs them — no component, no setup, and nothing your script has to send.

lualocal lastWave = -1

function start()
    dp.on_leader_changed(function(old, new)       -- fires once now with (nil, current), then on change
        show_crown(new == dp.me())
    end)
end

function update()
    if not dp.clock_synced() then return end
    local wave = math.floor(dp.clock() / 20)      -- every headset is on the same wave: zero messages
    if wave ~= lastWave then
        lastWave = wave
        open_gate(dp.random('wave:' .. wave .. ':gate', 3))   -- gate 1..3, the same one everywhere
    end
end

Who leads

• Scoped to your title. Only devices running your title count, so a guest playing someone else's attraction across the park never ends up running your boss. Inside a script all of these answer for that script's title; you never pass self.
• The most senior synced headset leads, and keeps the lead until it leaves. A newcomer never takes over mid-round, and a late joiner can't lead before it holds the room's state. In a fresh room, ties go to the lowest id.
• Phones lead last — only when no headset running your title is there. The Editor counts as a headset.
• A headset taken off leaves straight away (the room re-elects within a beat) and rejoins as the newest member when it's put back on. A device that simply vanishes is dropped after about 4 seconds.
• The leader is not the relay host. The host owns the socket; the leader runs your gameplay; they change independently. dp.session().is_host stays a diagnostic.

The clock and the dice

• dp.clock() is real time — it keeps counting through pauses — and once synced it never runs backwards. Time.time is different on every headset: never compare it across devices. Put dp.clock() values in your state and messages (t0 = dp.clock()) and derive from them.
• Derive before you broadcast. With one clock, math.floor(dp.clock() / roundLength) is the same round everywhere at zero cost. Reach for that before sending anything.
• dp.random agrees once dp.clock_synced() is true: the session's seed is picked by the first leader and arrives with the clock. Build keys from things every device knows — a wave number, an encounter epoch, an index.
• Never use math.random for anything a player can see — targets, attack choice, spawn order, where an enemy wanders or looks. It's a different number on every headset, and "the boss looks at me on my headset and at you on yours" is that bug. Never call math.randomseed: the Lua VM is shared by every title in the park. Purely cosmetic jitter can stay local.

Shared state New in the next SDK release

An encounter — a boss's phase and health, a round timer, which wave is up — has to be one thing in the room, not one per headset. dp.shared_state(name) is a replicated table with one writer: everyone reads it, the writer applies every change, everyone else sends requests, and anyone who walks in late gets the whole table automatically. Here's a complete boss, condensed from the SDK's mp_encounter_sample.lua.txt:

lua-- cake_boss.lua.txt, on the boss's manager object inside your attraction
local s                                            -- the whole encounter

local function pick_target()
    local ids = { dp.me() }
    for _, p in ipairs(dp.peers()) do
        if p.game == dp.game_id(self.gameObject) then ids[#ids + 1] = p.id end
    end
    table.sort(ids)
    return ids[dp.random('target:' .. s.get('epoch', 0), #ids)]
end

-- Runs on the WRITER only. Every change to the fight is decided here, so two
-- players pressing Start in the same frame get one fight: the second request
-- finds the phase already 'fight' and does nothing.
local function on_request(kind, p, from)
    if kind == 'start' and s.get('phase', 'idle') ~= 'fight' then
        s.set('epoch', s.get('epoch', 0) + 1)
        s.set('hp', 50)
        s.set('t0', dp.clock())                    -- the fight's timeline, shared
        s.set('target', pick_target())             -- the writer picks; everyone sees it
        s.set('phase', 'fight')
    elseif kind == 'hit' and s.get('phase') == 'fight' then
        local hp = math.max(0, s.get('hp', 0) - (p.n or 1))
        s.set('hp', hp)
        if hp == 0 then s.set('phase', 'won') end
    end
end

function start()                                   -- never at file scope or in awake()
    s = dp.shared_state('boss')
    s.on_request(on_request)
    s.on_change(function(key, value)               -- fires for what's already there, then on each change
        if key == 'phase' then play_phase(value) end
        if key == 'hp' then set_health_bar(value / 50) end
    end)
end

function on_start_pressed()                        -- a button, a touch
    if not s.synced() then return end              -- a late joiner may not start anything
    s.request('start', {})
end

function on_boss_hit(n)                            -- THIS player landed a hit
    if not s.synced() then return end
    s.request('hit', { n = n })                    -- the writer applies the damage
    s.add('damage', n)                             -- my running total: a merge cell, no round trip
end

function update()
    if s == nil or not s.synced() or s.get('phase') ~= 'fight' then return end
    animate(dp.clock() - s.get('t0'), s.get('target'))   -- same moment, same target, every headset
end

Registers

Merge cells: everyone writes their own part

Some state is written by every player at once — damage per player, claimed chests, ready flags. Sending all of that through one writer is slow and fragile, so these keys are merge cells: each device writes only its own part, directly, and every device merges. Nothing conflicts, and nothing waits on a round trip.

A key is either a plain value or a merge cell, never both.

The rules it runs by

• One writer. It's the most senior synced device holding this state — headsets before phones, and the session leader whenever the leader has it open. Every holder keeps the whole table, so when the writer leaves, the next one carries on from the current revision.
• Late join is automatic. A device that opens the state asks the room for it (and again on every reconnect). Until it arrives, s.synced() is false. In a fresh room, the first device starts the state once every player of your title has announced itself, or after about 10 seconds with no answer. With no networking client in the scene, it syncs on its own straight away (with a client that never connects, after about 6 seconds). If you played solo and then connect to a room that already has this state, the room's version wins.
• Writes made before s.synced() are held. If the room turns out to be empty, they're applied. If it already had state, they're dropped, with a console warning — so a late joiner's start() can never reset a fight in progress, but also an unguarded s.set in start() can silently vanish. Gate starts on s.synced(). Requests made before sync are held and delivered after it, where the writer's rule decides.
• Make starts idempotent. A start is a request, and the handler checks the phase before changing it. Two simultaneous starts are then one fight.
• Effects are not state. Hits, sparks and sounds are events: play them locally, send them as messages, and never replay them to late joiners.
• Where it lives. The state belongs to the calling script's attraction (or the object you pass as dp.shared_state(name, go)); outside any attraction — the Player rig, the Game Manager — it belongs to your title. No NetId needed, and its traffic never reaches your onnet. Two placed copies of one attraction have separate states.
• Values: numbers, strings, booleans, Vector3s and rotations (attraction-relative on the wire), and small tables. Keys up to 64 characters, values up to about 4 KB. The whole table is the late-join snapshot: keep it to a few KB (the hard cap is about 14 KB).

Physics props New in the next SDK release

A ball, a crate, a party hat — anything players push around. If every headset simulates it, each one ends up with its own copy somewhere different. dp.net_body makes a Rigidbody one shared object: one owner simulates it while it moves, and everyone else follows.

lua-- on a GameObject with a Rigidbody and a collider, inside your attraction
local body

function start()
    body = dp.net_body(self.gameObject, { max_speed = 2.6, max_spin = 9, max_push = 1.2, home = true })
    body.on_owner_changed(function(old, new)
        set_glow(new == dp.me())
    end)
end

That's all — no NetId and no component to add; the platform attaches what it needs at runtime. The prop has to be part of your attraction prefab (pre-placed, not instantiated), for the same reason as every networked object.

• Touch it and it's yours while it moves. Any collider under your PlayerRig counts. When it settles, the lease is released. Motion nobody owns — knocked by another prop — is claimed by the leader. You can't steal a prop someone else is streaming, and ties resolve the same way on every device.
• Followers glide, they don't simulate. Everyone else moves their copy smoothly toward the owner's stream at a capped speed, and only teleports for a gross error (over 3 m).
• It stays gentle. Speed, spin and push-out are clamped, so a fast hand or two overlapping props can't launch a party hat across the room. Separately, every content Rigidbody now starts capped at 2 m/s depenetration and 14 rad/s spin; values your game sets itself are kept.
• Late joiners get every pose that has moved, and the leader re-broadcasts them shortly after anyone joins. Poses are attraction-relative.
• Safe under the optimizer. Nothing is written while the prop is parked, and an owner whose prop gets parked stops streaming and hands it back. A body your game made kinematic stays kinematic; its scripted motion is streamed while you own it.
• It shares the platform's send budget (below): poses are dead-banded and capped at rate, and all bodies, shared states and the session on a headset draw from one 24-a-second pool.
• Recipes beat streaming for anything every headset can simulate identically — a thrown ball, a bolt, a knock on an idle prop. Send the recipe once (origin, direction, speed, t = dp.clock()) and let each headset run it. net_body is for things people push around.

The send budget New in the next SDK release

A headset relay drops message 61 of any second from one headset, silently — and that counts everything the headset sends. In the next SDK the platform's own services send too, so the 60 is split once, up front, and nothing grows into anyone else's share:

The SDK doesn't throttle your net_send to 24 — keeping your title's own traffic inside it is your job, and the guarantee is that the platform will never eat into it. Check it with dp.budget():

lualocal b = dp.budget()
-- b.floor = 60, b.presence = 12, b.sdk = 24, b.game = 24
-- b.this_second, b.last_second   everything this headset sent, this and last second
-- b.remaining                    what's left of the 60 this second, all senders included
-- b.sdk_available, b.sdk_sent, b.sdk_denied   the SDK pool

The budget scenario measures a real session: peak rate, relay drops and a breakdown by message kind.

Setting it up

Two components on the prop, and you're networked:

1. Add Component → NetId.
2. Add a LuaBehaviour on the same GameObject, pointed at your script.
3. Define function onmessage(kind, payload) (or onnet(raw)) at file scope in that script, and call net_send where you want to broadcast.

That's it — there's no registration step, no manager to update, and no toggle on the AttractionTemplate.

Testing on your machine

You don't need two headsets to develop against this. Run a relay locally:

menuDreamPark → Multiplayer → Start Local Server
DreamPark → Multiplayer → Open Control Panel

The relay comes up on UDP port 7777 and advertises itself like a DreamBox, with a web panel at http://127.0.0.1:7780 showing connected peers and live traffic. It needs the .NET 9 SDK, or run DreamPark → Multiplayer → Rebuild Binaries once. Your scene also needs a networking client: in the DreamPark app it's always there, but in your SDK project it's only in the test scene — run DreamPark → Multiplayer → Create Test Scene, or add DreamBoxClient and NetSessionArbiter to a GameObject in your own test scene. Then open two Unity editor instances — or one editor and one Quest build — and you'll see state sync between them. The control panel's peer counter is the quickest way to confirm both sides actually joined.

Testing with simulated peers New in the next SDK release

The bugs that matter in multiplayer — a private boss on each headset, a late joiner who never syncs, two leaders, a prop flung across the room — are invisible to one player in the Editor. Simulated peers put more players into your Play session, so you find them at your desk instead of at a two-headset playtest:

menuDreamPark → Multiplayer → Simulated Peers...

• They're real on the wire. Peers join over the shipping relay code — no echo to the sender, 60 messages a second per peer, reliable and ordered — hosted on loopback with no beacon, so they can never merge with a real headset on the same Wi-Fi. They stream real presence, so dp.peers(), name tags and RemoteRig clones react to them exactly as to a headset. Nothing to add to your scene.
• They run the platform's engines. Each peer has its own session (leader election, clock, seed) and a replica of every dp.shared_state your game opened. So peers agree, or don't, on the leader; answer a late joiner with the snapshot; and can become a state's writer when you leave.
• They don't run your Lua. The Editor runs the one real copy of your game. A peer's s.request reaches your on_request, but a peer that has become the writer can't run your handlers.
• You can puppet them. Move and walk them, put their hands on things, push a dp.net_body prop, make them s.request / s.set or net_send anything to any NetId, drop their Wi-Fi, quit or crash them, make one a phone or another title's player — and make the Editor itself leave and rejoin as the newest player. Peers on Play in the window adds N peers every time you press Play.
• Your world is turned away from the park frame (35° by default) for every scenario, the way it is on every headset. At a desk the park frame is usually identity, which hides every world-space number on the wire; misaligned, those land metres off and fail the position checks.
• The Park Simulator gives a Sequence the same Net ID scopes a device does, so a Sequence that only works in the Editor fails in the Editor too.

The six scenarios

Each scenario becomes a test of your game through a few parameters: the path of your manager object, and Lua expressions run in its scope to start the encounter, check it's healthy and check there's only one. mp_encounter_sample.peers.json, next to the SDK's multiplayer samples, is a complete set. A parameter you leave out skips its steps and says so — never a silent pass. Results land in Logs/DreamParkPeers/<time>_<name>/ (result.json and log.txt).

shellTools/agent/u.sh editor_play
Tools/agent/u.sh --timeout 400 dreampark_peers_scenario --name all --wait true --params '{
  "target": "A_CakeParty/Cake Boss", "start": "on_start_pressed()", "healthy": "healthy()",
  "one_encounter": "one_encounter()", "state": "boss", "peer_request": "start",
  "body": "A_CakeParty/Gift", "body_touch": "claim()", "activity": "on_boss_hit(1)" }'
Tools/agent/u.sh editor_stop

The same commands drive peers by hand: dreampark_peers_add --name B [--rank low] [--device phone], dreampark_peers_act (one scenario step), dreampark_peers_inbox --name B (what B received), dreampark_peers_remove --name B --mode crash, and dreampark_peers_status (each peer's leader, sync and replica revisions).

Writing your own scenario is a JSON file: parameters, plus a list of steps that either do something (peer_add, peer_walk, peer_hand, peer_send, peer_request, peer_push, peer_link, peer_remove, local_rejoin, local_lua, wait…) or expect something, optionally within a few seconds (lua, recv, no_recv, sees, local_peers, leader, state_agrees, budget, net_body, no_errors). Pass a file path or inline JSON as --name. The full step list is at the top of Assets/DreamPark/Editor/ParkSimulator/ParkSimPeerScenario.cs.

json{
  "name": "door_late_join",
  "params": { "target": "A_Vault/Door" },
  "steps": [
    { "do": "peer_add", "name": "B" },
    { "expect": "local_peers", "count": 1, "within": 8 },
    { "do": "local_lua", "target": "${target}", "code": "open()" },
    { "do": "mark", "name": "join" },
    { "do": "peer_add", "name": "C" },
    { "expect": "state_agrees", "peer": "C", "name": "door", "within": 5 }
  ]
}

Patterns & limits

The networking layer is deliberately thin. It moves messages between objects that already exist and does nothing else — no simulation, no authority, no state. That keeps it fast and impossible to desync in confusing ways, but it does mean a few things are your job.

There is no host, as far as your game is concerned

Every peer is equal at the gameplay layer. The host is an implementation detail that can change mid-session — when someone takes their headset off, or when a DreamBox kiosk appears and everyone migrates to it. Design for last-write-wins: if two guests hit the same button at the same moment, the later message should simply be the answer, not a conflict to resolve.

dp.session() does report is_host, but treat it as diagnostic — something to print on a debug panel, not to branch gameplay on. Any logic that only runs on the host stops running the moment the host changes, which it will, mid-session, with no warning.

Next SDK When something genuinely needs one decider — a boss, a round, a spawn — the next SDK gives you one that doesn't move with the host: dp.is_leader(), and the writer of a dp.shared_state. Last-write-wins stays right for cosmetics.

Messages aren't retained for late joiners

The relay keeps no history. A guest who joins after the crate turned red sees the crate's original colour until someone changes it again — no message you sent before they arrived will ever reach them.

There are two ways out, and the first is usually the right one:

• Put it in player state. dp.set_state is resent to late joiners automatically. Anything that belongs to a player — team, colour, score, loadout — should live there rather than in a message you have to replay.
• Rebroadcast on a slow heartbeat for state that belongs to the world rather than to a player — a door, a crate, a round timer. Every few seconds is plenty, and it costs almost nothing:

lualocal nextBeat = 0

function update()
    if net_send == nil then return end
    local now = CS.UnityEngine.Time.time
    if now < nextBeat then return end
    nextBeat = now + 3

    net_send("state", string.format('{"open":%s}', tostring(doorOpen)))
end

Next SDK In the next SDK, world state you keep in dp.shared_state reaches late joiners automatically, with no heartbeat of your own; pushed props get the same from dp.net_body.

Anything that must survive the session belongs in game storage, not on the wire.

Budget your messages

Sixty messages per second, per headset, is the ceiling — anything over it is dropped by a headset host. The host logs [PeerRelay] Rate limit: dropped N message(s) and the sender warns about its send rate, but nothing errors in your Lua. More importantly, relay traffic grows with the square of the peer count, and Wi-Fi in a room full of headsets is a genuinely scarce resource. Send on events, not on frames. If you're syncing something continuous like a position, throttle it to 10–20 Hz and interpolate locally.Next SDK In the next SDK your title's own share is 24 a second: The send budget.

Messages are also capped at 16 KB. If you're anywhere near that, you're probably sending state that should be derived instead.

One writer per networked property

Pick a single owner for each visual property on a networked object. In particular, never mix a MaterialPropertyBlock writer and a renderer.material writer on the same object — the property block silently masks the material change, and you'll see one headset update while another appears frozen with no error anywhere.

Summary of what isn't there

Next SDK The next SDK fills three of those rows: late-join world state (dp.shared_state), authority (dp.leader, the shared-state writer, a dp.net_body owner) and shared physics. Spawns are still recipes or pre-placed objects, and the channel is still reliable and ordered.

The rules for a networked attraction New in the next SDK release

Each of these broke a shipped game.

1. Encounters have one writer. Bosses, enemies, rounds, timers and spawns live in dp.shared_state; the writer applies changes and everyone else sends requests.
2. Nothing a player can see is rolled per device. Targets, attack choice, AI wander, gaze and spawn order come from the writer, dp.random(key) or dp.clock() — never math.random, never math.randomseed.
3. Starts are gated. An unsynced late joiner may not start or reset anything (s.synced()), and a start is a request, so two at once are one fight. Effects never replay to late joiners.
4. Pushed props go through dp.net_body. Never write a remote prop's transform, and never simulate a prop you don't own.
5. No world coordinates on the wire. Typed net_send converts for you; players come from dp.peers(); nobody streams player positions.
6. Don't set explicitId except on a Player.prefab bus. One hashed NetId on the attraction's manager; props and buttons call the manager.
7. Music, voice-over and greetings start in onzoneenter(), never in start(). In the next SDK this also fires inside a Dream Sequence, where the active level is the attraction.
8. One send budget per headset — design your own traffic for 24 a second, inside the floor of 60.
9. Test before a headset does: all six simulated-peer scenarios, then one two-headset late-join test.

And two lifecycle facts under all of them: nothing sends at file scope or in awake() — do it in start() or later, when the object is placed and its Net ID is final — and ondisable() is not "the player left": the rig hides in other titles' zones and the optimizer parks distant objects. Never leave a room or drop a lease there.

Moving a title to the next SDK New in the next SDK release

• Require the new app. Net IDs change and the session protocol moves to 2, so older and newer apps never meet in one session.
• Delete your hand-rolled plumbing: roster, join, leader and heartbeat code (→ dp.leader), clock beats (→ dp.clock), seed broadcasts (→ dp.random), encounter snapshot-and-sync (→ dp.shared_state), position streams for pushed props (→ dp.net_body), hand-mount maths (→ dp.hold), and explicitId buses that only existed to dodge the Sequence id problem.
• Keep grow-only per-player counters, recipes and deterministic simulations, and victim-authoritative hits.
• Move leadership in one step. A game that mixes its own leader with dp.leader() has two leaders. Remove every math.randomseed call.
• Re-run the scenarios and the two-headset late-join test.

mp_kit.lua.txt keeps its counters, send-budget and dedupe helpers for anything the platform doesn't cover; its room, leader and clock predate the platform's, so on the next SDK use dp.leader and dp.clock, and keep mp_kit for titles that must run on older apps.

Debugging a session

Tick Verbose Net Logs on the networking client (DreamBoxClient) — it's live-toggleable while you're in Play mode.

A healthy two-device session looks like this: one side logs a transition to Hosting, the other to ClientPeer, and the host reports Peer connected … (2/16). A host sitting at 1/16 is broadcasting to nobody — that's the signature of a discovery problem rather than a code problem.

Pre-upload checks

When you press Start in the launch window, the SDK first checks your Lua for APIs the headset sandbox denies — those work in the Editor and throw on a headset, so they stop the upload outright. Then it scans your content folder for a specific set of problems that are cheap to fix now and expensive to discover after a release. Each finding offers a direct fix, a guided resolver, or a jump to the exact object that needs your judgment. You can run the full suite any time from Pre Launch Options → Review Pre-Upload Checks... in the Content Uploader.

Blocking findings stop the upload; the button reads "Fix N blocking issues to continue". Warnings open the window, but Continue · Upload ships past them once you've read them. Info findings never interrupt. If a finding is genuinely wrong for your content, Ignore… records it, with a reason you type, in Assets/Content/<your-id>/.preupload-ignores.json — commit that file so your whole team sees the decision.

If the check suite itself fails to run, the upload proceeds and logs a warning. That's on purpose — a broken safety net shouldn't be able to stop a release.

Publishing

Publishing is one panel: DreamPark → Content Uploader. You'll use it for every release.

Fill in, in the panel itself:

• Content ID — pick from a dropdown of the content folders in your project
• Name and description — the launch window shows these read-only, and an empty name blocks the upload
• Logo image

You need to be signed in, and the folder has to contain at least one Attraction or Prop — until it does, the upload button stays disabled and says so. The reserved Sample folder can't be uploaded.

Then hit Upload Release. That opens the launch window, which shows your name and description read-only. There you write release notes — required, and shown to players in the DreamPark app — and confirm build targets: Android and iOS are locked on, and Editor (Mac) and Editor (Windows) are toggles, on by default and expected for an official release. Hit Start · All (the label follows your upload scope): the pre-upload checks run, your build is packaged as Unity Addressables for each target, and it's pushed to DreamPark.

A new version is playable in the DreamPark app right away under Experimental Mode. It reaches everyone — and can award and spend DreamPoints — once it's approved.

Every upload is a full re-upload by default, which is also the only valid mode for a first publish — patching needs a baseline to diff against. Once you've published once, the launch window's Upload Scope picker offers two much cheaper modes:

• Patch — incremental upload of just the files that changed. Unchanged bundles are served from prior versions.
• Code only — Lua bundle plus catalog. Use when you've only changed Lua and want a fast OTA update. C# can't ship this way; compiled scripts live in the player binary. If anything other than Lua changed too, it stops and asks for a Patch upload instead.

Both are worth switching to as soon as you're iterating rather than launching — Code only in particular turns a Lua tweak into a few seconds of upload instead of a full rebuild, and the picker remembers your choice.

If an upload fails partway, Try Reupload re-sends what's already built without recompiling, and offers to re-send only the bundles that failed last run.

Upload Beta, next to it, builds the same folder to a separate content ID (<your-id>Beta) with its own version history and release notes. Use it to put a build in front of testers without touching your release title.

Updating the SDK

When DreamPark ships a new SDK version, the editor checks for it on launch and shows a small popup with release notes. You can also check on demand:

menuDreamPark → Check for SDK Updates

The update is delivered as a .unitypackage file. When you click Update Now, the editor downloads it, removes any SDK files the new version retired, and opens Unity's standard import dialog so you can review what's changing. Click Import and you're on the new version.

The check needs you to be signed in, runs once per editor session, and the release notes cover every version you skipped. You can dismiss the popup (Remind Me Later snoozes it for 24 hours) and keep editing, but you can't publish on an out-of-date SDK: the Content Uploader re-checks the version on every upload and disables uploading until you update (it only lets you through if the version server can't be reached). Skip This Version is also there, but it won't unlock uploading. Import everything under Assets/DreamPark/ — if you untick files, the editor tells you the update didn't complete. The Developer Terms ask you to ship compatibility updates within 30 days of a new SDK release.

Optimization

The SDK ships dedicated tools to slim down your build before publishing. They live under DreamPark → Optimization:

• Texture Optimizer... — converts oversized .tga/.tif sources to PNG or JPG, and sizes each texture to 256, 512 or 1024 based on the largest prop that uses it
• Material Optimizer... — converts materials onto the DreamPark Universal / Unlit / Particles shaders, flagging orphans along the way
• Audio Optimizer... — re-encodes oversized WAVs as Vorbis or ADPCM, down-mixes to mono where it fits, and resamples by the clip's role
• Animation Optimizer... — runs every clip through Unity's keyframe reducer

Every tool previews its changes row by row before touching a file, and preserves GUIDs. DreamPark → Diagnostics → Bundle Size Breakdown... shows what's actually taking up space. Run them before each publish — they make a real difference to download size on real-world networks. They're optional, and all of them are buttons in the Content Uploader's Pre Launch Options. The pre-upload checks are separate: they run automatically and are about correctness, not size.

Troubleshooting

The Content ID Setup popup keeps reappearing

It shows once per editor session for as long as the template placeholder folder Assets/Content/YOUR_GAME_HERE/ is still on disk — even if you've already created a properly named folder beside it. Delete or rename the leftover placeholder and it stops. The ID format is: starts with a letter, letters and digits only (no dashes, spaces or underscores), 2–64 characters. The Content Uploader shows a Set Content ID button for the placeholder, or Fix Folder Name for a folder with an invalid name. Both reopen the popup.

Login popup keeps coming back

The Content Uploader and SDK Update Checker need you to be signed in. If you keep getting bounced to the login popup, your session has likely expired — sign in once and it should hold. Sessions last 14 days. If it persists, check that your computer's clock is correct (session validation is time-sensitive).

The sign-in code doesn't arrive

Sign-in is passwordless: DreamPark → Sign In emails you a 6-digit code, and verifying it creates your account if you don't have one — there is no password to reset. If the email is slow, check spam, wait out the 30-second cooldown and hit Resend code. The server allows three sends per address per ten minutes, so don't burn them faster than the mail can land.

"DreamPark/Troubleshooting" menu

The editor includes a built-in menu at DreamPark → Troubleshooting with one-click fixes for common issues: Check Git LFS, Regenerate Level Previews, Generate XLua Code / Verify XLua Codegen, Cleanup Addressables, Remove Broken Addressables and Fix Script Namespaces. Try those first.

Builds are huge

Usually traceable to unoptimized or unused assets in your content folder's ThirdParty/. Run the tools under DreamPark → Optimization to find the worst offenders, and use DreamPark → Manage Third Party Assets to make sure you're only shipping what you actually use.

Lua changes aren't picked up

Lua scripts are plain .lua.txt TextAssets, so a new or renamed script needs no codegen — check that the LuaBehaviour points at the right asset. If Lua calls a Unity type that works in the editor but fails on device, run DreamPark → Troubleshooting → Scan Lua API Surface and Verify XLua Codegen. To get Lua to live headsets, upload with the Code only scope — no app release needed.

Pink materials, silent audio or missing meshes

The repo was cloned without Git LFS, so those assets are text placeholders. Run DreamPark → Troubleshooting → Check Git LFS, or git lfs install && git lfs pull in the project folder.

Console errors on first open

Let Unity finish downloading packages. Still broken? Close Unity, delete the project's Library folder, and reopen.

The Quest doesn't appear when you press Play

Check Developer Mode is on, that the USB-C cable carries data (not charge-only), and that you accepted the USB debugging prompt inside the headset.

My attraction doesn't appear in the app

Turn on Experimental Mode in your park settings, and make sure the app is signed in to the same account as the Content Uploader. If it's missing from the Attractions browser specifically, check the prefab root has an AttractionTemplate (see How your content gets addressed).

It loads on device but doesn't behave

New C# scripts need manual review and a future app release before they run on device. Move the logic to Lua.

Get support

The fastest place to reach us:

• Email community@dreampark.app for SDK and program questions.
• Use DreamPark → Troubleshooting in the editor for common fixes.
• See Revenue Share for economic terms.