Extensions im Underground Simulator

In diesem Guide geht es um die Erweiterungen des Underground Simulator mit sogenannten Extensions. Java-Vorkenntnisse sind teilweise erforderlich.

Empfohlen wird OpenJDK 21 oder neuer (intern wird aktuell Version 25 genutzt).

(i) Dieser Guide gilt nur für Version v0.5.0-alpha.dev-SNAPSHOT!

Schritt 1: Projekt aufsetzen

Schritt 1.1: Maven

Für Maven-Nutzer ist der Einstieg besonders einfach. Führt in einem leeren Ordner folgende Befehle aus:

mvn dependency:get \
  -Dartifact=de.qstudios:underground-mod-archetype:1.0-SNAPSHOT \
  -DrepoUrl=https://mvn.deepslatesmp.de/repository/maven-snapshots

und dann:

mvn archetype:generate \
  -DarchetypeCatalog=local \
  -DarchetypeGroupId=de.qstudios \
  -DarchetypeArtifactId=underground-mod-archetype \
  -DarchetypeVersion=1.0-SNAPSHOT

Das war's – ihr könnt direkt mit der Entwicklung (Schritt 3) starten.

Schritt 1.2: Gradle oder andere Tools

Hier ist etwas mehr Handarbeit nötig. Die grundlegende Projektstruktur sollte so aussehen:

(Modname)/                       ← Root-Ordner des neuen Mods
├─ (Gradle-Dateien)                    ← Optionale Gradle-Builddateien
├─ mod.json                    ← Konfigurationsdatei der Mod
└─ src/
   └─ main/
       ├─ java/
       │   └─ (dein Package)   ← Package aus groupId/artifactId
       │       └─ App.java        ← Beispiel-Klassen-Datei
       └─ resources/
           └─ config/             ← Optional: zusätzliche Ressourcen/Configs

Dependency einbinden

Groovy (Gradle):

implementation 'de.qstudios.underground:underground:v0.5.0-alpha.dev-SNAPSHOT'

und für Kotlin-Nutzer:

implementation("de.qstudios.underground:underground:v0.5.0-alpha.dev-SNAPSHOT")

Alternativ kann das JAR manuell heruntergeladen und dem Classpath hinzugefügt werden. hier

Schritt 2: mod.json erstellen

Falls ihr kein Maven nutzt, müsst ihr die Datei selbst erstellen:

{
    "name": "(Modname)",
    "version": "1.0",
    "author": "(Ihr)",
    "description": "Eine neue Mod für dein Spiel",
    "extension": {
        "where": "(Deprecated, einfach leerlassen)",
        "file": "(Link zur kompilierten Datei)"
    }
}

Wichtig: Beim Bauen muss die Main-Class ins Manifest eingetragen werden!

Schritt 3: Entwickeln

Damit eure Mod funktioniert, muss eure Hauptklasse das Interface implementieren: de.qstudios.underground.mod.Modfile

public interface Modfile {
   void activity();

   void onLogin();

   void onLaunch();

   void onGameStart();
   
   void onEnable();
}

Methoden erklärt

activity – Wird im Endmenü nach einem Spieltag ausgeführt
onLogin – Beim Login des Spielers
onLaunch – Beim Start des Simulators (Begrüßung)
onGameStart – Beim Start einer Runde
onEnable – Wird beim Laden der Mod ausgeführt (z. B. für Shop-Registrierung)

Die Modularisierung erlaubt es nun, viele Dinge dynamisch zu erweitern – früher war z. B. der Shop fest im Code eingebaut, jetzt kann man ihn modden.

Schritt 4: Bauen

WICHTIG: Main-Class ins Manifest eintragen!

Apache Maven:

mvn clean package

Gradle:

gradle build

Ohne Build-Tool (manuell)

Wenn ihr weder Maven noch Gradle nutzt, könnt ihr eure Mod auch manuell bauen:

Beispiel für eine MANIFEST.MF:

Main-Class: de.qstudios.underground.Main

Anschließend müsst ihr den Pfad zur erzeugten JAR in der mod.json eintragen.

Schritt 5: fertigstellen und in den Ordner verschieben

Um es für den Underground Simulator Kompatibel zu machen, müssen wir den Ordner mit dem JAR und dem JSON noch zippen, und dann nach $HOME/FnF-Apps/US/stable/resources/extensions/ verlegen. Bitte überprüft nochmal, dass ihr es so habt, dass direkt im innern der ZIP-Datei das JAR und JSON drin sind, nicht in einem Unterordner.

Fertig!

Jetzt könnt ihr eure Mod im Underground Simulator laden und testen 🚀

FAQ

Bei mir lädt es irgendwie nicht: schau dir nochmal die Tipps an und überprüfe ob du alles richtig gemacht hast.
Bei mir kommt "Manifest nicht gefunden.": Du hast einen Fehler gemacht, da du kein Manifest in das JAR inkludiert hast. Wie das geht schau oben.
Bei mir steht da: Die Klasse (Klasse) implementiert Modfile nicht.: Du hast vergessen, oben in deine Modhauptklasse implements de.qstudios.underground.mod.Modfile