API reference

The greengames object#

The script is a program that runs inside the room: the authoritative simulation of the match. It runs isolated (a Web Worker inside a sandboxed iframe): there is no DOM, no network, no site storage, no browser timers and no eval. Only standard JavaScript and the greengames object, with eleven services, exist.

import { juego, mundo, jugadores, interfaz, sonido, progreso, puntajes, azar, reloj, actores, camara } from '@greengames/sdk';

Inside the .ggx the script is classic JavaScript and those names come from the global: a script written by hand, with no tools, can start with const { juego, mundo, jugadores } = greengames;.

The rules a script must follow are in Scripts.

The eleven services#

Availability#

Everything this reference describes works on the web portal, in the CLI, in launcher 0.4.0 and in editor 0.4.0: all four ship the full contract, version 1.2. The 0.3.0 apps shipped version 1.1, without 3D models, textures or recorded sounds; the 0.2.0 apps, the eleven services without what version 1.1 added: the cube terrain, the pointer and the hotbar.

What the 0.1.0 apps did not have#

All of this was added after the first version of the contract. The changes were additive: a game written for the first version still works untouched.

• juego: juego.senalar.
• mundo: mundo.mientrasToca, mundo.alChocar, mundo.piezasEn, mundo.jugadoresEn, mundo.grupo, mundo.crearZona, mundo.mapa, mundo.mapas, mundo.luz, mundo.luces, mundo.crearLuz, mundo.ambiente, mundo.terreno, mundo.modelo, mundo.modelos, mundo.crearModelo; pieza.grupo, pieza.rebote, pieza.friccion, pieza.opacidad, pieza.emision, pieza.velocidadDeGiro, pieza.lamina, pieza.animacion, pieza.espejo, pieza.modelo, pieza.clips, pieza.reproducir, pieza.pararAnimacion, pieza.alTerminarClip; all of Grupo; all of Luz; zona.datos, zona.actores, zona.eliminar; all of Mapa; all of Terreno.
• jugadores: jugadores.alCambiarPantalla, jugadores.alCambiarRanura; jugador.entrada, jugador.pantalla, jugador.apariencia, jugador.equipo, jugador.vista, jugador.mirada, jugador.apunta, jugador.caminarA, jugador.ranura, jugador.puntero, jugador.apuntaBloque, jugador.vuelo, jugador.enAgua.
• interfaz: interfaz.rotulo, interfaz.flotante, interfaz.marcadorDePuntos, interfaz.barraRapida, interfaz.marcarBloque; formato of interfaz.cronometro; lugar, tamano and cola of interfaz.mensaje; the deshabilitada menu option; translatable texts as variables of interfaz.t; 16 of the 24 icons.
• sonido: sonido.ruido, sonido.muestra; ataque and caida of sonido.tono.
• actores: the whole service.
• camara: the whole service.
• In the format: views (vista in the scene and in zones), sprites (laminas/, the lamina shape), tile maps (mapas) and multijugador in the manifest. They are covered in Scenes and Manifest.

What version 1.1 added#

The cube terrain, the pointer and the hotbar. They are on the portal, in the CLI and from launcher 0.3.0 and editor 0.3.0 on; launcher 0.2.0 and editor 0.2.0 did not ship them. How to build a game with them: Open world.

• mundo: mundo.terreno; all of Terreno.
• jugadores: jugadores.alCambiarRanura; jugador.ranura, jugador.puntero, jugador.apuntaBloque, jugador.vuelo, jugador.enAgua.
• interfaz: interfaz.barraRapida, interfaz.marcarBloque.

What version 1.2 added#

3D models, image textures and recorded sounds. They are on the portal, in the CLI, in launcher 0.4.0 and in editor 0.4.0; the 0.3.0 apps did not ship them. How to use them from a scene and from the script: Models, textures and sounds.

• mundo: mundo.modelo, mundo.modelos, mundo.crearModelo; pieza.modelo, pieza.clips, pieza.reproducir, pieza.pararAnimacion, pieza.alTerminarClip.
• sonido: sonido.muestra.
• In the format: the modelo shape with its modelo and its animacion, textura and repetir in the material, the flat image with textura, the player model (avatar), and the modelos/, texturas/ and sonidos/ folders with creditos.json.

Common types#

The signatures use these types. The ones that describe scene data (PiezaDef, ZonaDef, LuzDef) have the same format as in the scene file: see Scenes.

Vec3#

A point, a direction or a size: [x, y, z]. Y is up. Rotations are in degrees.

type Vec3 = [number, number, number];

Texto#

What is shown to a player: a key from textos built with interfaz.t, an { es, en } object or a plain string. It is explained under interfaz.

type Texto = string | { es: string; en: string } | TextoClave;
interface TextoClave {
  clave: string;
  vars?: Record<string, string | number | TextoClave | { es: string; en: string }>;
}

Selector#

Which pieces, zones or actors an event listens to: an id ('meta') or a tag with a hash sign ('#moneda').

type Selector = string;

MaterialDef#

The material of a piece: the name of a palette color, or an object with color, finish and pattern.

type MaterialDef = string | { color: string; acabado?: Acabado; patron?: Patron; textura?: string; repetir?: [number, number]; pixelada?: boolean };
type Acabado = 'mate' | 'brillante' | 'neon' | 'cristal';
type Patron = 'liso' | 'cuadros' | 'franjas' | 'rejilla';

Forma and Fisica#

The shape of a piece and how it takes part in physics: fija does not move on its own, dinamica is pushed by physics and ninguna is scenery with no collision and no events. The lamina shape is a flat pixel image: see Scenes.

type Forma = 'caja' | 'esfera' | 'cilindro' | 'cuna' | 'rampa' | 'lamina' | 'modelo';
type Fisica = 'fija' | 'dinamica' | 'ninguna';

AccionEntrada#

A player's three buttons, the same on keyboard, touch screen and gamepad.

type AccionEntrada = 'saltar' | 'accion' | 'accion2' | 'primaria' | 'secundaria';

OpcionesMover#

The options of pieza.moverA and grupo.moverA: how long it takes, the easing, whether it goes back and forth, and what to call on arrival.

interface OpcionesMover {
  duracion: number;
  suavizado?: 'lineal' | 'suave';
  vaiven?: boolean;
  espera?: number;
  alLlegar?: () => void;
}

Impacto#

What mundo.rayo and jugador.apunta return: the piece the ray hit (null if it hit something that is not a piece, such as a block of a tile map), the point and the distance.

interface Impacto {
  pieza: Pieza | null;
  punto: Vec3;
  distancia: number;
}

VistaDef#

A view: the camera, how the player moves and, in the 2D ones, which plane the player is confined to. It is the same object as vista in the scene and in zones; camara.vista also accepts just the type. Every parameter is explained in Scenes.

interface VistaDef {
  tipo: TipoVista;
  campo?: number;
  zoom?: number;
  distancia?: number;
  inclinacion?: number;
  giro?: number;
  altura?: number;
  suavizado?: number;
  limites?: { min: Vec3; max: Vec3 };
  zonaMuerta?: [number, number];
  plano?: { eje: 'x' | 'z'; valor?: number };
  giroPorPasos?: boolean;
  clicParaMover?: boolean;
  reticula?: boolean;
  salto?: boolean;
}
type TipoVista = 'tercera-persona' | 'primera-persona' | 'isometrica' | 'cenital' | 'lateral' | 'plano';

ColisionBaldosa#

How a tile of a map collides: what mapa.colision returns. Every value is explained in Scenes.

type ColisionBaldosa = 'solida' | 'suelo' | 'plataforma' | 'peligro' | 'escalera' | 'ninguna';

Aparicion#

A spawn point of the scene: where players enter and respawn.

interface Aparicion {
  readonly id: string;
  readonly posicion: Vec3;
  readonly rotacionY: number;
}

Icono#

The icons the HUD can draw by name.

type Icono =
  | 'moneda' | 'reloj' | 'corazon' | 'estrella' | 'bandera' | 'llave' | 'rayo' | 'jugador'
  | 'escudo' | 'espada' | 'martillo' | 'casa' | 'gota' | 'hoja' | 'fuego' | 'engranaje' | 'diana'
  | 'diamante' | 'calavera' | 'flecha' | 'caja' | 'pregunta' | 'luz' | 'ola';

LugarHud#

The six HUD positions.

type LugarHud =
  | 'arriba-izquierda' | 'arriba-centro' | 'arriba-derecha' | 'abajo-izquierda' | 'abajo-centro'
  | 'abajo-derecha';

SonidoPredefinido#

The sounds sonido.tocar can synthesize by name.

type SonidoPredefinido =
  | 'moneda' | 'salto' | 'golpe' | 'caida' | 'control' | 'victoria' | 'derrota' | 'clic' | 'alerta'
  | 'tic' | 'luz' | 'poder';

How to read the reference#

• There is one page per service. Each lists the functions and properties of the service first, and then those of the objects it hands out (for example Pieza, Zona and Jugador).
• Each function comes with its signature, what it does and an example. The signature is the one for format 1, API 1.
• The examples were not written for the documentation: they are fragments of the SDK examples or of the games in the catalog, and each one says which file it comes from. A function with no example is one that none of those files uses yet.
• Simple properties go in a table. "Read-only" means the script can read it but not assign it.
• At the end of each page are the behavior notes and the complete examples for the service.
• The reference pages are generated from the Green Games sources: if you find a difference with what the engine does, the engine wins.

Next#

• The juego service
• Current limits
• The validator and its codes