Skip to main content
Runtime composition is where a Minestom application selects its active modules. Classpath discovery finds available providers, but only explicitly selected providers are installed.

​
Build a server

Use GroundsServer.builder() from your application entrypoint.
start() calls build() and starts Minestom. Use build() in tests when you need to inspect composition without starting a server process.

​
Discover providers

discoverProviders() scans the current thread context classloader with Java ServiceLoader.
Discovery reports found provider IDs and versions in the runtime logs. If no providers are found, it reports that result instead.
Discovery does not activate every provider. Select each required provider with useProvider.

​
Select a discovered provider

Select a provider by stable module ID:
The ID must match a discovered GroundsModuleProvider.id. A missing provider fails before Minestom starts:
Multiple discovered providers with the same ID also fail as ambiguous. Keep provider IDs stable and globally unique.

​
Use direct providers or modules

Use use(provider) when the application creates a provider directly instead of relying on ServiceLoader.
Direct providers still participate in descriptor validation, service dependency ordering, and server-type filtering. Use use(module) for a simple module that does not need descriptor metadata:
Direct modules are installed after provider-backed modules. Prefer providers for reusable modules because their descriptors make dependencies and service contracts visible before startup.

​
Configure the runtime

Without an explicit RuntimeConfig, the builder reads these environment variables: Set GROUNDS_VELOCITY_FORWARDING_SECRET when proxy mode is velocity; the runtime rejects forced Velocity mode without it. Tests can supply configuration directly:

​
Startup and shutdown behavior

When the runtime starts, it:
  1. resolves selected discovered providers;
  2. filters providers by server type;
  3. validates descriptors and service contracts;
  4. orders provider-backed modules by dependencies;
  5. initializes Minestom and calls install(ctx) on every module;
  6. starts Minestom on the configured host and port;
  7. calls start() on every module.
Shutdown calls stop() in reverse module order, runs registered shutdown hooks in reverse registration order, then stops Minestom cleanly.