Construcción de Mundos
Bloques y Variables
Cómo los bloques definen tu estructura de datos y se convierten en variables para los flujos.
Los bloques (blocks) son los campos de una ficha. Cada bloque tiene un tipo y una etiqueta. A menos que se marque como constante o use un tipo que no genera variables, un bloque se convierte automáticamente en una variable que los flujos pueden leer y modificar.
Tipos de bloques
Storyarn admite 10 tipos de bloques:
| Tipo | Descripción | ¿Variable? | Ejemplo de valor |
|---|---|---|---|
| Texto | Entrada de texto corto o de una sola línea con placeholder opcional | Sí | "Jaime" |
| Texto Enriquecido | Texto formateado con negrita, cursiva, listas, enlaces | Sí | "<p>Un guerrero valiente...</p>" |
| Número | Entrada numérica con restricciones opcionales de mín, máx y paso | Sí | 42 |
| Booleano | Interruptor. Admite modo de dos estados (true/false) o tres estados (true/false/nil) | Sí | true |
| Selección | Elección única de una lista de opciones definida | Sí | "warrior" |
| Selección Múltiple | Múltiples elecciones de una lista definida (etiquetas) | Sí | ["fire", "ice"] |
| Fecha | Selector de fecha | Sí | "2024-03-15" |
| Tabla | Cuadrícula tipo hoja de cálculo con columnas tipadas y filas con nombre | Sí (a nivel de celda) | Ver Bloques de tabla |
| Referencia | Enlace a otra hoja o flujo | No | – |
| Galería | Colección de imágenes de recursos subidos | No | – |
Los bloques de referencia y galería se excluyen del sistema de variables porque no llevan un valor significativo en tiempo de ejecución.
Nombrado de variables
Las variables siguen el patrón {atajo_de_hoja}.{nombre_de_variable}.
El nombre de variable se genera automáticamente a partir de la etiqueta del bloque: los espacios se convierten en guiones bajos, los caracteres acentuados se transliteran a ASCII y todo se pone en minúsculas.
| Etiqueta | Nombre de variable | Referencia completa (en mc.jaime) |
|---|---|---|
| Health Points | health_points | mc.jaime.health_points |
| Clase Social | clase_social | mc.jaime.clase_social |
| Is Alive | is_alive | mc.jaime.is_alive |
Puedes personalizar el nombre de variable después de crearlo, y se queda como lo nombraste hasta que cambias la etiqueta. Un bloque heredado toma su nombre de variable de la etiqueta del bloque de su padre; desvincúlalo para darle un nombre propio. En ambos casos, una variable que se usa en otro sitio, en un flujo o en una escena, conserva su nombre cuando cambia la etiqueta, para que nada de lo que la usa se rompa. Si una ficha ya tiene una variable con el mismo nombre (p.ej., por herencia), Storyarn añade un sufijo numérico para mantener los nombres únicos.
Constantes
Marca un bloque como constante para excluirlo del sistema de variables. Las constantes son para datos estáticos que los flujos nunca necesitan comprobar o modificar: descripciones de personajes, texto de ambientación, entradas de lore, imágenes de referencia.
Un bloque constante sigue mostrándose en la ficha y se incluye en las capturas de versión — simplemente no aparecerá en el selector de variables al construir condiciones o instrucciones en los flujos.
La marca de constante también se hereda: cuando un bloque padre con alcance “hijos” es constante, todas las instancias hijas también lo son. Una ficha hija solo puede cambiarla tras desvincular el bloque.
Configuración de bloques
Cada tipo de bloque tiene sus propias opciones de configuración:
- Texto – texto de placeholder.
- Número – placeholder, valores mínimo, máximo y de paso para validación de entrada.
- Booleano – modo de dos estados (true/false) o tres estados (true/false/sin asignar).
- Selección / Selección Múltiple – una lista de opciones, cada una con una clave y un valor de visualización.
- Tabla – visualización plegable, más definiciones de columnas y filas (ver Bloques de tabla).
- Referencia – tipos de destino permitidos (hoja, flujo).
Alcance de propiedades
Cada bloque tiene un alcance (scope) que controla la herencia:
- Propio (Self) – el bloque solo existe en esta hoja. Es el valor predeterminado.
- Hijos (Children) – la definición del bloque se propaga en cascada a todas las fichas descendientes. Cada hija obtiene una instancia con el mismo tipo, etiqueta y configuración pero su propio valor independiente. Un bloque que pasas a Hijos más tarde llega también a todas las fichas que tiene debajo, incluso a una ficha que esté en la papelera. Si vuelves a pasarlo a Propio, el bloque sale de las fichas hijas; si lo pasas de nuevo a Hijos, cada ficha recupera la instancia que tenía, con su valor.
Cuando un bloque padre con alcance “hijos” se actualiza (etiqueta, tipo, opciones), todas las instancias hijas no desvinculadas se sincronizan automáticamente, también en una ficha hija que alguien tenga abierta. Si el tipo cambia, los valores de las hijas se restablecen al valor predeterminado del nuevo tipo.
Una instancia heredada toma del bloque padre su etiqueta, su configuración y sus marcas de constante y obligatorio, así que la ficha hija no las edita. Puedes desvincular (detach) una instancia heredada para que deje de sincronizarse con el padre. Un bloque desvinculado mantiene su configuración actual y puede editarse independientemente. Puedes volver a vincularlo (re-attach) más tarde para resincronizarlo con la definición del padre, siempre que el bloque padre siga llegando a la ficha.
Bloques obligatorios
Marca un bloque como obligatorio (required) desde su barra de herramientas (el asterisco) para saber si está completo. Un bloque obligatorio muestra la etiqueta obligatorio junto a su nombre y, mientras está vacío, es un aviso en el estado de la ficha, de modo que las fichas incompletas se ven de un vistazo. Un bloque de tabla marca como obligatorias sus columnas.
La marca de obligatorio también se hereda: cuando un bloque padre con alcance “hijos” es obligatorio, todas las instancias hijas heredan esa obligación.
Disposición en columnas
Los bloques pueden organizarse en una disposición multicolumna usando grupos de columnas. Dentro de un grupo, los bloques pueden colocarse en las posiciones 0, 1 o 2, permitiendo hasta tres bloques lado a lado para disposiciones de hoja más compactas.