Referencia de la API — La superficie pública

Esta página enumera todos los tipos públicos de los ensamblados del producto. Cualquier cosa que no aparezca aquí es internal por diseño; la superficie pública es deliberadamente estrecha.

• Core (SheetForge.Core + SheetForge.Core.Tooling): 137 tipos públicos (Core: 131, Core.Tooling: 6). Core.Tooling es la mitad exclusiva del editor que contiene servicios en tiempo de importación como el reporting y la planificación de Push — nada de ella se distribuye en las builds del jugador.
• Editor: 53 tipos públicos de nivel superior más sus tipos anidados públicos.
• Runtime: 7 tipos, más las salidas generadas.

Esta es exactamente la superficie contra la que compilan las pruebas de simulación de consumidor (sin InternalsVisibleTo).

Contrato de detección (no es un tipo): un asset independiente también puede detectar que SheetForge está instalado en tiempo de compilación mediante el símbolo de definición de scripting SHEETFORGE que autorregistra el ensamblado Editor. Es un define, no un tipo público, así que no aparece en las tablas de abajo — consulta Creación de plugins ▸ Detectar SheetForge desde otro asset. (Distinto de SHEETFORGE_ADDRESSABLES, un version-define interno que solo indica si el paquete Addressables está presente.)

Convenciones: las firmas están abreviadas (… = consulta los documentos XML del código fuente); "puro" significa sin UnityEngine / sin E/S.

Ensamblado Core (SheetForge.Core) — C# puro

Sin UnityEngine, sin E/S, sin red, sin conocimiento de dominio. Impuesto por el compilador: Core no hace referencia a nada.

Contratos de registro de plugin (SheetForge.Core.Plugins)

Composición y compatibilidad (SheetForge.Core.Plugins)

El descubrimiento es por host — TypeCache de Unity en el editor, el escaneo del ensamblado subido del navegador en la web. Todo lo que viene después (instanciación, ordenamiento, aislamiento y la barrera de compatibilidad) es una única función compartida del Core, que es lo que evita que los dos hosts se desalineen slot por slot.

PluginComposition — los dos miembros:

• IReadOnlyList<Type> ContractTypes — el filtro de descubrimiento. Su orden es fijo, porque decide el orden en que aparecen los diagnósticos.
• PluginSet Compose(IReadOnlyList<Type> candidateTypes, string hostVersion, ErrorCollector errors, ICollection<string> failures, Func<string,bool> isProductKey = null) — la propia llamada de ensamblaje.

Se mantienen separados dos tipos de problema. Los conflictos de registro y los rechazos de compatibilidad se convierten en diagnósticos estructurados en errors; los errores de implementación — fallo de construcción, un callback que lanza una excepción — se convierten en líneas en inglés en failures, y pasar null ahí los descarta.

El predicado final isProductKey es cómo se impone la regla "un plugin no puede sobrescribir una clave del producto" de la superposición de cadenas sin que Core llegue a ver nunca las tablas de idioma: la regla vive aquí, el host solo suministra el material. Omite el predicado y solo esa regla se salta.

Registros (SheetForge.Core.Model / .Validation / .Edges)

EnumRegistry — los tres miembros en detalle:

• EnumRegistry(EnumRegistry parent) — un hijo que lee a través de un padre y solo se registra en sí mismo. El padre contiene los enums CLR registrados por plugin durante todo el domain reload, el hijo los definidos en hoja de esta importación, así que una importación nunca muta la caché compartida. Registrar un nombre que el padre ya posee lanza una excepción en lugar de sombrearlo.
• Contains(name) — propio y luego el padre, Ordinal.
• SetClrTypeName(name, fullTypeName) — rellena un nombre CLR después de un registro solo de string. El nombre de ensamblado queda vacío porque el tipo todavía no existe.

Plantillas de "Crear hoja" (SheetForge.Core.Model)

Tipos de celda personalizados (SheetForge.Core.Model)

Constantes de la gramática de hoja (SheetForge.Core.Model)

Un paquete que lee o escribe texto de celda funciona con la misma gramática que usa el importador — dividir una celda de lista, componer una cadena @type, comprobar si un nombre ya está en uso.

Estas constantes son la única fuente de verdad de esa gramática, así que un paquete nunca vuelve a declarar su propio separador: un carácter copiado se desincroniza el día que la gramática cambie. Las listas se entregan de solo lectura, así que nada de lo que haga un paquete puede cambiar la gramática en sí. La notación que describen está documentada por completo en la página Sintaxis de la hoja — esto es el asidero programático sobre ella.

Marcadores

• CommentPrefix (#) · MarkerPrefix (@).
• Una constante por cada fila de marcador integrado: NameMarker · TypeMarker · DescMarker · OverlapMarker · StyleMarker · EnumMarker · LocMarker.
• RequiredMarkers — los tres que toda hoja debe llevar.
• ReservedMarkers — todos los nombres integrados. Consúltalo antes de nombrar un marcador personalizado: una colisión se rechaza en el registro.

Separadores

• ListSeparator (;) — entre elementos de una lista.
• EntrySeparator (,), FieldSeparator (:), SectionSeparator (|), KeyTimeSeparator (@) — las capas dentro de un solo valor, razón por la cual ; nunca aparece en el texto propio de un valor.
• StyleKeyValueSeparator (=) — dentro de una celda @style.

Notación de @type

• OptionalSuffix (?) · DefaultSeparator (=) · TargetSeparator (@, como en RecordId@Tab).
• ListTypeName · ListOpen (List<) · ListClose (>).

Nombres de tipo

• Una constante por cada nombre integrado: IntTypeName · FloatTypeName · BoolTypeName · StringTypeName · RecordIdTypeName · IntIdTypeName · AssetRefTypeName · LocRefTypeName · ColorTypeName · AnimationCurveTypeName · GradientTypeName · EnumTypeName.
• BuiltinScalarTypes e IsBuiltinScalarTypeName(name) — responden "¿este nombre ya es integrado?" antes de que se registre un analizador con él.
• StyleKeyNames (title, color) · LocReservedColumns (smart, comment).

Valores

• TrueCanonical / FalseCanonical — el texto canónico de bool.
• NumberCellStyles — el NumberStyles con el que se lee cada celda numérica. Los separadores de miles quedan excluidos y la cultura es siempre invariante, así que una coma decimal local falla de forma ruidosa en lugar de cambiar el número en silencio.

Validación de dominio (SheetForge.Core.Validation)

Costura de aristas (SheetForge.Core.Validation / .Edges)

ReferenceScanner — los dos predicados de referencia:

• GetReferencedTab(TypeToken) — el único predicado que todo consumidor pregunta, "¿es esto una referencia, y hacia dónde?". Responde para RecordId@Tab, para IntId@Tab (el espacio de clave entero), para el interior de un wrapper, y para un tipo personalizado marcado IsCustomReference. Por eso una sola adhesión opcional — y, para IntId@Tab, una ampliación de este predicado — los activa todos a la vez.
• GetReferenceKind(TypeToken) → RefKeyKind — si la referencia compara contra el espacio de clave de tipo string o entero, así que la propagación de renombrado, la lista desplegable y el selector se ramifican correctamente.
• GetReferenceKind(TypeToken, tables) — la sobrecarga consciente de la tabla.

Una referencia del core declara su propio espacio (RecordId / IntId). Un tipo personalizado de referencia no tiene notación para decirlo — MyType@Tab es la única forma de escribirlo — así que su espacio se deriva de la identidad de la pestaña destino: una clave propia RecordId significa espacio de tipo string, IntId solo significa espacio entero, y una pestaña desconocida o unas tables null recae en espacio de tipo string, la misma respuesta que da la sobrecarga que solo toma el token. Esa derivación es lo que permite que una implementación existente de IReferencingCellType apunte a una pestaña con clave IntId sin cambiar ni una línea.

Índice del grafo de referencias (SheetForge.Core.Edges)

Una instantánea inmutable que fusiona las referencias escaneadas por el core y las aristas de los contribuyentes en un solo modelo, indexado en ambos sentidos. Material de visualización — nunca produce diagnósticos (los Diagnostics de la proyección siguen siendo la única fuente de verdad para los problemas).

Lienzo de registros de Data Studio (SheetForge.Core.Graphing)

El lienzo decide qué dibujar por sí mismo: recorre el índice de referencias hacia afuera desde el registro que abriste (el término) y dispone el resultado de forma determinista. Un plugin no reemplaza esa imagen — la añade. Datos puros en todo momento: las columnas son celdas de cuadrícula, no píxeles, y los colores son un string Category libre que la ventana mapea a una paleta.

CanvasAugmentBuilder — la superficie de escritura. Solo cuatro cosas:

• AddNode(tab, recordId, title = null, category = null) / AddNode(tab, recordId, title, category, CellCoordinate address) — un nodo virtual para una identidad que no es un registro de hoja (una clave de evento, un átomo de código); la pestaña puede estar vacía.
• AddEdge(fromTab, fromRecordId, toTab, toRecordId, label = null, fieldName = null, fieldOnTarget = false, isCyclic = false, cyclicNote = null) — una arista extra que el escáner del core no puede ver. Nombrar fieldName indica en qué celda se escribe el enlace, fieldOnTarget indica que esa celda está en la llegada en lugar de la salida, y el par de ciclo marca un bucle para visualización con la nota que solo el dominio conoce.
• SetLayer(tab, recordId, layer) — un hint de capa absoluto (0 = más a la izquierda, negativo = más a la izquierda todavía, todo se desplaza a la derecha para compensar). SetLayerRelative(tab, recordId, offset) — lo mismo contado desde el término (−1 = una columna a su izquierda), resuelto contra la columna del término antes de que cualquier hint la moviera.
• SetSubtitle(tab, recordId, subtitle) — un hint de visualización, lo único que se aplica a registros que ya existen y a registros que no están en pantalla (el selector de conectar los lee).

Los elementos con clave vacía se ignoran, y lo recopilado es interno, porque las reglas de fusión viven en un solo lugar. Cada ampliación es al final, así que un override escrito contra una superficie anterior sigue compilando.

IAuthorableGraphShape — los dos valores predeterminados sin ella:

• La lista de pestañas creables que esta capacidad reemplaza — el eje que también decide si un lienzo se abre siquiera y hasta dónde llega el barrido de filas pendientes — cubre toda pestaña alcanzable desde la pestaña de foco siguiendo el esquema transitivamente.
• La cascada de enlace que el usuario realmente ve empieza desde las pestañas a las que apuntan los puertos actualmente dibujados.

Ambas descartan las pestañas de registro de código y las pestañas sin columna clave. Una pestaña que esto devuelve y que ningún puerto dibujado acepta permanece listada en la cascada de enlace con su motivo adjunto, y las propias barreras de la ventana se siguen aplicando encima.

Preajustes de color (SheetForge.Core.Theming)

Un preajuste sobrescribe solo los slots que nombra; todos los demás slots mantienen el valor predeterminado del producto, así que un preajuste se mantiene válido a medida que se añaden slots. Registrar nunca aplica un preajuste — el usuario elige uno en Preferences ▸ SheetForge ▸ Theme.

Superficies de creación declarativas (SheetForge.Core.Studio)

Un plugin describe qué mostrar — la carcasa como datos, el predicado y el efecto como delegados — y cada host lo dibuja con sus propios widgets: UIToolkit en el editor, React en el navegador. Ningún número de layout aparece en ningún lugar. Qué decir es del plugin, cómo colocarlo es del renderizador.

Cada enum aquí es de solo adición, así que un registro conserva su significado a medida que crece el vocabulario.

StudioUiNode — fábricas, lecturas y la regla de URL:

• Fábricas: Row · Label · Chip · Badge · Button · Rule · Heading · KeyValue · Table(headerRow, rows) · List · Progress · Input · Link, más WithTooltip(text), que devuelve un nuevo nodo en lugar de cambiar este.
• Lecturas: Kind · Text · Tooltip · ThemeColorSlot? Tone (nunca un color codificado, así que sigue el tema) · ActionId · Detail · Ratio · Url · Children.
• estático bool IsAllowedUrl(url) — solo http/https. Un predicado que ambos hosts consultan, así que no pueden discrepar sobre qué es seguro abrir.

Cadenas de UI de plugin (SheetForge.Core.Model)

StringOverlayRegistry — coincidencia y rechazos. language es un código IETF ("en", "ko", "zh-Hans", "pt-BR", …), comparado sin distinguir mayúsculas/minúsculas. La búsqueda recae en idioma solicitado → inglés → fallo, y el fallback vive aquí para que ambos hosts respondan de forma idéntica.

Se rechazan cuatro registros, cada uno registrando un motivo dirigido al desarrollador en lugar de fallar en silencio:

• una clave integrada del producto — una superposición puede añadir claves, nunca sobrescribir las propias frases o rutas de menú del producto;
• una clave+idioma que otro paquete ya registró — gana el primero encontrado, porque de lo contrario el orden de instalación decidiría la pantalla;
• una clave o un valor vacíos;
• un código de idioma que el producto no conoce, que nunca se pliega a inglés.

Observación de la canalización (SheetForge.Core.Plugins / .Model)

Registros de código (SheetForge.Core.Graphing)

Destinos de referencia que viven en código, expuestos a la superficie de creación como pestañas virtuales bloqueadas. Consumidos por Data Studio (barra lateral / grafo / inspector), no por el validador de importación.

El modelo de lectura del IR (SheetForge.Core.Model)

Referencias de asset tipadas (SheetForge.Core.Model)

El <Type> en AssetRef@Group<Type> lo resuelve el host — el Core no conoce ni el motor ni los ensamblados del proyecto — y el Core solo juzga el resultado. Todo lo de aquí son datos puros.

El codegen lee el diccionario resuelto que produce la canalización y emite AssetReferenceT<global::FullName> para un nombre resuelto; un nombre que no encuentra en ese diccionario nunca se emite tal cual — el campo recae en AssetReference y se recopila una advertencia AssetTypeUnresolvedFallback. El nombre completo resuelto también se mezcla en la huella del esquema.

Tipos de valor visuales (SheetForge.Core.Model)

Modelos de valor libres del motor para los tres tipos visuales integrados. Cada uno es inmutable, IEquatable, y posee su propia forma de texto (TryParse / Render) — la misma notación que documenta la página de Sintaxis de la hoja — así que un tipo de plugin que almacena un color, una curva o un degradado puede reutilizarlos en lugar de inventar una segunda notación. El Editor hace bake de ellos en UnityEngine.Color / AnimationCurve / Gradient y los vuelve a leer; el navegador los muestrea mediante los evaluadores de abajo en lugar de reimplementar las matemáticas.

Errores y resultados (SheetForge.Core.Model / .Reporting)

ImportErrorCode — las familias que cubre:

• marcadores, esquema, tipos, celdas, claves/referencias y claves de asset;
• orígenes/archivos, csv/xlsx, identificadores de codegen, addressables, baseline/exportación, Google/autenticación/Push y plantillas;
• plugins — PluginRegistrationConflict, más PluginIncompatible cuando la declaración de compatibilidad de un ensamblado cae fuera de lo que este host lee;
• IntId — DuplicateIntId, y para referencias IntId@Tab: UnresolvedIntId · TargetTabHasNoIntId;
• @overlap y DomainRuleViolation;
• hojas de definición de enum — EnumSheetMarkerConflict · DuplicateEnumName · EnumSheetEmptyColumn · InvalidEnumIdentifier · InvalidEnumUnderlyingType · InvalidEnumMemberValue;
• DropdownNotSupportedByFormat, que es una advertencia en lugar de un error;
• referencias de asset tipadas — UnknownAssetType · AmbiguousAssetType · AssetTypeNotReferenceable (una vez por columna, en la fila @type), AssetTypeMismatch por celda, y la advertencia de codegen AssetTypeUnresolvedFallback.

Índices y utilidades (SheetForge.Core.Validation / .Model / .Parsing / .Unparse)

Plan de Push (SheetForge.Core.Unparse)

Públicos porque IPushApprover.Approve(PushPlan) los expone; datos puros.

Ensamblado Editor (SheetForge.Editor)

Ajustes, localización, composición (SheetForge.Editor.Pipeline / .Localization)

PluginRegistry — el paquete y el aislamiento de slots. El PluginBundle anidado expone el PluginSet Set ensamblado — la única verdad de doce slots, que es cómo se lee un slot recién crecido sin ampliar el paquete — más nueve ventanas de conveniencia sobre él: Enums · Parsers · Validators · EdgeContributors · Markers · Templates · GraphShapes · CodeRegistries · Themes. Los constructores anteriores de seis y ocho argumentos se mantienen como sobrecargas que ponen los registros posteriores en vacío por defecto, lo que se comporta igual que las versiones anteriores a esos contratos.

El aislamiento es del Core, no de este tipo: un plugin que lanza una excepción al registrarse se reporta por nombre y se omite, y todos los demás slots y plugins se siguen registrando.

SheetForgeActions — semántica de finalización. RunImport/RunPush son fire-and-forget. Sus cuerpos son async void porque el hilo principal del editor no puede bloquearse en E/S de red, así que el retorno no es la finalización — suscríbete a ImportEvents.ImportCompleted para eso. RunExport/RunHealthCheck/RunLocalizationSync se completan de forma síncrona — RunLocalizationSync recorre la ruta hoja → StringTable que recorre la finalización de una importación, y sin el paquete Unity Localization muestra el aviso de instalación y no cambia nada.

Costura de proveedor de origen (SheetForge.Editor.Sources)

Puntos de extensión de Data Studio (SheetForge.Editor.Studio)

Del lado del Editor porque tocan UIElements / estado de ventana — la misma asimetría justificada que ISheetSourceProvider. Los cuatro contratos los descubre TypeCache (constructor sin parámetros; sin llamada de registro), y todos se llaman dentro de try/catch. La propia ventana (DataStudioWindow) es internal.

Cualquier cosa expresable como datos pertenece en su lugar al vocabulario ISheetForgeStudioPlugin del Core, que también se renderiza en el navegador. Estas son las vías de escape sin techo para lo que la descripción no puede decir.

Las últimas cuatro entradas no son contratos sino herramientas que un widget montado puede usar:

• los propios valores de skin de solo lectura de la ventana, para que pueda parecer que pertenece ahí;
• el menú desplegable de claves, para que un widget de celda elija claves de la misma manera que la celda integrada;
• y el reinicio de la caché de descubrimiento, para que tus propias pruebas puedan volver a descubrir una sonda.

StudioInspectorContext — los dos delegados de preparación:

• StageCell recibe tab, recordId, field y texto canónico en bruto. La ventana registra el paso de Undo, incrementa la generación de proyección y prepara la dirección lógica.
• StageCells hace lo mismo para varias celdas que deben cambiar juntas: un solo paso de Undo nativo, todo o nada. Si una sola no se puede preparar, la sesión no se toca en absoluto.

Un fallo es silencioso en pantalla de todas formas, y solo la barrera se explica a sí misma. Un origen de solo lectura, una canalización ya en ejecución, o una pestaña respaldada por libro escriben su motivo en la consola. Una lista vacía, una escritura sin su pestaña o campo, y una clave de registro que no resuelve a ninguna fila no hacen nada y no dicen nada.

StudioPalette — los miembros:

• 33 slots de color: Canvas · Panel · Band · Chrome · Surface · Chip · Selection · PendingCell · Line · LineSoft · GridLine · LineHover · Text · TextMuted · TextFaint · RefText · OnAccent · Accent · AccentDim · Warning · Danger · Ok · SheetTone · CodeTone · EditedCell · NewRowCell · NewRowLine · DangerChip · DangerPanel · Scrim · Wire · WireDot · GridDot.
• IsDark.
• Espaciado: SectionSpace · RowSpace · RuleHeight · ButtonHeight · PrimaryButtonHeight · GlyphWidth.
• Tamaños de tipo: HeadingFontSize · SectionFontSize · CaptionFontSize.
• FromRgb(uint) · ToHex(uint).

Aprobación de Push (SheetForge.Editor.Push)

Motor de creación (SheetForge.Editor.Structure / .Pipeline / .Export)

Tipos de valor de preparación (SheetForge.Editor.Structure; StagedCellEdit/StagedNewRow están en SheetForge.Editor.Windows)

Ayudantes de creación (SheetForge.Editor.Windows / .Structure)

Ensamblado Runtime (SheetForge.Runtime)

autoReferenced — utilizable desde el código del juego sin una referencia de asmdef.

Tipos generados (patrón — por proyecto, no es API distribuida)

Para cada pestaña Foo, el codegen emite en tu generatedNamespace:

public sealed partial class FooDefinition    // one strongly-typed field per column; @desc → doc/tooltip
public sealed partial class FooDatabase : DefinitionDatabase
{
    // TabName, Count, SchemaFingerprint, Records, RecordsUntyped override,
    // lazy _byId/_byIntId lookups, InvalidateIndex override
}

Carga con SheetForgeDatabases.LoadAsync<FooDatabase>("Foo").

Ambas clases se emiten como partial, así que puedes añadir miembros derivados — una propiedad calculada, una implementación de interfaz, un operador — en tu propio archivo junto al generado, y una reimportación no lo sobrescribirá. Un límite: no añadas campos serializados en tu parte. El ScriptableObject horneado (bake) se reconstruye desde la hoja en cada importación, así que cualquier cosa que solo serialice tu parte vuelve a su valor predeterminado — si un valor pertenece a los datos, pertenece a una columna. (La palabra clave partial no afecta a SchemaFingerprint, que se calcula solo a partir del esquema, así que hacer las clases partial no invalidó ni un solo bake existente.)

Otros ensamblados

• SheetForge.Setup — el bootstrap sin dependencias para la ausencia de Addressables. Sin API pública (todo internal; existe para mostrar una ventana de orientación).

• SheetForge.PluginDemo (un asmdef combinado + un asmdef Demo.Editor; el namespace del contenido sigue siendo SheetForge.Skills) — el paquete de ejemplo de referencia, no es API del producto. Contiene:

  • SkillsPlugin (siete interfaces de plugin — base, validador, arista, plantilla, grafo, registro de código, tema);
  • Modifier + ModifierCellParser (tipo de celda personalizado), ModifierStatEdgeContributor (contribuyente de aristas);
  • ExamplePipelineAugmenter / ExampleReactiveAugmenter (overrides de lienzo), ExampleCodeAtoms (el registro de código _Refs);
  • ExampleStudioUi (acciones declarativas, panel, insignia de columna y pista de editor de celda), ExampleImportObserver (observador de canalización);
  • ExampleStageStripWidget / ExampleInspectorAction / ExampleStudioPanel (puntos de extensión del Editor de Data Studio, pintados desde la paleta pública), ExampleLocStrings (registra esas etiquetas en dos idiomas — en el ensamblado principal, así que el navegador también las muestra);
  • una declaración SheetForgePluginCompat a nivel de ensamblado;
  • SkillRunner (consumo en runtime), tipos Example* generados en el espacio de nombres predeterminado SheetForge.Generated (el aislamiento es mediante el prefijo Example*, no un espacio de nombres separado).

  El ejemplo sin plugin SheetForge.CoreDemo se distribuye con cero asmdefs (compila dentro de Assembly-CSharp).

Páginas relacionadas

• Creación de plugins — los contratos en uso, con ejemplos completos
• Núcleo de creación — los tipos del motor en contexto
• Capacidades y límites — los límites de comportamiento de estas API