Skip to content
Docs

The actores service

Reference for the actores service. Block characters driven by the script: rivals, neighbors, enemies.

DescribesFormato 1, API 1 For those who write code This page is generated from the SDK sources.

On this page

Block characters driven by the script: rivals, neighbors, enemies. They use the same body and the same physics as a player (they walk, jump, fall and ride platforms), but they do not collide with players or with each other: you detect them with events. Up to 64 at once. They go away when the scene changes.

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

Functions and properties of actores#

actores.crear#

ts
actores.crear(def: { id?; posicion: Vec3; rotacionY?; apariencia?: { torso?, piernas?, piel?, gorro? }; escala?; rapidez?; salto?; equipo?; etiquetas?; fisica?; datos? }): Actor

Creates an actor. Only posicion is required: it is where its feet go.

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

ts
// Un vecino que saluda con su nombre y se pasea por la plaza.
const vecino = actores.crear({ id: 'vecino', posicion: [4, 0, 4], apariencia: { torso: 'cielo', gorro: 'ambar' }, rapidez: 3 });

actores.actor#

ts
actores.actor(id: string): Actor

The actor with that id. Fails with a clear message if it does not exist (use actores.existe to ask first).

actores.existe#

ts
actores.existe(id: string): boolean

Tells whether an actor with that id exists.

actores.todos#

ts
actores.todos(etiqueta?: string): Actor[]

Every actor, or those with that tag.

actores.en#

ts
actores.en(centro: Vec3, radio: number): Actor[]

Actors closer than radio to a point.

actores.alTocar#

ts
actores.alTocar(selectorDeActor: Selector, fn: (actor: Actor, jugador: Jugador) => void): void

A player starts touching an actor. The selector is an actor id or '#tag'.

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

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

actores.alEncontrarse#

ts
actores.alEncontrarse(selectorDeActor: Selector, fn: (actor: Actor, otro: Actor) => void): void

Two actors start touching. The selector picks the first one.

actores.alTocarPieza#

ts
actores.alTocarPieza(selectorDePieza: Selector, fn: (pieza: Pieza, actor: Actor) => void): void

An actor starts touching a piece. The selector is a piece selector: its id or '#tag'.

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

ts
actores.alTocarPieza('#trampa', (trampa, a) => { trampa.eliminar(); a.eliminar(); });

actores.alEntrar#

ts
actores.alEntrar(selectorDeZona: Selector, fn: (zona: Zona, actor: Actor) => void): void

An actor enters a zone. The selector is a zone selector.

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

ts
// Un actor llega a una zona, toca una pieza o cae del mundo.
actores.alEntrar('base', (_zona, a) => { if (a.tiene('enemigo')) juego.terminar({ resultado: 'derrota' }); });

actores.alSalir#

ts
actores.alSalir(selectorDeZona: Selector, fn: (zona: Zona, actor: Actor) => void): void

An actor leaves a zone. The selector is a zone selector.

actores.alCaer#

ts
actores.alCaer(fn: (actor: Actor) => void): void

An actor fell below alturaCaida: the room has already removed it.

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

ts
actores.alCaer((a) => juego.registro('cayo', a.id));

Actor#

A block character controlled by the script. It walks with the same physics as a player.

PropertyTypeDescription
actor.idstringRead-only. Id of the actor. If none was given on creation, the room assigned one.
actor.existebooleanRead-only. false once it has been removed (or has fallen out of the world).
actor.posicionVec3Position of the feet. Assigning it teleports the actor.
actor.rotacionYnumberWhere it faces, in degrees (0 is +Z).
actor.velocidadVec3Velocity of the actor.
actor.enSuelobooleanRead-only. true while standing on something.
actor.sueloPieza | nullRead-only. The piece it is standing on, if any.
actor.enCaminobooleanRead-only. true while heading to a destination (irA, seguirRuta, seguir).
actor.rapideznumberWalking speed in units per second. Defaults to 5.
actor.saltonumberJump height.
actor.equipostringTeam name, free text.
actor.nombreTexto | nullText floating above its head. null removes it.
actor.apariencia{ torso?, piernas?, piel?, gorro? }Colors of the actor: torso, legs, skin and hat.
actor.visiblebooleanfalse: it is not drawn.
actor.etiquetasreadonly string[]Read-only. The tags of the actor.
actor.datosRecord<string, unknown>Free data for the script, per actor.

actor.tiene#

ts
actor.tiene(e: string): boolean

Tells whether the actor has that tag.

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

ts
// Un actor llega a una zona, toca una pieza o cae del mundo.
actores.alEntrar('base', (_zona, a) => { if (a.tiene('enemigo')) juego.terminar({ resultado: 'derrota' }); });

actor.etiquetar#

ts
actor.etiquetar(e: string): void

Adds a tag.

actor.desetiquetar#

ts
actor.desetiquetar(e: string): void

Removes a tag.

actor.irA#

ts
actor.irA(destino: Vec3, opciones?: { tolerancia?: number; ruta?: boolean; alLlegar?: () => void }): void

Walks to a point. With ruta: true it goes around walls and gaps. Replaces the previous order.

actor.seguirRuta#

ts
actor.seguirRuta(puntos: Vec3[], opciones?: { ciclo?: boolean; alLlegar?: () => void }): void

Walks through the points, in order. With ciclo, it returns to the first one forever (patrols).

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

ts
// Un vecino que saluda con su nombre y se pasea por la plaza.
const vecino = actores.crear({ id: 'vecino', posicion: [4, 0, 4], apariencia: { torso: 'cielo', gorro: 'ambar' }, rapidez: 3 });
// ...
vecino.seguirRuta([[4, 0, -4], [-4, 0, -4], [-4, 0, 4], [4, 0, 4]], { ciclo: true });

actor.seguir#

ts
actor.seguir(objetivo: Jugador | Actor | Pieza, opciones?: { distancia?: number; ruta?: boolean }): void

Chases a player, another actor or a piece, until it is distancia away (1.5 by default).

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

ts
// Enemigos que persiguen al jugador rodeando los muros; tocar uno cuesta una vida.
for (let i = 0; i < 3; i++) {
  const e = actores.crear({ posicion: [10 + i * 2, 0, 10], etiquetas: ['enemigo'], equipo: 'rojo', apariencia: { torso: 'coral', piernas: 'tinta' }, escala: 1.2 });
  e.seguir(jugadores.todos()[0], { distancia: 0.8, ruta: true });
}

actor.detener#

ts
actor.detener(): void

Stays where it is.

actor.mirarA#

ts
actor.mirarA(objetivo: Vec3 | Jugador | Actor | Pieza): void

Turns to face a point, a player, an actor or a piece.

actor.saltar#

ts
actor.saltar(): void

Jumps, if it is on the ground.

actor.impulsar#

ts
actor.impulsar(velocidad: Vec3): void

Adds velocity instantly.

actor.eliminar#

ts
actor.eliminar(): void

Removes the actor from the world.

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

ts
actores.alTocarPieza('#trampa', (trampa, a) => { trampa.eliminar(); a.eliminar(); });

Behavior notes#

  • An actor walks in a straight line and does not step into the void: it stops at an edge. It jumps steps that block its way. With ruta: true it goes around walls and gaps on the same level, using the same router as the test bot.
  • The animation (walking, jumping, falling) follows from its movement by itself.
  • fisica: false leaves it floating wherever it is put (no gravity, no collisions): the script moves it with posicion, or with irA, which then goes straight.
  • escala goes from 0.4 to 3 (a big boss, a child).

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.

actores: script characters#

scripts/principal.ts
import { actores, interfaz, juego, jugadores, mundo } from '@greengames/sdk';

juego.alIniciar(() => {
  // Un vecino que saluda con su nombre y se pasea por la plaza.
  const vecino = actores.crear({ id: 'vecino', posicion: [4, 0, 4], apariencia: { torso: 'cielo', gorro: 'ambar' }, rapidez: 3 });
  vecino.nombre = interfaz.t('vecino');
  vecino.seguirRuta([[4, 0, -4], [-4, 0, -4], [-4, 0, 4], [4, 0, 4]], { ciclo: true });

  // Enemigos que persiguen al jugador rodeando los muros; tocar uno cuesta una vida.
  for (let i = 0; i < 3; i++) {
    const e = actores.crear({ posicion: [10 + i * 2, 0, 10], etiquetas: ['enemigo'], equipo: 'rojo', apariencia: { torso: 'coral', piernas: 'tinta' }, escala: 1.2 });
    e.seguir(jugadores.todos()[0], { distancia: 0.8, ruta: true });
  }
  actores.alTocar('#enemigo', (enemigo, j) => { j.reaparecer(); enemigo.posicion = [10, 0, 10]; });

  // Un actor llega a una zona, toca una pieza o cae del mundo.
  actores.alEntrar('base', (_zona, a) => { if (a.tiene('enemigo')) juego.terminar({ resultado: 'derrota' }); });
  actores.alTocarPieza('#trampa', (trampa, a) => { trampa.eliminar(); a.eliminar(); });
  actores.alCaer((a) => juego.registro('cayo', a.id));
});

Next#