Servicio actores

Referencia del servicio actores. Personajes de bloques que maneja el script: rivales, vecinos, enemigos.

Corresponde aFormato 1, API 1 Para quien escribe código Esta página se genera desde las fuentes del SDK.

En esta página

Personajes de bloques que maneja el script: rivales, vecinos, enemigos. Usan el mismo cuerpo y la misma física que un jugador (caminan, saltan, caen, viajan sobre plataformas), pero no chocan con jugadores ni entre sí: se detectan con eventos. Hasta 64 a la vez. Se van al cambiar de escena.

Los tipos que aparecen en las firmas (Vec3, Texto, el selector) están en la referencia de la API.

Funciones y propiedades de `actores`#

`actores.crear`#

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

Crea un actor. Solo posicion es obligatoria: es donde quedan sus pies.

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

// 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`#

actores.actor(id: string): Actor

El actor con ese id. Falla con un mensaje claro si no existe (usa actores.existe para preguntar).

`actores.existe`#

actores.existe(id: string): boolean

Dice si hay un actor con ese id.

`actores.todos`#

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

Todos los actores, o los que tienen esa etiqueta.

`actores.en`#

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

Actores a menos de radio de un punto.

`actores.alTocar`#

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

Un jugador empieza a tocar a un actor. El selector es el id de un actor o '#etiqueta'.

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

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

`actores.alEncontrarse`#

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

Dos actores empiezan a tocarse. El selector elige al primero.

`actores.alTocarPieza`#

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

Un actor empieza a tocar una pieza. El selector es de pieza: su id o '#etiqueta'.

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

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

`actores.alEntrar`#

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

Un actor entra a una zona. El selector es de zona.

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

// 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`#

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

Un actor sale de una zona. El selector es de zona.

`actores.alCaer`#

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

Un actor cayó bajo alturaCaida: la sala ya lo eliminó.

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

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

Actor#

Un personaje de bloques controlado por el script. Camina con la misma física que un jugador.

Propiedad	Tipo	Descripción
`actor.id`	`string`	Solo lectura. Id del actor. Si no se indicó al crearlo, la sala le asignó uno.
`actor.existe`	`boolean`	Solo lectura. `false` cuando fue eliminado (o cayó del mundo).
`actor.posicion`	`Vec3`	Posición de los pies. Asignarla lo teletransporta.
`actor.rotacionY`	`number`	Hacia dónde mira, en grados (0 es +Z).
`actor.velocidad`	`Vec3`	Velocidad del actor.
`actor.enSuelo`	`boolean`	Solo lectura. `true` si está parado sobre algo.
`actor.suelo`	`Pieza \| null`	Solo lectura. Pieza sobre la que está parado, si hay.
`actor.enCamino`	`boolean`	Solo lectura. `true` mientras va hacia un destino (`irA`, `seguirRuta`, `seguir`).
`actor.rapidez`	`number`	Unidades por segundo al caminar. Por defecto 5.
`actor.salto`	`number`	Altura del salto.
`actor.equipo`	`string`	Nombre de equipo, libre.
`actor.nombre`	`Texto \| null`	Texto que flota sobre su cabeza. `null` lo quita.
`actor.apariencia`	`{ torso?, piernas?, piel?, gorro? }`	Colores del actor: torso, piernas, piel y gorro.
`actor.visible`	`boolean`	`false`: no se dibuja.
`actor.etiquetas`	`readonly string[]`	Solo lectura. Las etiquetas del actor.
`actor.datos`	`Record<string, unknown>`	Datos libres del script, por actor.

`actor.tiene`#

actor.tiene(e: string): boolean

Dice si el actor tiene esa etiqueta.

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

// 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`#

actor.etiquetar(e: string): void

Le pone una etiqueta.

`actor.desetiquetar`#

actor.desetiquetar(e: string): void

Le quita una etiqueta.

`actor.irA`#

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

Camina hasta un punto. Con ruta: true rodea muros y huecos. Reemplaza la orden anterior.

`actor.seguirRuta`#

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

Camina pasando por los puntos, en orden. Con ciclo, vuelve al primero para siempre (patrullas).

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

// 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`#

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

Persigue a un jugador, a otro actor o a una pieza, hasta quedar a distancia (por defecto 1.5).

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

// 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`#

actor.detener(): void

Se queda donde está.

`actor.mirarA`#

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

Gira para mirar a un punto o a un jugador, actor o pieza.

`actor.saltar`#

actor.saltar(): void

Salta, si está en el suelo.

`actor.impulsar`#

actor.impulsar(velocidad: Vec3): void

Suma velocidad al instante.

`actor.eliminar`#

actor.eliminar(): void

Quita al actor del mundo.

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

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

Notas de comportamiento#

Un actor camina en línea recta y no se tira al vacío: ante un borde se detiene. Salta escalones que le cortan el paso. Con ruta: true rodea muros y huecos del mismo nivel, con el mismo enrutador que usa el bot de prueba.
La animación (caminar, saltar, caer) sale sola de su movimiento.
fisica: false lo deja flotando donde lo pongan (sin gravedad ni choques): el script lo mueve con posicion, o con irA, que entonces avanza derecho.
escala va de 0,4 a 3 (un jefe grande, un niño).

Ejemplos completos#

Scripts completos de docs/EJEMPLOS.md. Cada uno supone una escena con lo que nombra, y las claves de texto (interfaz.t('...')) deben existir en textos de juego.json.

actores: personajes del script#

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));
});

Sigue con#

Servicio camara
Referencia de la API: los once servicios y los tipos comunes.
Scripts: las reglas de un script y cómo corre dentro de la sala.

Funciones y propiedades de actores#

actores.crear#

actores.actor#

actores.existe#

actores.todos#

actores.en#

actores.alTocar#

actores.alEncontrarse#

actores.alTocarPieza#

actores.alEntrar#

actores.alSalir#

actores.alCaer#

Actor#

actor.tiene#

actor.etiquetar#

actor.desetiquetar#

actor.irA#

actor.seguirRuta#

actor.seguir#

actor.detener#

actor.mirarA#

actor.saltar#

actor.impulsar#

actor.eliminar#

Notas de comportamiento#

Ejemplos completos#

actores: personajes del script#

Sigue con#

Funciones y propiedades de `actores`#

`actores.crear`#

`actores.actor`#

`actores.existe`#

`actores.todos`#

`actores.en`#

`actores.alTocar`#

`actores.alEncontrarse`#

`actores.alTocarPieza`#

`actores.alEntrar`#

`actores.alSalir`#

`actores.alCaer`#

`actor.tiene`#

`actor.etiquetar`#

`actor.desetiquetar`#

`actor.irA`#

`actor.seguirRuta`#

`actor.seguir`#

`actor.detener`#

`actor.mirarA`#

`actor.saltar`#

`actor.impulsar`#

`actor.eliminar`#