Preguntas frecuentes y solución de problemas

Respuestas orientadas a síntomas. Cada error de importación también lleva su propia frase de dónde/qué/por qué/cómo en el informe de la consola — empieza por ahí.

Configuración y primera ejecución

"Importé el asset sin Addressables — ¿compila? ¿Por qué la importación está bloqueada?"

El asset compila sin Addressables: el código que usa Addressables está protegido detrás de un version-define SHEETFORGE_ADDRESSABLES. La carga por dirección y el tipo AssetRef@Group sí necesitan com.unity.addressables, así que toda la canalización (importación · exportación · push · escritura de vuelta) queda bloqueada hasta que lo instales. Cada punto de entrada muestra un aviso de instalación y se detiene — sin ejecución parcial.

Instala com.unity.addressables mediante Package Manager. La fila de Addressables de la ventana Primeros pasos tiene un botón Open Package Manager, y esa ventana se ejecuta con normalidad en lugar de quedar bloqueada por el Safe Mode, porque el Editor compila sin el paquete.

Si sigues viendo errores de compilación después de instalarlo, vienen de otro código del proyecto — SheetForge compila tanto con el paquete como sin él.

"Actualicé a una versión más nueva y ahora el proyecto no compila."

Una importación de .unitypackage añade y actualiza archivos pero nunca los elimina. Así que un archivo que este producto retiró en una versión posterior puede quedar rezagado y hacer referencia a una API que ya no existe.

Al cargar el editor, el bootstrap SheetForge.Setup, sin dependencias, detecta esas rutas retiradas conocidas y ofrece eliminarlas, listando cada ruta antes de tocar nada. Aprueba el diálogo y la compilación se recupera. Como vive en su propio ensamblado, sigue funcionando mientras los ensamblados principales están fallando. Para saltarte el aviso por completo, elimina la carpeta Assets/SheetForge antes de importar el nuevo paquete.

Lo que esto no cubre es tu propio código escrito contra un contrato que desde entonces se ha retirado. Pórtalo a mano usando la tabla Upgrade notes en CHANGELOG.md en el repositorio de origen — el paquete de lanzamiento no incluye ese archivo — y Primeros pasos resume lo que dice.

"Create Sheet solo muestra las plantillas integradas — ¿dónde está la plantilla de demo de habilidades? / ¿Cómo añado la mía propia?"

La lista integrada de Create Sheet incluye dos plantillas más "from scratch": Ejemplo de ítem (solo tipos del núcleo), y Enum definitions, que dispone una hoja @enum.

Las plantillas de dominio que necesitan un plugin (como la demo de habilidades) las registra ese plugin, así que solo aparecen cuando el plugin está presente. Importa el paquete Plugin Demo y aparece su plantilla Skill demo. Para distribuir la tuya propia, implementa ISheetForgeTemplatePlugin — consulta Creación de plugins §4.6.

"¿Por dónde empiezo? / Una ventana se sigue abriendo cuando abro el Editor."

Es la ventana Primeros pasos. Se abre automáticamente la primera vez que el Editor carga, y es el punto de entrada recomendado: el estado de Addressables, elegir el asset de ajustes activo, importar un ejemplo, y ejecutar tu primera importación, todo en un solo lugar.

Desactiva la apertura automática con el interruptor "Mostrar esta ventana al iniciar el Editor" en la parte inferior, y reábrela en cualquier momento desde Tools ▸ SheetForge ▸ Primeros pasos.

"Importé un paquete de demo pero no pasa nada — no hay asset de ajustes ni grupo de addressables."

Cada paquete de demo incluye un asset de ajustes preconfigurado, y al importar el paquete se activa automáticamente — pero solo cuando no tienes ajustes propios activos. Si ya tienes uno, la ventana Primeros pasos se abre para sugerir el cambio, en lugar de modificar tu configuración en silencio.

Luego pulsa ↓ Pull from source en Tools ▸ SheetForge ▸ Data Studio una vez: eso crea el grupo de addressables y las direcciones por pestaña automáticamente. Flujo: importar el paquete → (ajustes activados automáticamente) → Ejecutar importación → Play.

"La escena de demostración solo muestra un mensaje de texto en lugar de la demo."

La demo carga por dirección de Addressables, y esas direcciones existen solo después de una importación en tu máquina (el asset del grupo es una caché no confirmada y autorreparable). Importa el paquete de demo (sus ajustes se activan automáticamente) y ejecuta Run Import una vez — consulta Primeros pasos §5.

(Los tipos confirmados de las demos usan el espacio de nombres predeterminado SheetForge.Generated, así que no se necesita ningún ajuste de generatedNamespace — la reimportación los regenera en el mismo lugar.)

"El primer import de la demo del plugin falla con UnknownAssetGroup 'Scripts'."

La demo del plugin tiene una columna script tipada List<AssetRef@Scripts>, que necesita un grupo de Addressables llamado Scripts. Los grupos de Addressables son específicos de cada máquina (no se confirman), así que una demo recién importada todavía no lo tiene.

La demo configura automáticamente ese grupo al importar (PluginDemoAddressableSetup, se dispara al recargar el dominio y al abrir la escena de la demo), así que una importación normal simplemente funciona. Si sigues viendo el error, reabre la escena de la demo (Tools ▸ SheetForge ▸ Open Plugin Demo Scene) para disparar la configuración, y luego vuelve a importar.

Esto aplica solo a la demo del plugin — tus propios grupos AssetRef@… son los que registras tú mismo.

"¿Qué asset de ajustes se usa cuando tengo más de uno?"

El activo. Los menús, Data Studio y las importaciones usan todos el asset de ajustes activo. Elígelo en la ventana Primeros pasos o en el menú desplegable de la barra de herramientas de Data Studio (se muestra solo cuando existen varios).

Con un único asset de ajustes, la primera importación lo selecciona automáticamente. La elección se guarda por proyecto y por usuario (un puntero de EditorPrefs — sin cambios en el VCS), y se autorrepara si el asset activo se elimina.

"Ya tengo una carpeta de hojas — ¿cuál es la forma más rápida de apuntar SheetForge hacia ella?"

Abre Data Studio y arrastra la 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 lo active, sin rellenar campos manualmente. Si ya tienes ajustes activos, el diálogo lo indica y ofrece cambiar.

"¿Cómo compruebo que mi proyecto está configurado correctamente / por qué la importación no se ejecuta?"

Elige ⋯ ▸ Health Check en la barra de herramientas de Data Studio. Reporta ✓/✗ con una solución sugerida para:

• los ajustes activos;
• la accesibilidad del origen — una carpeta local que existe, o un id de Google + ruta de clave de cuenta de servicio, sin llamada de red;
• el baseline de importación;
• la frescura del código generado/bake/addressables.

Los resultados van a la consola más un diálogo resumen.

"Los menús y la UI se abrieron en un idioma que no elegí."

En la primera apertura de un proyecto, SheetForge establece el idioma de su UI a partir del idioma del sistema de tu Editor (nueve idiomas se mapean, de lo contrario inglés). Nunca sobrescribe un idioma que hayas elegido tú mismo. Cámbialo en cualquier momento en Preferences ▸ SheetForge — consulta Localización.

(Cambiar el idioma activa una recompilación corta porque las etiquetas de menú se regeneran.)

"Cloné el repositorio y mis referencias de escena a los SO generados mediante bake están en Missing."

Es lo esperado: los SO generados mediante bake son cachés específicas de cada máquina, con GUID específicos de cada máquina. Nunca los referencies directamente desde escenas — carga por dirección (SheetForgeDatabases.LoadAsync("Tab")). Ejecuta la importación una vez para reconstruir tu caché local.

"Mi build se abortó con un mensaje de SheetForge."

Eso es el hook de vigencia previo a la build, que te protege de enviar una caché vacía/obsoleta. Haz lo que dice la frase — pulsa ↓ Pull from source en Tools ▸ SheetForge ▸ Data Studio — y vuelve a hacer la build.

Importación y validación

"La importación se ejecutó, encontró errores, y no produjo nada en absoluto."

Por diseño: un error ⇒ ninguna salida (sin ensamblaje parcial). El informe enumera todos los problemas con coordenadas y soluciones sugeridas — corrígelos en una sola pasada y vuelve a importar. Nunca pierdes trabajo por esto; la hoja no se toca.

"¿Puedo saltar directamente a la celda de la que trata un error?"

Sí. Cada error en el informe legible para humanos de la consola tiene un enlace en el que se puede hacer clic, "Open in Data Studio". Al hacer clic, se abre Data Studio, cambia a esa pestaña y resalta esa celda (solo la pestaña para errores a nivel de archivo/pestaña). La línea de coordenadas legible por máquina no cambia, así que el scraping de CI/logs no se ve afectado.

"La importación escribió código, recompiló… ¿terminó?"

Sí. Cuando un esquema es nuevo o ha cambiado, la importación es internamente de dos etapas (codegen → compilación/recarga → bake), y el bake se reanuda automáticamente después de la recarga. Vigila la consola para ver el informe final.

Si tu código de juego ya no compila (por ejemplo, después de un renombrado de columna), la cadena aborta de forma segura con una frase accionable; corrige tu código y vuelve a importar.

"Error de celda vacía, pero yo quería que la celda fuera opcional."

Los tipos sin marcar son obligatorios (protección contra contaminación silenciosa). Para hacer que una celda sea opcional:

• declara float? — valor predeterminado del tipo;
• declara int=1 — valor predeterminado explícito;
• o usa List<T>, donde una celda vacía es una lista vacía.

Consulta Sintaxis de la hoja.

"1.5 importa bien, pero 1,5 da error."

Es deliberado: los números son independientes de la configuración regional — siempre con . decimal. Los decimales con coma, NaN e Infinity se bloquean en la entrada.

"La importación se volvió muy lenta de repente."

El tiempo de importación es lineal en el tamaño de tus datos: 50k filas × 20 columnas ≈ 628 ms en el editor. Se mantiene lineal incluso cuando muchas referencias se rompen a la vez, porque la búsqueda de coincidencia más cercana tiene un presupuesto por campo y un prefiltro por longitud (≈ 45 ms con 4,000 referencias rotas, sin interfaz/headless).

Si una importación de repente tarda mucho más que eso, lo que hay que revisar es el tamaño de la hoja, no la cantidad de errores.

"Error de marcador desconocido / tipo desconocido con una sugerencia de '¿quisiste decir'."

Los errores tipográficos en nombres @marker, nombres de tipo, o miembros de enum son errores con sugerencias de coincidencia más cercana — aplica la sugerencia. Un @ desconocido en un nombre de tipo no registrado también es un error (seguridad frente a errores tipográficos para referencias estilo RecordId@Tab).

Google Sheets

"La importación de Google falla con PERMISSION_DENIED (403)."

La hoja de cálculo no está compartida con la dirección client_email de la cuenta de servicio — la clave por sí sola no otorga nada. Abre la clave JSON, copia client_email, y comparte la hoja con ella (Visor para importar, Editor para Push). El recorrido completo está en Configuración de Hojas de Google.

"Push dice que requiere SheetsApi."

Estás en modo ExportUrl, que es de solo lectura (sin autenticación). Cualquier escritura de vuelta necesita el modo SheetsApi con una clave de cuenta de servicio. Consulta Fuentes, exportación y envío. Crear la cuenta de servicio y la clave se explica en Configuración de Hojas de Google.

"La importación con ExportUrl falla pidiendo un mapa de gid."

Es obligatorio: una URL de exportación sin gid devuelve silenciosamente solo la primera pestaña, así que el mapa (nombre de pestaña → #gid=) se hace obligatorio. O cambia al modo SheetsApi, que no necesita ningún mapa.

"Push reportó celdas omitidas."

La nueva obtención en vivo antes del envío encontró conflictos (un compañero de equipo editó una celda, una fila se movió/desapareció, una clave duplicada). Las celdas omitidas son protección, no un fallo — el informe muestra los recuentos de aplicadas/omitidas. Vuelve a importar para reconciliar, y luego haz Push de nuevo.

"Eliminé filas localmente pero siguen en la hoja de Google después de Push."

Las eliminaciones de fila nunca se envían mediante Push (las eliminaciones posicionales contra una hoja en vivo son inseguras) — en su lugar, recibes un aviso. Elimina las filas en la hoja, y luego vuelve a importar.

Creación

"Ctrl+Z no deshace mi cambio en preparación."

Dos límites:

• un campo de texto enfocado consume Ctrl+Z primero — haz clic en otro lugar y luego deshaz;
• después de que "Reflejar en hoja" tenga éxito, el historial de preparación se borra, así que deshacer funciona solo dentro de la sesión previa al reflejo.

Después del reflejo, edita la hoja (es canónica).

"Algunas de mis ediciones en preparación muestran una insignia 'aislada' y no se reflejaron."

La hoja cambió externamente entre la preparación y el reflejo de una forma que rompió la dirección lógica de esas ediciones (la clave de la fila se renombró desde fuera / la fila se eliminó / conflicto de clave). Se excluyen — no se pierden en silencio, no bloquean el resto. Descártalas individualmente y vuelve a prepararlas contra el nuevo baseline.

"Renombré una columna/pestaña y ahora mi código de juego no compila."

Es lo esperado y se indica en el diálogo de confirmación: los renombrados cambian el nombre del campo/clase generado. Actualiza tu código de juego; la cadena de importación entonces se completa en la siguiente ejecución. Los valores de datos de la columna se preservaron por completo.

"¿Puedo intercambiar dos nombres de pestaña (A↔B), o renombrar pestañas en un ciclo, en un solo lote?"

Sí. Los intercambios mutuos y los ciclos (A→B→C→A) se preparan y reflejan en un solo lote, y la UI solo rechaza un conflicto real: dos renombrados que apuntan al mismo nombre. Las referencias siguen a los datos y se reescriben atómicamente.

Queda un caso límite en Google: dos pestañas intercambiadas que se referencian entre sí no se recolocan (lo local es totalmente correcto). Encamina la referencia mutua a través de una tercera pestaña, o refleja mediante un nombre intermedio. Consulta Data Studio y Capacidades y límites.

"Mi renombrado de clave no actualizó una referencia que escribí en el mismo lote."

La propagación reescribe solo las celdas del baseline — nunca el texto que acabas de escribir (sin reescritura silenciosa de la entrada reciente). La validación previa marca la referencia colgante; corrígela tú mismo.

"El reflejo se rehusó debido a una pestaña xlsx."

Dos casos conocidos:

• las pestañas de origen xlsx no se pueden renombrar (protección del libro);
• la propagación de renombrado de clave que tocaría una pestaña xlsx bloquea todo el lote (sin reflejo parcial).

Edita el libro directamente, y luego vuelve a importar.

"Edité un SO generado mediante bake en el inspector y la reimportación lo borró."

Es por diseño — la hoja es la única fuente de verdad y el SO es una caché. El interruptor de "edición de prueba" del inspector es explícitamente temporal. Haz cambios reales a través de la hoja o de Data Studio.

Exportación y varios

"La exportación falla con una discrepancia de esquema."

Tu bake está obsoleto respecto a un cambio de esquema (ExportSchemaMismatch — comprobación de huella). Ejecuta la importación para completar el codegen + bake, y luego exporta/Push.

"Mi float exportado dice 1 pero la hoja tenía 1.0."

Ida y vuelta semántica: los valores se preservan exactamente; la notación se normaliza a la forma de ida y vuelta más corta. La estructura (marcadores, orden de columnas, comentarios, tu texto) se preserva al 100%.

"La importación de xlsx rechazó algunas celdas."

El lector OOXML integrado es deliberadamente mínimo. Tres cosas no son compatibles:

• las celdas de fórmula sin valores en caché;
• las celdas de error;
• las tabulaciones/saltos de línea dentro de una celda.

Materializa las fórmulas en valores; usa ; para las listas.

"No puedo cambiar el idioma del editor en este momento."

Los cambios de idioma están bloqueados mientras se ejecuta una importación/exportación/Push (el cambio activa una regeneración del archivo de menú + una recompilación corta). Espera a que la canalización termine.

"Partes de mi informe de errores están en inglés aunque mi idioma es coreano/japonés/…"

El esqueleto del informe y las frases de por qué/cómo están localizados. Los detalles interpolados en tiempo de ejecución (el valor causante, las sugerencias) y los registros de bajo nivel están en inglés en línea — el límite estándar de la localización.

"¿A dónde fueron los elementos de menú Tools ▸ SheetForge ▸ … después de clonar?"

El archivo de menú localizado se genera (en gitignore) — se autorrepara al cargar el editor. Si las etiquetas están en el idioma equivocado, se regeneran en el siguiente cambio de idioma o inicio del editor.

Páginas relacionadas

• Capacidades y límites — la versión sistemática de estas respuestas
• Primeros pasos — los pasos de configuración referenciados arriba
• Sintaxis de la hoja — las reglas de notación referenciadas arriba