# NeoLitematica

Client-seitiger Schematic-Viewer und Bauassistent für **Minecraft 1.21.1 / NeoForge 21.1.265**. Er liest das
originale **`.litematic`-Format** von Litematica, zeigt Blueprints als transparente Vorschau in der Welt und
vergleicht sie mit dem tatsächlich Gebauten. Er ist eine eigenständige Neuimplementierung: Fabric, Malilib und
Code von Litematica werden nicht verwendet.

## Installation

1. `build/libs/neolitematica-1.21.1-1.0.0.jar` in den `mods`-Ordner der ATM10-Instanz kopieren.
2. Minecraft starten. **Auf dem Server muss nichts installiert werden**, auch nicht auf Multiplayer-Servern.

Schematics liegen in `.minecraft/schematics/` (bzw. `<Instanz>/schematics/`). Das ist derselbe Ordner wie bei
Litematica, vorhandene Sammlungen funktionieren also direkt.

## Schnellstart

1. In einer Welt **Alt+L** drücken (oder **Alt+M** → „Schematic laden…").
2. **Importieren…** wählen (Windows-Dateidialog) oder `.litematic`-Dateien ins Minecraft-Fenster ziehen.
3. Schematic auswählen → **Hier platzieren** (oder Doppelklick). Die minimale Ecke liegt an deiner Position.
4. Verschieben: **Pfeiltasten** (relativ zur Blickrichtung), **Bild↑/Bild↓** für hoch/runter,
   mit **Strg** in 10er-Schritten. Exakte Koordinaten: **Alt+E** (Placement-Editor).
5. Drehen mit **Alt+R**, Spiegeln im Placement-Editor.
6. Bauen: Im Standardmodus „Nur fehlende" verschwinden korrekt gesetzte Blöcke sofort aus der Vorschau.
   Falsche Blöcke werden rot markiert, falsche Ausrichtung/Zustand orange.

## Tastenbelegung

Alle Tasten lassen sich unter Optionen → Steuerung → „NeoLitematica" ändern (auch mit dem ATM10-Mod *Controlling*).
Die Standardbelegung nutzt Alt-Kombinationen, weil `M` in ATM10 bereits von FTB Chunks belegt ist.

| Taste | Funktion |
|---|---|
| Alt+M | Hauptmenü (Placements, Rendering-Einstellungen) |
| Alt+L | Schematic-Übersicht (Import, Laden, Umbenennen, Löschen) |
| Alt+E | Ausgewähltes Placement bearbeiten |
| Pfeiltasten | Placement vor/zurück/links/rechts (relativ zur Blickrichtung), Strg = ×10 |
| Bild↑ / Bild↓ | Placement hoch / runter |
| Alt+R | Im Uhrzeigersinn drehen |
| Alt+P | Placement an Spielerposition setzen |
| Alt+N | Nächstes Placement auswählen |
| Alt+H | Alle Schematics ein-/ausblenden |
| Alt+V | Rendering-Modus wechseln |
| *(nicht belegt)* | Gegen Uhrzeigersinn drehen, Spiegeln X/Y/Z, Placement ein-/ausblenden, Position zurücksetzen |

## Oberfläche

- **Hauptmenü (Alt+M):** Liste aller Placements der aktuellen Dimension mit Position, Größe und Drehung.
  Bearbeiten, ein-/ausblenden, an eigene Position setzen, entfernen. Dazu Rendering an/aus, Modus,
  Deckkraft, Render-Distanz sowie Links zu den Einstellungen und zur Steuerung.
- **Schematic-Übersicht (Alt+L):** alle `.litematic`-Dateien (auch in Unterordnern) mit Name, Autor,
  Abmessungen, Blockanzahl, Volumen, Regionen, Version und Dateigröße. Import per Dialog oder Drag & Drop,
  Ordner öffnen, umbenennen, löschen.
- **Placement-Editor (Alt+E):** X/Y/Z-Felder mit −10/−1/+1/+10 (Umschalt = ×10), „Zu meiner Position",
  „Position zurücksetzen", „Als Ursprung merken", Drehung 0/90/180/270°, Spiegeln X/Z/Y, Sichtbarkeit,
  Blockvergleich. Die Welt wird dabei weder pausiert noch weichgezeichnet, Änderungen sind live sichtbar.
- **HUD (oben links):** ausgewähltes Placement, Position, Größe, Drehung/Spiegelung, fehlende/falsche/korrekte Blöcke.
- **Einstellungen:** Mods → NeoLitematica → Konfiguration, oder Hauptmenü → „Einstellungen…".
  Gespeichert in `config/neolitematica-client.toml`.

## Rendering-Modi und Farben

| Modus | Verhalten |
|---|---|
| Alle Blöcke | Alle Blöcke als Geisterblöcke, ohne Vergleich mit der Welt |
| Nur fehlende *(Standard)* | Geisterblöcke nur für fehlende Blöcke; korrekte Blöcke werden ausgeblendet |
| Prüfen | Wie „Nur fehlende", dazu korrekt = grün, überzählig = magenta |

Rot = falscher Block, orange = richtiger Block mit falschem Zustand (z. B. Treppenrichtung), violett = Block-Typ
nicht installiert. Ersetzbare Blöcke wie Gras, Schneeschicht oder Wasser zählen als „fehlend", nicht als „falsch".

## Placements und Speicherung

- Beliebig viele Placements gleichzeitig, jedes unabhängig positionierbar und ausblendbar.
- Gespeichert pro Welt bzw. Server in `config/neolitematica/placements/<welt>.json`, inklusive Dimension,
  Position, ursprünglicher Position, Drehung, Spiegelung und Sichtbarkeit. Nach einem Neustart wird alles
  wiederhergestellt.
- Die `.litematic`-Datei wird direkt verwendet, es gibt keine Konvertierung.

## Technische Umsetzung

```
de.lucas.litematica
├── NeoLitematica          Einstieg, @Mod(dist = CLIENT), Event-Registrierung
├── schematic/             .litematic lesen (NBT, Bit-Array, Paletten, DataFixer), Dateiverwaltung, Cache
├── placement/             Placements, Transformation (Drehung/Spiegelung), Persistenz, Vergleichsstatistik
├── render/                Chunk-basiertes Mesh-Rendering, Blockvergleich, Block-Entity-Geister
├── gui/                   Hauptmenü, Schematic-Übersicht, Placement-Editor, HUD
├── input/                 Tastenbelegung und Hotkey-Verarbeitung
├── config/                NeoForge ModConfigSpec (Client)
├── mixin/                 genau ein Mixin (siehe unten)
└── dev/                   automatischer Ingame-Test, nur mit System-Property aktiv
```

**Dateiformat.** `.litematic` ist gzip-komprimiertes NBT: `Version`, `MinecraftDataVersion`, `Metadata`, und
`Regions` mit je `Position`, `Size` (auch negativ), `BlockStatePalette`, `BlockStates` (dicht gepacktes
`long[]`, Einträge können über Long-Grenzen reichen, `max(2, ceil(log2(Palettengröße)))` Bit) und
`TileEntities`. Index = `(y·sizeZ + z)·sizeX + x`. Dateien älterer Minecraft-Versionen werden über
Minecrafts eigenen DataFixer aktualisiert. Unbekannte Blöcke werden erkannt, gezählt, angezeigt und violett
markiert. Ungültige oder beschädigte Dateien liefern eine verständliche Fehlermeldung, kein Absturz.

**Rendering.** Ein Placement wird in 16×16×16-Welt-Sektionen zerlegt. Jede Sektion wird **einmal auf
Hintergrund-Threads** zu GPU-Vertex-Buffern gemesht (vanillas `BlockRenderDispatcher` mit echten Blockmodellen,
Biom-Farben, Flüssigkeiten) und nur neu gebaut, wenn sich das Placement oder ein Block in genau dieser
Sektion ändert. Pro Frame werden nur noch gecachte Buffer gebunden, plus Frustum-Culling und Render-Distanz.
Flächen zwischen benachbarten Schematic-Blöcken werden weggelassen. Connected Textures (CTM, Fusion,
Connected Glass) verbinden sich innerhalb des Schematics. Die Weltdaten für den Vergleich werden auf dem
Main-Thread kopiert, sodass Worker nie auf live Chunk-Daten zugreifen (wie vanillas Chunk-Builder).
Gezeichnet wird in `RenderLevelStageEvent.AFTER_TRANSLUCENT_BLOCKS` mit vanilla-Shadern
(`rendertype_cutout` + Alpha-Blending über `ColorModulator`). Geisterblöcke sind voll beleuchtet und damit
auch nachts und unter Tage sichtbar.

**Warum ein Mixin?** NeoForge hat kein clientseitiges Event für Blockänderungen. Damit die Vorschau sofort
reagiert, wenn ein Block gesetzt oder abgebaut wird, hängt sich ein einzelner `@Inject` an
`LevelRenderer#setSectionDirty`, über den vanilla alle Neuzeichnungs-Anforderungen schickt. Das Mixin ist
mit `require = 0` markiert: Ersetzt ein anderer Mod die Methode, startet das Spiel trotzdem, und Updates
kommen dann nur noch über `ChunkEvent.Load`.

**Client-only.** `@Mod(dist = Dist.CLIENT)` (die Mod-Klasse wird auf dedizierten Servern nie geladen),
`displayTest = "IGNORE_ALL_VERSION"`, das Mixin nur im `client`-Abschnitt, keine Netzwerk-Payloads, und alle
Abhängigkeiten in der `neoforge.mods.toml` mit `side = "CLIENT"`. Außer NeoForge gibt es keine Abhängigkeiten.

**Transformation.** Reihenfolge: Spiegeln Y → X → Z → Drehen um Y, wie bei vanillas Strukturplatzierung.
Blockzustände nutzen vanillas `BlockState.mirror/rotate`, das alle Vanilla- und korrekt implementierten
Mod-Blöcke unterstützt (Treppen, Türen, Öfen, Truhen, Schienen, …). Ein Unit-Test prüft für alle 32
Kombinationen, dass Positions- und Zustandstransformation übereinstimmen.

## Kompatibilität mit ATM10

Grundlage ist eine Analyse von `mods-atm10.txt` (464 Mods):

| Mod(s) | Bewertung |
|---|---|
| Sodium / Embeddium / Iris / Oculus | **Nicht in ATM10.** Damit läuft die Welt über vanillas Renderer, dessen Schnittstellen hier genutzt werden. |
| ImmediatelyFast, ModernFix, FerriteCore | Unkritisch: Es werden nur öffentliche Render-APIs genutzt, Blockmodelle lädt der Mod wie vanilla. |
| CTM, Fusion, Connected Glass, Chisel, Rechiseled, Chipped | Unterstützt: Verbindungen werden aus den Schematic-Nachbarn berechnet. |
| Macaw's (mcw-*), Supplementaries, viele Deko-Mods | Normale Blockmodelle, werden korrekt dargestellt und gedreht. |
| FramedBlocks, Mekanism Covers | **Einschränkung:** Das Tarn-Aussehen hängt an Block-Entity-Daten der echten Welt; in der Vorschau erscheint der leere Rahmen. Der Blockvergleich funktioniert trotzdem. |
| Create (+Addons), AE2, Refined Storage, Mekanism, Pipez, LaserIO | **Einschränkung:** Teile, die über Block-Entity-Renderer oder Flywheel gezeichnet werden (Wellen, Zahnräder, Kabelverbindungen), fehlen in der Vorschau teilweise. Der Grundblock und der Vergleich funktionieren. |
| FTB Chunks, JourneyMap | Belegen `M` bzw. `J` → Standardtasten von NeoLitematica nutzen Alt+… |
| Building Gadgets 2, Construction Sticks, Mining Gadgets | Zeichnen eigene Vorschauen, ohne Konflikt. |
| Controlling, KeybindsPurger | Zum Umbelegen der Tasten nutzbar. |

Kein Mod wird verändert, und Serverkommunikation findet nicht statt. Wer Embeddium oder Oculus nachinstalliert:
Das Rendering sollte weiter funktionieren, aber mit aktiven Shaderpacks sind Darstellungsfehler möglich, und
Embeddium ersetzt eventuell die Methode des Mixins (dann Updates nur bei Chunk-Ladevorgängen). Getestet ist
das nicht.

## Bekannte Einschränkungen

- **Drehung um X- und Z-Achse wird nicht angeboten.** Minecraft-Blockzustände können „seitlich gekippte"
  Treppen, Türen usw. nicht abbilden; eine solche Drehung würde zwangsläufig falsche Blöcke erzeugen.
  Angeboten werden Drehung um Y in 90°-Schritten sowie Spiegeln an X, Y und Z.
- **Spiegeln an Y ist eine Annäherung:** Halbe Blöcke, Stufen, Türen, oben/unten-Ausrichtung,
  Boden/Decke-Befestigung und Tropfstein werden umgedreht. Blöcke ohne vertikales Gegenstück (z. B.
  hängende Laternen) behalten ihren Zustand.
- **Entities** (Gemälde, Rahmen, Rüstungsständer) im Schematic werden nicht angezeigt.
- **Block-Entities** werden für Vanilla-Blöcke (Truhen, Schilder, Betten, Banner, Köpfe, Töpfe, …) transparent
  dargestellt. Mod-Block-Entities bekommen absichtlich keine Welt-Referenz; schlägt ihr Renderer fehl, wird
  der Typ für die Sitzung übersprungen und geloggt.
- **Blockvergleich** gilt nur für Sektionen innerhalb der Render-Distanz und für geladene Chunks. Die
  Statistik weist „In der Nähe" aus, solange nicht alles geprüft ist.
- **Umbenennen oder Löschen** einer Schematic-Datei trennt bestehende Placements dieser Datei. Beim nächsten
  Betreten der Welt erscheint eine Fehlermeldung; neu platzieren behebt das.
- Kein Speichern neuer Schematics aus der Welt, keine Materialliste und kein automatisches Platzieren
  (Litematicas „Easy Place"). Die Architektur ist darauf vorbereitet; die Funktionen fehlen aber noch.

## Aus dem Quellcode bauen

Voraussetzung: JDK 21.

```
gradlew build          # Kompilieren + Unit-Tests → build/libs/neolitematica-1.21.1-1.0.0.jar
gradlew test           # Nur Unit-Tests (Reader gegen "Another castle", Transformationen)
gradlew runClient      # Entwicklungs-Client
gradlew runSmokeTest   # Automatischer Ingame-Test, siehe unten
gradlew runServer      # Dedizierter Server (vorher EULA in run-server/eula.txt selbst akzeptieren)
```

**Automatischer Ingame-Test** (`runSmokeTest`): erstellt eine Flachwelt, platziert
`ressources/Another castle.litematic`, baut über den integrierten Server einen Teil korrekt, falsch und
überzählig nach, prüft die Vergleichszahlen in allen Modi, dreht das Placement, öffnet alle Bildschirme,
speichert Screenshots nach `run/screenshots/smoke_*.png` und beendet das Spiel. Letztes Ergebnis:
`correct=3452 missing=11355 wrongBlock=78 wrongState=20 extra=25` bei 14905 Blöcken, was genau den gesetzten
Blöcken entspricht.

## Lizenz und Herkunft

MIT. Litematica (LGPLv3, masa) diente nur als funktionale Referenz und für das Dateiformat; es wurde kein
Code übernommen.