Visión general de las Fichas

Las Fichas (Sheets) son contenedores de datos estructurados para los datos del mundo de tu proyecto. Perfiles de personajes, catálogos de objetos, detalles de ubicaciones, registros de facciones — cualquier cosa que necesites definir y rastrear a lo largo de tu narrativa.

Cada ficha contiene un conjunto de bloques (blocks) (campos tipados como texto, número, selección o booleano) que definen su estructura. Los bloques con valor que no estén marcados como constantes se convierten en variables que los flujos pueden leer y modificar en tiempo de ejecución. Los bloques de referencia y galería no participan en el sistema de variables.

Atajos (Shortcuts)

Cada ficha tiene un atajo (shortcut) — un identificador con notación de puntos que los flujos, condiciones e instrucciones usan para referenciarla.

Los atajos se generan automáticamente a partir del nombre de la ficha, pero pueden editarse manualmente. El formato es alfanumérico en minúsculas con puntos y guiones (p.ej., mc.jaime). Usa prefijos para organizar por dominio:

• mc.jaime – personaje principal
• item.healing-potion – un objeto
• loc.tavern – una ubicación
• faction.guild – una facción

Los atajos deben ser únicos dentro de un proyecto. Si una ficha ya tiene variables referenciadas en flujos, renombrarla no cambiará el atajo para evitar romper referencias.

Referencias de variables

Los bloques que admiten variables usan el patrón:

{atajo_de_hoja}.{nombre_de_variable}

El nombre de variable se genera automáticamente a partir de la etiqueta del bloque usando notación con guiones bajos. Por ejemplo, un bloque etiquetado “Health Points” en la ficha mc.jaime se convierte en:

mc.jaime.health_points

Estas referencias son las que los flujos usan en condiciones (“¿Es mc.jaime.health_points mayor que 50?”) e instrucciones (“Establecer mc.jaime.health_points a 100”).

Organización con carpetas

Las fichas admiten una estructura de árbol. Arrastra y suelta para reordenar, anida fichas dentro de otras para organizarlas.

Un árbol admite hasta 100 niveles de profundidad. Storyarn no crea, mueve ni restaura una ficha por debajo del nivel 100, y te dice por qué. Un nivel admite tantas fichas como permita tu plan.

Main Characters/
  mc.jaime
  mc.elena
  mc.kai
Items/
  Weapons/
    item.iron-sword
    item.fire-staff
  Potions/
    item.healing-potion

Cualquier ficha puede tener tanto hijos como sus propios bloques. Las fichas padre también pueden definir propiedades heredadas que se propagan a sus hijos (ver Herencia de propiedades más abajo).

Herencia de propiedades

Los bloques tienen un ajuste de alcance (scope) que controla si permanecen locales o se propagan a las fichas hijas:

• Propio (Self) (predeterminado) – el bloque existe solo en esta hoja.
• Hijos (Children) – la definición del bloque se propaga a todas las fichas descendientes. Cada hija obtiene su propia instancia con valores locales pero el mismo tipo, etiqueta y configuración.

Esto te permite crear fichas padre tipo plantilla. Una ficha “Base de Personaje” con bloques de alcance hijos (salud, nivel, facción) les da automáticamente esos mismos campos a todas las fichas hijas, cada una con sus propios valores independientes.

Las instancias hijas se mantienen sincronizadas con la definición del padre: si cambias la etiqueta, el tipo o las opciones en el bloque padre, todas las instancias no desvinculadas se actualizan. Puedes desvincular (detach) una instancia para hacerla completamente independiente, o volver a vincularla (re-attach) para sincronizarla de nuevo. Un bloque desvinculado que pasas a Hijos sustituye al bloque del padre en las fichas que tiene debajo: gana la definición más cercana, y cada una de esas fichas conserva su valor. Cuando la copia vuelve a quedarse en su ficha, se vuelve a vincular o se elimina, vuelven al bloque del padre, con sus valores. Un bloque desvinculado en una de esas fichas se vuelve a vincular a la copia.

Las fichas también pueden ocultar bloques heredados específicos, evitando que se propaguen más abajo a sus propios hijos. Una ocultación se mantiene cuando el bloque del padre pasa a Propio y vuelve a Hijos. Cubre todo el bloque heredado: sigue aplicándose cuando una copia de ese bloque, transmitida más cerca, sustituye al bloque del padre, y cuando la copia deja de transmitirse. Ocultar conserva lo que una ficha ya tiene, y no llega nada nuevo debajo: una ficha que mueves bajo una ocultación desde fuera de ella conserva su instancia del bloque oculto como copia propia, con su valor (una que mueves dentro de la parte oculta la conserva tal como estaba), y restaurar una versión mantiene el vínculo de un bloque que la ficha sigue teniendo.

Personalización de fichas

Cada ficha admite metadatos adicionales:

• Color – un color hexadecimal para identificación visual en la barra lateral y las referencias.
• Avatar – una imagen subida que se muestra como el icono de la ficha.
• Banner – una imagen de cabecera que se muestra en la parte superior de la ficha.
• Descripción – texto enriquecido para notas y anotaciones (no se expone como variable).

Versionado

Storyarn registra el historial de cada ficha mediante capturas de versión (version snapshots).

• Auto-versionado – se crea automáticamente una captura cuando editas una ficha, con un intervalo mínimo de 10 minutos entre capturas para evitar ruido. Las capturas automáticas se conservan tanto tiempo como los elementos de la papelera, un plazo que depende del plan del propietario del workspace, y después se eliminan. Ponerle nombre a una la conserva, dentro del límite de versiones con nombre del plan.
• Capturas manuales – puedes crear una versión con nombre, con título y descripción, en cualquier momento para marcar un hito significativo.
• Restaurar – vuelve a cualquier versión anterior. Esto restaura el nombre de la ficha, el atajo, el avatar, el banner y todos los tipos, configuraciones y valores de los bloques. Un bloque heredado que sigue vinculado a su padre toma la definición del bloque padre tal como está ahora y conserva el valor de la versión; una tabla vinculada toma las columnas y filas del padre y conserva las celdas de la versión allí donde su fila sigue existiendo y su columna conserva su tipo, aunque el padre les haya cambiado el nombre. Un bloque que la ficha ya no hereda, porque el padre borró su bloque, dejó de transmitirlo o la ficha se movió a otro lugar, vuelve desvinculado con los valores de la versión, y la vista previa de la restauración enumera esos bloques. Un bloque cuyo alcance cambió desde la versión vuelve a cambiar como lo cambia la barra de herramientas: si vuelve a transmitirse, cada ficha de debajo recupera la instancia que tenía, con su valor; si vuelve a quedarse en la ficha, las fichas de debajo lo pierden. La vista previa de la restauración también enumera esos bloques. Un bloque que el padre añadió después de la versión se queda, con el valor que le dio la ficha, después de los bloques de la versión. Si otra ficha usa ahora ese atajo, la restaurada lo toma con -restored añadido (mc.jaime-restored, luego mc.jaime-restored-2), y la vista previa de la restauración te muestra ese nombre antes de confirmar. Si ese nombre cambia antes de que confirmes, porque otra ficha lo ocupa o libera el atajo que la vista previa tenía que sustituir, la restauración se detiene y te dice el atajo que usaría ahora; vuelve a restaurar para usarlo.

Cada versión registra quién hizo el cambio y genera un resumen de lo que cambió (bloques añadidos, eliminados o modificados).