Ueberblick

Die aktuelle Minigames Engine als eine zentrale Game-Plattform.

Diese Seite dokumentiert die aktuelle v2-Minigames-Engine als statisches Handbuch: feste Wartelobby im Core, eine Match-Session pro Service, typed Setup-Aufloesung, Profile fuer externe Games und eine neue Game-SPI ueber GameServerInstance.

Fester Core

Die Wartelobby, der Lobby-Flow und der Uebergang nach Preparation bleiben engine-owned.

Spielbare Games

Neue Spiele registrieren sich ueber GameServerInstance, definieren Profile ueber die DSL und binden ihre Runtime ueber Hooks oder GameRuntimeHandlers an.

GameServerInstance
-> GameConfigurator / DSL
-> Profile
-> ModeRuntime
-> ModeSetupSchema
-> MatchSession

Wichtig: Diese Dokumentation beschreibt nur die eigentliche Engine-Doku. Technische Sidecar-Themen sind bewusst aus dieser Praesentationsseite herausgenommen.

Schnellstart

Build, Run, Standalone-Local und Bundle.

Die Engine wird mit Java 25 gebaut. Der normale Einstieg laeuft ueber Gradle-Tasks, die Run-Verzeichnisse unter build/ und das Bundle unter minigames-server/build/bundle.

Voraussetzungen

Java 25
Netzwerkkonnektivitaet fuer den ersten Dependency-Download
Schreibrechte fuer build/, config/, data/ und extensions/

Run-Varianten

:minigames-server:run fuer den normalen Dev-Run
:minigames-server:runStandaloneLocal fuer lokale Offline-Tests
:minigames-server:assemble fuer das Deployment-Bundle

./gradlew :minigames-server:test
./gradlew :minigames-server:run
./gradlew :minigames-server:runStandaloneLocal
./gradlew :minigames-server:assemble
./gradlew :minigames-server:assembleStandaloneLocal
java -jar application.jar --migrate-stats-to-cloudnet

Server bauen oder direkt lokal starten.
config/minigames.conf pruefen.
Eigenes Game-JAR bei Bedarf in extensions/ legen.
Server aus dem Run- oder Bundle-Verzeichnis starten.

Pfad	Zweck
`minigames-server/build/run`	normaler Dev-Run
`minigames-server/build/standalone-local/run`	lokaler Offline-Run
`minigames-server/build/bundle`	Deployment-Bundle
`minigames-server/build/standalone-local/bundle`	lokales Offline-Bundle

Game-API

Der empfohlene v2-Pfad fuer neue spielbare Games.

Neue Games werden ueber GameServerInstance registriert, beschreiben ihre Match-Semantik ueber Profile und erhalten ihre Runtime ueber Hooks, Handlers und typed Setup-Aufloesung.

public final class ExampleApplication extends GameServerInstance {
    public static void main(String[] args) {
        GameServerInstance.run(ExampleApplication::new, args);
    }

    @Override
    public void onLoad(GameServerContext server) {
        server.getConfigurator().setup(game -> game
                .id("example")
                .displayName("Example")
                .setupSchema(ModeSetupSchema.identity())
                .runtime(runtime -> runtime.onRoundStarted(context -> { }))
                .profile("example-solo", profile -> profile
                        .minPlayers(2)
                        .maxPlayers(8)
                        .teams(TeamModels.ffa())
                )
        );
    }
}

`GameServerInstance`

Entry-Point fuer spielbare Games. Nutzt onLoad, onEnable und onDisable.

`GameServerContext`

Stabiler Server-Context mit Zugriff auf Configurator, SetupService, StatsService, InventoryService, KitService, PerkService, ItemSpawnerService, PlayerIdentityService und Session-Eventbus.

DSL und Profile

GameDefinitionConfigurator definiert Spiel-ID, Setup-Schema, Stats und Runtime. Profile definieren Spielerlimits, Teammodell, Timer, Sieg- und Respawnlogik.

Runtime

GameRuntimeConfigurator bindet Phase- und Gameplay-Hooks an. Groessere Runtimes laufen ueber GameRuntimeHandlers.

`ModeRuntime` und `ModeServices`

Die eigentliche Match-Runtime arbeitet ueber typed Services, Session-Events, Setup-Zugriff, State-Store und Match-Control.

Typed Setup

ModeSetupSchema und ModeSetupAccess trennen Profil-Semantik sauber von Karten-Geometrie, Markern und Spawns.

`MatchListenerRegistry`

Zusatzlistener werden match-scoped ueber ModeServices.listeners() registriert, statt direkt manuell an die Instance gehangen zu werden.

Gameplay-Primitives

Wiederverwendbare Bausteine wie CustomItemAction, GeneratorPlan, NpcHandle, MatchSidebar und MatchBossBar ersetzen Glue-Code.

Typ	Zweck
`GameDefinitionConfigurator`	Spieldefinition auf Root-Ebene
`GameProfileConfigurator`	Match-Semantik pro Profil
`GameRuntimeConfigurator`	Hooks und Handler fuer die Runtime
`GameRuntimeHandlers`	groessere Runtime-Klassen statt Inline-Hooks
`ModeEvents`	Gameplay- und Session-nahe Runtime-Events
`ModeStateStore`	typed Runtime-State statt freier String-Maps

Migration: Alte Einstiegspunkte wie GameModeHandlerFactory oder GameModeContext sind nur noch Legacy-Kontext und nicht mehr der empfohlene Hauptpfad.

API-Referenz

Vollstaendige Referenz der relevanten oeffentlichen Engine-Typen.

Diese Referenz spiegelt den aktuellen oeffentlichen Satz aus minigames-extension-api und die relevanten oeffentlichen Server-Modelle aus minigames-server. Markierungen: Hauptpfad, Ergaenzende API, Server-Modell und Legacy.

application

GameServerInstance, GameServerContext, GameConfigurator, GameDefinitionConfigurator, GameModeConfigurator, GameProfileConfigurator, GameRuntimeConfigurator, GameRuntimeHandlers, GameRuntimeFactory, GameStatsConfigurator, GameVictoryPolicy, GameRespawnPolicy, GameEliminationPolicy, GameRoundTimer, GameTeamModel, TeamModels, GameCombatRuleset, AdvancedGameServerContext.

mode

ModeRuntime, ModeEvents, ModeServices, ModeMatch, ModeDefinition, ModeRegistry, ModeSetupSchema, ModeSetupAccess, ModeStateKey, ModeStateStore, ModeStatKey, ModeTestKit, MatchListenerRegistry, MatchListenerHandle, MatchQueryApi, MatchControlApi, MatchRuntimeView, MatchParticipantView, MatchTeamView, MatchPhase, MatchResult, LobbyModeProfile, CustomItemAction, GeneratorPlan, NpcHandle, MatchSidebar, MatchBossBar.

session und setup

MatchSessionEvent, MatchSessionEventBus, MatchSessionEventSubscription, MatchCreatedEvent, LobbyStartedEvent, PreparationStartedEvent, MatchStartedEvent, ParticipantEliminatedEvent, MatchFinishedEvent, ServiceShutdownScheduledEvent, ForcedMapChangedEvent, ActiveSetupChangedEvent, SetupService, SetupEditSession, GameSetupRegistry, GameSetupDefinition, GameSetupMarkerDefinition, GameSetupTeamDefinition, GameWorldLoader, GameWorldLoaders, SetupWorldSourceType, StoredGameSetupDefinition, StoredItemSpawnDefinition, StoredItemSpawnerStageDefinition, StoredSetupMarkerDefinition, StoredTeamSpawnDefinition.

Services und Modelle

InventoryService, InventoryBuilder, InventoryView, InventoryOpenContext, InventoryCloseContext, InventoryClickContext, InventoryItemChangeContext, KitService, KitBuilder, KitDefinition, KitItem, PerkService, PerkBuilder, PerkDefinition, PerkAction, ItemSpawnerService, ItemSpawnerBuilder, ItemSpawner, ItemSpawnerStage, ItemSpawnContext, ItemSpawnMode, PlayerIdentityService, PlayerIdentitySnapshot, CountdownService, CountdownBuilder, CountdownHandle, CountdownListener, StatsService, CloudNetAccess, GameTemplateRegistry, LobbySelectionService, MobService, ParticleService.

Bereich	Wichtige Typen	Einordnung
Hauptpfad fuer neue Games	`GameServerInstance`, `GameServerContext`, `GameDefinitionConfigurator`, `GameProfileConfigurator`, `GameRuntimeConfigurator`, `GameRuntimeHandlers`, `ModeRuntime`, `ModeServices`, `ModeSetupSchema`, `ModeSetupAccess`, `MatchListenerRegistry`	`Hauptpfad`
Ergaenzende Runtime- und Match-Modelle	`MatchQueryApi`, `MatchControlApi`, `MatchRuntimeView`, `MatchParticipantView`, `MatchTeamView`, `MatchPhase`, `MatchResult`, `ModeStateStore`, `ModeStateKey`, `ModeStatKey`, `ModeTestKit`	`Ergaenzende API`
Persistenz, Setup und Session	`SetupService`, `SetupEditSession`, `GameSetupDefinition`, `GameWorldLoaders`, `MatchSessionEventBus`, `ForcedMapChangedEvent`, `ActiveSetupChangedEvent`	`Ergaenzende API`
Inventories, Kits, Perks, Spawner	`InventoryClickContext`, `KitDefinition`, `PerkDefinition`, `ItemSpawnerBuilder`, `ItemSpawnerStage`, `PlayerIdentitySnapshot`, `CountdownService`	`Ergaenzende API`
Oeffentliche Server-Modelle	`MinigamesMain`, `MinigamesBootstrap`, `MinigamesExtensionManager`, `ConfiguredGameApplication`, `ExternalGameDefinition`, `ExternalGameProfile`, `GameServerContextServices`, `MinigamesConfig`, `ForwardingMode`, `MatchTemplate`, `CombatRuleset`, `RespawnMode`, `VictoryMode`, `TeamDefinition`	`Server-Modell`
Legacy-Pfade	`MinigamesExtension`, `MinigamesExtensionContext`, `GamePhaseController`, `GamePhaseDefinition`, `GamePhaseListener`, `GamePhaseType`	`Legacy`

Wichtig: Die kanonische Vollreferenz lebt in docs/game-api.md. Diese Seite spiegelt dieselben Typen im praesentationsorientierten Format. Die nachrangigen Lobby-Pet-Typen LobbyPetProfileSource und LobbyPetType bleiben bewusst ausserhalb des allgemeinen API-Hauptpfads.

Architektur

Bootstrap, Match-Orchestrierung und Dateisystem-Sicht.

Die aktuelle Engine besteht im Kern aus minigames-extension-api und minigames-server. Spielbare Games werden beim Bootstrap als Game-Applications geladen und noch vor dem Match-Core registriert.

Bootstrap in Kurzform

MinigamesMain bestimmt das Basisverzeichnis und laedt die Config.
MinigamesBootstrap initialisiert Minestom und MinestomPvP.init(true, false).
Stats-, Setup-, Inventory-, Kit-, Perk- und Runtime-Services werden gebaut.
Die feste Lobby-Instance wird erzeugt.
MinigamesExtensionManager laedt Game-JARs aus extensions/.
onLoad(GameServerContext) registriert Spieldefinitionen und Profile.
MatchManager baut genau eine MatchSession.
Commands werden registriert, danach startet der eigentliche Server.

Wichtige Kernbausteine

MatchManager
MatchSession
MatchParticipantRegistry
MatchLobbyPresentation
MatchResultPersistence

Dateisystem-Sicht

config/ fuer Hauptkonfiguration
config/setups/ fuer persistente Setups
extensions/ fuer Game-JARs
data/ fuer lokale Daten

GameServerInstance
-> Game DSL
-> ExternalGameProfile
-> MatchTemplate
-> MatchSession

Konfiguration

`minigames.conf`, Match-Auswahl und Setups.

Die zentrale Engine-Konfiguration liegt in config/minigames.conf. Neue externe Games werden ueber Profile aktiviert; Built-in-Modi koennen weiter ueber Templates laufen.

Block	Aufgabe
`runtime`	Service- oder Standalone-Local-Modus
`server`	Adresse, Port, Forwarding-Mode
`lobby-world`	optionale echte Lobby-Weltquelle
`stats`	Backend-Auswahl, JDBC und dokumentbasierte Konfiguration
`match`	`active-profile-id` oder `active-template`
`phases`	Dauern, Anzeigenamen und Join-Regeln fuer die festen Phasen
`templates`	Built-in-Templates fuer `ffa` und `team`

match {
  active-template = "ffa-default"
  active-profile-id = "bedwars-solo"
}

active-profile-id fuer externe Games active-template fuer Built-ins oder Fallback

Wichtig: Externe spielbare Games definieren ihre Match-Semantik nicht mehr ueber templates in Zusatz-Configs. Extension-Configs mit eigenen templates sind ungueltig.

Match-System

Phasen, Session-Lifecycle, Maps, Commands und Events.

Die Match-Session bleibt der zentrale Orchestrator fuer Lobby, Preparation, Ingame und End. Profile bestimmen fuer externe Games die Match-Semantik; Setups liefern Karten, Marker und Spawns.

Lobby Preparation Ingame End

Spielerfluss

Spieler joinen zuerst in die feste Lobby-Instance.
Preparation laeuft bereits auf der aktiven Match-Map.
Neue Joins waehrend Ingame oder End werden Spectator.
Disconnects aktiver Teilnehmer zaehlen wie Ausscheiden.

Map- und Setup-Auswahl

forcedMap hat Vorrang vor normalem Voting.
allowed-map-ids schneidet Kandidaten ein.
ForcedMapChangedEvent und ActiveSetupChangedEvent sind getrennt.
Die aktive Karte wird erst fuer die Runde final aufgeloest.

Command	Bedeutung
`/mg`	Session- und Match-Informationen
`/start`	startet die laufende Session sofort
`/forcemap <mapId>`	erzwingt eine Map fuer die naechste Runde
`/forcemap clear`	entfernt eine gesetzte forced Map
`/setup`	arbeitet auf der persistenten Setup-API

Built-ins und externe Games: Eingebaute Modi wie ffa und team bleiben ueber Templates aktivierbar. Neue Games arbeiten ueber GameServerInstance und Profile.

Setup

Persistente Setups, Weltquellen, Marker und Publish-Flows.

Die SetupAPI ist die persistente Karten-Schicht der Engine. Sie sitzt vor der Runtime-Registry und verbindet Dateisystem, Edit-Sessions und Runtime-Publishing.

storedSetups()
find(id)
create(id)
edit(id)
save(session)
publish(id)
publishAll()
setupDirectory(id)

Persistentes Modell

Setups liegen unter config/setups/<setupId>/ und enthalten ID, Weltquelle, spectator spawn, player spawns, team spawns, item spawns, marker groups und metadata.

Weltquellen

Unterstuetzt werden Weltverzeichnisse und Schematic-Dateien ueber GameWorldLoaders.worldDirectory(Path) und GameWorldLoaders.schematic(Path).

Marker und Team-Spawns

Markergruppen sind die generische Erweiterung fuer mode-spezifische Spawnanker. Team-Spawns und FFA-Spawns bleiben Teil der Setup-Geometrie.

Publish-Modell

save(session) schreibt nur auf Platte. publish(id) und publishAll() registrieren Setups zusaetzlich sofort fuer die laufende Runtime.

Stats

Match-Record, Totals und Backend-Auswahl.

Die Engine verwendet die oeffentliche StatsService-SPI und kann Match- und Aggregatdaten ueber JDBC oder ein dokumentbasiertes Backend persistieren.

recordMatch(MatchRecord)
loadPlayerTotals(UUID playerUuid)
loadTeamTotals(String templateId, String teamId)

Aktuelle Core-Stat-Keys

kills
deaths
assists
damage_dealt
damage_taken
hits
wins, losses, draws
score

Backend-Auswahl

auto bevorzugt das dokumentbasierte Backend und faellt sonst auf JDBC zurueck.
jdbc erzwingt SQL.
cloudnet erzwingt das dokumentbasierte Backend.

pre 1.9 PvP

Combat-Initialisierung, Events und Default-Loadout.

Die Engine arbeitet bewusst mit einem pre 1.9-Combat-Setup auf Basis von MinestomPvP. Combat ist Teil des aktuellen Match-Standards und nicht nur ein optionales Beispielsystem.

MinestomPvP.init(true, false);
CombatFeatures.legacyVanilla().createNode()

Wichtige Combat-Events

FinalAttackEvent
FinalDamageEvent
EntityPreDeathEvent

Aktuelles Default-Loadout

STONE_SWORD
BOW mit ARROW x32
COOKED_BEEF x16
Chainmail/ Iron Armor Mix

Respawn: Bei DELAYED wird der Spieler erst Spectator und nach Ablauf des Respawn-Delays wieder ausgeruestet und an einen Match-Spawn gesetzt.

Betrieb

Bundle, Deployment, Update-Vorgehen und Betriebsfallen.

Das vorgesehene Deployment-Ziel ist das Bundle unter minigames-server/build/bundle. Fuer lokale Offline-Tests gibt es zusaetzlich das Standalone-Local-Bundle.

Pfad	Zweck
`application.jar`	Start-JAR im Bundle
`config/`	Hauptkonfiguration und gespeicherte Setups
`extensions/`	Game-JARs und optionale Zusatz-JARs
`data/`	lokale Daten wie H2-Dateien

:minigames-server:test ausfuehren.
:minigames-server:assemble bauen.
CHANGELOG.md und relevante Docs pruefen.
Neues application.jar ins Ziel deployen.
Eigenes Game-JAR in extensions/ aktualisieren.
Config- und Setup-Differenzen pruefen.

Typische Betriebsfallen: falscher forwarding-mode, Reload waehrend aktiver Runde, Datenbankfehler beim Start und veraltete Bundle-Inhalte nach einem Engine- oder Game-Update.