Referencia de scripting

1. Crear y asignar un script

Cada proyecto tiene una carpeta scripts. Puedes crear, editar, renombrar y eliminar scripts desde la pestana Scripts del panel inferior. Cada objeto puede tener un script asignado desde el Inspector. Un mismo script puede asignarse a varios objetos.

Usa Refresh, situado a la derecha de la pestaña Scripts, después de crear, eliminar o cambiar el nombre de un archivo directamente desde VS Code o el Explorador. Si utilizas Rename desde el editor, GameCrom cambia el archivo y actualiza automáticamente sus asignaciones en los objetos, escenas guardadas y prefabs.

1. Selecciona un objeto en la escena o en la jerarquia.
2. En el Inspector busca el componente Script o abre la pestana Scripts.
3. Pulsa Create para crear uno nuevo o elige uno existente en File.
4. Pulsa Edit para abrirlo en Visual Studio Code.
5. Pulsa Play para ejecutar el script.

Los scripts solo se ejecutan en Play. Al salir de Play, la escena vuelve al estado de edicion.

Prefabs

Un prefab es una plantilla reutilizable de un objeto. Sirve para guardar un objeto de la escena con sus propiedades y sus hijos, y despues crear copias nuevas cuando las necesites.

1. Selecciona el objeto que quieres convertir en prefab.
2. Abre la pestana Prefabs en el panel inferior.
3. Pulsa Create From Selection.
4. Escribe el nombre del prefab y confirma.
5. Usa Instantiate para crear una copia del prefab en la escena.
6. Usa Delete para eliminar el archivo del prefab del proyecto.

La lista de prefabs muestra una miniatura del objeto raiz. Si el objeto tiene textura se ve la imagen; si no, se muestra una forma con su color.

En la barra superior del editor, Snap conserva el desplazamiento por pasos. El check Snap to Grid encaja la esquina superior izquierda del objeto directamente en la rejilla.

Los prefabs se guardan dentro de la carpeta prefabs del proyecto. Al instanciar uno, el motor crea objetos nuevos con IDs nuevos para no modificar el prefab original ni pisar objetos de la escena.

De momento el prefab funciona como plantilla reutilizable. Si editas el objeto instanciado en la escena, esos cambios pertenecen a esa copia. No se aplican automaticamente al prefab guardado.

Luces 2D

Puedes crear un objeto Light desde Add GameObject. En Play no se dibuja como sprite normal: ilumina la escena con una luz radial sobre el canvas. Los objetos Light no muestran Sprite Renderer ni Collider 2D porque no son objetos fisicos ni sprites del juego. La luz solo afecta a las capas que estan por debajo de ella en el orden de dibujo; los objetos colocados por encima se dibujan despues y no quedan iluminados por esa luz.

Los efectos se animan durante Play. Torch y Candle simulan parpadeo organico, Alarm alterna hacia un color secundario, Fluorescent crea pequenos cortes de intensidad y Pulse respira suavemente. El boton Play del componente permite previsualizar el efecto en el editor sin ejecutar el juego.

Recortar sprites

El recortador sirve para separar una textura grande que contiene muchos sprites mezclados, como una hoja de sprites. Los recortes se guardan como texturas PNG nuevas dentro del proyecto.

1. Abre la pestana Slice Sprite del panel inferior.
2. Elige la textura fuente.
3. Configura Cell W y Cell H con el tamano de cada sprite.
4. Ajusta Offset X/Y si la hoja tiene margen exterior.
5. Ajusta Spacing X/Y si hay separacion entre sprites.
6. Usa Columns y Rows para limitar el area, o deja 0 para calcularlo automaticamente.
7. Pulsa Save Slices para guardar cada recorte como textura nueva.

La textura original no se modifica. Si Empty esta desactivado, los recortes totalmente transparentes se saltan.

2. Ciclo de ejecucion

Un script puede exportar funciones de ciclo. Todas reciben el objeto que tiene asignado el script. Si no declaras una funcion, simplemente no se llama.

export function start(object) {
    debug("Empieza: " + object.name);
}

export function fixedUpdate(object, fixedDeltaTime) {
    // Paso fijo: ideal para fisica.
}

export function update(object, deltaTime) {
    object.x += 100 * deltaTime;
}

export function lateUpdate(object, deltaTime) {
    // Se ejecuta cuando todos los update del frame han terminado.
}

3. El objeto recibido

El parametro object es el objeto real de la escena durante Play. Puedes leer sus datos y cambiar propiedades como posicion, rotacion, escala, color, opacidad o estado activo.

export function start(object) {
    debug({
        id: object.id,
        name: object.name,
        tag: object.tag,
        x: object.x,
        y: object.y
    });
}

Si quieres ver todo lo que tiene un objeto, puedes enviarlo completo a la consola:

export function start(object) {
    debug(object);
}

4. Manejo de variables

En los scripts puedes crear variables normales de JavaScript. Segun donde las guardes, duran solo dentro de una funcion, pertenecen a un objeto, a la escena actual o a toda la partida del proyecto.

Tipos habituales

Variables locales

Viven solo dentro de la funcion donde se crean. Se pierden al terminar esa llamada.

export function update(object, deltaTime) {
    const speed = 120;
    object.translate(speed * deltaTime, 0);
}

Variables del script

Si las creas fuera de start y update, se conservan mientras ese script esta cargado en Play. Si el mismo script se asigna a varios objetos, esa variable se comparte entre ellos.

let totalUpdates = 0;

export function update(object, deltaTime) {
    totalUpdates += 1;
    debug(totalUpdates);
}

Variables locales de un objeto

Para guardar datos de un objeto concreto, crea tus propias propiedades dentro de object. Cada objeto tendra sus propios valores.

export function start(object) {
    object.vida = 100;
    object.velocidad = 180;
}

export function update(object, deltaTime) {
    object.translate(object.velocidad * deltaTime, 0);
}

Variables globales de escena

Usa Scene.vars para datos compartidos por todos los scripts de la escena actual. Se reinicia al entrar en Play y tambien cuando cargas otra escena con Scene.load.

export function start(object) {
    Scene.vars.enemigos = Scene.vars.enemigos || 0;
    Scene.vars.enemigos += 1;
}

Variables globales de proyecto

Usa Project.vars para datos que deben sobrevivir al cambiar de escena durante la misma partida, como puntuacion, vidas o progreso.

export function start(object) {
    Project.vars.score = Project.vars.score || 0;
}

export function update(object, deltaTime) {
    Project.vars.score += 1;
    debug("Score: " + Project.vars.score);
}

Datos guardados con PlayerPrefs

Usa PlayerPrefs para guardar datos que deben seguir existiendo aunque cierres el juego, como récord, opciones, volumen, monedas o el último nivel desbloqueado. Los datos se guardan separados por proyecto.

Project.vars se borra al salir de Play. PlayerPrefs se queda guardado en el navegador/Tauri hasta que borres la clave o llames a PlayerPrefs.deleteAll().

Ejemplo: guardar record

export function start(object) {
    Project.vars.score = 0;
    Project.vars.record = PlayerPrefs.getInt("record", 0);
}

export function update(object, deltaTime) {
    Project.vars.score += Math.round(10 * deltaTime);

    if (Project.vars.score > Project.vars.record) {
        Project.vars.record = Project.vars.score;
        PlayerPrefs.setInt("record", Project.vars.record);
    }

    debug({
        score: Project.vars.score,
        record: Project.vars.record
    });
}

Ejemplo: guardar opciones

export function start(object) {
    const volume = PlayerPrefs.getNumber("volume", 1);
    const fullscreen = PlayerPrefs.getBool("fullscreen", false);

    debug({ volume, fullscreen });
}

export function update(object) {
    if (Input.getKeyDown("M")) {
        PlayerPrefs.setNumber("volume", 0);
    }

    if (Input.getKeyDown("F")) {
        const current = PlayerPrefs.getBool("fullscreen", false);
        PlayerPrefs.setBool("fullscreen", !current);
    }
}

Matematicas disponibles

Los scripts pueden usar directamente el objeto estandar Math de JavaScript. El motor tambien incluye las APIs Random, Mathf y Vector2.

const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
const lerp = (a, b, t) => a + (b - a) * t;
const randomRange = (min, max) => min + Math.random() * (max - min);

API Random

export function start(object) {
    object.x = Random.range(100, 700);
    object.vida = Random.int(2, 5);
    object.color = Random.choose(["#ff0000", "#00ff00", "#0088ff"]);

    if (Random.chance(0.2)) {
        debug("Enemigo especial");
    }
}

Mathf trabaja con numeros y angulos. Vector2 devuelve objetos nuevos { x, y }; no modifica los vectores recibidos.

API Mathf

API Vector2

const direction = Vector2.normalize({
    x: enemy.x - object.x,
    y: enemy.y - object.y
});

object.translate(direction.x * 120 * deltaTime, direction.y * 120 * deltaTime);

5. Movimiento de objetos

Durante Play los objetos tienen metodos utiles para moverse y orientarse. Estos metodos devuelven el propio objeto, asi que puedes encadenarlos si te resulta comodo.

export function update(object, deltaTime) {
    object.translate(100 * deltaTime, 0);
}

export function update(object, deltaTime) {
    const enemy = FindByTag("Enemy");
    if (!enemy) return;

    object.lookAt(enemy, "x");
    object.moveTowards(enemy, 120, deltaTime);
}

lookAt y moveTowards aceptan un objeto o un punto como { x: 100, y: 50 }. En lookAt, el eje por defecto es "x". Tambien puedes usar "-x", "y" o "-y". Por ejemplo, si tu sprite mira hacia arriba, usa object.lookAt(enemy, "-y").

6. Jerarquia de objetos

Durante Play puedes consultar y cambiar relaciones padre/hijo. Al cambiar de padre, el motor intenta mantener la posicion visual del objeto en el mundo.

export function start(object) {
    const gun = FindByName("Gun");
    if (!gun) return;

    object.addChild(gun);
}

export function update(object, deltaTime) {
    for (const child of object.children()) {
        debug(child.name);
    }
}

export function start(object) {
    object.destroyAllChildren(2);
}

addChild no permite crear bucles de jerarquia. Por ejemplo, no puedes hacer hijo a un objeto de uno de sus propios descendientes.

7. Propiedades del objeto

Estas son las propiedades principales que puedes leer y modificar desde un script.

Si un objeto tiene isStatic = true, se recomienda no moverlo, rotarlo, escalarlo ni cambiar su jerarquia durante Play. Esta marca sirve para que el motor pueda optimizar render, colisiones, navegacion y otros sistemas en el futuro.

Ciclo de activacion: si active es false, no se ejecutan los componentes, las colisiones ni el script del objeto. Tambien se aplica cuando uno de sus padres esta inactivo. Si se activa despues de iniciar la escena, start(object) se ejecuta entonces una sola vez y antes del primer update(object, deltaTime). Los componentes automaticos, como Audio Source / Play On Start, arrancan al activarse.

8. API de debug

Los mensajes aparecen en la pestaña Console del panel inferior del editor.

export function start(object) {
    Debug.log({ nombre: object.name, posicion: { x: object.x, y: object.y } });
}

9. Esperas con Wait

Wait permite pausar una funcion asincrona, parecido a una corrutina. Para usarlo, la funcion debe declararse con async.

export async function start(object) {
    object.color = "#ff0000";
    await Wait.seconds(0.2);
    object.color = "#ffffff";
}

export async function start(object) {
    debug("3");
    await Wait.seconds(1);
    debug("2");
    await Wait.seconds(1);
    debug("1");
}

Animaciones de propiedades con Tween

Tween cambia suavemente propiedades numericas durante Play. Sirve para mover, rotar, escalar o desvanecer objetos sin programar la interpolacion dentro de update. La duracion y los retrasos se expresan en segundos.

export function start(object) {
    Tween.to(object, {
        x: object.x + 240,
        rotation: 360,
        scaleX: 2,
        scaleY: 2
    }, 1.5, {
        ease: "cubicInOut",
        yoyo: true,
        repeat: 1
    });
}

Opciones disponibles: ease, delay, repeat, repeatDelay, yoyo, paused, overwrite, onStart, onUpdate, onRepeat, onComplete y onCancel. Por defecto, un tween nuevo cancela tweens anteriores que modifiquen las mismas propiedades del mismo objeto. Usa overwrite: false para permitirlos.

Curvas incluidas: linear, easeIn, easeOut, easeInOut, quadIn, quadOut, quadInOut, cubicIn, cubicOut, cubicInOut, backIn, backOut, sineIn, sineOut y sineInOut.

export async function start(object) {
    const movement = Tween.to(object, { y: object.y - 100 }, 0.8, {
        ease: "backOut"
    });

    const result = await movement;
    debug(result.status); // "completed" o "cancelled"
}

El valor devuelto permite pause(), resume(), cancel() y complete(). Tambien se puede esperar directamente con await. Los tweens se cancelan automaticamente al salir de Play, destruir su objeto o cambiar de escena.

Tween solo interpola propiedades numericas. Si un componente fisico o un script modifica al mismo tiempo la misma propiedad, ambos sistemas competiran por el valor.

10. Buscar objetos

export function start(object) {
    const player = FindByName("Player");

    if (player) {
        debug("Jugador encontrado en X: " + player.x);
    }
}

export function update(object, deltaTime) {
    const target = FindByTag("Target");
    if (!target) return;

    object.x += Math.sign(target.x - object.x) * 80 * deltaTime;
}

Grupos temporales

Groups permite reunir objetos durante Play sin cambiar su nombre, tag o jerarquia. Los grupos se vacian automaticamente al cambiar de escena.

export function start(object) {
    const enemies = FindAllByTag("Enemy");
    Groups.create("wave", enemies);
}

export function update(object) {
    if (Input.getKeyDown("K")) {
        Groups.setActive("wave", false);
    }
}

11. Destruir objetos

Si destruyes un objeto que tiene hijos, tambien se destruyen sus hijos. Destroy solo debe usarse durante Play.

export function start(object) {
    Destroy(object, 3);
}

export function update(object, deltaTime) {
    const enemy = FindByTag("Enemy");

    if (enemy && enemy.x < -500) {
        Destroy(enemy);
    }
}

Instanciar prefabs desde codigo

Prefab permite crear copias de prefabs durante Play. El prefab debe existir en la pestana Prefabs del proyecto.

Si el prefab tiene un solo objeto raiz, la funcion devuelve ese objeto. Si el prefab tiene varios objetos raiz, devuelve una lista. Los scripts del prefab se cargan y empiezan a ejecutarse en Play.

export async function start(object) {
    const enemy = await Prefab.instantiate("Enemy", {
        x: object.x + 120,
        y: object.y,
        name: "EnemySpawned"
    });

    debug(enemy.name);
}

export async function start(object) {
    await Wait.seconds(1);

    const bullet = await Prefab.instantiate("Bullet", {
        x: object.x + 32,
        y: object.y,
        parent: object
    });

    bullet.translate(10, 0);
}

Prefab.instantiate solo se usa durante Play y necesita Tauri para leer el prefab guardado en el proyecto.

Pool de prefabs

Pool precarga copias inactivas y las reutiliza. Es recomendable para balas, enemigos, monedas y explosiones que aparecen muchas veces.

export async function start(object) {
    await Pool.create("bullets", "Bullet", 32);
}

export async function update(object) {
    if (Input.getKeyDown("Space")) {
        const bullet = await Pool.spawn("bullets", {
            x: object.x + 24,
            y: object.y
        });
        Physics.setVelocity(bullet, 500, 0);
    }
}

export function recycleBullet(bullet) {
    Pool.release(bullet);
}

Los pools son temporales y se limpian al cambiar de escena. Usa Pool.release en vez de Destroy para devolver una instancia reutilizable.

12. Cargar escenas

Scene.load carga una escena del proyecto por nombre. Durante Play mantiene el juego en marcha, cambia a la nueva escena y arranca los scripts de los objetos de esa escena.

export async function start(object) {
    await Wait.seconds(2);
    await Scene.load("Level1");
}

Transicion Fade

Puedes pasar opciones como segundo parametro. Con transition: "fade", la pantalla se funde a negro, el motor cambia de escena cuando ya esta cubierta y despues muestra gradualmente la nueva escena. Usa duration para indicar los segundos de cada fase del fundido.

export async function update(object) {
    if (object.x > 800) {
        await Scene.load("Level2", {
            transition: "fade",
            duration: 0.4
        });
    }
}

Usa await para esperar hasta que la carga y el fundido hayan terminado. Si omites duration, se usan 0.3 segundos. Sin opciones, el cambio es inmediato: await Scene.load("Level2").

export async function update(object, deltaTime) {
    if (object.x > 800) {
        await Scene.load("NextLevel");
    }
}

El nombre debe coincidir con una escena existente del proyecto. No escribas la extension del archivo. Scene.vars, los grupos y los pools se reinician al cambiar de escena.

13. API de animaciones

Animaciones Sprite y Property

El editor separa los dos sistemas para que no se mezclen. La pestana Animations contiene exclusivamente clips Sprite con texturas y FPS. La pestana Timeline contiene exclusivamente clips Property organizados mediante pistas y fotogramas clave.

Para crear un clip de propiedades abre Timeline y pulsa New Property. Asigna despues ese clip desde el campo Animation Timeline del Inspector del objeto. Timeline usa automaticamente ese objeto como Target Object; no se selecciona dentro del editor. El nombre y el ID indican siempre que objeto se esta editando. Elige una pista y coloca el cursor en el tiempo deseado. Pulsa Add/Update Key para capturar el valor actual del objeto. Modifica el objeto, mueve el tiempo y anade otra clave; el motor interpolara los valores entre ambas.

Para asignarlo a un objeto usa el campo Animation Timeline de la seccion Timeline Animator del Inspector. El campo Animation queda reservado exclusivamente para animaciones Sprite. Al abrir la pestana Timeline con ese objeto seleccionado, el editor carga su clip asignado y permite verlo con Play.

• Duration define la duracion total del clip en segundos.
• Target Object muestra automaticamente el objeto que tiene el clip asignado en su campo Animation Timeline.
• Local Position marcado aplica el desplazamiento del clip desde la posicion inicial de cada objeto; desmarcado usa los valores X/Y absolutos del clip.
• El panel Timeline se acopla en la parte inferior del editor para mantener visible la escena mientras transformas el objeto.
• La linea roja es el cabezal de reproduccion: indica el instante actual y avanza sobre las pistas durante la previsualizacion.
• Play reproduce desde el tiempo actual, Pause y Stop conservan la posicion, y Rewind vuelve al inicio.
• Los controles de reproduccion conservan el zoom y la zona visible del Timeline.
• Activa Follow Playhead para que la vista horizontal siga automaticamente la linea roja durante la reproduccion.
• Al mover el cursor se actualizan en vivo posicion, escala, rotacion, opacidad y color del objeto objetivo.
• Al cerrar Timeline, cambiar de pestana o entrar en Play se restaura automaticamente el estado original.
• Loop repite el clip continuamente.
• Pingpong reproduce de ida y vuelta cuando Loop esta activo.
• Pulsa un rombo para seleccionar su tiempo.
• Arrastra un rombo horizontalmente con el raton para cambiar el tiempo de ese fotograma clave y previsualizar el resultado.
• Selecciona un rombo y pulsa Duplicate Key para copiarlo 0,10 segundos mas adelante.
• Usa Zoom - y Zoom + para comprimir o ampliar horizontalmente el Timeline entre 50% y 400%.
• Pulsa con el boton derecho sobre un rombo para eliminar esa clave.

Los clips Property se asignan y reproducen desde el Inspector igual que los clips Sprite. Tambien funcionan con la misma API Animations y se incluyen en el juego exportado.

Control desde scripts

Animations permite asignar y controlar animaciones desde un script. Puedes usar el ID o el nombre de la animacion.

export function start(object) {
    Animations.assign(object, "Idle");
    Animations.play(object);
}

export async function start(object) {
    Animations.play(object, "Hit");
    await Wait.seconds(0.5);
    Animations.play(object, "Idle");
}

14. API de particulas

Particles permite asignar y controlar sistemas de particulas desde un script. Puedes usar el ID o el nombre del sistema.

export function start(object) {
    Particles.assign(object, "Smoke");
    Particles.play(object);
}

export async function start(object) {
    Particles.play(object, "Explosion");
    await Wait.seconds(1);
    Destroy(object);
}

15. Ejemplos completos

Mover un objeto

export function update(object, deltaTime) {
    object.x += 120 * deltaTime;
}

Rotar constantemente

export function update(object, deltaTime) {
    object.rotation += 180 * deltaTime;
}

Parpadear cambiando opacidad

let time = 0;

export function update(object, deltaTime) {
    time += deltaTime;
    object.opacity = 0.5 + Math.sin(time * 8) * 0.5;
}

Seguir al jugador

export function update(object, deltaTime) {
    const player = FindByName("Player");
    if (!player) return;

    const speed = 90;
    object.x += Math.sign(player.x - object.x) * speed * deltaTime;
    object.y += Math.sign(player.y - object.y) * speed * deltaTime;
}

Eliminar enemigos por tag

export function start(object) {
    const enemy = FindByTag("Enemy");

    if (enemy) {
        Destroy(enemy, 1.5);
    }
}

Cambiar de escena tras una espera

export async function start(object) {
    debug("Cargando siguiente nivel...");
    await Wait.seconds(1);
    await Scene.load("Level2");
}

Follow Camera

La camara de Play puede seguir automaticamente a un objeto por tag. En el panel izquierdo Scene > Camera, activa Follow Player y elige el tag del objeto que quieres seguir, por ejemplo Player.

Los fondos con componente Parallax usan esta camara cuando no tienen target manual. Por eso el parallax se mueve de forma natural al activar Follow Player.

API de Camera

Camera permite mover la camara de juego desde scripts durante Play. Si Follow Player esta activo, el seguimiento puede volver a moverla en el siguiente frame; usa { disableFollow: true } cuando quieras colocarla manualmente.

export function start(object) {
    Camera.moveTo(0, 0, { disableFollow: true });
}

export function update(object) {
    const player = FindByTag("Player");
    if (player && Input.getKeyDown("C")) {
        Camera.centerOn(player.x, player.y, { disableFollow: true });
    }
}

Detectar salida de camara

export function update(object) {
    object.translate(300 * deltaTime, 0);

    if (object.isOutsideCamera(64)) {
        Destroy(object);
    }
}

Fade para cambio de escena

export async function start(object) {
    await Camera.fadeOut(1, "#000000");
    await Scene.load("Level2");
    await Camera.fadeIn(1, "#000000");
}

16. UI Canvas

La UI de usuario se dibuja dentro del canvas del juego. En el editor se coloca dentro del rectangulo de camara y en Play aparece como Screen Space Overlay, encima de la escena y sin moverse con la camara del mundo.

Desde Add GameObject puedes crear: UI Canvas, UI Panel, UI Text, UI Image, UI Button, UI Input, UI Checkbox, UI Select, UI Progress Bar y UI Slider.

Canvas UI en móvil

Los controles interactivos de Canvas UI funcionan tanto con ratón como con pantalla táctil: UI Button, UI Checkbox, UI Select y UI Slider responden al dedo. Al tocar un UI Input, GameCrom abre el teclado virtual del móvil y sincroniza el texto con UI.getValue y UI.onChange.

En el Inspector, Input Type permite elegir Text, Number, Email o Password. Esta opción solicita al dispositivo el teclado más adecuado. Password oculta visualmente los caracteres, aunque el valor continúa disponible para el script como texto. Los elementos puramente visuales —paneles, textos, imágenes y barras de progreso— se muestran normalmente en móvil, pero no capturan pulsaciones.

La UI usa Rect Transform: Anchor, Pivot, offset X/Y, tamano y orden Z. Para crear ventanas, haz un UI Panel y mete textos, botones, inputs, checks, selects, sliders o barras como hijos en la jerarquia. Anchor funciona como preset: al elegir Center, Top Right, Bottom, etc. el control se coloca en esa zona, ajusta su Pivot y deja el offset X/Y a cero. Despues puedes moverlo con X/Y como margen desde ese anchor. En Play los hijos UI se dibujan encima de su padre aunque tengan menor Z. Todos los controles tienen Opacity. El campo Font permite elegir Arial o cualquier fuente importada en Fonts. Los controles con texto tienen Align y V Align para alinear el texto a izquierda, centro, derecha, arriba, medio o abajo. UI Text puede activar Multiline para trabajar como bloque de texto: acepta saltos de linea con \n, Word Wrap, Line Height, Max Lines y Overflow en modo Clip, Visible o Ellipsis. Los objetos UI tambien pueden llevar un Script igual que cualquier otro objeto: reciben start(object) y update(object, deltaTime) solo durante Play. En UI Select, las opciones se editan en el Inspector como una lista: puedes añadir, borrar y cambiar cada opción por separado. Visible Rows controla cuantas opciones se ven antes de activar scroll y Row Height permite ajustar la altura de cada fila del desplegable. UI Panel y UI Button tienen Corner Radius para redondear bordes.

API de UI

export function start(object) {
    const score = UI.find("ScoreText");
    const button = UI.find("StartButton");

    UI.setText(score, "Score: 0");

    UI.onClick(button, () => {
        Scene.load("Level1");
    });
}

// UI Text multiline.
export function start(object) {
    UI.setText("DialogText", "Linea 1\nLinea 2\nLinea 3");
}

// Script asignado directamente a un UI Button.
export function start(object) {
    UI.onClick(object, () => {
        debug("Boton pulsado");
    });
}

// Progress Bar: mostrar vida del jugador.
let vida = 100;

export function start(object) {
    const healthBar = UI.find("HealthBar");
    const healthText = UI.find("HealthText");

    UI.setRange(healthBar, 0, 100, vida);
    UI.setText(healthText, `Vida: ${vida}`);
}

export function update(object, deltaTime) {
    const healthBar = UI.find("HealthBar");
    const healthText = UI.find("HealthText");

    // Ejemplo: la vida baja poco a poco.
    vida = Math.max(vida - 5 * deltaTime, 0);

    UI.setValue(healthBar, vida);
    UI.setText(healthText, `Vida: ${Math.round(vida)}`);
}

// Slider: mostrar el valor en un UI Text.
export function start(object) {
    const slider = UI.find("VolumeSlider");
    const valueText = UI.find("VolumeValueText");

    UI.setRange(slider, 0, 100, 50);
    UI.setText(valueText, "Volumen: 50");

    UI.onChange(slider, () => {
        const value = Math.round(UI.getValue(slider));
        UI.setText(valueText, `Volumen: ${value}`);
    });
}

17. Componentes

Los componentes anaden comportamiento o datos extra a un objeto. Selecciona un objeto, pulsa Add Component en el Inspector y busca el componente que quieres anadir.

Audio Source

Audio Source reproduce sonidos del proyecto desde un objeto. Sus parametros son: sonido, volumen, pitch, loop, play on start y enabled.

Los sonidos del proyecto se cargan en memoria al abrir/refrescar el proyecto. Audio Source no carga sonidos en caliente durante Play; si un sonido no esta precargado, se mostrara un error.

API de AudioSource

export async function start(object) {
    AudioSource.setVolume(object, 0.7);
    AudioSource.setPitch(object, 1.2);
    await AudioSource.play(object);
}

export function update(object) {
    if (Input.getKeyDown("Space")) {
        AudioSource.play(object);
    }
}

Audio Effect

Audio Effect procesa el sonido del Audio Source que esta en el mismo objeto. Se pueden anadir varios Audio Effect: el motor los conecta en el mismo orden en que aparecen en la lista de componentes.

El objeto necesita un Audio Source. Por ejemplo, puedes encadenar Filter → Delay → Reverb. En equipos de poca potencia conviene limitar el numero de reverbs y delays que suenan simultaneamente.

API de Audio Effect

Ejemplo: delay y reverb

export function start(object) {
    // Primer Audio Effect: Delay.
    AudioEffect.setDelay(object, 0, {
        time: 0.25,
        feedback: 0.35,
        mix: 0.25
    });

    // Segundo Audio Effect: Reverb.
    AudioEffect.setReverb(object, 1, {
        duration: 1.8,
        decay: 2.2,
        mix: 0.4
    });

    AudioSource.play(object);
}

export function update(object) {
    if (Input.getKeyDown("R")) {
        AudioEffect.setEnabled(object, 1, false);
    }
}

Empuje directo en objetos

Para aplicar fuerza no necesitas anadir Physics Body manualmente. Puedes llamar a estas funciones directamente desde el objeto y el motor creara el componente fisico automaticamente si hace falta.

Anade Physics Body en el editor solo cuando quieras configurar masa, drag, rebote, friccion, gravedad o bloqueo de ejes visualmente.

Ejemplo: nave tipo Asteroids

Para una nave tipo Asteroids, desactiva la gravedad y aplica empuje en la direccion hacia la que mira la nave. Si quieres que no acelere infinitamente, anade Physics Body en el editor y sube un poco Drag.

export function start(object) {
    object.setGravity(false);
}

export function update(object, deltaTime) {
    if (Input.getKey("ArrowLeft")) {
        object.rotation -= 180 * deltaTime;
    }

    if (Input.getKey("ArrowRight")) {
        object.rotation += 180 * deltaTime;
    }

    if (Input.getKey("ArrowUp")) {
        // Usa "x" si el sprite mira a la derecha por defecto.
        // Usa "-y" si el sprite mira hacia arriba por defecto.
        object.addForwardForce(520 * deltaTime, "x");
    }
}

Bouncy Ball

Bouncy Ball convierte un objeto en una bola tipo Pong o Arkanoid. No necesita Physics Body: usa su propia velocidad interna y rebota contra los colliders de la escena.

Al anadir este componente, el motor activa Collision, desactiva Trigger y marca el objeto como no Static. Usa colliders en paredes, palas, bloques y limites para que la bola pueda rebotar.

API de Bouncy Ball

Ejemplo: bola de Pong o Arkanoid

Crea una bola, anade el componente Bouncy Ball y activa Start On Play. Despues coloca colliders en las paredes, la pala y los bloques. Para Pong suele funcionar bien salir en diagonal. Para Arkanoid puedes relanzarla desde abajo cuando pierdes una vida.

// Script de la bola
export function start(object) {
    // Sale hacia arriba y a la derecha.
    object.launchBouncy(-45, 360);
}

export function update(object) {
    // Relanzar la bola durante pruebas.
    if (Input.getKeyDown("R")) {
        object.launchBouncy(-45, 360);
    }

    // Subir velocidad poco a poco.
    if (Input.getKeyDown("Space")) {
        const speed = BouncyBall.getSpeed(object);
        BouncyBall.setSpeed(object, speed + 40);
    }
}

Ejemplo: pala de Arkanoid

La pala solo necesita moverse y tener Collision activo. La bola rebotara contra ella porque el componente Bouncy Ball gestiona su propia direccion despues del choque.

// Script de la pala
export function update(object, deltaTime) {
    const speed = 420;

    if (Input.getKey("A") || Input.getKey("ArrowLeft")) {
        object.translate(-speed * deltaTime, 0);
    }

    if (Input.getKey("D") || Input.getKey("ArrowRight")) {
        object.translate(speed * deltaTime, 0);
    }
}

Waypoint Mover

Waypoint Mover mueve un objeto siguiendo una lista de puntos de mundo. Sirve para patrullas, plataformas, enemigos voladores, camaras, decoracion en movimiento o cualquier objeto que deba recorrer una ruta durante Play.

En el editor, al seleccionar el objeto, veras los puntos WP y las flechas de ruta. El componente solo mueve el objeto durante Play.

Para recolocar una patrulla completa, activa Move Points With Object antes de mover el objeto. Desactivalo si quieres cambiar la posicion inicial del objeto sin desplazar la ruta.

API de Waypoint Mover

Ejemplo: patrulla con ping pong

export function start(object) {
    WaypointMover.setWaypoints(object, [
        { x: 100, y: 200, pauseMin: 0.2, pauseMax: 0.5 },
        { x: 360, y: 200, pauseMin: 0.2, pauseMax: 0.5 },
        { x: 360, y: 320, pauseMin: 0.8, pauseMax: 1.2 }
    ]);

    WaypointMover.setLoop(object, true, true);
    WaypointMover.setSpeed(object, 120);
}

Ejemplo: enemigo que elige puntos al azar

export function start(object) {
    WaypointMover.setRandom(object, true);
    WaypointMover.setPause(object, 0.3, 1.4);
    WaypointMover.setRotateToWaypoint(object, true, 0);
}

Ejemplo: cambiar movimiento durante Play

export function update(object) {
    if (Input.getKeyDown("1")) {
        object.goToWaypoint(0);
    }

    if (Input.getKeyDown("2")) {
        object.goToWaypoint(1);
    }

    if (Input.getKeyDown("Space")) {
        object.pauseWaypointMover(1);
    }

    if (Input.getKeyDown("R")) {
        object.resumeWaypointMover();
        object.setWaypointSpeed(220);
    }
}

Pathfinding Agent

Pathfinding Agent convierte un objeto en un agente capaz de buscar y seguir automaticamente una ruta alrededor de los objetos con colision. Es util para enemigos que persiguen al player, NPC, unidades de estrategia o personajes que deben llegar a un punto sin atravesar muros.

Anade el componente desde Add Component > Pathfinding Agent. Los colliders activos forman los obstaculos; los objetos marcados como trigger no bloquean la ruta. Activa Debug Path para ver la ruta en color magenta durante Play en el editor.

API de Pathfinding Agent

Ejemplo: perseguir al player

export function start(object) {
    const player = FindByTag("Player");
    PathfindingAgent.setTarget(object, player);
    PathfindingAgent.setSpeed(object, 100);
}

Ejemplo: enviar un objeto a una posicion

export function update(object) {
    if (Input.getKeyDown("Space")) {
        PathfindingAgent.setDestination(object, 640, 320);
    }

    if (PathfindingAgent.hasArrived(object)) {
        // El objeto ya ha llegado.
    }
}

Waypoint Mover sigue una ruta dibujada manualmente. Pathfinding Agent calcula la ruta y la modifica para rodear obstaculos.

Look At Target

Look At Target mantiene un objeto orientado hacia otro. Esta pensado para torretas, canones, focos, ojos, enemigos y cualquier objeto que deba seguir visualmente a un objetivo sin cambiar su posicion.

Ejemplo: si el canon de la imagen apunta hacia arriba, selecciona Up (-90°). El componente aplicara automaticamente la correccion necesaria para que esa punta mire al target.

API de Look At Target

Ejemplo: torreta que sigue al player

export function start(object) {
    LookAtTarget.setTarget(object, "Player", "tag");
    LookAtTarget.setTurnSpeed(object, 120);
    LookAtTarget.setReactionDelay(object, 0.1);

    // La imagen original del canon apunta hacia arriba.
    LookAtTarget.setOriginalAngle(object, -90);
}

Physics Body

Physics Body anade gravedad, velocidad y respuesta fisica sencilla a un objeto. Usalo para cajas, enemigos, proyectiles, objetos que caen o elementos que quieras mover con fuerzas. Para personajes jugables de plataformas sigue siendo mejor usar Character Controller.

El componente solo se actualiza durante Play. Al anadirlo, el objeto activa automaticamente Collision y deja de ser Static, porque necesita poder moverse. Los objetos con Body Type: Dynamic pueden ser empujados lateralmente por el player, por otro Character Controller o por otro Physics Body. Cuanta mas Mass tenga el objeto, mas costara moverlo.

API de Physics

export function start(object) {
    Physics.setVelocity(object, 120, -300);
}

export function update(object) {
    if (Input.getKeyDown("Space") && Physics.isGrounded(object)) {
        Physics.addForce(object, 0, -650);
    }

    if (object.isOutsideCamera(100)) {
        Destroy(object);
    }
}

Parallax

Parallax desplaza la textura del objeto usando la camara de Play o un objeto target. Para fondos, nubes y capas de escenario, el parallax usa la camara de Play cuando no hay target asignado. Solo se movera si la camara de Play tiene Follow Player activo.

En el editor el efecto permanece estatico. El movimiento de Parallax solo se ejecuta durante Play. El objeto mantiene su posicion original y su tamano en pantalla; el componente compensa la camara y solo desplaza la textura. El target manual queda para casos especiales donde quieras que la capa responda a un objeto concreto en vez de a la camara.

API de Parallax

export function start(object) {
    const player = FindByName("Player");

    Parallax.setTarget(object, player);
    Parallax.setSpeed(object, 1, 0);
    Parallax.setSmooth(object, 0.85, 0);
    Parallax.setMargin(object, 120, 0);
    Parallax.setRepeat(object, true, false);
    Parallax.setLock(object, false, true);
}

Character Controller

Character Controller mueve un personaje 2D sin tener que escribir todo el codigo de movimiento a mano. Sirve para juegos de plataformas y movimiento libre tipo top-down.

El componente solo se ejecuta durante Play. En el editor no mueve el objeto. En el Inspector se muestra una tarjeta resumida; pulsa Edit para abrir la ventana completa de configuracion en el centro de la pantalla. La ventana cambia segun el modo elegido y oculta las opciones que no se usan en ese tipo de controlador.

Parametros comunes

Tipo Platformer

Usa Platformer para juegos laterales con gravedad: plataformas, saltos, suelo, rampas, escaleras y plataformas moviles. El controlador aplica movimiento horizontal, gravedad, salto y deteccion de suelo durante Play.

Para que las escaleras funcionen, el objeto escalera debe tener el componente Ladder. El personaje puede saltar desde la escalera para salir de ella.

Tipo Top Down

Usa Top Down para juegos vistos desde arriba o con movimiento libre en X/Y: aventuras, shooters, RPG de accion o juegos donde el personaje no tiene gravedad ni salto. El controlador normaliza la diagonal para que moverse en diagonal no sea mas rapido.

Animaciones y sonidos por estado

Los sonidos del Character Controller usan los sonidos del panel Sounds. Se cargan al iniciar el proyecto y se mantienen en memoria; el componente solo elige cual reproducir al cambiar de estado. Si Mute in Play esta activo, estos sonidos tambien se silencian.

API de CharacterController

export function update(object) {
    if (Input.getKeyDown("K")) {
        CharacterController.setDead(object, true);
    }

    if (CharacterController.isGrounded(object)) {
        debug("En suelo");
    }
}

18. Input

Input permite leer teclado, ratón, gamepad y touch desde scripts. La API funciona en Play. En modo editor no controla la escena ni devuelve pulsaciones para no interferir con las herramientas del editor.

Fuera de Play, Input devuelve valores neutros: false en botones/teclas, 0 en ejes y posiciones, y null en getTouch.

Teclado

Puedes usar letras como "A", teclas especiales como "Escape", "Enter", "Shift", "Control", "Alt", "Space", flechas como "ArrowLeft" y tambien codigos de KeyboardEvent.code como "KeyA".

Teclas habituales soportadas: "A", "B", "Escape", "Enter", "Shift", "Control", "Alt", "ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown" y "Space".

export function update(object, deltaTime) {
    if (Input.getKey("D")) {
        object.translate(160 * deltaTime, 0);
    }

    if (Input.getKeyDown("Space")) {
        debug("Salto");
    }
}

Raton

Botones: 0 izquierdo, 1 central, 2 derecho.

export function update(object, deltaTime) {
    if (Input.getMouseButtonDown(0)) {
        object.x = Input.mouseWorldX;
        object.y = Input.mouseWorldY;
    }
}

export function start(object) {
    Input.hideCursor();
}

export function update(object, deltaTime) {
    if (Input.getKeyDown("Escape")) {
        Input.showCursor();
    }
}

Gamepad

Input usa la Gamepad API del navegador y normaliza mandos Xbox, PlayStation, Nintendo, USB, Bluetooth y genericos. Puede haber varios mandos conectados.

Botones soportados: A, B, X, Y, Cross, Circle, Square, Triangle, L1, R1, L2, R2, Start, Select, Back, Options, Share, LeftStick, RightStick, DPadUp, DPadDown, DPadLeft y DPadRight.

Ejes soportados: LeftStickX, LeftStickY, RightStickX, RightStickY, LeftTrigger y RightTrigger.

Si hay varios mandos, puedes indicar el indice como segundo parametro: Input.getButton("A", 0). Si no indicas indice, se acepta el primer mando que tenga ese boton pulsado.

La vibracion depende del mando, navegador y sistema operativo. La intensidad fuerte y suave usa valores entre 0 y 1. Si el dispositivo no dispone de actuador, la funcion devuelve false sin detener el juego.

Activar y detener la vibracion

export async function update(object) {
    if (Input.getButtonDown("A")) {
        const supported = await Input.vibrate(
            300, // duracion en milisegundos
            1,   // motor fuerte: 0 a 1
            0.4, // motor suave: 0 a 1
            0    // indice del mando
        );

        if (!supported) {
            debug("Este mando no soporta vibracion");
        }
    }

    if (Input.getButtonDown("B")) {
        Input.stopVibration(0);
    }
}

export function onPlayerHit() {
    // Golpe corto.
    Input.vibrate(120, 0.8, 0.3);
}

export function onExplosionStart() {
    // Empieza una vibracion larga.
    Input.vibrate(2000, 1, 1);
}

export function onExplosionEnd() {
    // La detiene antes de que terminen los 2000 ms.
    Input.stopVibration();
}

Ejes de movimiento

Horizontal y Vertical combinan teclado y gamepad. Por defecto: A/D, flechas izquierda/derecha, W/S y flechas arriba/abajo.

Movimiento vertical para Pong

export function update(object, deltaTime) {
    const vertical = Input.getAxis("Vertical");
    object.translate(0, -vertical * speed * deltaTime);
}

Este ejemplo controla un solo eje con W/S, las flechas arriba/abajo y el stick izquierdo. La intensidad del stick se conserva, por lo que una inclinacion pequeña produce un movimiento mas lento.

export function update(object, deltaTime) {
    const move = Input.getMovementVector();

    object.translate(
        move.x * 180 * deltaTime,
        -move.y * 180 * deltaTime
    );
}

Input.getMovementVector() combina Horizontal y Vertical y normaliza la diagonal. Asi no se mueve mas rapido al pulsar dos direcciones. En este motor Vertical devuelve positivo hacia arriba; por eso el ejemplo usa -move.y.

El teclado y el mando funcionan con la misma API tanto en Play como en los builds Web y Windows. Si pruebas una correccion del sistema de entrada, genera un build nuevo: los builds anteriores conservan el runtime con el que fueron creados.

Touch

18.1. Controles moviles

GameCrom incluye controles tactiles visuales para que los juegos Web puedan jugarse desde moviles y tabletas. Los controles forman parte de Canvas UI, admiten varias pulsaciones a la vez y alimentan la misma API Input que el teclado y el mando. No necesitas crear una version diferente del movimiento para movil.

Crear controles tactiles

1. Crea o selecciona un UI Canvas.
2. Abre Add GameObject > Mobile Controls.
3. Anade Touch Joystick, Touch D-Pad o Touch Button.
4. Coloca el joystick o la cruceta en la parte inferior izquierda y los botones en la derecha.
5. Configura sus ejes o su accion desde el Inspector.
6. Opcionalmente, asigna una imagen de Textures a cada control.
7. Pruebalo en Play con el raton o genera un build nuevo para probar multitouch en el dispositivo.

Propiedades del Inspector

Leer movimiento y acciones

En modo Floating in Area no hace falta acertar sobre un control pequeno: el primer toque dentro de la zona crea el centro del joystick en ese punto. El dedo puede desplazarse desde ese centro y, al soltarlo, el joystick vuelve a ocultarse. Los botones tactiles colocados sobre la zona tienen prioridad, por lo que siguen funcionando aunque las areas se solapen.

Al seleccionar un Touch Joystick flotante en el editor, su zona de activacion aparece marcada con lineas discontinuas y un relleno azul tenue. La guia solo pertenece al editor y no se dibuja en el juego.

export function update(object, deltaTime) {
    // Teclado, mando, joystick tactil y cruceta usan los mismos ejes.
    const x = Input.getAxis("Horizontal");
    const y = Input.getAxis("Vertical");

    object.translate(x * 220 * deltaTime, -y * 220 * deltaTime);

    // Verdadero mientras el boton tactil permanezca pulsado.
    if (Input.isActionPressed("Attack")) {
        // Ataque continuo.
    }

    // Solo durante el frame inicial de la pulsacion.
    if (Input.isActionDown("Jump")) {
        // Saltar una vez.
    }

    // Solo durante el frame en que se suelta.
    if (Input.isActionUp("Pause")) {
        // Abrir o cerrar el menu de pausa.
    }
}

Character Controller

El Character Controller usa automaticamente los ejes Horizontal y Vertical. Tambien reconoce las acciones tactiles Jump, Run y Crouch. Para un personaje basico basta con crear un joystick y un boton cuya accion sea Jump; no hace falta modificar el componente ni escribir movimiento adicional.

Multitouch y builds

Cada dedo mantiene su propio control: el jugador puede mover el joystick y pulsar varios botones al mismo tiempo. Funciona en los builds Web y Windows cuando el dispositivo dispone de entrada tactil. Despues de modificar controles o actualizar el motor, genera un build nuevo porque un build anterior conserva el runtime con el que fue creado.

Los controles visuales y Input.getTouch(index) resuelven casos distintos. Usa los controles visuales para movimiento y acciones habituales. Usa getTouch cuando necesites posiciones de dedos, dibujar con el dedo, seleccionar objetos del mundo o implementar un gesto personalizado.

19. Colisiones 2D

El motor incluye colisiones 2D basadas en SAT. Para que un objeto participe en colisiones, activa Collision en el bloque Collider 2D del Inspector. Si activas Trigger, el objeto detecta contactos pero no empuja ni bloquea a otros objetos.

Las colisiones funcionan con rotacion, escala y jerarquias. El collider se ve en azul en la escena cuando el objeto esta seleccionado y Collision esta activo. Solo se actualizan en Play.

Componentes de escenario

Conveyor Belt

Conveyor Belt crea el efecto clasico de cinta transportadora. Mientras un objeto compatible esta apoyado encima, la cinta lo desplaza horizontalmente a la velocidad configurada. Funciona tanto en el Play del editor como en el juego exportado.

Para usarlo, selecciona el suelo o plataforma, pulsa Add Component > Conveyor Belt y ajusta sus propiedades. Al anadirlo, el editor activa automaticamente Collision y desactiva Trigger en la cinta.

El objeto transportado debe estar apoyado sobre la parte superior de la cinta y tener Character Controller o Physics Body, segun los filtros activados. La cinta no desplaza objetos decorativos sin uno de esos componentes.

API de Conveyor Belt

Texture Scroller

Texture Scroller modifica continuamente Texture Offset X y Texture Offset Y durante Play. Sirve para cintas animadas, agua, lava, nubes, fondos en movimiento o cualquier textura repetida. La textura debe tener un tiling adecuado para que el desplazamiento sea visible de forma continua.

API de Texture Scroller

export function start(object) {
    TextureScroller.setSpeed(object, 0.4, 0);
}

export function update(object) {
    if (Input.getKeyDown("Space")) {
        const component = TextureScroller.get(object);
        TextureScroller.setEnabled(object, !component.enabled);
    }
}

Callbacks en scripts

Si tu objeto tiene un script asignado, puedes exportar estas funciones. El motor las llama cuando el collider del objeto entra, permanece o sale de contacto con otro.

export function onCollisionEnter(object, collision) {
    debug(object.name + " choca con " + collision.other.name);
}

export function onTriggerEnter(object, collision) {
    if (collision.other.tag === "Coin") {
        Destroy(collision.other);
    }
}

Datos de collision

API Collision

export function update(object, deltaTime) {
    const enemy = FindByName("Enemy");
    const hit = Collision.check(object, enemy);

    if (hit) {
        debug("Tocando enemigo");
    }
}

Events y Time

Events

Events comunica scripts sin buscar ni referenciar directamente otros objetos. Los eventos se limpian al cambiar de escena.

export function start(object) {
    Events.on("player-hit", data => {
        UI.setText("HealthText", `Vida: ${data.health}`);
    });
}

export function hitPlayer(health) {
    Events.emit("player-hit", { health });
}

Time

export function update(object) {
    if (Input.getKeyDown("P")) {
        if (Time.isPaused()) Time.resume();
        else Time.pause();
    }

    if (Input.getKeyDown("T")) {
        Time.timeScale = 0.35;
    }
}

Time.pause() solo detiene el tiempo escalado. Para detener de forma coordinada todo el juego utiliza la API global Game explicada a continuación.

Pausa global del juego

Game.pause() aplica una pausa completa y segura tanto en Editor Play como en las builds. Detiene scripts normales, física, colisiones, animaciones, partículas, tweens, pathfinding, cámara y audio. El juego continúa dibujándose y Input sigue disponible para controlar el menú.

Cómo pausar y reanudar

export function update(object, deltaTime) {
    // update deja de ejecutarse después de pausar.
    if (Input.getKeyDown("Escape") || Input.getButtonDown("Start")) {
        Game.pause();
        UI.show("PauseMenu");
    }
}

export function pausedUpdate(object, unscaledDeltaTime) {
    // Solo se ejecuta durante la pausa global.
    if (Input.getKeyDown("Escape") || Input.getButtonDown("Start")) {
        UI.hide("PauseMenu");
        Game.resume();
    }
}

Para reanudar desde un script usa pausedUpdate(object, unscaledDeltaTime), porque update, fixedUpdate y lateUpdate permanecen detenidos. No uses Game.togglePause() solamente dentro de update: después de pausar ese callback ya no se ejecutará. unscaledDeltaTime permite animar manualmente una interfaz de pausa.

APIs de componentes adicionales

const platform = FindByName("Lift");
MovingPlatform.setSpeed(platform, 120);
MovingPlatform.setMovement(platform, 0, -300);

const alarm = FindByName("AlarmLight");
Light.setColor(alarm, "#ff2020");
Light.setEffect(alarm, "alarm", { speed: 3, amount: 0.8 });

Guardar partidas con Save

Save guarda objetos completos por slot y proyecto. Para opciones pequeñas sigue siendo adecuado PlayerPrefs; para partidas usa Save.

Save.write("slot1", {
    scene: Scene.current,
    score: Project.vars.score,
    lives: 3,
    player: { x: object.x, y: object.y }
}, {
    title: "Partida principal"
});

const game = Save.read("slot1", null);
if (game) {
    Project.vars.score = game.score;
    object.x = game.player.x;
    object.y = game.player.y;
}

Los datos deben poder convertirse a JSON. No guardes funciones, elementos HTML, Audio ni referencias circulares.

Archivos TXT y JSON

GameCrom utiliza la misma API Files para trabajar con TXT y JSON, pero separa los archivos en dos zonas con finalidades y permisos diferentes. Elegir la zona correcta evita confundir el contenido original del proyecto con los datos que genera cada jugador.

Caso 1: datos internos del proyecto — assets/data/

Abre la pestaña Data del panel de Recursos. Desde ella puedes importar archivos .txt y .json, o crear uno nuevo con New TXT y New JSON. Los archivos se guardan en assets/data/ y el botón Open in VS Code los abre directamente en Visual Studio Code. También puedes usar subcarpetas escribiéndolas en el nombre, por ejemplo dialogues/es.json.

assets/data/ es siempre de solo lectura durante el juego. Sus archivos forman parte del proyecto y se incluyen en la compilación, pero un script no puede modificarlos ni eliminarlos. Para cambiar su contenido debes volver al proyecto, editarlo con VS Code y generar una nueva build.

// Leer contenido preparado por el desarrollador
const traducciones = await Files.readJSON("assets/data/translations/es.json", {});
const dialogos = await Files.readText("assets/data/dialogos.txt", "");

// Esto está prohibido porque assets/data es de solo lectura:
// await Files.writeJSON("assets/data/config.json", nuevaConfig);

Caso 2: archivos modificables del jugador — user/

Usa user/ cuando el juego necesite crear, leer, modificar o eliminar TXT y JSON durante la ejecución. Estos archivos no forman parte del proyecto original y son independientes para cada juego, navegador o instalación.

// Crear o sobrescribir un archivo del jugador
await Files.writeJSON("user/perfil.json", {
    name: "Player",
    level: 3
}, { pretty: true });

// Leerlo, modificarlo y volverlo a guardar
const perfil = await Files.readJSON("user/perfil.json", { level: 1 });
perfil.level += 1;
await Files.writeJSON("user/perfil.json", perfil);

await Files.writeText("user/notas.txt", "Nivel completado");
const archivos = await Files.list("user/");
await Files.delete("user/notas.txt");

Dónde se guarda user/

• Editor Play: en el almacenamiento local del editor.
• Build Web: en el navegador y asociado al dominio desde el que se ejecuta el juego. No crea archivos visibles junto a la web.
• Build Windows: en los datos locales de la aplicación, separado por juego. No se guarda junto al EXE ni dentro de assets/data/.

Para controlar errores, usa try/catch y consulta error.code: NOT_FOUND, INVALID_JSON, ACCESS_DENIED o QUOTA_EXCEEDED.

Solo se admiten archivos .txt y .json, con un máximo de 5 MB por archivo. Las rutas absolutas y ../ están bloqueadas. Usa PlayerPrefs para preferencias sencillas, Save para partidas organizadas en slots y Files para archivos auxiliares personalizados.

Guardado local

Qué sistema debes utilizar

GameCrom 2D Studio no utiliza cuentas ni guardado en la nube. Los datos no se sincronizan entre navegadores, equipos o dispositivos.

Dónde se guardan los datos

• Editor Play: en el almacenamiento local del editor.
• Build Web: en el almacenamiento local del navegador y del dominio desde el que se ejecuta el juego.
• Build Windows: en el almacenamiento local de la aplicación.

En Web, cada navegador y cada dominio mantienen una copia independiente. Borrar los datos del sitio, usar navegación privada o abrir el juego desde otro dominio puede hacer que la partida no esté disponible. En Windows, eliminar los datos locales de la aplicación también elimina sus preferencias y partidas.

Uso recomendado

// Preferencias del dispositivo
PlayerPrefs.setNumber("volume", 0.8);
PlayerPrefs.setString("language", "es");

// Progreso de la partida
Save.write("autosave", {
    level: 4,
    score: 12500,
    player: { x: object.x, y: object.y }
});

const data = Save.read("autosave", null);

Guarda en puntos de control y después de cambios importantes. No esperes únicamente al cierre de la pestaña o de la aplicación, porque un cierre forzado puede impedir la última escritura.

Pathfinding

Pathfinding.findPath usa A* sobre una cuadricula temporal. Los objetos con collider activo bloquean celdas; los triggers no bloquean. No requiere Tilemap.

Opciones principales: cellSize, diagonal, padding, marginCells, maxNodes e ignore. Un cellSize pequeño encuentra rutas mas precisas pero cuesta mas CPU.

export function start(object) {
    const player = FindByTag("Player");
    const path = Pathfinding.findPath(object, player, {
        cellSize: 32,
        diagonal: true,
        padding: 6,
        ignore: [object, player]
    });

    Pathfinding.follow(object, path, 110, {
        arriveDistance: 3,
        onComplete(enemy) {
            debug(enemy.name + " ha llegado");
        }
    });
}

export function update(object) {
    if (Input.getKeyDown("Escape")) {
        Pathfinding.stop(object);
    }
}

Pixel Canvas

El objeto Pixel Canvas es una imagen dinamica y escalable cuyo contenido procede de un framebuffer controlado por scripts. Sirve para emuladores, programas de dibujo, minimapas, pantallas, efectos procedurales y juegos basados directamente en pixeles.

Crea Add GameObject > Pixel Canvas y configura su resolucion interna. El tamano y la escala del objeto controlan el tamano visible; su resolucion controla cuantos pixeles contiene el framebuffer.

let screen;

export function start(object) {
    screen = PixelCanvas.create(object, 256, 192, {
        indexed: true
    });
    screen.setPalette([
        "#000000", "#0000d7", "#d70000", "#d700d7",
        "#00d700", "#00d7d7", "#d7d700", "#d7d7d7"
    ]);
    screen.clear(0).present();
}

export function update(object) {
    const pixels = screen.getIndexBuffer();
    pixels[40 * screen.width + 80] = 6;
    screen.markDirty();
    screen.present();
}

Para maximo rendimiento modifica directamente el buffer y llama a markDirty() antes de present(). Con Auto Present activo, el renderer publica automaticamente cualquier superficie marcada como modificada.

Engine, tipos y contrato de API

export function start(object) {
    debug({
        engine: Engine.version,
        api: Engine.apiVersion,
        editor: Engine.isEditor,
        platform: Engine.platform
    });
}

El archivo DOCUMENTOS/gamecrom-2d-studio-api.d.ts ofrece autocompletado y tipos para las APIs nuevas. La prueba node TESTS/runtimeApiContract.mjs valida matematicas, eventos, tiempo, Random, Save, Pathfinding y PixelCanvas.

API Application: salir del juego

Usa Application.quit() para abandonar el juego desde cualquier script. La misma llamada funciona durante Play en el editor, en una version web publicada en GameCrom y en un ejecutable de Windows. Application.exit() es un alias equivalente.

Salir directamente

export async function salirDelJuego() {
    await Application.quit();
}

Puedes llamar a esta funcion desde la logica de un boton de menu, una pantalla de Game Over o cualquier otro script. La promesa devuelve true si la solicitud se ha enviado y false si otro codigo ha cancelado la salida.

Salir al pulsar Escape

export function start(object) {
    // No hace falta preparar nada al iniciar.
}

export async function update(object, deltaTime) {
    if (Input.getKeyDown("Escape")) {
        await Application.quit("escape-key");
    }
}

Guardar antes de salir

export async function salirGuardando(object) {
    PlayerPrefs.setInt("record", Project.vars.record || 0);
    PlayerPrefs.setJSON("configuracion", Project.vars.configuracion || {});
    PlayerPrefs.save();

    await Application.quit("main-menu");
}

Guarda primero y solicita la salida despues. No pongas operaciones largas despues de Application.quit(), porque el juego puede cerrarse inmediatamente.

Cancelar temporalmente la salida

let hayCambiosSinGuardar = true;

export async function intentarSalir() {
    if (hayCambiosSinGuardar) {
        window.addEventListener("gamecrom:before-quit", event => {
            event.preventDefault();
            debug("Guarda la partida antes de salir");
        }, { once: true });
    }

    const saliendo = await Application.quit("main-menu");
    debug({ saliendo }); // false si se ha cancelado
}

export async function guardarYSalir() {
    PlayerPrefs.setInt("nivel", Project.vars.nivel || 1);
    hayCambiosSinGuardar = false;
    await Application.quit("saved-game");
}

Antes de cerrar se emite el evento cancelable gamecrom:before-quit. Su propiedad event.detail.reason contiene el motivo enviado a quit. El listener debe decidir de forma sincrona si cancela la salida mediante event.preventDefault().

Metodos disponibles

20. Compilar y exportar el juego

Desde Project Settings puedes generar localmente diferentes versiones del juego. Antes de compilar, el editor guarda la escena actual y la configuracion del proyecto.

El campo Builds, situado encima de los botones de compilacion, permite elegir la carpeta de salida. Por defecto se usa C:\GAMECROM_BUILDS. Cuando termina correctamente una compilacion, Open Folder abre directamente la carpeta generada; el boton permanece oculto mientras no exista una ruta de salida valida.

Build Web

La version protegida no deja visibles las carpetas scripts, scenes, assets, prefabs ni ENGINE. El juego se empaqueta en pocos archivos y se reconstruye en memoria al arrancar.

El motor se agrupa en un único módulo y, junto con el código de arranque y los scripts del proyecto, se minifica. Los scripts del juego reciben además un renombrado moderado de identificadores, sin transformaciones agresivas de flujo, código basura ni decodificadores que se ejecuten en cada frame. El núcleo compartido de física y colisiones recibe únicamente minificación segura y renombrado de identificadores locales; no utiliza ofuscación de flujo ni operaciones adicionales en ejecución, para preservar su rendimiento. Los archivos originales del editor y del proyecto nunca se modifican; el proceso trabaja únicamente sobre las copias de la carpeta compilada.

C:\GAMECROM_BUILDS\PONG\web\
  index.html
  p.js
  s.css
  m.json
  d.json
  r/
    e.js

En web no existe proteccion absoluta: el navegador siempre necesita descargar los datos del juego. Esta salida dificulta el análisis y la copia, pero no debe usarse para guardar secretos, claves privadas o logica sensible.

21. Consejos de uso

• Usa deltaTime para que el movimiento no dependa de los FPS.
• Comprueba siempre si FindByName o FindByTag devuelven null.
• Usa tags para categorias como Enemy, Player, Pickup o Target.
• Si un script se asigna a varios objetos, cada objeto recibira su propia llamada a start y update.
• Los cambios hechos durante Play son temporales y se restauran al salir de Play.