The jugadores service

Who is in the room, humans and bots: their position, abilities, actions, view and state.

The types used in the signatures (Vec3, Texto, the selector) are in the API reference.

Functions and properties of jugadores#

jugadores.todos#

jugadores.todos(): Jugador[]

Players present, humans and bots.

From docs/EJEMPLOS.md, «interfaz: menú»:

for (const j of jugadores.todos()) j.congelado = true;       // un menú no pausa la partida

jugadores.humanos#

jugadores.humanos(): Jugador[]

Players present that are not bots.

From games/copa-de-bloques/scripts/principal.ts:

hum = jugadores.humanos()[0] ?? jugadores.todos()[0];

jugadores.porId#

jugadores.porId(id: string): Jugador | null

The player with that id, or null if there is none.

jugadores.alEntrar#

jugadores.alEntrar(fn: (j: Jugador) => void): void

A player enters the room. It is also called for those already in when the event is registered.

From docs/EJEMPLOS.md, «interfaz: HUD, mensajes y cronómetro»:

jugadores.alEntrar((j) => {
  interfaz.hud('puntos', { icono: 'estrella', texto: interfaz.t('puntos', { n: 0 }), lugar: 'arriba-izquierda' }, j);
});

jugadores.alSalir#

jugadores.alSalir(fn: (j: Jugador) => void): void

A player leaves the room.

From games/isla-taller/scripts/principal.ts:

jugadores.alSalir((j) => {
  for (const p of pilas.get(j.id) ?? []) p.eliminar();
  pilas.delete(j.id);
});

jugadores.alAccion#

jugadores.alAccion(accion: 'saltar' | 'accion' | 'accion2', fn: (j: Jugador) => void): void

A player presses an action (once per press).

From docs/EJEMPLOS.md, «jugadores: estado por jugador, acciones y caídas»:

jugadores.alAccion('accion', (j) => {            // una vez por pulsación
  j.impulsar([0, 14, 0]);
  sonido.tocar('poder', { para: j });
});

jugadores.alCaer#

jugadores.alCaer(fn: (j: Jugador) => void): void

A player fell below alturaCaida. The room has already respawned them; here you take a life, add a penalty, and so on.

From docs/EJEMPLOS.md, «jugadores: estado por jugador, acciones y caídas»:

jugadores.alCaer((j) => {                        // la sala ya lo devolvió a su aparición
  const vidas = (j.datos.vidas as number) - 1;
  j.datos.vidas = vidas;
  interfaz.hud('vidas', { icono: 'corazon', texto: interfaz.t('vidas', { n: vidas }), estilo: vidas === 1 ? 'peligro' : 'normal' }, j);
  if (vidas <= 0) juego.terminar({ resultado: 'derrota', puntaje: j.puntos, de: j });
});

jugadores.alCambiarPantalla#

jugadores.alCambiarPantalla(fn: (j: Jugador) => void): void

A player's screen changed size or orientation. It is also called once when the screen is first known.

From docs/EJEMPLOS.md, «interfaz: mensajes que no estorban, menú con opción deshabilitada, textos anidados»:

// Textos mas cortos en telefonos verticales.
jugadores.alCambiarPantalla((j) => interfaz.hud('ayuda', { texto: interfaz.t(j.pantalla.vertical ? 'ayudaCorta' : 'ayuda'), lugar: 'abajo-centro' }, j));

jugadores.alCambiarRanura#

jugadores.alCambiarRanura(fn: (j: Jugador, ranura: number) => void): void

The player picked another slot of the hotbar.

From games/valle-abierto/scripts/principal.ts:

jugadores.alCambiarRanura((j) => sonido.tocar('tic', { para: j, volumen: 0.4 }));

Jugador#

A player in the room: a person or a bot.

jugador.teletransportar#

jugador.teletransportar(destino: Vec3 | string, rotacionY?: number): void

Takes the player to a point or to a spawn point (by id), and zeroes its velocity.

From docs/EJEMPLOS.md, «jugadores: mover, teletransportar y cambiar habilidades»:

mundo.alTocar('#portal', (_p, j) => j.teletransportar('sala-2'));       // id de una aparición

jugador.reaparecer#

jugador.reaparecer(): void

Sends the player back to its current spawn point.

From docs/EJEMPLOS.md, «actores: personajes del script»:

actores.alTocar('#enemigo', (enemigo, j) => { j.reaparecer(); enemigo.posicion = [10, 0, 10]; });

jugador.impulsar#

jugador.impulsar(velocidad: Vec3): void

Adds velocity instantly (bounces, trampolines).

From docs/EJEMPLOS.md, «jugadores: mover, teletransportar y cambiar habilidades»:

mundo.alTocar('#trampolin', (_p, j) => j.impulsar([0, 20, 0]));

jugador.pulsa#

jugador.pulsa(accion: AccionEntrada): boolean

true while the action is held down.

From docs/CONTRATO.md, section 4.3:

jugador.pulsa('primaria')

jugador.apunta#

jugador.apunta(distancia?: number): Impacto | null

The first thing in front of the player, up to distancia (4 by default): the piece being looked at. For "interact with what I am looking at".

jugador.caminarA#

jugador.caminarA(destino: Vec3 | null): void

Sends the avatar walking to a point (it goes around obstacles). null stops it. Any movement by the player cancels it.

jugador.apuntaBloque#

jugador.apuntaBloque(distancia?: number): BloqueApuntado | null

The terrain block the player is pointing at, up to distancia units from the eyes (5 by default), or null. It carries the face touched and the neighboring cell where a new block would go.

From games/valle-abierto/scripts/principal.ts:

const a = j.apuntaBloque(ALCANCE);

Behavior notes#

Pointer and hotbar (version 1.1). Two more actions, declared in controles.acciones like the others:

They are used like the others: jugadores.alAccion('primaria', fn) (once per press) and jugador.pulsa('primaria') (while held). When a game declares either of them:

• the mouse is captured on click in third person too (Esc releases it; the click that captures it does not count as an action) and the crosshair appears in the center. If the browser does not allow capturing it, you look around by dragging and clicks act the same;
• jugador.puntero is the ray from the camera through the crosshair. In first person it is the same as jugador.mirada; in third person it starts at the camera, behind the avatar. For bots it is the look direction;
• the hotbar is drawn with interfaz.barraRapida and a slot is picked with the mouse wheel, keys 1 to 9, the gamepad d-pad (left and right) or by touching a slot. The selected one is jugador.ranura.

They work for any game (shooting, picking up, using what you look at), not only for cube games.

Details worth knowing:

• rapidez accepts 0 to 40 and salto 0 to 30; values out of range are clamped.
• velocidad returns the actual velocity (walking plus pushes). To know what the player wants to do, use entrada.
• A horizontal impulsar slows down on its own (friction of 0.82 per frame on the ground, 0.985 in the air): it is a push, not a sustained speed.
• teletransportar puts the player on the ground right away if there is floor under its feet.
• pantalla is 1280 x 720, not touch, for bots and in greengames probar. On phones, a HUD chip comfortably shows about 24 characters per line (it wraps up to three lines).

Complete examples#

Complete scripts from docs/EJEMPLOS.md. Each one assumes a scene containing what it names, and the text keys (interfaz.t('...')) must exist in textos of juego.json.

jugadores: per-player state, actions and falls#

import { interfaz, juego, jugadores, sonido } from '@greengames/sdk';

juego.alIniciar(() => {
  jugadores.alEntrar((j) => {
    j.datos = { vidas: 3 };
    interfaz.hud('vidas', { icono: 'corazon', texto: interfaz.t('vidas', { n: 3 }) }, j);
  });

  jugadores.alCaer((j) => {                        // la sala ya lo devolvió a su aparición
    const vidas = (j.datos.vidas as number) - 1;
    j.datos.vidas = vidas;
    interfaz.hud('vidas', { icono: 'corazon', texto: interfaz.t('vidas', { n: vidas }), estilo: vidas === 1 ? 'peligro' : 'normal' }, j);
    if (vidas <= 0) juego.terminar({ resultado: 'derrota', puntaje: j.puntos, de: j });
  });

  jugadores.alAccion('accion', (j) => {            // una vez por pulsación
    j.impulsar([0, 14, 0]);
    sonido.tocar('poder', { para: j });
  });
});

jugadores: moving, teleporting and changing abilities#

import { juego, mundo } from '@greengames/sdk';

juego.alIniciar(() => {
  mundo.alTocar('#trampolin', (_p, j) => j.impulsar([0, 20, 0]));
  mundo.alTocar('#portal', (_p, j) => j.teletransportar('sala-2'));       // id de una aparición
  mundo.alTocar('#botas', (botas, j) => { botas.eliminar(); j.saltosExtra = 1; j.rapidez = 11; });
  mundo.alTocar('#hielo', (_p, j) => { j.congelado = true; });
});

Next#

• The interfaz service
• API reference: the eleven services and the common types.
• Scripts: the rules of a script and how it runs inside the room.