FAQ & Fehlerbehebung

Symptomorientierte Antworten. Jeder Importfehler trägt außerdem seinen eigenen Wo/Was/Warum/Wie-Satz im Konsolenbericht — beginnen Sie dort.

Einrichtung & erster Durchlauf

„Ich habe das Asset ohne Addressables importiert — kompiliert es? Warum ist der Import gesperrt?"

Das Asset kompiliert auch ohne Addressables (der Addressables-nutzende Code ist hinter einem Versions-Define SHEETFORGE_ADDRESSABLES abgesichert). Adressbasiertes Laden und der Typ AssetRef@Group benötigen jedoch com.unity.addressables, sodass die gesamte Pipeline (Import · Export · Push · Rückschreiben) gesperrt bleibt, bis Sie es installieren — jeder Einstiegspunkt zeigt einen Installationshinweis und bricht ab (kein Teillauf).

Installieren Sie com.unity.addressables über den Package Manager. Die Addressables-Zeile im Fenster „Erste Schritte" hat eine Schaltfläche Open Package Manager, und — weil der Editor auch ohne das Paket kompiliert — läuft dieses Fenster normal, statt vom Safe Mode blockiert zu werden.

Bestehen nach der Installation weiterhin Kompilierungsfehler, stammen sie aus anderem Code im Projekt — SheetForge kompiliert sowohl mit als auch ohne das Paket.

„Ich habe auf eine neuere Version aktualisiert, und jetzt kompiliert das Projekt nicht mehr."

Ein .unitypackage-Import fügt Dateien hinzu und aktualisiert sie, löscht aber niemals welche, daher kann eine Datei, die dieses Produkt in einer späteren Version ausrangiert hat, zurückbleiben und eine API referenzieren, die es nicht mehr gibt.

Beim Laden des Editors erkennt das abhängigkeitsfreie Bootstrap-Fenster SheetForge.Setup diese bekannten ausrangierten Pfade und bietet an, sie zu löschen — dabei werden zunächst alle Pfade aufgelistet, bevor irgendetwas angefasst wird; bestätigen Sie den Dialog, und die Kompilierung erholt sich. Weil es in seiner eigenen Assembly lebt, funktioniert es weiter, während die Hauptassemblies fehlschlagen. Um die Abfrage ganz zu überspringen, löschen Sie den Ordner Assets/SheetForge, bevor Sie das neue Paket importieren.

Was dies nicht abdeckt, ist Ihr eigener Code, der gegen einen inzwischen ausrangierten Vertrag geschrieben wurde — portieren Sie ihn von Hand anhand der Upgrade notes-Tabelle in der CHANGELOG.md im Quell-Repository (das Release-Paket liefert diese Datei nicht mit) — Erste Schritte fasst zusammen, was dort steht.

„Create Sheet zeigt nur die eingebauten Vorlagen — wo ist die Skills-Demo-Vorlage? / Wie füge ich meine eigene hinzu?"

Die eingebaute Create Sheet-Liste liefert zwei Vorlagen — Item-Beispiel (nur Kerntypen) und Enum definitions, die eine @enum-Tabelle anlegt — plus „von Grund auf".

Domänen-Vorlagen, die ein Plugin benötigen (wie die Skills-Demo), werden von diesem Plugin selbst registriert, sodass sie nur erscheinen, wenn das Plugin vorhanden ist. Importieren Sie das Paket Plugin Demo, und die Vorlage Skill demo erscheint. Um Ihre eigene auszuliefern, implementieren Sie ISheetForgeTemplatePlugin — siehe Plugin-Erstellung §4.6.

„Wo fange ich an? / Beim Öffnen des Editors öffnet sich immer wieder ein Fenster."

Das ist das Fenster „Erste Schritte". Es öffnet sich automatisch beim ersten Laden des Editors und ist der empfohlene Einstiegspunkt — Addressables-Status, Wahl des aktiven Einstellungs-Assets, Import eines Beispiels und Ihr erster Import, alles an einem Ort.

Schalten Sie das automatische Öffnen mit dem Schalter „Dieses Fenster beim Start des Editors anzeigen" unten aus, und öffnen Sie es jederzeit erneut über Tools ▸ SheetForge ▸ Erste Schritte.

„Ich habe ein Demo-Paket importiert, aber nichts passiert — es gibt kein Einstellungs-Asset und keine Addressables-Gruppe."

Jedes Demo-Paket bringt ein vorkonfiguriertes Einstellungs-Asset mit, und der Import des Pakets aktiviert es automatisch (nur, wenn Sie noch kein eigenes aktives Asset haben — haben Sie bereits eines, öffnet sich stattdessen das Fenster „Erste Schritte" mit dem Vorschlag zu wechseln, statt Ihre Einrichtung stillschweigend zu ändern).

Klicken Sie dann einmal auf ↓ Pull from source unter Tools ▸ SheetForge ▸ Data Studio: Das erzeugt automatisch die Addressables-Gruppe und die Adressen pro Tab. Ablauf: Paket importieren → (Einstellungen automatisch aktiviert) → Import ausführen → Play.

„Die Demo-Szene zeigt nur eine Textmeldung statt der Demo."

Die Demo lädt über die Addressables-Adresse, und diese Adressen existieren erst nach einem Import auf Ihrer Maschine (das Gruppen-Asset ist ein nicht committeter, selbstheilender Cache). Importieren Sie das Demo-Paket (seine Einstellungen werden automatisch aktiviert) und führen Sie einmal Import ausführen aus — siehe Erste Schritte §5.

(Die committeten Typen der Demos verwenden den Standard-Namespace SheetForge.Generated, sodass keine generatedNamespace-Einstellung nötig ist — ein erneuter Import regeneriert sie an Ort und Stelle.)

„Der erste Import der Plugin-Demo schlägt mit `UnknownAssetGroup 'Scripts'` fehl."

Die Plugin-Demo hat eine script-Spalte vom Typ List<AssetRef@Scripts>, die eine Addressables-Gruppe namens Scripts benötigt. Addressables-Gruppen sind maschinenspezifisch (nicht committet), sodass eine frisch importierte Demo sie noch nicht hat.

Die Demo konfiguriert diese Gruppe beim Import automatisch (PluginDemoAddressableSetup, ausgelöst bei Domain-Reload und beim Öffnen der Demo-Szene), sodass ein normaler Import einfach funktioniert. Sehen Sie den Fehler weiterhin, öffnen Sie die Demo-Szene erneut (Tools ▸ SheetForge ▸ Open Plugin Demo Scene), um das Setup auszulösen, und importieren Sie dann erneut.

Dies gilt nur für die Plugin-Demo — Ihre eigenen AssetRef@…-Gruppen registrieren Sie selbst.

„Welches Einstellungs-Asset wird verwendet, wenn ich mehrere habe?"

Das aktive. Menüs, das Data Studio und Importe verwenden alle das aktive Einstellungs-Asset. Wählen Sie es im Fenster „Erste Schritte" oder über das Dropdown in der Symbolleiste des Data Studio (nur sichtbar, wenn mehrere existieren).

Bei einem einzigen Einstellungs-Asset wählt der erste Import es automatisch aus. Die Wahl wird pro Projekt und pro Benutzer gespeichert (ein EditorPrefs-Zeiger – keine VCS-Änderungen) und heilt sich selbst, falls das aktive Asset gelöscht wird.

„Ich habe bereits einen Ordner mit Tabellen — wie richte ich SheetForge am schnellsten darauf aus?"

Öffnen Sie das Data Studio und ziehen Sie den Ordner darauf, oder eine einzelne .tsv-/.csv-/.xlsx-Datei.

Es bietet an, ein Import-Einstellungs-Asset zu erstellen, das aus diesem Ordner liest, und es zu aktivieren, ohne manuelle Feldeingabe. Haben Sie bereits aktive Einstellungen, weist der Dialog darauf hin und bietet den Wechsel an.

„Wie prüfe ich, ob mein Projekt korrekt eingerichtet ist / warum der Import nicht läuft?"

Wählen Sie ⋯ ▸ Zustandsprüfung in der Symbolleiste des Data Studio. Sie meldet ✓/✗ mit einem Lösungsvorschlag für:

die aktiven Einstellungen;
die Erreichbarkeit der Quelle — ein vorhandener lokaler Ordner, oder eine Google-ID plus Service-Account-Schlüsselpfad, mit keinem Netzwerkaufruf;
die Import-Baseline;
die Aktualität von generiertem Code, Bake und Addressables.

Die Ergebnisse erscheinen in der Konsole plus einem Zusammenfassungsdialog.

„Die Menüs und die UI haben sich in einer Sprache geöffnet, die ich nicht gewählt habe."

Beim ersten Öffnen eines Projekts setzt SheetForge seine UI-Sprache anhand der Systemsprache Ihres Editors (neun Sprachen werden zugeordnet, sonst Englisch). Eine von Ihnen selbst gewählte Sprache wird nie überschrieben. Ändern Sie sie jederzeit unter Preferences ▸ SheetForge — siehe Lokalisierung.

(Der Sprachwechsel löst eine kurze Neukompilierung aus, da die Menübeschriftungen neu erzeugt werden.)

„Ich habe das Repo geklont, und meine Szenenreferenzen auf per Bake erzeugte SOs sind Missing."

Erwartet: Per Bake erzeugte SOs sind maschinenspezifische Caches mit maschinenspezifischen GUIDs. Referenzieren Sie sie niemals direkt aus Szenen — laden Sie über die Adresse (SheetForgeDatabases.LoadAsync("Tab")). Führen Sie einmal einen Import aus, um Ihren lokalen Cache neu aufzubauen.

„Mein Build wurde mit einer SheetForge-Meldung abgebrochen."

Das ist der Pre-Build-Aktualitäts-Hook, der Sie davor schützt, einen leeren/veralteten Cache auszuliefern. Tun Sie, was der Hinweissatz sagt — klicken Sie auf ↓ Pull from source unter Tools ▸ SheetForge ▸ Data Studio — und bauen Sie erneut.

Import & Validierung

„Der Import lief, fand Fehler und erzeugte überhaupt nichts."

By design: ein Fehler ⇒ keine Ausgabe (kein Teil-Zusammenbau). Der Bericht listet jedes Problem mit Koordinaten und Lösungsvorschlägen auf — beheben Sie sie in einem Durchgang und importieren Sie erneut. Dadurch geht nie Arbeit verloren; die Tabelle bleibt unangetastet.

„Kann ich direkt zu der Zelle springen, um die es bei einem Fehler geht?"

Ja. Jeder Fehler im menschenlesbaren Konsolenbericht hat einen anklickbaren Link „In Data Studio öffnen"; ein Klick darauf öffnet das Data Studio, wechselt zu diesem Tab und hebt diese Zelle hervor (bei Fehlern auf Datei-/Tab-Ebene wird nur der Tab fokussiert). Die maschinenlesbare Koordinatenzeile bleibt unverändert, sodass CI/Log-Auswertung davon unberührt bleibt.

„Der Import hat Code geschrieben, neu kompiliert … ist er fertig?"

Ja — ist ein Schema neu/geändert, läuft der Import intern zweistufig ab (Codegen → Kompilierung/Reload → Bake), und der Bake setzt sich nach dem Reload automatisch fort. Achten Sie auf den finalen Bericht in der Konsole.

Kompiliert Ihr Spielcode nicht mehr (z. B. nach einer Spaltenumbenennung), bricht die Kette sicher ab mit einem umsetzbaren Hinweissatz; beheben Sie Ihren Code und importieren Sie erneut.

„Fehler wegen leerer Zelle, aber ich wollte die Zelle optional machen."

Unmarkierte Typen sind erforderlich (Schutz vor stiller Kontamination). Um eine Zelle optional zu machen:

deklarieren Sie float? — Typ-Standardwert;
deklarieren Sie int=1 — expliziter Standardwert;
oder verwenden Sie List<T>, wo eine leere Zelle eine leere Liste ist.

Siehe Tabellensyntax.

„`1.5` importiert einwandfrei, aber `1,5` erzeugt einen Fehler."

Beabsichtigt: Zahlen sind unabhängig vom Gebietsschema — immer . als Dezimaltrennzeichen. Komma-Dezimalzahlen, NaN und Infinity werden am Eingang blockiert.

„Der Import wurde plötzlich sehr langsam."

Die Importzeit ist linear zur Größe Ihrer Daten (50k Zeilen × 20 Spalten ≈ 628 ms im Editor) und bleibt linear, selbst wenn viele Referenzen gleichzeitig brechen — die Suche nach der nächstliegenden Übereinstimmung ist pro Feld budgetiert und längen-vorgefiltert (≈ 45 ms bei 4,000 defekten Referenzen, Headless).

Dauert ein Import plötzlich deutlich länger als das, sollten Sie sich die Größe der Tabelle ansehen, nicht die Anzahl der Fehler.

„Fehler wegen unbekannter Markierung/unbekanntem Typ mit einem ‚meinten Sie‘-Hinweis."

Tippfehler in @marker-Namen, Typnamen oder enum-Membern sind Fehler mit Vorschlägen für die nächstliegende Übereinstimmung — wenden Sie den Vorschlag an. Ein unbekanntes @ bei einem unregistrierten Typnamen ist ebenfalls ein Fehler (Tippfehler-Sicherheit für Referenzen im Stil von RecordId@Tab).

Google Sheets

„Der Google-Import schlägt mit `PERMISSION_DENIED` (403) fehl."

Die Tabelle ist nicht mit der client_email-Adresse des Service-Accounts geteilt — der Schlüssel allein gewährt nichts. Öffnen Sie den JSON-Schlüssel, kopieren Sie client_email, und teilen Sie die Tabelle damit (Viewer für Import, Editor für Push). Die vollständige Anleitung steht in Google Sheets einrichten.

„Push meldet, dass SheetsApi erforderlich ist."

Sie befinden sich im ExportUrl-Modus, der schreibgeschützt ist (keine Authentifizierung). Jedes Rückschreiben benötigt den SheetsApi-Modus mit einem Service-Account-Schlüssel. Siehe Quellen, Export & Push. Das Anlegen des Service-Accounts und des Schlüssels wird in Google Sheets einrichten behandelt.

„Der ExportUrl-Import schlägt fehl und fordert eine Gid-Map."

Erforderlich: Eine Export-URL ohne Gid liefert stillschweigend nur den ersten Tab zurück, daher wird die Map (Tab-Name → #gid=) erzwungen. Oder wechseln Sie zum SheetsApi-Modus, der keine Map benötigt.

„Push meldet übersprungene Zellen."

Das erneute Abrufen der Live-Daten vor dem Senden hat Konflikte gefunden (ein Teammitglied hat eine Zelle bearbeitet, eine Zeile hat sich verschoben/ist verschwunden, ein doppelter Schlüssel). Übersprungene Zellen sind Schutz, kein Fehlschlag — der Bericht zeigt die Anzahl der angewendeten/übersprungenen Zellen. Importieren Sie zum Abgleich erneut, und pushen Sie dann erneut.

„Ich habe Zeilen lokal gelöscht, aber sie sind nach dem Push immer noch im Google Sheet."

Zeilenlöschungen werden nie gepusht (positionsbasierte Löschungen gegen eine Live-Tabelle sind unsicher) — Sie erhalten stattdessen einen Hinweis. Löschen Sie die Zeilen in der Tabelle und importieren Sie dann erneut.

Authoring

„Ctrl+Z macht meine vorgemerkte Änderung nicht rückgängig."

Zwei Grenzen:

Ein fokussiertes Textfeld verbraucht Ctrl+Z zuerst — klicken Sie woanders hin, dann Rückgängig;
und nachdem „Ins Sheet übernehmen" erfolgreich war, wird der Staging-Verlauf gelöscht, sodass Rückgängig nur innerhalb der Sitzung vor dem Übernehmen funktioniert.

Nach dem Übernehmen bearbeiten Sie die Tabelle (sie ist kanonisch).

„Einige meiner vorgemerkten Bearbeitungen zeigen ein ‚isoliert‘-Badge und wurden nicht übernommen."

Die Tabelle hat sich extern zwischen Vormerken und Übernehmen so geändert, dass die logische Adresse dieser Bearbeitungen gebrochen ist (Schlüssel der Zeile von außen umbenannt / Zeile gelöscht / Schlüsselkonflikt). Sie werden ausgeschlossen — nicht stillschweigend verloren, blockieren nicht den Rest. Verwerfen Sie sie einzeln und merken Sie sie gegen die neue Baseline erneut vor.

„Ich habe eine Spalte/einen Tab umbenannt, und jetzt kompiliert mein Spielcode nicht mehr."

Erwartet und im Bestätigungsdialog offengelegt: Umbenennungen ändern den Namen des generierten Feldes/der Klasse. Aktualisieren Sie Ihren Spielcode; die Importkette schließt dann beim nächsten Durchlauf ab. Die Datenwerte der Spalte blieben vollständig erhalten.

„Kann ich zwei Tab-Namen tauschen (A↔B) oder Tabs zyklisch in einem Batch umbenennen?"

Ja — gegenseitige Tausche und Zyklen (A→B→C→A) werden in einem einzigen Batch vorgemerkt und übernommen (die UI lehnt nur einen echten Konflikt ab: zwei Umbenennungen mit demselben Zielnamen). Referenzen folgen den Daten und werden atomar umgeschrieben.

Ein Grenzfall bleibt bei Google: Zwei getauschte Tabs, die sich gegenseitig referenzieren, werden nicht umgebogen (lokal ist es vollständig korrekt) — leiten Sie die gegenseitige Referenz über einen dritten Tab, oder übernehmen Sie über einen Zwischennamen. Siehe Data Studio und Möglichkeiten & Grenzen.

„Meine Schlüssel-Umbenennung hat eine Referenz nicht aktualisiert, die ich im selben Batch eingegeben habe."

Die Propagierung schreibt nur Baseline-Zellen um — niemals Text, den Sie gerade erst eingegeben haben (kein stilles Umschreiben frischer Eingaben). Die Vorab-Validierung markiert die hängende Referenz; beheben Sie sie selbst.

„Übernehmen wurde wegen eines xlsx-Tabs verweigert."

Zwei bekannte Fälle:

Tabs mit xlsx-Ursprung können nicht umbenannt werden (Schutz der Arbeitsmappe);
eine Propagierung von Schlüssel-Umbenennungen, die einen xlsx-Tab betreffen würde, blockiert den gesamten Batch (kein teilweises Übernehmen).

Bearbeiten Sie die Arbeitsmappe direkt und importieren Sie dann erneut.

„Ich habe ein per Bake erzeugtes SO im Inspector bearbeitet, und der erneute Import hat es gelöscht."

By design — die Tabelle ist die einzige Quelle der Wahrheit, und das SO ist ein Cache. Der Schalter „Testbearbeitung" im Inspector ist ausdrücklich temporär. Nehmen Sie echte Änderungen über die Tabelle oder das Data Studio vor.

Export & Sonstiges

„Export schlägt mit einer Schema-Diskrepanz fehl."

Ihr Bake ist im Verhältnis zu einer Schema-Änderung veraltet (ExportSchemaMismatch — Fingerabdruck-Prüfung). Führen Sie einen Import aus, um Codegen + Bake abzuschließen, dann Export/Push.

„Mein exportiertes Float zeigt `1`, aber die Tabelle hatte `1.0`."

Semantischer Round-Trip: Werte bleiben exakt erhalten; die Notation normalisiert sich zur kürzesten round-trip-fähigen Form. Die Struktur (Markierungen, Spaltenreihenfolge, Kommentare, Ihr Text) bleibt zu 100 % erhalten.

„Der xlsx-Import hat einige Zellen abgelehnt."

Der eingebaute OOXML-Reader ist absichtlich minimal gehalten. Drei Dinge werden nicht unterstützt:

Formelzellen ohne zwischengespeicherte Werte;
Fehlerzellen;
Tabulatorzeichen/Zeilenumbrüche innerhalb einer Zelle.

Materialisieren Sie Formeln zu Werten; verwenden Sie ; für Listen.