Key concepts

The Sandbox vocabulary: the game document, assets, entities and their roles, tags, modes, rules, scripts, the content hash and the 24-hour reward epochs.

A handful of notions are enough to understand all of Sandbox. This page introduces them in the order you meet them: the document, what it holds, what makes it come alive, and what happens when it is published.

The game document

A Sandbox game is one JSON document of type SandboxGame, currently at version 2. Everything is inside: no side files, no database. The studio edits it, the runtime plays it, the platform stores it and the registry keeps its hash.

src/engine/types.tsTypeScript
interface SandboxGame {
  format: number          // 2
  meta: GameMeta          // title, description, mode, dates, remixOf
  assets: VoxelAsset[]    // up to 96
  terrain: Terrain        // height grid up to 256×256
  entities: Entity[]      // up to 3000
  rules: Rules            // mode settings and look
  vars?: GameVar[]
  gameRules?: GameRule[]
  settings?: GameSettings
  hud?: HudSettings
  scripts?: ScriptDoc[]
}

Older documents are migrated automatically on open. Full format reference.

Assets

An asset is a reusable object: a character, a tree, a door. It is defined once in assets and placed as many times as you want. Each asset has a kind (kind):

KindMade ofBest for
voxelA grid from 8³ to 64³, a colour palette and articulated parts.Blocky style, simple characters, prototypes.
meshPrimitives (box, sphere, cylinder, extrude, lathe…) with PBR materials and boolean operations.Sets, buildings, game props.
modelA GLB, OBJ, FBX or STL file, by URL (library, AI generation) or embedded in the document.Rigged characters, realistic models.

Every asset can carry animation clips. Models also play the animations of their file, or ones borrowed from another skeleton.

Entities, roles and tags

Entity

An entity is an asset placed in the world: a position, a rotation around the vertical axis (yaw, in degrees), a scale, and parameters. An entity can also have no asset (assetId: null): it is then an invisible marker, such as a trigger zone.

Role

The role tells the runtime what the entity does. The same rock model can be a prop, an obstacle or a hazard depending on its role. There are 23 roles: player start, prop, obstacle, coin, checkpoint, finish, enemy, hazard, boost, door, key, moving platform, trigger, NPC, light, spawner, sound, flag, base, turret, waypoint, enemy spawn and sign. See every role

Tag

A tag is a free label set on an entity (params.tag). Rules hook onto it (“when the player touches lava”) and actions target a group by its tag (hide, show, remove). In rules, the tag * means “any tagged entity”: an entity without a tag fires no rule event.

an entityJSON
{
  "id": "e_k3f9",
  "assetId": "a_rock",
  "role": "hazard",
  "pos": [4, 1, -6],
  "yaw": 90,
  "scale": 1.2,
  "params": { "tag": "lava", "solid": false }
}

Mode

The mode (meta.mode) provides the player controller, the default camera and the way to win. There are 7: Race, Platformer, Arena, Runner, Explore, Capture the flag, Tower defense. You pick it on the way into the studio and change it on the Rules step; switching mode keeps the terrain and entities. Modes in detail

Logic: settings, rules, variables, scripts

Two fields with similar names have very different jobs:

FieldHoldsEdited in
rulesMode settings and the look: laps, lives, waves, gravity, render style, sky, hour, weather, water, post-processing, music.Map step for the look, Rules step for the mode settings
gameRulesLogic rules: event → conditions → actions.Rules step
varsGame variables (number, boolean or text) and their starting value.Rules step
settingsRound duration, win and lose, teams, respawn.Rules step
hudWhat the interface shows: score, timer, health, lives, coins, variables.Rules step
scriptsJavaScript run in a sandboxed Web Worker.Rules step
a ruleJSON
{
  "id": "r1",
  "name": "Ten down",
  "enabled": true,
  "once": true,
  "event": { "on": "variable", "name": "kills" },
  "conditions": [{ "name": "kills", "op": ">=", "value": 10 }],
  "actions": [{ "type": "message", "text": "Ten raptors down." }, { "type": "score", "value": 500 }]
}
From the dinosaur hunt template.

Rules or scripts?

Always start with rules: they are readable, shareable and cover the vast majority of needs. Move to scripts for maths, loops, randomness or scheduled spawns. Both read and write the same variables.

Hash and registry

When publishing, the document is validated, canonicalised (sorted keys, cached thumbnails removed) then hashed with keccak256. The same game always has the same hash, and the slightest change changes it. The document is stored under a path derived from that hash, and that hash is what gets written to the on-chain registry.

Draft registry

The Sandbox.sol contract is not deployed yet. Meanwhile the registry runs in draft mode: you sign the hash with your wallet, the platform checks the signature and lists the game with an id derived from the hash (d-…).

Plays and epochs

Playing a published game needs a connected wallet: that is the anti-bot rule that makes play counts meaningful. Every finished run is posted to the platform and filed under an epoch of 24 hours: a game’s weight depends on how many distinct wallets played it, and the $SANDBOX creator fee vault is split pro rata at the end of every epoch. The formula

At a glance

Project
A document being edited, saved in this browser.
Template
A complete, playable game provided for each mode, to remix.
Starting map
Terrain, a sky and its water, with no gameplay at all: the second way to open a project.
Step
One of the studio’s six surfaces: Map, Cast, Build, Rules, Test, Publish.
Remix
A new project made from a published game; the link to the original is kept.
Runtime
The engine that plays the document, identical on the Test step and for players.
Builder
The creator of a published game, paid every 24 hours according to plays.

Full glossary

Scene formatEvery field of the document.RulesEvents, conditions, actions.Variables and HUDStore state and display it.ScriptingThe sandbox.* API to go further.