Primeros pasos

Requisitos

• Unity 6 (desarrollado y probado en la versión 6000.0.79f1, plantilla URP).
• Paquete Addressables (com.unity.addressables) — obligatorio. La carga por dirección es la ruta de tiempo de ejecución, y el tipo AssetRef@Group necesita Addressables.
  • Sin el paquete, el asset sigue compilando, porque todo el código que usa Addressables está protegido detrás de un version-define SHEETFORGE_ADDRESSABLES.
  • Pero la canalización — importación · exportación · Push · reflejo de creación — permanece bloqueada. Cada punto de entrada muestra un aviso de instalación, y la ventana Primeros pasos te guía para instalarlo.

Instalación de Addressables

• Ruta principal: cuando importas el asset desde el Asset Store, el aviso de "dependencias del Package Manager" aparece antes de la compilación — elige Install y Addressables se instala junto con él.
• Red de seguridad: si pulsaste Skip (o lo importaste manualmente), la canalización permanece bloqueada y la ventana Primeros pasos te guía para instalarlo desde su fila de estado de Addressables. Esa ventana se ejecuta incluso sin Addressables, porque el Editor sigue compilando.
  • La ventana bootstrap sin dependencias SheetForge.Setup también detecta el paquete faltante al cargar el editor y muestra un aviso una vez por sesión. Como no tiene dependencias, sigue funcionando incluso cuando otros errores de compilación bloquean los ensamblados principales.
• No existe una instalación programática de un solo clic: las reglas de publicación del Asset Store restringen la instalación programática de paquetes, así que la ventana te guía en su lugar.
• El aviso refleja el estado real de instalación. Explica que el producto compila pero sus funciones permanecen bloqueadas hasta que se instale el paquete, y después te dirige a la ventana Primeros pasos. Puedes reabrirlo en cualquier momento desde Tools ▸ SheetForge ▸ Addressables Setup (este menú sobrevive incluso si los ensamblados principales no logran compilar por algún otro motivo).

Actualizar desde una versión anterior

Una importación de .unitypackage añade y actualiza archivos, pero nunca los elimina. Así que un archivo que una versión más nueva retiró puede quedar rezagado en Assets/SheetForge, todavía haciendo referencia a una API que ya no existe. La compilación se rompe, y parece que la actualización rompió tu proyecto. Dos redes de seguridad cubren esto:

• Detección automática. Al cargar el editor, el bootstrap SheetForge.Setup, sin dependencias, comprueba las rutas que este producto ha retirado. Si encuentra alguna, ofrece eliminarlas — listando cada ruta en el diálogo primero y sin tocar nada hasta que apruebes. Vive en su propio ensamblado precisamente para sobrevivir a los errores de compilación que existe para solucionar.
• Borrón y cuenta nueva (clean slate). Para una actualización con limpieza garantizada, elimina la carpeta Assets/SheetForge existente, importa el nuevo paquete y luego ejecuta Ejecutar importación una vez para reconstruir lo que la eliminación se llevó consigo. Los assets de ajustes y los SO generados mediante bake (Assets/SheetForgeBaked) viven fuera de esa carpeta y no se ven afectados, y lo mismo ocurre con el código generado una vez que reside en su ubicación predeterminada Assets/SheetForgeGenerated. Si tu proyecto todavía genera en la ubicación anterior dentro del producto (Assets/SheetForge/Runtime/Generated), eliminar la carpeta borra ese código y la reimportación lo escribe en Assets/SheetForgeGenerated en su lugar. Esa es la forma admitida de mover un proyecto existente a la nueva ubicación. Lo único que ninguna reimportación puede reconstruir es lo que tú hayas puesto dentro de Assets/SheetForge por tu cuenta (un asset de ajustes guardado ahí, tus propios scripts de plugin, archivos de hoja), así que saca eso primero.

Vale la pena decir un límite con claridad: la limpieza automática elimina los archivos retirados propios de SheetForge, nunca los tuyos. Si tu propio código de plugin implementa un contrato que desde entonces se ha retirado, tiene que portarse a mano. En resumen:

• un constructor de grafo por pestaña (IGraphShapeBuilder / GraphSpecBuilder) se convierte en el aumentador del lienzo de registros (IRecordCanvasAugmenter / CanvasAugmentBuilder), que añade al cierre que el lienzo ya construyó en lugar de construir la imagen completa;
• GraphMode desaparece, ya que la dirección ahora es control propio del lienzo;
• StudioGraphContext.ShapeId / ModeId todavía compilan pero cada uno devuelve una constante, así que cualquier comparación AppliesTo contra ellos debería simplemente eliminarse;
• IAuthorableGraphShape.CreatableTabs no cambia.

La tabla completa de en qué se convirtió cada contrato retirado está en la sección Upgrade notes de CHANGELOG.md en el repositorio de origen (el paquete de lanzamiento no lo incluye). Los miembros retirados que todavía compilan se marcan [Obsolete] en lugar de eliminarse, así que una actualización los muestra como advertencias en lugar de romper la build.

La ventana Primeros pasos (empieza aquí)

Una vez instalado Addressables, una ventana Primeros pasos se abre automáticamente una vez por sesión del editor — en cada inicio del Editor, pero no de nuevo tras un domain reload. Sigue haciéndolo mientras su interruptor "Mostrar esta ventana al iniciar el Editor" esté activado, que lo está por defecto.

Es el punto de entrada recomendado. Puedes reabrirla en cualquier momento desde Tools ▸ SheetForge ▸ Primeros pasos, y desactivar la apertura automática con ese interruptor en la parte inferior (la elección se guarda por proyecto y por usuario).

Reúne todo el flujo de primera ejecución en un solo lugar:

1. Panel de estado — un semáforo de tres filas: Addressables instalado, un asset de ajustes de importación activo, y primera importación completada. Cada fila muestra ✓ o ✗, y todo lo que aún necesita atención tiene un botón de acción justo al lado (Nuevo asset de ajustes, o Ejecutar importación).
2. Ajustes de importación — enumera todos los assets SheetForgeSettings con un botón de radio para elegir cuál es el activo, además de un botón Nuevo asset de ajustes y un botón Reveal para localizar cada asset.
3. Ejemplos — un clic para importar el paquete de demo de Plugin o el de Core.
4. Empezar desde una plantilla — elige una de las dos plantillas integradas, elige "from scratch" para definir los campos tú mismo, o usa una plantilla registrada por un plugin. "Use" abre el panel de creación de Data Studio pre-rellenado con ella. Esto necesita un asset de ajustes activo con un origen escribible; si todavía no tienes uno, el requisito se muestra.
   • Las integradas son Ejemplo de ítem, que usa solo tipos del núcleo, y Enum definitions, que dispone una hoja @enum.
   • Las pestañas de la demo de habilidad solo aparecen aquí cuando un plugin de plantillas, como el Plugin Demo, está presente.
5. Ejecutar — Run Import (usa los ajustes activos) y Abrir Data Studio.
6. Open Full Guide — un enlace a este sitio de documentación.

Las secciones de abajo explican cada paso en detalle; puedes hacerlo todo desde la ventana, o desde los menús y la ventana Project como se describe.

Todavía más rápido — arrastrar y soltar. Si ya tienes una carpeta de archivos de hoja, abre Data Studio y arrastra esa carpeta sobre ella — o un único archivo .tsv/.csv/.xlsx. Se ofrece a crear un asset de ajustes de importación que lea desde esa carpeta y activarlo, sin configuración manual.

Al abrirse sin ajustes activos, Data Studio muestra un panel "Get started" con los mismos botones de crear / importar demo / Primeros pasos en lugar de una tabla vacía.

Comprobación de estado. En cualquier momento, abre Data Studio y elige ⋯ ▸ Health Check en la barra de herramientas para un diagnóstico rápido sin red. Reporta ✓/✗ — cada uno con una solución sugerida — para:

• los ajustes activos;
• si el origen es accesible (una carpeta local que existe, o un id de Google + ruta de clave);
• si existe un baseline de importación;
• si el código generado, los SO generados mediante bake y los addressables están actualizados.

Idioma de la UI. La primera vez que abres un proyecto, SheetForge establece el idioma de su UI a partir del idioma del sistema de tu Editor (nueve idiomas se mapean directamente; cualquier otro se queda en inglés). Nunca sobrescribe un idioma que ya hayas elegido; cámbialo en cualquier momento en Preferences ▸ SheetForge (consulta Localización).

1. Elige un asset de ajustes de importación

Crea uno desde el botón Nuevo asset de ajustes de la ventana Primeros pasos, o haz clic derecho en la ventana Project → Create ▸ SheetForge ▸ Ajustes de importación (las etiquetas de menú siguen tu configuración de idioma — consulta Localización).

Puedes mantener varios assets de ajustes (por ejemplo, uno por origen de datos) y elegir cuál es el activo. Los menús, Data Studio y las importaciones usan todos el activo. La elección se guarda por proyecto y por usuario — un puntero de EditorPrefs, sin cambios en el VCS, independiente por cada compañero de equipo — y si el asset activo se elimina, el puntero se autorrepara.

Con un único asset de ajustes, tu primera importación lo selecciona automáticamente; no se necesita una elección explícita. Cuando existen varios, elige el activo en la ventana Primeros pasos o desde el menú desplegable que aparece en la barra de herramientas de Data Studio.

Configura el asset SheetForgeSettings:

El inspector de ajustes muestra solo los campos relevantes para el modo de origen actual — el modo local oculta las entradas de Google; gidMap solo aparece en el modo Google ExportUrl.

2. Seguridad de la clave de cuenta de servicio (origen Google)

¿Usas una fuente LocalFile? Omite esta sección.

Usar Google Sheets en modo SheetsApi requiere una clave JSON de cuenta de servicio. Si nunca has creado una, Configuración de Hojas de Google recorre todo el proceso paso a paso. Mantén esta clave fuera de Assets/ y fuera de tu repositorio: nunca hagas commit de ella.

• Recomendado: define la variable de entorno SHEETFORGE_SHEETS_KEY con la ruta absoluta de tu archivo de clave. Tiene prioridad sobre el campo de ruta de clave del asset de ajustes, de modo que cada desarrollador inyecta su clave local sin dejar ninguna ruta en el repositorio.
• Si debes poner una ruta en el campo de ajustes, apunta fuera del repositorio (por ejemplo, C:/keys/service-account.json). Un archivo de clave dentro de Assets/ se filtraría en las builds y en los commits.

3. Ejecuta tu primera importación

Tools ▸ SheetForge ▸ Data Studio, luego pulsa ↓ Pull from source en la barra de herramientas.

• La canalización obtiene → valida → (si tiene éxito) genera código → hace bake. Los diagnósticos se imprimen en la consola como un informe legible para humanos en tu idioma.
• La primera importación se completa automáticamente en dos etapas internas. Cuando un esquema es nuevo o ha cambiado, la importación escribe el código generado, lo que activa una recompilación/domain reload. Luego reanuda automáticamente el bake después de la recarga. Una sola acción del usuario; sin necesidad de volver a activarlo manualmente. Si la compilación falla, la reanudación automática aborta de forma segura (límite de 3 intentos) y deja una frase accionable en la consola.
• La validación recopila todos los diagnósticos en el momento de la importación (nunca se detiene en el primer error). Si existe aunque sea un solo error, no se produce ninguna salida (sin ensamblaje parcial).
• La importación registra automáticamente el SO de base de datos de cada pestaña en el grupo de Addressables SheetForge, en la dirección "SheetForge/{tab}" — tu juego lo carga mediante esa dirección estable (consulta Conceptos fundamentales).

4. Carga datos en tu juego

using SheetForge.Runtime;
using UnityEngine.ResourceManagement.AsyncOperations;
 
AsyncOperationHandle<DefinitionDatabase> handle = SheetForgeDatabases.LoadAsync("Items");
await handle.Task;   // or coroutine yield / handle.WaitForCompletion()
if (handle.Status == AsyncOperationStatus.Succeeded)
{
    DefinitionDatabase db = handle.Result;
    // For strong typing: SheetForgeDatabases.LoadAsync<ItemsDatabase>("Items")
}
SheetForgeDatabases.Release(handle);   // Addressables is ref-counted — release what you load

El ensamblado SheetForge.Runtime es autoReferenced, por lo que el código del juego puede usarlo sin una referencia de asmdef.

Nunca hagas referencia a un SO generado mediante bake directamente desde una escena. Los SO generados mediante bake son cachés no confirmadas (non-committed) y específicas de cada máquina — sus GUID difieren entre máquinas y entre bakes, por lo que una referencia directa desde una escena queda como Missing en la máquina de un compañero de equipo. La carga por dirección absorbe esto por diseño.

5. Prueba las escenas de demostración

Dos ejemplos se distribuyen como paquetes de importación selectiva. El ejemplo de plugin SheetForge.PluginDemo (tipos personalizados, enums, validadores, aristas) y un ejemplo sin plugin SheetForge.CoreDemo (solo tipos integrados del Core) incluyen cada uno una escena de demostración "abrir y pulsar Play".

Las importaciones de demo viven en un solo lugar — la sección Ejemplos de la ventana Primeros pasos — así que no existe una hoja de menú para ellas.

• Demo de plugin: pulsa Importar Plugin Demo en Primeros pasos, o haz doble clic en Assets/SheetForge/Examples/SheetForgePluginDemo.unitypackage. Cualquiera de las dos formas lo restaura bajo Assets/SheetForge.PluginDemo/…. Escena: Demo/PluginDemo.unity (menú Tools ▸ SheetForge ▸ Open Plugin Demo Scene, añadido por el propio ejemplo). Carga las bases de datos de ejemplo por dirección y muestra una habilidad ensamblada a partir de datos de la hoja (daño total de la bola de fuego = Damage 10 + DamageOverTime 3×3 = 19).
• Demo solo de Core: pulsa Importar Core Demo en Primeros pasos, o haz doble clic en Assets/SheetForge/Examples/SheetForgeCoreDemo.unitypackage. Eso lo restaura bajo Assets/SheetForge.CoreDemo/…. Escena: Demo/CoreDemo.unity (menú Tools ▸ SheetForge ▸ Open Core Demo Scene). Muestra equipamientos ensamblados a partir de referencias a items usando únicamente tipos integrados del Core. La demo también incluye una hoja de localización (ExampleStrings) cuyas claves los items referencian mediante celdas LocRef — consulta Hojas de localización.

(Las etiquetas finales de estos menús de ejemplo están en inglés, ya que quedan fuera de la canalización de menús localizados del Core.)

Cada paquete de demo incluye un asset de ajustes preconfigurado. Cuando importas un paquete de demo, SheetForge activa automáticamente ese asset de ajustes incluido si no tienes ajustes propios activos. Si ya tienes uno, abre la ventana Primeros pasos para sugerir el cambio en lugar de sobrescribir tu elección en silencio. Así que el flujo de la demo es simplemente: importar el paquete → (ajustes activados automáticamente) → Ejecutar importación → Play — sin creación manual de ajustes.

Una demo funciona únicamente después de ejecutar una importación en tu máquina — las direcciones de Addressables que carga solo existen después de que la importación se haya ejecutado una vez (el asset del grupo de Addressables es una caché no confirmada y autorreparable). Antes de eso, la escena de demostración muestra un mensaje de orientación en lugar de fallar.

Para terminar una demo (después de importar el paquete de ejemplo anterior):

1. Asegúrate de que el asset de ajustes incluido con la demo esté activo (la ventana Primeros pasos lo muestra, o la importación lo activó automáticamente). Usa origen = LocalFile, carpeta local = la carpeta DemoSheets del ejemplo, y el espacio de nombres predeterminado SheetForge.Generated, de modo que la reimportación regenera los tipos confirmados en el mismo lugar.
2. No se necesita ninguna acción para la referencia de script de la demo de plugin. La pestaña ExampleEffects incluye un ejemplo de AssetRef@Scripts. El propio ejemplo registra DemoScripts/special_effect.lua.txt bajo la dirección special_effect en un grupo de Addressables Scripts por sí solo, de forma idempotente, así que la primera importación pasa la validación de referencias. Solo si se registra una advertencia de que no pudo hacerlo (por ejemplo, un asset faltante) necesitas añadir esa entrada a mano — o eliminar la fila si no quieres el ejemplo de Addressables.
3. Pulsa ↓ Pull from source en Tools ▸ SheetForge ▸ Data Studio una vez (o el botón Run Import en Primeros pasos), luego abre la escena de demostración y pulsa Play.

6. Resumen del flujo de trabajo en equipo

• Los SO generados mediante bake (Assets/SheetForgeBaked) son una caché específica de cada máquina. Ponlos en gitignore, y después de clonar, cada miembro del equipo ejecuta Ejecutar importación una vez.
• El código generado (Assets/SheetForgeGenerated) es el propio código fuente de tu proyecto, y la recomendación es confirmarlo (commit). Así, un clon nuevo compila antes de que nadie haya ejecutado una importación, y los cambios de esquema aparecen en la revisión de código. Es una salida determinista, así que la importación de un compañero produce los mismos bytes y no genera ruido. Ponerlo en gitignore en su lugar también funciona; Ejecutar importación después de clonar es entonces lo que restaura la compilación.
• Un hook de frescura previo a la build comprueba, para cada tipo de Database generado y confirmado: (i) que el SO generado mediante bake exista, (ii) que la huella del esquema coincida con el baseline, (iii) que exista el registro de Addressables. Si algo falla, la build se aborta con una frase accionable, de modo que una máquina clonada o de CI nunca pueda enviar una caché vacía en silencio.

Páginas relacionadas

• Conceptos fundamentales — por qué la hoja es canónica y cuáles son las etapas de la canalización
• Sintaxis de la hoja — cómo escribir tu primera hoja
• Fuentes, exportación y envío — detalles de configuración de Google
• Preguntas frecuentes y solución de problemas — problemas de la primera ejecución