191 lines
12 KiB
Markdown
191 lines
12 KiB
Markdown
# 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.
|