GameMasterMC

GameMasterMC is a PaperMC plugin that connects Minecraft chat to an OpenAI-compatible chat completions API. Players can talk to a GameMaster through chat, and the model can inspect the live server and execute server-authority actions through a JSON tool protocol.

It works with any API that supports the OpenAI-style /v1/chat/completions endpoint, including hosted APIs, self-hosted gateways, and local model servers.

Requirements

• PaperMC 1.21.x
• Java 21
• An OpenAI-compatible chat completions endpoint

Installation

1. Download GameMasterMC-1.0.0.jar.
2. Put the jar in your Paper server's plugins folder.
3. Start the server once to generate the config.
4. Stop the server and edit:

plugins/GameMasterMC/config.yml

1. Start the server again.

Configuration

Set your API endpoint and model in plugins/GameMasterMC/config.yml:

llm:
  endpoint: "https://your-api-host.example.com/v1/chat/completions"
  model: "your-model-name"
  api-key: "your-api-key-if-needed"
  timeout-seconds: 300
  temperature: 0.4
  max-tokens: 1200

If your endpoint does not require an API key, leave api-key empty:

api-key: ""

Player chat access is controlled with chat.allowed-players:

chat:
  prefix: "@gm "
  allowed-players:
    - "*"

Use * to allow everyone, or list specific player names/UUIDs:

allowed-players:
  - "PlayerName"
  - "00000000-0000-0000-0000-000000000000"

Action access is controlled here:

access:
  allow-actions: true
  require-player-tool-permission: false
  allow-console-commands: false

allow-console-commands lets the model run anything the server console can run. Only enable it if you fully trust the model endpoint and the players allowed to use GameMasterMC.

Usage

Players can talk to the GameMaster with the configured prefix:

@gm what is happening on the server?
@gm put me in survival mode

Commands:

/gm <message>
/gm reload
/gm status
/gm ping

From the server console, omit the slash:

gm reload
gm status
gm ping

Permissions

• gamemaster.chat: allows using the chat bridge, default true.
• gamemaster.admin: allows reload, status, and ping commands, default op.
• gamemaster.tool.execute: optional action gate when require-player-tool-permission: true.

Players with gamemaster.admin bypass chat.allowed-players.

The GameMaster executes actions with server authority. Player permissions do not limit model actions unless require-player-tool-permission is enabled.

Model Tools

The model receives live server context and can request these actions:

broadcast, say, give_item, teleport_player, set_time, set_weather, effect,
gamemode, heal, feed, set_health, set_food, set_xp, clear_inventory,
set_inventory_slot, kick_player, ban_player, pardon_player, op_player,
deop_player, set_block, fill_area, spawn_entity, remove_entities,
strike_lightning, create_explosion, generate_tree, kill_entity, tame_entity,
mount_player, set_entity_target, give_mob_equipment, apply_entity_effect,
rename_entity, debug_summary, recent_logs, list_plugins, list_world_entities,
run_console

Safety

GameMasterMC can give the model powerful control over your server. Review your config before enabling public use:

• Use allowed-players to restrict who can talk to the GameMaster.
• Keep allow-console-commands: false unless you explicitly want full console-level access.
• Use a trusted API endpoint, because server state and player information are sent to it.
• Check server logs when testing new models or prompts.