Imported from DanyaNADAMU/lifecycle (
AGENTS.md). Install upstream withnpx skills add DanyaNADAMU/lifecycle. Copyright stays with the author.
AGENTS.md
Project Context
- Project Name: lifecycle
- Target Platform: Velocity Proxy (version 4.0.0+)
- Runtime: Java 25
- Build System: Gradle with Kotlin DSL (
build.gradle.kts) - Group:
mu.nada - Artifact:
lifecycle - Target OS / Environment: Debian 12, Rootless Podman with Quadlet (
systemd --user)
Key Architecture Principles
- Separation of Concerns:
client/provides an asynchronous HTTP client to interact with the systemd webhook bridge on the host (SystemdBridgeClient).model/defines server lifecycle states (ServerState:STOPPED,STARTING,RUNNING,STOPPING) and runtime tracker (ManagedServer).service/encapsulates server registry, on-demand waking, polling, and idle stopping (ServerRegistry,WakeService,IdleService).auth/contains the soft integration bridge tonadamu-auth(AuthBridge), guaranteeing zero auth bypasses while maintaining optional coupling.i18n/andutil/provide multi-language dictionary management (LanguageManager,MessagesConfig) and localized MiniMessage rendering (MessageService) with client locale auto-detection and dialect fallbacks.listeners/handles early wakeup detection and connection proxying (InitialServerListener,PreConnectListener,DisconnectListener).commands/provides admin CLI control (/lifecycleor/nlc).
- Flexible Pool Discovery & Defaults:
auto: trueautomatically registers all backend servers declared invelocity.toml(excludinglimbo-serverand servers markedenabled: false).auto: falserestricts management to servers explicitly declared inservers:.defaults:block supplies baseline parameters (idleTimeoutMinutes,startupGracePeriodSeconds, etc.) merged cleanly into per-server overrides.
- Infrastructure Integration (Quadlet & Systemd):
- Backend servers are deployed as declarative Quadlet templates (
mc@<name>.container). - Because Quadlet uses
--rmon container termination, containers are ephemeral. The authoritative controller issystemctl --user. - The plugin communicates with systemd via an official
webhookdaemon running under userminecrafton the host athttp://host.containers.internal:8012.
- Backend servers are deployed as declarative Quadlet templates (
- Security & Auth Bypass Prevention:
lifecyclenever independently teleports a player whose state innadamu-authisPENDING_LOGIN.- Parallel warmup boots the container immediately when a player joins via a forced host, but player transfers only occur after successful authentication.
- Velocity event priorities (
PostOrder.FIRST/PostOrder.EARLY) ensure that auth firewalls always retain final authority.
- Scale-to-Zero & Resource Optimization:
- Unused backend servers are automatically stopped via
systemctl --user stop mc@<server>whenplayersConnected == 0after a configurable idle timeout. - Startup grace periods prevent false shutdown triggers during initial world generation and player connection handshakes.
- Unused backend servers are automatically stopped via
Code Standards & Conventions
- All code, code comments, and technical documentation must be exclusively in English.
- Russian documentation is provided alongside English in
README.ru.mdanddocs/ru/.
