Referencia de la API

El objeto greengames#

El script es un programa que corre dentro de la sala: la simulación autoritativa de la partida. Corre aislado (un Web Worker dentro de un iframe con sandbox): no hay DOM, red, almacenamiento del sitio, temporizadores del navegador ni eval. Solo existen JavaScript estándar y el objeto greengames con once servicios.

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

Dentro del .ggx el script es JavaScript clásico y esos nombres salen del global: un script escrito a mano, sin herramientas, puede empezar con const { juego, mundo, jugadores } = greengames;.

Las reglas que debe cumplir un script están en Scripts.

Los once servicios#

Disponibilidad#

Todo lo que describe esta referencia funciona en el portal web, en el CLI, en el launcher 0.4.0 y en el editor 0.4.0: los cuatro traen el contrato completo, versión 1.2. Las aplicaciones 0.3.0 traían la versión 1.1, sin los modelos 3D, las texturas ni los sonidos grabados; las 0.2.0, los once servicios sin lo que agregó la versión 1.1: el terreno de cubos, el puntero y la barra rápida.

Lo que no traían las aplicaciones 0.1.0#

Todo esto se agregó después de la primera versión del contrato. Los cambios fueron aditivos: un juego escrito para la primera versión sigue funcionando sin tocarlo.

• 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; todo Grupo; todo Luz; zona.datos, zona.actores, zona.eliminar; todo Mapa; todo 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 de interfaz.cronometro; lugar, tamano y cola de interfaz.mensaje; la opción de menú deshabilitada; los textos traducibles como variables de interfaz.t; 16 de los 24 iconos.
• sonido: sonido.ruido, sonido.muestra; ataque y caida de sonido.tono.
• actores: el servicio entero.
• camara: el servicio entero.
• En el formato: las vistas (vista en la escena y en las zonas), las láminas (laminas/, la forma lamina), los mapas de baldosas (mapas) y multijugador en el manifiesto. Están en Escenas y Manifiesto.

Lo que agregó la versión 1.1#

El terreno de cubos, el puntero y la barra rápida. Están en el portal, en el CLI y desde el launcher 0.3.0 y el editor 0.3.0; el launcher 0.2.0 y el editor 0.2.0 no los traían. Cómo se arma un juego con ellos: Mundo abierto.

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

Lo que agregó la versión 1.2#

Los modelos 3D, las texturas de imagen y los sonidos grabados. Están en el portal, en el CLI, en el launcher 0.4.0 y en el editor 0.4.0; las aplicaciones 0.3.0 no los traían. Cómo se usan desde una escena y desde el script: Modelos, texturas y sonidos.

• mundo: mundo.modelo, mundo.modelos, mundo.crearModelo; pieza.modelo, pieza.clips, pieza.reproducir, pieza.pararAnimacion, pieza.alTerminarClip.
• sonido: sonido.muestra.
• En el formato: la forma modelo con su modelo y su animacion, textura y repetir en el material, la imagen plana con textura, el modelo del jugador (avatar), y las carpetas modelos/, texturas/ y sonidos/ con creditos.json.

Tipos comunes#

Las firmas usan estos tipos. Los que describen datos de una escena (PiezaDef, ZonaDef, LuzDef) tienen el mismo formato que en el archivo de la escena: están en Escenas.

Vec3#

Un punto, una dirección o un tamaño: [x, y, z]. Y es arriba. Las rotaciones van en grados.

type Vec3 = [number, number, number];

Texto#

Lo que se le muestra a un jugador: una clave de textos armada con interfaz.t, un objeto { es, en } o una cadena tal cual. Está explicado en interfaz.

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

Selector#

A qué piezas, zonas o actores escucha un evento: un id ('meta') o una etiqueta con numeral ('#moneda').

type Selector = string;

MaterialDef#

El material de una pieza: el nombre de un color de la paleta, o un objeto con color, acabado y patrón.

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 y Fisica#

La forma de una pieza y cómo participa en la física: fija no se mueve sola, a la dinamica la empuja la física y ninguna es decorado sin colisión ni eventos. La forma lamina es una imagen plana de píxeles: está en Escenas.

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

AccionEntrada#

Los tres botones de un jugador, iguales en teclado, pantalla táctil y mando.

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

OpcionesMover#

Las opciones de pieza.moverA y grupo.moverA: cuánto tarda, con qué suavizado, si va y vuelve y a quién avisa al llegar.

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

Impacto#

Lo que devuelven mundo.rayo y jugador.apunta: la pieza con la que chocó el rayo (null si chocó con algo que no es una pieza, como un bloque de un mapa de baldosas), el punto y la distancia.

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

VistaDef#

Una vista: la cámara, cómo se mueve el jugador y, en las 2D, a qué plano queda restringido. Es el mismo objeto que vista en la escena y en las zonas; camara.vista también acepta solo el tipo. Cada parámetro está explicado en Escenas.

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#

Cómo choca una baldosa de un mapa: lo que devuelve mapa.colision. Cada valor está explicado en Escenas.

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

Aparicion#

Un punto de aparición de la escena: donde entran y reaparecen los jugadores.

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

Icono#

Los iconos que el HUD sabe dibujar por nombre.

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#

Las seis posiciones del HUD.

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

SonidoPredefinido#

Los sonidos que sonido.tocar sabe sintetizar por nombre.

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

Cómo leer la referencia#

• Hay una página por servicio. Cada una lista primero las funciones y propiedades del servicio y después las de los objetos que entrega (por ejemplo Pieza, Zona y Jugador).
• Cada función trae su firma, qué hace y un ejemplo. La firma es la del formato 1, API 1.
• Los ejemplos no están escritos para la documentación: son fragmentos de los ejemplos del SDK o de los juegos del catálogo, y cada uno dice de qué archivo sale. Una función sin ejemplo es una función que ninguno de esos archivos usa todavía.
• Las propiedades simples van en una tabla. «Solo lectura» quiere decir que el script puede leerla pero no asignarla.
• Al final de cada página están las notas de comportamiento y los ejemplos completos del servicio.
• Las páginas de la referencia se generan desde las fuentes de Green Games: si encuentras una diferencia con lo que hace el motor, manda el motor.

Sigue con#

• Servicio juego
• Límites vigentes
• El validador y sus códigos