Referencia de sintaxis de NovelML

Este documento explica la sintaxis básica de NovelML y cómo se ejecuta.

Para obtener una explicación detallada de cada etiqueta, consulte "Referencia de etiquetas Suika3".

1. NovelML es una lista de comandos del motor llamados "etiquetas"

NovelML es una lista de etiquetas. Una etiqueta es un comando para el motor.

Cada etiqueta le dice al motor que haga algo.
Las etiquetas se ejecutan una por una, en el orden en que aparecen
Después de que se ejecuta una etiqueta, se "termina" y la "posición de ejecución" continúa

Si vuelves a escribir la misma etiqueta, hará lo mismo cada vez que se ejecute.

2. La ejecución va de arriba a abajo

NovelML se ejecuta desde la parte superior del archivo hasta el final, una etiqueta a la vez.

La ejecución normalmente avanza.
Sólo hay un puesto de ejecución actual

[text text="Hello"]
[text text="World"]

En este caso:

Se muestra Hello
Luego se muestra World

3. Todo debe escribirse como etiquetas.

En NovelML, cada línea debe ser una etiqueta.

Todo el escenario está escrito usando etiquetas.
Incluso el texto debe usar la etiqueta [text]

[text text="It's a beautiful day."]

4. Etiquetas que esperan y etiquetas que no esperan

Hay dos tipos principales de etiquetas:

Etiquetas que se ejecutan y pasan inmediatamente a la siguiente etiqueta
Etiquetas que esperan la entrada del usuario o que algo termine

Las etiquetas comunes de "espera" incluyen:

text (espera un clic)
click (espera un clic)
wait (espera un tiempo específico)
video (espera hasta que finalice la reproducción)

Estas etiquetas pausan la ejecución sin ninguna sintaxis especial.

4.1 Etiquetas que se ejecutan en segundo plano (asincrónicamente)

Algunas etiquetas pueden ejecutarse en segundo plano (de forma asincrónica).

Ejemplos típicos:

anime
move

Estas etiquetas:

Crear e iniciar una animación o movimiento.
Si se especifica async="true", el motor no espera a que finalice y continúa inmediatamente con la siguiente etiqueta.

Debido a esto, las etiquetas después de una etiqueta async="true" pueden ejecutarse mientras la animación aún se está reproduciendo.

Esto te permite hacer cosas como:

Mover un fondo o personaje
Al mismo tiempo que muestra texto o ejecuta otros efectos

5. Etiquetas que cambian el flujo de ejecución

Normalmente la ejecución va de arriba a abajo, pero algunas etiquetas cambian donde continúa la ejecución.

5.1 Etiquetas

[label start]

Una etiqueta marca una posición con nombre en el escenario.
Ejecutar una etiqueta no hace nada por sí solo.

5.2 Saltos

[goto name="start"]

6. Ramificación condicional (if / elseif / else)

[if ...]
  ...
[elseif ...]
  ...
[else]
  ...
[endif]

Sólo se ejecuta el primer bloque coincidente.
Los bloques que no se eligen se omiten por completo
Puedes escribir elseif cero o más veces
else es opcional

7. Variables y expansión de variables.

7.1 Configuración de variables

Utilice la etiqueta [set] para establecer una variable.

[set name="player_name" value="Alice"]

Todas las variables son cadenas
Los números y valores booleanos también se almacenan como cadenas.

7.2 Expansión variable

Puede utilizar la expansión de variables dentro de los valores y el texto de las etiquetas.

[text text="${player_name} stands up"]

${...} se reemplaza con el valor de la variable en tiempo de ejecución
La expansión ocurre cuando se ejecuta la etiqueta

[set name="x" value="1"]
[text text="${x}"]
[set name="x" value="2"]
[text text="${x}"]

En este ejemplo, la salida es 1 y luego 2.

8. Las macros son bloques que puedes ejecutar como una unidad

Las macros le permiten agrupar varias etiquetas y ejecutarlas juntas.

[defmacro name="greet"]
  [text text="Hello"]
[endmacro]

[callmacro name="greet"]

9. Cambiar archivos (cargar)

[load file="scene2.txt" label="start"]

file= es obligatorio y label= es opcional.

10. ¿Qué sucede al final de un archivo?

Si se ejecuta:

Llega al final del archivo y
No ocurren más etiquetas goto o load

Entonces la ejecución del escenario finaliza.

Sin embargo, en algunas plataformas (por ejemplo, iOS o consolas de juegos), no se permite cerrar la aplicación.

Por lo tanto, se recomienda que su escenario explícitamente:

Vuelve al título usando goto, o
Carga una escena de título usando load

en lugar de finalizar automáticamente.

11. Cómo encaja este documento con otros documentos

Este documento está destinado a ir con:

Referencia de etiqueta: explica qué hace cada etiqueta
Este documento: explica cómo se ejecuta un escenario.

Para obtener detalles sobre etiquetas individuales, consulte la "Referencia de etiquetas".