Flightless SMC - Server Management Console

Flightless SMC is a comprehensive application designed to manage a Dockerized Minecraft server through an in-game Minecraft interface (the "console") and Discord integration. It allows users to start, stop, and restart the server, view its status, and link their Minecraft accounts to Discord for enhanced interaction.

Features

• In-Game Server Control: Manage your Minecraft server (running in Docker) directly from within a special Minecraft client connection.
  • /start: Start the Dockerized Minecraft server.
  • /stop: Stop the Dockerized Minecraft server.
  • /restart: Restart the Dockerized Minecraft server.
• Real-time Server Status:
  • The Minecraft server's state (starting, started, stopping, stopped, restarting) is displayed in the action bar.
  • Readiness of the server (whether it's accepting connections) is also indicated.
• Discord Integration:
  • Link Minecraft accounts to Discord user IDs.
  • Mechanism for sending link requests from the driver to Discord and processing responses.
• User Persistence:
  • Stores user UUIDs, Minecraft usernames, and linked Discord user IDs in an SQLite database.
• Flexible Connection Modes:
  • Supports Offline mode (UUIDs generated from usernames).
  • Supports Velocity proxy mode (authenticated UUIDs from a Velocity proxy).
• Docker Management:
  • Interfaces with the Docker daemon to control container lifecycle.
  • Automatically discovers the exposed TCP port of the managed container.
• Limbo Mode: The SMC console can run even if the main Minecraft server is down, allowing users to connect and issue /start commands.
• Robust Backend: A gRPC-based driver server handles core logic, separating concerns from the Minecraft-facing console.
• Configuration: Uses TOML files for configuring both the driver and the SMC application.

Architecture Overview

Flightless SMC consists of several key components that work together:

1. SMC Application (smc crate):

   • This is the Minecraft server that players connect to for managing the actual game server.
   • It listens for Minecraft client connections.
   • Parses in-game commands (e.g., /start, /stop).
   • Communicates with the driver-server via gRPC to execute actions and retrieve status.
   • Displays server status in the action bar.

2. Driver Server (driver-server crate):

   • The core backend service.
   • Exposes a gRPC API over a Unix domain socket.
   • Services:
     • UsersService: Manages user data (get, get/insert from database).
     • DockerService: Interacts with the Docker daemon (start/stop/restart container, get state, stream state changes, get port).
     • DiscordService: Facilitates two-way communication with the Discord bot component.
   • Connects to the smc-database.
   • Initializes and manages the smc-discord bot client.
   • Monitors the Docker container's state and port.

3. Discord Bot (smc-discord crate):

   • Integrates with Discord.
   • Handles account linking requests initiated from the game.
   • Listens for linking codes sent by users in DMs.
   • Updates the user's Discord ID in the database upon successful linking.

4. Database (smc-database crate):

   • An SQLite database storing user information (Minecraft UUID, username, Discord User ID).
   • Uses sqlx for database operations and migrations.
   • Includes a file-based lock (database.lock) to prevent multiple driver instances from accessing the same database file simultaneously (unless :memory: is used).

5. Docker Interaction (smc-docker crate):

   • Uses the bollard library to communicate with the Docker daemon.
   • Provides functionalities to manage the lifecycle of the target Minecraft server container.

6. Network Protocol (smc-network crate):

   • Handles low-level Minecraft protocol interactions (handshaking, login, status pings).
   • Supports offline mode and Velocity proxy integration for player authentication.

7. Inter-Service Communication (smc-proto, smc-conversions):

   • smc-proto defines the gRPC service contracts using Protocol Buffers.
   • smc-conversions provides traits and implementations for converting between internal smc-models and the generated protobuf types.

Prerequisites

• Rust (latest stable recommended)
• Cargo
• Docker daemon running
• protoc (Protocol Buffer compiler) - required for building smc-proto.

Building

1. Clone the repository (if applicable).
2. Ensure protoc is installed and in your PATH.
   • On Debian/Ubuntu: sudo apt install protobuf-compiler
   • On macOS (Homebrew): brew install protobuf
3. Build the project:

   cargo build --release

   This will build all workspace members. The main executables will be:
   • target/release/smc-driver-server
   • target/release/smc

Configuration

The system uses TOML configuration files. By default, these are stored in a platform-specific user config directory (e.g., ~/.config/flightless-smc/ on Linux) or can be overridden by setting the SMC_PATH environment variable to a custom directory.

1. Driver Server Configuration (driver.toml): Located at SMC_PATH/config/driver.toml or $XDG_CONFIG_HOME/flightless-smc/driver.toml.

# Common network settings (shared with smc app if common.toml is used)
[common.network]
# socket_path = "/custom/path/to/flightless-smc-driver.socket" # Optional

# Discord Bot Configuration
[discord]
token = "YOUR_DISCORD_BOT_TOKEN"

# Docker Configuration
[docker.container]
name = "name_of_your_minecraft_server_container"
# How often to poll Docker for container state changes.
# Can be Constant(Duration) or Fuzzy { min: Duration, max: Duration }
# Example: state_poll_duration = { Fuzzy = { min = "1s", max = "5s" } }
state_poll_duration = { Fuzzy = { min = { secs = 1, nanos = 0 }, max = { secs = 5, nanos = 0 } } } # Default
port = 25565 # Optional: Manually specify the game server port if auto-detection is problematic.

# Database Configuration
[database]
# path = "/custom/path/to/database.db" # Optional, defaults to config_dir/database.db
                                     # Use ":memory:" for an in-memory database (not persistent).

2. SMC Application Configuration (smc.toml): Located at SMC_PATH/config/smc.toml or $XDG_CONFIG_HOME/flightless-smc/smc.toml.

# Common network settings
[common.network]
# socket_path = "/path/to/flightless-smc-driver.socket" # Optional, must match driver's socket

# SMC Network Configuration
[network]
# Address and port for the SMC console in normal mode
[network.normal]
# address = "0.0.0.0" # Optional, defaults to 0.0.0.0
port = 25565        # Port players connect to for the console

# Address and port for the SMC console in limbo mode (if different from normal)
[network.limbo]
# address = "0.0.0.0" # Optional
port = 25566        # Port for limbo mode console

# Connection mode for authenticating players connecting to the SMC console
# Options: "Offline" or { Velocity = { secret = "YOUR_VELOCITY_SECRET" } }
connection_mode = "Offline" # Default

Default Paths:

• Unix Socket: /tmp/flightless-smc-driver.socket
• Database File: config_dir/database.db
• Database Lock File: config_dir/database.lock

Running the Application

1. Start the Driver Server:

   # If SMC_PATH is set:
   # SMC_PATH=/path/to/your/custom/smc_data target/release/smc-driver-server
   # Otherwise, using default config location:
   target/release/smc-driver-server

   The driver server needs to be running before the SMC application can connect to it.

2. Start the SMC Application (Minecraft Console):

   # Normal mode (connects to port specified in smc.toml under network.normal)
   # SMC_PATH=/path/to/your/custom/smc_data target/release/smc
   target/release/smc
   
   # Limbo mode (connects to port specified in smc.toml under network.limbo)
   # SMC_PATH=/path/to/your/custom/smc_data target/release/smc --limbo
   target/release/smc --limbo

3. Connect with a Minecraft Client: Connect to the address and port specified in your smc.toml for the smc application (e.g., localhost:25565 or localhost:25566 for limbo).

4. In-Game Commands:

   • /start: Starts the managed Minecraft server container.
   • /stop: Stops the managed Minecraft server container.
   • /restart: Restarts the managed Minecraft server container.
   • /link: (Implementation seems partial) Intended to initiate Discord account linking.
   • /help: Displays available commands.

Environment Variables

• SMC_PATH: Overrides the default directory for configuration and data files. If set, configuration files will be expected in $SMC_PATH/config/.
• SMC_DISABLE_COLORBT: If set, disables color backtrace for panics.
• SMC_ENABLE_CONSOLE_SUBSCRIBER: If set, enables console-subscriber for Tokio task debugging.
• SMC_USE_ST_RUNTIME: If set, forces the Tokio runtime to be single-threaded.

Acknowledgements

This project incorporates code from the following open-source projects:

• Valence: The smc-packet-io crate contains code which is directly derived from Valence. It is used under the terms of the MIT License.

License

This project is licensed under the MIT License - see the LICENSE file for details.