Erste Schritte

Voraussetzungen

• Unity 6 (entwickelt und getestet mit 6000.0.79f1, URP-Template).
• Addressables-Paket (com.unity.addressables) — erforderlich. Das adressbasierte Laden ist der Laufzeitpfad, und der Typ AssetRef@Group benötigt Addressables.
  • Ohne das Paket kompiliert das Asset weiterhin, weil der gesamte Addressables-nutzende Code hinter einem Versions-Define SHEETFORGE_ADDRESSABLES liegt.
  • Doch die Pipeline – Import · Export · Push · Authoring-Rückschreiben – bleibt gesperrt. Jeder Einstiegspunkt zeigt einen Installationshinweis, und das Fenster „Erste Schritte" leitet durch die Installation.

Addressables installieren

• Primärer Weg: Beim Import des Assets aus dem Asset Store erscheint der Dialog „Package Manager dependencies" vor der Kompilierung – wählen Sie Install, und Addressables wird gleich mit installiert.
• Sicherheitsnetz: Wenn Sie Skip gedrückt haben (oder manuell importiert haben), bleibt die Pipeline gesperrt, und das Fenster „Erste Schritte" leitet Sie über seine Addressables-Statuszeile zur Installation an. Dieses Fenster läuft auch ohne Addressables, weil der Editor weiterhin kompiliert.
  • Das abhängigkeitsfreie Bootstrap-Fenster SheetForge.Setup erkennt das fehlende Paket zusätzlich beim Laden des Editors und zeigt einmal pro Sitzung einen Hinweis an. Da es keine Abhängigkeiten hat, funktioniert es auch dann noch, wenn andere Kompilierungsfehler die Hauptassemblies blockieren.
• Es gibt keine Ein-Klick-Installation per Programmcode: Die Einreichungsregeln des Asset Store schränken die programmatische Paketinstallation ein, weshalb das Fenster Sie stattdessen anleitet.
• Der Hinweis spiegelt den tatsächlichen Installationsstatus wider. Er erklärt, dass das Produkt zwar kompiliert, seine Funktionen aber bis zur Installation des Pakets gesperrt bleiben, und verweist Sie anschließend auf das Fenster „Erste Schritte". Sie können ihn jederzeit über Tools ▸ SheetForge ▸ Addressables Setup erneut öffnen (dieses Menü bleibt auch erhalten, wenn die Hauptassemblies aus einem anderen Grund nicht kompilieren).

Aktualisieren von einer früheren Version

Ein .unitypackage-Import fügt Dateien hinzu und aktualisiert sie, löscht aber niemals welche. Eine Datei, die eine neuere Version ausrangiert hat, kann daher in Assets/SheetForge zurückbleiben und weiterhin eine API referenzieren, die es nicht mehr gibt. Die Kompilierung bricht, und es sieht so aus, als hätte das Update Ihr Projekt zerstört. Zwei Sicherheitsnetze fangen das ab:

• Automatische Erkennung. Beim Laden des Editors prüft das abhängigkeitsfreie Bootstrap-Fenster SheetForge.Setup, ob Pfade vorhanden sind, die dieses Produkt ausrangiert hat. Falls es welche findet, bietet es an, sie zu löschen – zunächst werden alle Pfade im Dialog aufgelistet, und nichts wird angefasst, bevor Sie zustimmen. Es lebt in seiner eigenen Assembly, genau damit es die Kompilierungsfehler übersteht, die es eigentlich beheben soll.
• Sauberer Neustart. Für ein garantiert sauberes Update löschen Sie den vorhandenen Ordner Assets/SheetForge, importieren das neue Paket und führen dann einmal Import ausführen aus, um das wiederherzustellen, was das Löschen mitgenommen hat. Einstellungs-Assets und per Bake erzeugte SOs (Assets/SheetForgeBaked) liegen außerhalb dieses Ordners und bleiben unberührt, und dasselbe gilt für generierten Code, sobald er sich an seinem Standardort Assets/SheetForgeGenerated befindet. Generiert Ihr Projekt noch in den älteren, produktinternen Ort (Assets/SheetForge/Runtime/Generated), entfernt das Löschen des Ordners diesen Code, und der erneute Import schreibt ihn stattdessen nach Assets/SheetForgeGenerated. Das ist der unterstützte Weg, ein bestehendes Projekt an den neuen Ort zu verschieben. Was kein erneuter Import wiederherstellen kann, ist alles, was Sie selbst in Assets/SheetForge abgelegt haben – ein dort gespeichertes Einstellungs-Asset, eigene Plugin-Skripte, Tabellendateien – verschieben Sie das also vorher heraus.

Eine Grenze sei klar benannt: Die automatische Bereinigung löscht nur SheetForges eigene ausrangierte Dateien, niemals Ihre. Implementiert Ihr eigener Plugin-Code einen Vertrag, der inzwischen ausrangiert wurde, muss dieser von Hand portiert werden. Kurz gesagt:

• Ein Graph-Builder pro Tab (IGraphShapeBuilder / GraphSpecBuilder) wird zum Augmenter der Record-Canvas (IRecordCanvasAugmenter / CanvasAugmentBuilder), der die von der Canvas bereits aufgebaute Closure erweitert, statt das gesamte Bild selbst zu erzeugen;
• GraphMode entfällt, da die Richtung jetzt allein von der Canvas gesteuert wird;
• StudioGraphContext.ShapeId / ModeId kompilieren zwar noch, geben aber jeweils eine Konstante zurück, sodass jeder AppliesTo-Vergleich damit einfach gelöscht werden sollte;
• IAuthorableGraphShape.CreatableTabs bleibt unverändert.

Die vollständige Tabelle, was aus jedem ausrangierten Vertrag geworden ist, steht im Abschnitt Upgrade notes der CHANGELOG.md im Quell-Repository (das Release-Paket liefert sie nicht mit). Ausrangierte Member, die weiterhin kompilieren, sind mit [Obsolete] markiert statt entfernt, sodass ein Update sie als Warnungen sichtbar macht, statt den Build zu brechen.

Das Fenster „Erste Schritte" (hier starten)

Sobald Addressables installiert ist, öffnet sich automatisch ein Fenster „Erste Schritte" – einmal pro Editor-Sitzung, also bei jedem Editor-Start, aber nicht erneut nach einem Domain-Reload. Das gilt so lange, wie der Schalter „Dieses Fenster beim Start des Editors anzeigen" aktiv ist, was er standardmäßig ist.

Es ist der empfohlene Einstiegspunkt. Sie können es jederzeit über Tools ▸ SheetForge ▸ Erste Schritte erneut öffnen und das automatische Anzeigen mit demselben Schalter unten ausschalten (die Wahl wird pro Projekt und pro Benutzer gespeichert).

Es bündelt den gesamten Erst-Setup-Ablauf an einem Ort:

1. Status-Dashboard – eine dreizeilige Ampel: Addressables installiert, ein aktives Einstellungs-Asset und erster Import abgeschlossen. Jede Zeile zeigt ✓ oder ✗, und alles, was noch Aufmerksamkeit braucht, hat direkt daneben eine Aktionsschaltfläche (Neues Einstellungs-Asset oder Import ausführen).
2. Import-Einstellungen – listet jedes SheetForgeSettings-Asset mit einem Radiobutton auf, um das aktive auszuwählen, dazu eine Schaltfläche „Neues Einstellungs-Asset" und eine Schaltfläche „Anzeigen", um jedes Asset zu lokalisieren.
3. Beispiele – ein Klick importiert das Plugin-Demo-Paket oder das Core-Demo-Paket.
4. Von einer Vorlage starten – wählen Sie eine der beiden eingebauten Vorlagen, wählen Sie „von Grund auf", um Felder selbst zu definieren, oder verwenden Sie eine per Plugin registrierte Vorlage. „Verwenden" öffnet das Erstellen-Panel des Data Studio, bereits damit vorausgefüllt. Dafür ist ein aktives Einstellungs-Asset mit einer beschreibbaren Quelle nötig; falls Sie noch keins haben, wird diese Voraussetzung angezeigt.
   • Die eingebauten Vorlagen sind Item-Beispiel, das ausschließlich Kerntypen verwendet, und Enum definitions, das eine @enum-Tabelle anlegt.
   • Die Skill-Demo-Tabs erscheinen hier nur, wenn ein Vorlagen-Plugin wie das Plugin-Demo vorhanden ist.
5. Ausführen – Import ausführen (verwendet die aktiven Einstellungen) und Data Studio öffnen.
6. Vollständige Anleitung öffnen – ein Link zu dieser Dokumentationsseite.

Die folgenden Abschnitte erklären jeden Schritt im Detail; Sie können alles aus dem Fenster heraus erledigen oder wie beschrieben über die Menüs und das Project-Fenster.

Noch schneller – Drag & Drop. Wenn Sie bereits einen Ordner mit Tabellendateien haben, öffnen Sie das Data Studio und ziehen Sie diesen Ordner darauf – oder eine einzelne .tsv-/.csv-/.xlsx-Datei. Es bietet an, ein Einstellungs-Asset zu erstellen, das aus diesem Ordner liest, und es zu aktivieren, ganz ohne manuelle Einrichtung.

Ohne aktive Einstellungen geöffnet, zeigt das Studio statt einer leeren Tabelle ein Panel „Erste Schritte" mit denselben Schaltflächen zum Erstellen / Demo-Importieren / Erste-Schritte-Öffnen.

Zustandsprüfung. Öffnen Sie jederzeit das Data Studio und wählen Sie in der Symbolleiste ⋯ ▸ Zustandsprüfung für eine schnelle Diagnose ohne Netzwerkzugriff. Sie meldet ✓/✗ – jeweils mit einem Lösungsvorschlag – für:

• die aktiven Einstellungen;
• ob die Quelle erreichbar ist (ein vorhandener lokaler Ordner oder eine Google-ID plus Schlüsselpfad);
• ob eine Import-Baseline existiert;
• ob generierter Code, gebackene SOs und Addressables aktuell sind.

UI-Sprache. Beim ersten Öffnen eines Projekts setzt SheetForge seine UI-Sprache anhand der Systemsprache Ihres Editors (neun Sprachen werden direkt zugeordnet; alles andere bleibt Englisch). Eine bereits von Ihnen gewählte Sprache wird dabei nie überschrieben; ändern Sie sie jederzeit unter Preferences ▸ SheetForge (siehe Lokalisierung).

1. Ein Import-Einstellungs-Asset wählen

Erstellen Sie eines über die Schaltfläche Neues Einstellungs-Asset im Fenster „Erste Schritte", oder per Rechtsklick im Project-Fenster → Create ▸ SheetForge ▸ Import Settings (die Menübeschriftungen folgen Ihrer Spracheinstellung – siehe Lokalisierung).

Sie können mehrere Einstellungs-Assets vorhalten (zum Beispiel eines pro Datenquelle) und festlegen, welches aktiv ist. Menüs, das Data Studio und Importe verwenden alle das aktive Asset. Die Wahl wird pro Projekt und pro Benutzer gespeichert – ein EditorPrefs-Zeiger, also keine VCS-Änderungen und unabhängig je Teammitglied –, und falls das aktive Asset gelöscht wird, heilt der Zeiger sich selbst.

Bei einem einzigen Einstellungs-Asset wählt Ihr erster Import es automatisch aus; keine explizite Wahl nötig. Existieren mehrere, wählen Sie das aktive im Fenster „Erste Schritte" oder über das Dropdown in der Symbolleiste des Data Studio.

Konfigurieren Sie das SheetForgeSettings-Asset:

Der Settings-Inspector zeigt nur die Felder, die für den aktuellen Source-Modus relevant sind – der Local-Modus blendet die Google-Eingaben aus; gidMap erscheint nur im Google-ExportUrl-Modus.

2. Sicherheit des Service-Account-Schlüssels (Google-Quelle)

Nutzen Sie eine LocalFile-Quelle? Dann können Sie diesen Abschnitt überspringen.

Die Verwendung von Google Sheets im SheetsApi-Modus erfordert einen Service-Account-JSON-Schlüssel. Wenn Sie noch nie einen erstellt haben, führt Sie Google Sheets einrichten Schritt für Schritt durch den gesamten Vorgang. Bewahren Sie diesen Schlüssel außerhalb von Assets/ und außerhalb Ihres Repositorys auf – committen Sie ihn niemals.

• Empfohlen: Setzen Sie die Umgebungsvariable SHEETFORGE_SHEETS_KEY auf den absoluten Pfad Ihrer Schlüsseldatei. Sie hat Vorrang vor dem Schlüsselpfad-Feld des Settings-Assets, sodass jeder Entwickler seinen lokalen Schlüssel einbringen kann, ohne einen Pfad im Repository zu hinterlassen.
• Wenn Sie doch einen Pfad im Settings-Feld angeben müssen, verweisen Sie ihn auf einen Ort außerhalb des Repositorys (z. B. C:/keys/service-account.json). Eine Schlüsseldatei unter Assets/ würde in Builds und Commits durchsickern.

3. Ihren ersten Import ausführen

Tools ▸ SheetForge ▸ Data Studio, dann in der Symbolleiste auf ↓ Pull from source klicken.

• Die Pipeline durchläuft Abrufen → Validieren → (bei Erfolg) Codegenerierung → Bake. Diagnosen werden als menschenfreundlicher Bericht in Ihrer Sprache in der Konsole ausgegeben.
• Der erste Import läuft automatisch in zwei internen Stufen ab. Ist ein Schema neu oder geändert, schreibt der Import den generierten Code, was einen Kompilierungs-/Domain-Reload auslöst. Er setzt den Bake danach automatisch fort. Eine einzige Benutzeraktion; kein manuelles erneutes Auslösen. Schlägt die Kompilierung fehl, bricht die automatische Fortsetzung sicher ab (maximal 3 Versuche) und hinterlässt einen umsetzbaren Hinweissatz in der Konsole.
• Die Validierung sammelt zur Importzeit alle Diagnosen (sie stoppt nie beim ersten Fehler). Existiert auch nur ein einziger Fehler, wird keine Ausgabe erzeugt (kein Teil-Zusammenbau).
• Der Import registriert das Database-SO jedes Tabs automatisch in der Addressables-Gruppe SheetForge unter der Adresse "SheetForge/{tab}" – Ihr Spiel lädt über diese stabile Adresse (siehe Kernkonzepte).

4. Daten in Ihrem Spiel laden

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

Die Assembly SheetForge.Runtime ist autoReferenced, sodass Spielcode sie ohne asmdef-Referenz verwenden kann.

Referenzieren Sie ein per Bake erzeugtes SO niemals direkt aus einer Szene. Per Bake erzeugte SOs sind nicht committete, maschinenspezifische Caches – ihre GUIDs unterscheiden sich zwischen Maschinen und erneuten Bakes, sodass eine direkte Szenenreferenz auf der Maschine eines Teammitglieds als „Missing" erscheint. Das adressbasierte Laden fängt dies konstruktionsbedingt ab.

5. Die Demo-Szenen ausprobieren

Zwei Beispiele werden als selektiv importierbare Pakete ausgeliefert. Das Plugin-Beispiel SheetForge.PluginDemo (benutzerdefinierte Typen, Enums, Validatoren, Kanten) und ein plugin-freies SheetForge.CoreDemo (nur integrierte Core-Typen) enthalten jeweils eine „Öffnen-und-Play"-Demo-Szene.

Demo-Importe leben an einem Ort – im Abschnitt Beispiele des Fensters „Erste Schritte" – daher gibt es dafür keinen eigenen Menüpunkt.

• Plugin-Demo: Klicken Sie in „Erste Schritte" auf Plugin Demo importieren, oder doppelklicken Sie auf Assets/SheetForge/Examples/SheetForgePluginDemo.unitypackage. Beides stellt es unter Assets/SheetForge.PluginDemo/… wieder her. Szene: Demo/PluginDemo.unity (Menü Tools ▸ SheetForge ▸ Open Plugin Demo Scene, vom Beispiel selbst hinzugefügt). Sie lädt die Beispieldatenbanken über die Adresse und zeigt einen Skill, der aus Tabellendaten zusammengesetzt ist (Fireball-Gesamtschaden = Damage 10 + DamageOverTime 3×3 = 19).
• Reine Core-Demo: Klicken Sie in „Erste Schritte" auf Core Demo importieren, oder doppelklicken Sie auf Assets/SheetForge/Examples/SheetForgeCoreDemo.unitypackage. Das stellt es unter Assets/SheetForge.CoreDemo/… wieder her. Szene: Demo/CoreDemo.unity (Menü Tools ▸ SheetForge ▸ Open Core Demo Scene). Sie zeigt Loadouts, die aus Item-Referenzen zusammengesetzt sind und ausschließlich integrierte Core-Typen verwenden. Die Demo enthält außerdem ein Lokalisierungs-Sheet (ExampleStrings), dessen Schlüssel die Items über LocRef-Zellen referenzieren — siehe Lokalisierungs-Sheets.

(Die Leaf-Beschriftungen dieser beiden Szenen-Menüs sind Englisch, da sie außerhalb der zentralen lokalisierten Menü-Pipeline liegen.)

Jedes Demo-Paket bringt ein vorkonfiguriertes Einstellungs-Asset mit. Beim Importieren eines Demo-Pakets aktiviert SheetForge dieses mitgelieferte Einstellungs-Asset automatisch, sofern 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 Wahl stillschweigend zu überschreiben. Der Demo-Ablauf lautet somit schlicht: Paket importieren → (Einstellungen automatisch aktiviert) → Import ausführen → Play – ohne manuelles Anlegen von Einstellungen.

Eine Demo funktioniert erst, nachdem Sie einmal einen Import auf Ihrer Maschine ausgeführt haben – die Addressables-Adressen, die sie lädt, existieren erst, nachdem der Import einmal gelaufen ist (das Addressables-Gruppen-Asset ist ein nicht committeter, selbstheilender Cache). Davor zeigt die Demo-Szene eine Hinweismeldung an, statt fehlzuschlagen.

Um eine Demo abzuschließen (nach dem Import des oben genannten Beispielpakets):

1. Stellen Sie sicher, dass das mitgelieferte Einstellungs-Asset der Demo aktiv ist (das Fenster „Erste Schritte" zeigt es an, oder der Import hat es automatisch aktiviert). Es verwendet Source = LocalFile, lokaler Ordner = der DemoSheets-Ordner des Beispiels, und den Standard-Namespace SheetForge.Generated, sodass ein erneuter Import die committeten Typen an Ort und Stelle regeneriert.
2. Für die Skript-Referenz der Plugin-Demo ist keine Aktion nötig. Der Tab ExampleEffects enthält ein Beispiel für AssetRef@Scripts. Das Beispiel registriert DemoScripts/special_effect.lua.txt von selbst und idempotent unter der Adresse special_effect in einer Addressables-Gruppe Scripts, sodass der erste Import die Referenzvalidierung besteht. Nur wenn eine Warnung protokolliert wird, dass dies nicht möglich war (etwa weil ein Asset fehlt), müssen Sie diesen Eintrag von Hand hinzufügen – oder die Zeile löschen, wenn Sie das Addressables-Beispiel nicht möchten.
3. Klicken Sie einmal auf ↓ Pull from source unter Tools ▸ SheetForge ▸ Data Studio (oder auf die Schaltfläche Import ausführen im Fenster „Erste Schritte"), öffnen Sie dann die Demo-Szene und drücken Sie Play.

6. Zusammenfassung des Team-Workflows

• Per Bake erzeugte SOs (Assets/SheetForgeBaked) sind ein maschinenspezifischer Cache. Nehmen Sie sie ins Gitignore auf; nach dem Klonen führt jedes Teammitglied einmal Import ausführen aus.
• Generierter Code (Assets/SheetForgeGenerated) ist der eigene Quellcode Ihres Projekts, und es wird empfohlen, ihn zu committen. Ein frischer Klon kompiliert dann, bevor jemand einen Import ausgeführt hat, und Schemaänderungen werden im Review sichtbar. Es handelt sich um deterministische Ausgabe, sodass der Import eines Teammitglieds dieselben Bytes erzeugt und keinen unnötigen Diff verursacht. Ihn stattdessen ins Gitignore aufzunehmen, funktioniert ebenso; das Import ausführen nach dem Klonen stellt die Kompilierbarkeit dann wieder her.
• Ein Pre-Build-Aktualitäts-Hook prüft für jeden committeten generierten Database-Typ, dass (i) das per Bake erzeugte SO existiert, (ii) der Schema-Fingerabdruck mit der Baseline übereinstimmt und (iii) die Addressables-Registrierung existiert. Schlägt etwas fehl, wird der Build mit einem umsetzbaren Hinweissatz abgebrochen, sodass eine Klon-/CI-Maschine niemals stillschweigend einen leeren Cache ausliefern kann.

Verwandte Seiten

• Kernkonzepte – warum die Tabelle kanonisch ist und welche Pipeline-Stufen es gibt
• Tabellensyntax – wie Sie Ihre erste Tabelle schreiben
• Quellen, Export & Push – Details zur Google-Einrichtung
• FAQ & Fehlerbehebung – Probleme beim ersten Ausführen