Escenas

Una escena es el mundo del juego escrito como datos: una lista de piezas, los puntos donde aparecen los jugadores, las zonas que avisan cuando alguien entra, las luces y el ambiente. También dice con qué vista se juega (tercera persona, primera persona, 2D de lado, desde arriba o isométrica) y puede traer mapas de baldosas. Cada escena es un archivo escenas/<id>.json. Un juego puede tener hasta 16 y empieza en la que nombra escenaInicial del manifiesto.

Solo formato, id, piezas y apariciones son obligatorias.

Una escena real#

Esta es la escena de la plantilla (packages/toolkit/plantilla/escenas/principal.json), recortada: un suelo, una tarima con su subida, una de las seis monedas y una de las cuatro losas de lava.

{
	"$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 }
	]
}

Qué mirar:

• El suelo mide 1 de alto y su centro está en y = -0,5: su cara superior queda en y = 0, donde está la aparición.
• La moneda es un cilindro acostado (rotacion de 90 grados en X), no sólido, con una etiqueta y un giro automático.
• La lava no tiene id: se reconoce por su etiqueta, y existe solo en dos de las tres dificultades.

Piezas#

Todo lo que se ve y se toca es una pieza. forma, posicion, tamano y material son obligatorias.

Una escena admite hasta 2000 piezas declaradas, y hasta 150 piezas dinámicas vivas a la vez. Todos los topes: Límites.

Formas#

La forma se escribe cuna, sin eñe, como todas las claves y valores del formato.

Para que una cuña o una rampa se pueda subir caminando, alto / largo debe ser menor que 1,19 (50 grados). La subida de la plantilla mide 2 de alto y 5 de largo: 0,4.

Materiales#

Un material es un nombre de color ("madera") o un objeto { "color", "acabado", "patron" }.

Color. Un nombre de la paleta base o uno agregado en paleta de la escena. La paleta base tiene 25 colores:

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.

Acabado.

Patrón. liso (por defecto), cuadros, franjas o rejilla. Se dibujan por código, en unidades del mundo: una rejilla en el suelo te deja contar distancias a ojo.

Textura. Desde la versión 1.2, un material puede llevar además una imagen de texturas/ con textura, repetida con repetir: { "color": "blanco", "textura": "ladrillo", "repetir": [2, 2] }. Ver Modelos, texturas y sonidos. Las imágenes de pixel art del juego son láminas.

Colores propios#

Si la paleta base no alcanza, la escena declara los suyos en paleta, como colores hexadecimales de seis dígitos. Así queda la escena del patio del tutorial después de pedirle al asistente del editor «cambia los colores a atardecer» (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"
	}

y los usa por nombre, igual que los de la paleta base:

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

Los nombres empiezan con minúscula y llevan letras, números y guiones, sin tildes ni espacios: verde-agua o verdeAgua. Hasta 32 por escena.

Movimiento declarativo#

Lo que se mueve siempre igual se declara en la escena, sin script. Sirve en piezas fija o ninguna.

La plataforma móvil de Circuito Luz Verde (games/circuito-luz-verde/escenas/principal.json) cruza un hueco de ida y vuelta, con una pausa en cada extremo:

{ "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 } }

Las plataformas que se mueven llevan a los jugadores y a los actores parados encima. Lo que depende de lo que pasa en la partida (una puerta que se abre, un ascensor que alguien llama) se mueve desde el script, con pieza.moverA: ver mundo.

Apariciones#

Los puntos donde aparecen los jugadores. Tiene que haber al menos una, y hasta 64.

La primera de la lista es donde empiezan los jugadores. Las demás sirven de puntos de control: el script cambia jugador.aparicion = 'control-2' y, desde entonces, ese jugador vuelve ahí cuando cae o cuando el juego lo hace reaparecer. Las apariciones de 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] }
	],

Zonas#

Una zona es un volumen invisible que avisa cuando un jugador o un actor entra o sale. Con ellas se hacen metas, puntos de control y sectores con reglas propias, y también tramos que se juegan con otra vista. Hasta 200 por escena.

	"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] }
	],

Haz las zonas de 3 unidades de alto o más cuando el jugador llega caminando o saltando: una zona baja se puede cruzar por encima.

Luces#

Luces puntuales de color. Hasta 8 por escena.

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

Ambiente#

El cielo, la luz general y dos números que cambian cómo se juega.

El ambiente de Circuito Luz Verde: cielo en degradado, sol de lado y niebla lejana.

	"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 },

Sube alturaCaida hasta poco más abajo de tu plataforma más baja: quien cae vuelve antes y no espera mirando el vacío.

Vistas#

Todos los juegos usan el mismo mundo 3D de piezas. La vista decide la cámara, cómo se mueve el jugador y, en las 2D, a qué plano queda restringido. Se declara en la escena ("vista"), en una zona (vale mientras el jugador está dentro) o la fija el script con camara.vista. Sin vista, la escena es de tercera persona.

Esta es la vista de la plantilla de plataformas 2D (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] } },

Todos los parámetros son opcionales: cada tipo tiene sus valores por defecto.

Reglas de las vistas 2D:

• En lateral, la sala lleva al jugador al plano (a 9 unidades por segundo: entrar a una zona 2D no es un salto) y lo mantiene ahí; ignora la entrada en el eje bloqueado. Las piezas dinamica de una escena lateral también quedan en el plano, y los actores igual.
• Con "eje": "z" se camina en X y la cámara mira desde +Z (X crece hacia la derecha). Con "eje": "x" se camina en Z.
• Diseña el nivel sobre el plano: las piezas deben cruzarlo. Basta con que tengan 2 o 3 unidades de fondo.
• En plano y en cenital conviene jugador.salto = 0 si los muros son bajos.

Juegos híbridos: zonas que cambian la vista#

Un juego puede mezclar 2D y 3D. Hay tres maneras:

• Zona con vista. Una zona con vista cambia la vista de quien entra y, al salir, vuelve la que tenía. transicion son los segundos que dura el cambio (por defecto 0,6). Si no se da plano.valor, se usa el centro de la zona.
• Escenas con vistas distintas. Cada escena tiene su vista; juego.cambiarEscena cambia las dos cosas.
• Desde el script. camara.vista('isometrica'), camara.vista({ tipo: 'lateral', plano: { eje: 'z', valor: 0 } }, { transicion: 1 }, jugador) y camara.vista(null), que devuelve la de la escena. La vista de una zona manda sobre la del script mientras se está dentro. Ver camara.

Las dos zonas de la plantilla híbrida (packages/toolkit/plantillas/hibrido/escenas/principal.json): un túnel que se juega de lado y una plaza isométrica, dentro de un mundo de tercera persona.

	"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 }
	]

Cómo se comporta el cambio:

• Transición. Entre dos vistas con la misma proyección, la cámara viaja de una pose a la otra. Entre perspectiva y ortográfica, o hacia la primera persona, no hay mezcla posible: funde a negro, cambia a mitad de camino y vuelve.
• Controles. Se reasignan al instante con la vista: lo que era "adelante" pasa a ser relativo a la cámara nueva. Al dejar una vista lateral, el eje se libera y el jugador queda donde está. Al volver a tercera persona, la cámara conserva el giro que tenía el jugador.
• La vista es por jugador. En una partida con varios jugadores, cada uno puede estar en una vista distinta.
• Para que el cambio no confunda: haz la zona más ancha que el pasillo (el jugador entra al plano de a poco); pon la entrada y la salida sobre el plano; mueve el punto de reaparición al entrar; y no cambies de vista en medio de un salto difícil.

En el editor las vistas se eligen sin escribir JSON: Tipos de juego.

Láminas#

Una lámina es un dibujo de píxeles guardado como datos, sin archivos de imagen. Vive en laminas/<id>.json. El nombre del archivo es su id: minúsculas, números y guiones.

La moneda de la plantilla de plataformas 2D (packages/toolkit/plantillas/plataformas-2d/laminas/moneda.json), con tres cuadros y una animación:

{
	"$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}
	}
}

Los píxeles se dibujan nítidos, sin suavizado y sin luces: el color es el que escribiste. Un juego admite hasta 128 láminas.

Una lámina tiene tres usos.

Pieza plana. Una pieza con "forma": "lamina". Así está la primera moneda de esa plantilla:

{ "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"] }

La imagen ocupa el ancho y el alto de tamano y mira hacia +Z; se gira con rotacion, como cualquier pieza. El tercer número de tamano es el fondo de su caja de colisión. material se exige como en toda pieza, pero no se dibuja. Hasta 400 piezas con lámina a la vez.

Desde el script se cambian con pieza.lamina, pieza.animacion (asignarla la reinicia) y pieza.espejo.

Baldosa de un mapa. Ver Mapas de baldosas.

Personaje. "avatar": { "lamina": "heroe" } en la escena dibuja a los jugadores con esa lámina en vez del avatar de bloques. Con un actor es apariencia: { lamina: 'guardia' }, y desde el script, jugador.apariencia = { lamina: 'heroe' }.

• La lámina se estira a la altura del avatar (1,8) y conserva su proporción: 8 x 16 píxeles calza con su ancho de choque.
• Dibuja al personaje mirando a la derecha: el motor lo espeja solo cuando va hacia la izquierda.
• Estas animaciones se usan solas, si existen: quieto, caminar, saltar y caer; y en las vistas desde arriba, quieto-arriba, caminar-arriba, quieto-abajo y caminar-abajo (de espaldas y de frente). La que falte se reemplaza por la más parecida.
• La colisión del personaje no cambia: sigue siendo la cápsula del avatar.

Mapas de baldosas#

Un mapa es una rejilla escrita como texto: cada carácter es una baldosa. Es la forma de hacer niveles 2D, y pisos y muros de juegos vistos desde arriba, sin colocar pieza por pieza. Una escena declara sus mapas en mapas, hasta 8.

El mapa del nivel de la plantilla de plataformas 2D, recortado a sus primeras 14 columnas (el archivo trae 64 y dos capas de fondo con cerros):

	"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",
				"##############"
			] }
		]
	}]

Con "origen": [0, 12, 0] y celdas de 1, la fila 12 va de y = 0 a y = -1: su borde de arriba es el piso en y = 0.

Una baldosa se dibuja con material (un color) o con lamina (y cuadro), puede llevar etiquetas y choca según colision:

Un piso con muros visto desde arriba es lo mismo con "plano": "xz". Así declara sus baldosas la plantilla cenital (packages/toolkit/plantillas/cenital/escenas/principal.json): un piso por el que se camina y un muro de 2 unidades de alto.

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

Cómo se comporta un mapa:

• Colisión fusionada. Las baldosas iguales y contiguas se juntan en rectángulos (por trozos de 32 x 32 celdas): un piso de mil baldosas es un puñado de bloques. Los bloques no son piezas: no cuentan para los límites de piezas ni salen en mundo.piezas(), pero los ven los toques, los rayos, el enrutador del bot y jugador.caminarA.
• Etiquetas de los bloques. mapa, mapa-<id>, las de etiquetas de la baldosa y, según la colisión, peligro, escalera o plataforma. Así mundo.alTocar('#peligro', (bloque, jugador) => jugador.reaparecer()) sirve igual para púas hechas con piezas o con baldosas. En bloque.datos vienen mapa, baldosa, columna y fila.
• Capas de fondo ("fondo": true). Solo se dibujan. profundidad las aleja del plano (por defecto 1; negativa las pone delante, como primer plano) y, en mapas xy, paralaje dice cuánto se mueven con la cámara: 1 normal, 0,5 la mitad (parecen lejos), 0 quietas en pantalla.
• Dibujo. En un mapa xy, las baldosas sólidas y las plataformas tienen volumen (el grosor), así que el nivel también se ve bien si la cámara pasa a 3D; lo demás (escaleras, púas, adornos) queda plano, justo detrás del avatar. En un mapa xz, las baldosas reciben luz y sombras como las piezas. El acabado y el patron del material no se aplican a las baldosas: solo el color.
• Tamaños. Hasta 512 x 512 celdas por mapa, 8 mapas por escena y 200 000 baldosas por escena.
• En mundos 3D. Un mapa xy tiene volumen, así que un tramo 2D se ve como un pasillo de bloques al salir a 3D. Usa el mismo z en origen del mapa y en plano.valor de la zona.
• Las láminas que miran a la cámara en una vista desde arriba quedan acostadas a su altura: un muro vecino más alto las tapa. Las de los personajes se dibujan sobre su cabeza para evitarlo; las demás, súbelas o aléjalas.

El script lee y cambia las baldosas con mundo.mapa(id): ver Mapa. Un mapa no crece más allá de las filas y columnas declaradas.

Lo que los mapas todavía no hacen: las baldosas no se animan solas (para agua o lava que se mueve, usa piezas con "forma": "lamina"), no hay pendientes y las piezas dinámicas chocan con las plataformas de un sentido por los dos lados.

Consejos para un nivel 2D#

• El plano del nivel lateral es el de vista.plano (por defecto z = 0): usa ese mismo z en origen del mapa y en las piezas sueltas (monedas, plataformas que se mueven).
• Deja el salto en lo que da el avatar. Una plataforma a 2 celdas de alto se alcanza; a 3, no.
• El personaje se dibuja mirando a la derecha, en una lámina de proporción 1 a 2 (por ejemplo 8 x 16).
• Todo lo demás (script, HUD, bot, puntajes) es igual que en un juego 3D.

Consejos para armar la escena#

• Centro contra pies. posicion de una pieza es su centro; la de una aparición son los pies. Una plataforma con la cara superior en y = 0 es "posicion": [x, -0.5, z], "tamano": [a, 1, l], y la aparición sobre ella va en y = 0.
• Parte por el suelo y las apariciones. Si la aparición no está sobre una pieza sólida, el jugador aparece y cae. El validador avisa.
• Diseña con las medidas del avatar: huecos de hasta 4 unidades, escalones de hasta 0,45 sin saltar, saltos de hasta 2,6 de alto. La tabla completa está en Estructura de un paquete.
• Etiquetas para lo que se repite, id para lo único. moneda, peligro, control son etiquetas; el id es para lo que el script o el bot nombran uno por uno (ascensor, meta). Si son muchas piezas iguales, omite el id.
• Lo que cambia con la dificultad va en la escena, con "dificultades": ["facil"] en la pieza o la zona. Circuito Luz Verde tiene dos juegos de losas en el mismo lugar: las anchas para facil y normal, y las angostas (con otro id) para dificil.
• Los peligros se entienden por el color. Usa { "color": "coral", "acabado": "neon" } y no hace falta explicarlos.
• Decorado sin costo de física. Lo que nadie toca va con "fisica": "ninguna".

Sigue con#

• Scripts: darle comportamiento a lo que declaraste.
• mundo: leer, crear, mover y eliminar piezas desde el script.
• La escena en el editor: armar lo mismo sin escribir JSON.
• Tipos de juego: elegir la vista al crear un proyecto en el editor.