Scenes

A scene is the game's world written as data: a list of pieces, the points where players appear, the zones that report when someone enters, the lights and the environment. It also says which view the game is played with (third person, first person, side-on 2D, from above or isometric) and can carry tile maps. Each scene is a file escenas/<id>.json. A game can have up to 16, and it starts in the one named by escenaInicial in the manifest.

Only formato, id, piezas and apariciones are required.

The examples on this page come from real files. Keys, ids and values are in Spanish, as the format requires.

A real scene#

This is the scene of the template (packages/toolkit/plantilla/escenas/principal.json), trimmed: a floor, a platform with its way up, one of the six coins and one of the four lava slabs.

{
	"$schema": "../../../packages/sdk/esquemas/escena.schema.json",
	"formato": 1,
	"id": "principal",
	"ambiente": { "cielo": "dia", "luzAmbiente": 0.8, "alturaCaida": -10 },
	"piezas": [
		{ "id": "suelo", "forma": "caja", "posicion": [0, -0.5, 0], "tamano": [24, 1, 24], "material": { "color": "papel", "patron": "rejilla" } },
		{ "id": "tarima", "forma": "caja", "posicion": [7, 1, 6], "tamano": [6, 2, 6], "material": { "color": "violeta", "patron": "cuadros" } },
		{ "id": "subida", "forma": "cuna", "posicion": [7, 1, 0.5], "tamano": [3, 2, 5], "material": "madera" },

		{ "id": "moneda-1", "forma": "cilindro", "posicion": [8, 1, -6], "rotacion": [90, 0, 0], "tamano": [0.9, 0.16, 0.9], "material": { "color": "ambar", "acabado": "brillante" }, "solida": false, "etiquetas": ["moneda"], "movimiento": { "tipo": "giro", "velocidad": [0, 160, 0] } },

		{ "forma": "caja", "posicion": [3, 0.1, -1], "tamano": [3, 0.2, 3], "material": { "color": "coral", "acabado": "neon" }, "etiquetas": ["lava"], "dificultades": ["normal", "dificil"] }
	],
	"apariciones": [
		{ "id": "inicio", "posicion": [0, 0, -9], "rotacionY": 0 }
	]
}

What to look at:

• The floor is 1 tall and its center is at y = -0.5: its top face ends up at y = 0, where the spawn point is.
• The coin is a cylinder lying down (a rotacion of 90 degrees on X), not solid, with a tag and an automatic spin.
• The lava has no id: it is recognized by its tag, and it exists on only two of the three difficulties.

Pieces#

Everything you see and touch is a piece. forma, posicion, tamano and material are required.

A scene accepts up to 2000 declared pieces, and up to 150 dynamic pieces alive at once. All the caps: Limits.

Shapes#

The shape is written cuna, with no ñ, like every key and value of the format.

For a wedge or a ramp to be walkable, height / length must be less than 1.19 (50 degrees). The way up in the template is 2 tall and 5 long: 0.4.

Materials#

A material is a color name ("madera") or an object { "color", "acabado", "patron" }.

Color. A name from the base palette or one added in the scene's paleta. The base palette has 25 colors:

tinta, papel, verde, violeta, coral, ambar, blanco, gris, grafito, piedra, cielo, azul, noche, menta, bosque, lima, rosa, magenta, rojo, naranja, amarillo, arena, tierra, madera, hielo.

Finish.

Pattern. liso (plain, the default), cuadros (checks), franjas (stripes) or rejilla (grid). They are drawn by code, in world units: a grid on the floor lets you count distances by eye.

Texture. Since version 1.2, a material can also carry an image from texturas/ with textura, repeated with repetir: { "color": "blanco", "textura": "ladrillo", "repetir": [2, 2] }. See Models, textures and sounds. A game's pixel-art images are sprites.

Your own colors#

If the base palette is not enough, the scene declares its own in paleta, as six-digit hexadecimal colors. This is the scene of the tutorial yard after asking the editor assistant to "change the colors to sunset" (documentacion/ejemplos/patio-al-atardecer/escenas/principal.json):

	"paleta": {
		"atardecer-sombra": "#2b1b3f",
		"atardecer-ciruela": "#5c2a5e",
		"atardecer-vino": "#a13d63",
		"atardecer-brasa": "#e2584a",
		"atardecer-mandarina": "#ff8a3c",
		"atardecer-durazno": "#ffb86b",
		"atardecer-crema": "#ffe3b0"
	}

and it uses them by name, just like those of the base palette:

{"id": "suelo", "forma": "caja", "posicion": [0, -0.5, 0], "tamano": [24, 1, 24], "material": {"color": "atardecer-crema", "patron": "rejilla"}}

Names start with a lowercase letter and have letters, numbers and hyphens, with no accents and no spaces: verde-agua or verdeAgua. Up to 32 per scene.

Declarative movement#

Whatever always moves the same way is declared in the scene, with no script. It works on fija or ninguna pieces.

The moving platform of Circuito Luz Verde (games/circuito-luz-verde/escenas/principal.json) crosses a gap back and forth, with a pause at each end:

{ "id": "movil-1", "forma": "caja", "posicion": [0, -0.3, 32.7], "tamano": [3.4, 0.6, 3.4], "material": { "color": "cielo", "patron": "cuadros" }, "movimiento": { "tipo": "vaiven", "hasta": [0, -0.3, 38.3], "duracion": 2.6, "espera": 0.9 } }

Moving platforms carry the players and actors standing on them. Whatever depends on what happens in the match (a door that opens, an elevator that someone calls) is moved from the script, with pieza.moverA: see mundo.

Spawn points#

The points where players appear. There has to be at least one, and up to 64.

The first one in the list is where the players start. The others serve as checkpoints: the script sets jugador.aparicion = 'control-2' and, from then on, that player returns there when they fall or when the game makes them respawn. The spawn points of Circuito Luz Verde:

	"apariciones": [
		{ "id": "salida", "posicion": [0, 0, -3], "rotacionY": 0 },
		{ "id": "control-1", "posicion": [0, 0, 27.5] },
		{ "id": "control-2", "posicion": [0, 4, 51] },
		{ "id": "control-3", "posicion": [0, 4, 71] },
		{ "id": "control-4", "posicion": [0, 4, 108] }
	],

Zones#

A zone is an invisible volume that reports when a player or an actor enters or leaves. You use them for goals, checkpoints and areas with their own rules, and also for stretches played with another view. Up to 200 per scene.

	"zonas": [
		{ "id": "zona-control-1", "forma": "caja", "posicion": [0, 1.5, 28], "tamano": [7, 3, 5], "etiquetas": ["control"] },
		{ "id": "zona-corredor", "forma": "caja", "posicion": [0, 6, 90], "tamano": [6, 4, 29] },
		{ "id": "meta", "forma": "caja", "posicion": [0, 11.9, 131.5], "tamano": [7, 3, 4] }
	],

Make zones 3 units tall or more when the player arrives walking or jumping: a low zone can be crossed over the top.

Lights#

Colored point lights. Up to 8 per scene.

	"luces": [
		{ "posicion": [0, 3, 2], "color": "verde", "intensidad": 2, "alcance": 14 },
		{ "posicion": [0, 8, 63.5], "color": "coral", "intensidad": 2.5, "alcance": 14 }
	]

Environment#

The sky, the general light and two numbers that change how the game plays.

The environment of Circuito Luz Verde: a gradient sky, a sun from the side and distant fog.

	"ambiente": { "cielo": { "arriba": "noche", "abajo": "violeta" }, "luzAmbiente": 0.85, "sol": { "direccion": [-0.45, -1, 0.35], "intensidad": 1.1 }, "niebla": { "desde": 70, "hasta": 220 }, "alturaCaida": -14 },

Raise alturaCaida to just below your lowest platform: whoever falls comes back sooner and does not wait staring at the void.

Views#

Every game uses the same 3D world of pieces. The view decides the camera, how the player moves and, in the 2D ones, which plane the player is confined to. You declare it in the scene ("vista"), in a zone (it applies while the player is inside) or the script sets it with camara.vista. Without vista, the scene is third person.

This is the view of the 2D platformer template (packages/toolkit/plantillas/plataformas-2d/escenas/principal.json):

	"vista": { "tipo": "lateral", "zoom": 13, "plano": { "eje": "z", "valor": 0 }, "limites": { "min": [0, -2, 0], "max": [64, 16, 0] } },

Every parameter is optional: each type has its own defaults.

Rules of the 2D views:

• In lateral, the room takes the player to the plane (at 9 units per second: entering a 2D zone is not a jump) and keeps them there; it ignores input on the locked axis. The dinamica pieces of a lateral scene also stay on the plane, and so do actors.
• With "eje": "z" you walk along X and the camera looks from +Z (X grows to the right). With "eje": "x" you walk along Z.
• Design the level on the plane: pieces must cross it. It is enough for them to be 2 or 3 units deep.
• In plano and in cenital, jugador.salto = 0 is a good idea if the walls are low.

Hybrid games: zones that change the view#

A game can mix 2D and 3D. There are three ways:

• A zone with a view. A zone with vista changes the view of whoever enters and, on leaving, the previous one comes back. transicion is how many seconds the change takes (0.6 by default). If plano.valor is not given, the center of the zone is used.
• Scenes with different views. Each scene has its vista; juego.cambiarEscena changes both things.
• From the script. camara.vista('isometrica'), camara.vista({ tipo: 'lateral', plano: { eje: 'z', valor: 0 } }, { transicion: 1 }, jugador) and camara.vista(null), which brings back the view of the scene. A zone's view takes precedence over the script's while the player is inside. See camara.

The two zones of the hybrid template (packages/toolkit/plantillas/hibrido/escenas/principal.json): a tunnel played from the side and an isometric plaza, inside a third-person world.

	"zonas": [
		{ "id": "tunel", "forma": "caja", "posicion": [26, 4, 0], "tamano": [28, 10, 6], "vista": { "tipo": "lateral", "zoom": 13, "plano": { "eje": "z", "valor": 0 } }, "transicion": 0.6 },
		{ "id": "plaza-iso", "forma": "caja", "posicion": [46, 3, 0], "tamano": [12, 8, 12], "vista": { "tipo": "isometrica", "zoom": 16 }, "transicion": 0.6 }
	]

How the change behaves:

• Transition. Between two views with the same projection, the camera travels from one pose to the other. Between perspective and orthographic, or toward first person, no blend is possible: it fades to black, switches halfway and comes back.
• Controls. They are remapped instantly with the view: what was "forward" becomes relative to the new camera. On leaving a lateral view, the axis is released and the player stays where they are. On returning to third person, the camera keeps the turn the player had.
• The view is per player. In a match with several players, each one can be in a different view.
• So the change does not confuse: make the zone wider than the corridor (the player eases onto the plane); put the entrance and the exit on the plane; move the respawn point on entering; and do not change the view in the middle of a hard jump.

In the editor you pick views without writing JSON: Game types.

Sprites#

A sprite (lamina in the format) is a pixel drawing stored as data, with no image files. It lives in laminas/<id>.json. The file name is its id: lowercase letters, numbers and hyphens.

The coin of the 2D platformer template (packages/toolkit/plantillas/plataformas-2d/laminas/moneda.json), with three frames and one animation:

{
	"$schema": "../../../packages/sdk/esquemas/lamina.schema.json",
	"formato": 1,
	"ancho": 8,
	"alto": 8,
	"paleta": ["tierra", "ambar", "papel"],
	"cuadros": [
		[
			"..0000..",
			".011110.",
			"01121110",
			"01211110",
			"01211110",
			"01111110",
			".011110.",
			"..0000.."
		],
		[
			"...00...",
			"..0110..",
			"..0120..",
			"..0120..",
			"..0110..",
			"..0110..",
			"..0110..",
			"...00..."
		],
		[
			"...00...",
			"...00...",
			"...00...",
			"...00...",
			"...00...",
			"...00...",
			"...00...",
			"...00..."
		]
	],
	"animaciones": {
		"girar": {"cuadros": [0, 1, 2, 1], "fps": 8}
	}
}

Pixels are drawn crisp, with no smoothing and no lighting: the color is the one you wrote. A game allows up to 128 sprites.

A sprite has three uses.

A flat piece. A piece with "forma": "lamina". This is the first coin of that template:

{ "id": "moneda-1", "forma": "lamina", "lamina": "moneda", "animacion": "girar", "posicion": [4, 1, 0], "tamano": [0.9, 0.9, 0.4], "material": "ambar", "solida": false, "etiquetas": ["moneda"] }

The image fills the width and the height of tamano and faces +Z; you turn it with rotacion, like any piece. The third number of tamano is the depth of its collision box. material is required as on every piece, but it is not drawn. Up to 400 sprite pieces at a time.

From the script you change them with pieza.lamina, pieza.animacion (assigning it restarts the animation) and pieza.espejo.

A tile of a map. See Tile maps.

A character. "avatar": { "lamina": "heroe" } in the scene draws the players with that sprite instead of the block avatar. For an actor it is apariencia: { lamina: 'guardia' }, and from the script, jugador.apariencia = { lamina: 'heroe' }.

• The sprite is stretched to the height of the avatar (1.8) and keeps its proportions: 8 x 16 pixels matches its collision width.
• Draw the character facing right: the engine mirrors it by itself when it goes left.
• These animations are used automatically, if they exist: quieto, caminar, saltar and caer; and in the views from above, quieto-arriba, caminar-arriba, quieto-abajo and caminar-abajo (from behind and from the front). A missing one is replaced by the closest one.
• The character's collision does not change: it is still the avatar's capsule.

Tile maps#

A map is a grid written as text: each character is a tile. It is the way to make 2D levels, and floors and walls of games seen from above, without placing piece by piece. A scene declares its maps in mapas, up to 8.

The map of the 2D platformer template's level, cut down to its first 14 columns (the file has 64, plus two background layers with hills):

	"mapas": [{
		"id": "nivel",
		"plano": "xy",
		"origen": [0, 12, 0],
		"baldosas": {
			"T": { "lamina": "tierra", "cuadro": 0 },
			"#": { "lamina": "tierra", "cuadro": 1 },
			"=": { "lamina": "tabla", "colision": "plataforma" },
			"^": { "lamina": "puas", "colision": "peligro" },
			"H": { "lamina": "escalera", "colision": "escalera" },
			"m": { "material": "cerro-lejos", "colision": "ninguna" },
			"n": { "material": "cerro", "colision": "ninguna" }
		},
		"capas": [
			{ "id": "suelo", "filas": [
				".",
				".",
				".",
				".",
				".",
				".",
				".",
				".",
				".",
				".",
				".",
				".",
				"TTTTTTTTTTTTTT",
				"##############"
			] }
		]
	}]

With "origen": [0, 12, 0] and cells of 1, row 12 goes from y = 0 to y = -1: its top edge is the floor at y = 0.

A tile is drawn with material (a color) or with lamina (and cuadro), it can carry etiquetas, and it collides according to colision:

A floor with walls seen from above is the same thing with "plano": "xz". This is how the top-down template declares its tiles (packages/toolkit/plantillas/cenital/escenas/principal.json): a floor you walk on and a wall 2 units tall.

		"baldosas": { "s": { "lamina": "piso", "colision": "suelo" }, "M": { "lamina": "ladrillo", "alto": 2, "etiquetas": ["muro"] } },

How a map behaves:

• Merged collision. Equal, adjacent tiles are joined into rectangles (in chunks of 32 x 32 cells): a floor of a thousand tiles is a handful of blocks. The blocks are not pieces: they do not count toward the piece limits and do not show up in mundo.piezas(), but touches, rays, the bot's router and jugador.caminarA see them.
• Tags of the blocks. mapa, mapa-<id>, those in the tile's etiquetas and, depending on the collision, peligro, escalera or plataforma. That way mundo.alTocar('#peligro', (bloque, jugador) => jugador.reaparecer()) works the same for spikes made of pieces or of tiles. bloque.datos carries mapa, baldosa, columna and fila.
• Background layers ("fondo": true). They are only drawn. profundidad moves them away from the plane (1 by default; a negative value puts them in front, as a foreground) and, in xy maps, paralaje says how much they move with the camera: 1 is normal, 0.5 is half (they look far away), 0 is still on screen.
• Drawing. In an xy map, solid tiles and platforms have volume (the grosor), so the level also looks right if the camera switches to 3D; the rest (ladders, spikes, decorations) stays flat, just behind the avatar. In an xz map, tiles receive light and shadows like pieces. The acabado and the patron of the material do not apply to tiles: only the color.
• Sizes. Up to 512 x 512 cells per map, 8 maps per scene and 200,000 tiles per scene.
• In 3D worlds. An xy map has volume, so a 2D stretch looks like a corridor of blocks when the camera leaves for 3D. Use the same z in the map's origen and in the zone's plano.valor.
• Sprites that face the camera in a view from above lie flat at their height: a taller neighboring wall covers them. Character sprites are drawn above their head to avoid it; raise the others or move them away.

The script reads and changes tiles with mundo.mapa(id): see Mapa. A map does not grow beyond its declared rows and columns.

What maps do not do yet: tiles do not animate on their own (for moving water or lava, use pieces with "forma": "lamina"), there are no slopes, and dynamic pieces collide with one-way platforms from both sides.

Tips for a 2D level#

• The plane of a side-on level is the one in vista.plano (z = 0 by default): use that same z in the map's origen and in loose pieces (coins, moving platforms).
• Keep the jump at what the avatar gives. A platform 2 cells up can be reached; one 3 cells up cannot.
• The character is drawn facing right, in a sprite with a 1 to 2 proportion (for example 8 x 16).
• Everything else (script, HUD, bot, scores) is the same as in a 3D game.

Tips for building the scene#

• Center versus feet. The posicion of a piece is its center; that of a spawn point is the feet. A platform with its top face at y = 0 is "posicion": [x, -0.5, z], "tamano": [a, 1, l], and the spawn point on it goes at y = 0.
• Start with the floor and the spawn points. If the spawn point is not over a solid piece, the player appears and falls. The validator warns.
• Design with the avatar's measurements: gaps of up to 4 units, steps of up to 0.45 without jumping, jumps of up to 2.6 high. The full table is in Package structure.
• Tags for what repeats, id for what is unique. moneda, peligro, control are tags; the id is for what the script or the bot names one by one (ascensor, meta). If there are many identical pieces, leave out the id.
• What changes with the difficulty goes in the scene, with "dificultades": ["facil"] on the piece or the zone. Circuito Luz Verde has two sets of slabs in the same place: the wide ones for facil and normal, and the narrow ones (with a different id) for dificil.
• Dangers are understood by their color. Use { "color": "coral", "acabado": "neon" } and there is no need to explain them.
• Decoration with no physics cost. What nobody touches goes with "fisica": "ninguna".

Next#

• Scripts: give behavior to what you declared.
• mundo: read, create, move and remove pieces from the script.
• Editing the scene: build the same thing without writing JSON.
• Game types: pick the view when you create a project in the editor.