Skip to content

Minecraft Custom

Jump to bottom
github-actions[bot] edited this page Oct 17, 2026 · 3 revisions

Common Minecraft

This guide covers the minecraft.custom module in AlphaGSM.

minecraft.custom is currently ENABLED (BYO) on the documented Ubuntu 24.04 Linux baseline. The current GitHub integration lane still exercises both process and Docker runtime selection around that user-supplied-jar prerequisite, while local runs remain process-backed by default unless you opt into the Docker backend.

Requirements

  • screen
  • Java 21 or compatible runtime
  • Python packages from requirements.txt

Quick Start

Create the server:

alphagsm mycustom create minecraft.custom

Run setup:

alphagsm mycustom setup

Start it:

alphagsm mycustom start

Check it:

alphagsm mycustom status

Stop it:

alphagsm mycustom stop

Setup Details

Setup configures:

  • the game port (default 25565)
  • the install directory

minecraft.custom is supported in ENABLED (BYO) mode. AlphaGSM does not know which custom server binary you want by default, so setup only succeeds after you provide the jar yourself.

Setup writes the managed server.properties values and, when -l / --eula is supplied, eula.txt. It does not start the jar; the first Java process is owned by the normal start lifecycle.

Supported operator workflow:

  1. create the server
  2. choose the jar filename AlphaGSM should execute
  3. copy the real server jar into the install directory
  4. rerun setup
  5. start the server normally

Example:

alphagsm mycustom create minecraft.custom
alphagsm mycustom set exe_name paper-1.21.1.jar
mkdir -p /srv/alphagsm/mycustom
cp /path/to/paper-1.21.1.jar /srv/alphagsm/mycustom/
alphagsm mycustom setup 25565 /srv/alphagsm/mycustom
alphagsm mycustom start

If setup says Can't find server jar (...), the fix is to place the jar at <install_dir>/<exe_name> or update exe_name and run setup again.

Resetting the World

Stop the server, then run alphagsm mymc reset-world (or wipe). AlphaGSM lists the world data to delete and asks for confirmation. Add -Y to skip the prompt. Run start afterwards to generate a fresh world.

See world creation and reset for exactly which files are removed and the supported layouts.

Useful Commands

alphagsm mycustom update
alphagsm mycustom backup
alphagsm mycustom set gamemap CustomWorld
alphagsm mycustom set servername "AlphaGSM Custom Server"
alphagsm mycustom set exe_name paper-1.21.1.jar

Notes

  • Module name: minecraft.custom
  • Default port: 25565
  • query and info use Java Edition Server List Ping (SLP) on the game port.

Server variables

After create minecraft.custom, inspect or change these with set:

alphagsm myserver set --list
alphagsm myserver set KEY --describe
alphagsm myserver set KEY VALUE
Key Aliases Type What it does
difficulty — string The world difficulty. Example: easy.
gamemode — string The default game mode. Example: survival.
map gamemap, level, world, startmap, worldname string The selected world or level name. Example: world.
maxplayers users integer The maximum number of players allowed on the server. Example: 20.
port gameport integer The port the server listens on. Example: 25565.
servername hostname, name string The server name shown in the client list. Example: AlphaGSM Server.

Developer Notes

Run File

  • Executable: custom .jar (user-specified)
  • Location: <install_dir>/<exe_name>
  • Engine: Java (Custom)

Server Configuration

  • Config file: server.properties
  • Key settings (in server.properties):
    • server-port — Game port (default 25565)
    • level-name — World name managed by set gamemap
    • motd — Message of the day, managed by set servername
    • max-players — Maximum players
    • level-seed — World generation seed
    • online-mode — Mojang authentication
  • Template: See server-templates/minecraft-custom/ if available

Maps and Mods

  • Map directory: world/
  • Mod directory: mods/ or plugins/ (depends on server type)
  • Workshop support: No
  • Map notes: The world directory contains all world data.
  • Mod notes: Depends on the custom server type (Forge, Fabric, Spigot, etc.).

BYO file helper

Inspect this game's required files, source instructions and destinations with alphagsm <server-name> assets requirements; check the declared files with alphagsm <server-name> assets check. File checks do not establish game readiness. This helper checks known sentinels only and directs you to stage the complete compatible distribution manually; managed import is unavailable for this recipe. See BYO files and private SteamCMD acquisition.

Clone this wiki locally