Docs / Minecraft Plugin Operations Reference

Minecraft Plugin Operations Reference

This is the quick operator reference for the _AugmentedIntelligence Minecraft Spigot bridge. Use docs/MinecraftPluginTrainingGuide.md for the full training curriculum and docs/MinecraftIntegration.md for the broader RCON/bridge integration notes.

Lab Topology

Recommended current layout:

EARTH   10.0.0.151 = _AI host, Minecraft client, DQN, optional MathNN
JUPITER 10.0.0.153 = Minecraft/Spigot server, AI bridge plugin
NEPTUNE            = optional always-on training or replay server later

The usual flow is:

JUPITER plugin observes players and world state
JUPITER plugin sends observations/events/rewards to _AI on EARTH
_AI DQN or MathNN selects an action
EARTH client controller presses keys/mouse, or the plugin executes a safe server action
JUPITER plugin records results, safety events, replay data, and metrics

Runtime responsibility split:

Spigot plugin = server observations, safe server actions, arenas, goals, replay, chat delivery, lightweight telemetry
_AI native app = TCP bridge listener, DQN loop, MathNN/RLAgentNet, client keyboard/mouse control, LLM replies, RCON fallback

Keep heavy learning and client input on _AI. Keep the plugin responsive and server-safe.

Build And Deploy

Plugin source:

minecraft_spigot_plugin/

Build:

cd minecraft_spigot_plugin
gradle jar

If Gradle is not on PATH:

.\gradle\bin\gradle.bat jar

Jar output:

minecraft_spigot_plugin/build/libs/AugmentedIntelligenceSpigotBridge-2.0.0.jar

The plugin metadata and Gradle artifact both use version 2.0.0.

Copy the jar to:

<minecraft-server>/plugins/

Restart the Minecraft server after replacing the jar.

Native _AI source:

_AugmentedIntelligence.vcxproj
MinecraftSpigotBridge.cpp
MinecraftDQN.cpp
MinecraftClientController.cpp

Build the Visual Studio project after native changes. For a bridge-only compile check, use MSBuild's selected-file target and adjust the Visual Studio path if needed:

& "C:\Program Files\Microsoft Visual Studio\18\Community\MSBuild\Current\Bin\MSBuild.exe" `
  _AugmentedIntelligence.vcxproj `
  /p:Configuration=Debug `
  /p:Platform=x64 `
  /t:ClCompile `
  /p:SelectedFiles=MinecraftSpigotBridge.cpp `
  /p:CL_MPCount=1

Required Config

On EARTH, start the native bridge inside _AI:

minecraft bridge configure 0.0.0.0 8765 YOUR_LONG_SHARED_TOKEN true
minecraft bridge start
minecraft bridge status

On JUPITER, edit:

plugins/AugmentedIntelligenceBridge/config.yml

Set:

bridge:
  host: "10.0.0.151"
  port: 8765
  token: "YOUR_LONG_SHARED_TOKEN"
  server-id: "jupiter-survival"
  reconnect-seconds: 5
  observation-period-ticks: 20
  send-all-players: true
  primary-player: ""

Optional Minecraft plugin integrations:

plugin-integrations:
  enabled: true
  include-in-observations: true
  include-in-events: true
  observe-teleports: true
  observe-player-plugin-commands: false
  include-plugin-command-arguments: false

The plugin detects common soft dependencies such as Vault, WorldGuard, WorldEdit, LuckPerms, Citizens, PlaceholderAPI, Essentials, CoreProtect, mcMMO, MythicMobs, GriefPrevention, Towny, Factions, Jobs, Quests, ProtocolLib, Multiverse-Core, DecentHolograms, Residence, BentoBox, PlotSquared, dynmap, and BlueMap. Detection adds stable fields to observations and events, but it does not call those plugin APIs or require them to be installed.

For OBJ/MTL model building, keep this disabled until you are intentionally placing a model:

model-build:
  allow-world-edit: false
  directory: "models"
  default-scale: 1.0
  max-scale: 16.0
  max-blocks: 25000
  max-dimension: 256
  blocks-per-tick: 500
  default-material: "stone"
  replace-existing: true

Then run:

/ai reload
/ai connect
/ai status

Expected healthy status:

plugin: connected=true or connected=yes
_AI: spigot_bridge=listening connected=yes observations increasing

Plugin integration smoke test:

/ai integrations status
/ai integrations scan
/ai integrations list
/ai integrations payload YourMinecraftName

Expected result is either detected=0 on a plain server or a comma-separated plugin/capability list when watched plugins are installed.

Useful native status fields:

observations       plugin observation messages received by _AI
events             reward/event messages received by _AI
actions_sent       safe action messages sent back to the plugin
chat_events        player/plugin chat prompts received by _AI
chat_replies       LLM replies sent back to the plugin
chat_controls      native chat memory/control messages received
chat_memory_players players with native chat history
last_error         most recent bridge, action, or chat error

Firewall

On EARTH, allow only JUPITER to reach the bridge port:

Remove-NetFirewallRule -DisplayName "AI Spigot Bridge 8765 from JUPITER" -ErrorAction SilentlyContinue

New-NetFirewallRule `
  -DisplayName "AI Spigot Bridge 8765 from JUPITER" `
  -Direction Inbound `
  -Protocol TCP `
  -LocalPort 8765 `
  -RemoteAddress 10.0.0.153 `
  -Action Allow `
  -Profile Any

From JUPITER:

Test-NetConnection 10.0.0.151 -Port 8765

You want:

TcpTestSucceeded : True

Plugin Permissions And Aliases

Commands:

/ai
/aibridge

Permission:

augmentedintelligence.admin

Default permission holder:

op

Plugin Command Reference

Bridge and diagnostics:

/ai help
/ai status
/ai connect
/ai disconnect
/ai reload
/ai observe
/ai monitor
/ai debug [player]
/ai explain [player]

Manual action execution:

/ai action <id> [player]
/ai dryrun on
/ai dryrun off
/ai qvalues [player]

Safety and movement:

/ai safety
/ai safety on
/ai safety off
/ai safety build-zone on
/ai safety build-zone off
/ai movement status
/ai movement smooth on
/ai movement smooth off
/ai movement ticks <1-40>
/ai movement speed <0.05-1.2>

Chat and coach:

/ai coach on
/ai coach off
/ai coach status
/ai coach explain [player]
/ai chat status
/ai chat on
/ai chat off
/ai chat listen on|off
/ai chat listen-all on|off
/ai chat listen-forward on|off
/ai chat mode mention|listen|all
/ai chat trigger <text>
/ai chat mention <text>
/ai chat require-mention on
/ai chat require-mention off
/ai chat scope <private|nearby|team|global>
/ai chat cooldown <seconds>
/ai chat global-cooldown <seconds>
/ai chat proximity <blocks>
/ai chat model <model-name>
/ai chat system <profile>
/ai chat ask <message>
/ai chat reply <player|@a> <message>
/ai chat transcript [player|global] [lines]
/ai chat clear-memory [player]
/ai chat mute <player-or-uuid>
/ai chat unmute <player-or-uuid>
/ai chat preference <player> <text>
/ai chat metrics
/ai remote <_AI typed command>

Admin remote command examples:

/ai remote minecraft bridge status
/ai remote minecraft dqn status
/ai remote minecraft bridge chat say @a hello from _AI

/ai remote is for server operators only by default. It requires the Bukkit permission augmentedintelligence.admin, remote-commands.enabled: true, and remote-commands.require-op: true unless you change the plugin config.

Plugin integration commands:

/ai integrations status
/ai integrations scan
/ai integrations list
/ai integrations payload [player]
/ai integrations observe on
/ai integrations observe off
/ai integrations events on
/ai integrations events off
/ai integrations commands on
/ai integrations commands off
/ai integrations args on
/ai integrations args off
/ai integrations event <name> [detail]

commands on observes metadata for allowlisted player plugin commands such as /quests, /jobs, /town, /f, /npc, /warp, /home, /tpa, /mcmmo, /claim, /region, /plot, and /island. Arguments are omitted unless args on is enabled.

Goals, quests, curriculum, and teaching:

/ai goal list
/ai goal set <profile> [player]
/ai goal clear [player]
/ai goal status [player]
/ai goal suggest [player]
/ai quest suggest [player]
/ai quest start [player]
/ai curriculum list
/ai curriculum start [phase] [player]
/ai curriculum next [player]
/ai curriculum reset [player]
/ai curriculum stop [player]
/ai curriculum status [player]
/ai teach start [player]
/ai teach stop [player]
/ai teach good [note] [player]
/ai teach bad [note] [player]
/ai teach try <hint> [player]

Arenas, memory, follow, HUD, and replay:

/ai arena create <name> [radius]
/ai arena build <name> [flat|hallway|wall|steps|bridge|pit|obstacle|random]
/ai arena start <name> [goal] [player]
/ai arena reset [player]
/ai arena stop [player]
/ai arena status [player]
/ai model list
/ai model preview <name> [scale] [material]
/ai model build <name> [scale] [material]
/ai model status
/ai model cancel
/ai memory mark <name>
/ai memory list
/ai memory nearest
/ai memory remove <name>
/ai follow <target-player> [follower]
/ai follow stop [follower]
/ai follow status [follower]
/ai hud on
/ai hud off
/ai hud status
/ai replay start
/ai replay stop
/ai replay status
/ai replay file

Operator utilities:

/ai kit miner [player]
/ai kit builder [player]
/ai kit survival [player]
/ai kit torch [player]
/ai kit clear [player]
/ai path [player]
/ai route <from-marker> <to-marker> [player]
/ai mob spawn <zombie|skeleton|spider|creeper> [count] [player]

OBJ/MTL Model Building

The Spigot plugin can convert Wavefront .obj meshes and optional .mtl materials into Minecraft blocks. Files must stay inside the plugin model directory:

plugins/AugmentedIntelligenceBridge/models/

Example server-side files:

plugins/AugmentedIntelligenceBridge/models/tower.obj
plugins/AugmentedIntelligenceBridge/models/tower.mtl

Recommended test sequence:

/ai reload
/ai model list
/ai model preview tower 1.0

Only after the preview block count and dimensions look reasonable:

/ai model build tower 1.0
/ai model status

Use cancel if the build is not what you expected:

/ai model cancel

The build origin is the executing player's current block. The model is centered on X/Z and its lowest OBJ Y coordinate starts at the player's Y level. .mtl Kd diffuse colors map to the closest concrete/stone/plank material. You can override all materials with a Bukkit block material:

/ai model build tower 1.5 stone
/ai model build tower 2.0 white_concrete

This is an approximate surface voxelizer, not a CAD-grade solid fill. Simplify large meshes before importing, start at scale 1.0, and raise model-build.max-blocks only after testing on a private server.

Metrics and plugin ML:

/ai metrics status [player]
/ai metrics actions [player]
/ai metrics reward [player]
/ai metrics recent [player]
/ai metrics prometheus
/ai metrics export
/ai ml status [player]
/ai ml systems
/ai ml train replay
/ai ml behavior [player]
/ai ml bc [player]
/ai ml reward [player]
/ai ml stuck [player]
/ai ml nav [player]
/ai ml planner [player]
/ai ml player [player]
/ai ml roles
/ai ml anomaly
/ai ml grief [player]
/ai ml coach [player]
/ai ml death [player]
/ai ml memory [player]
/ai ml vision request [player]
/ai ml mathnn [player]
/ai ml quest [player]
/ai ml council [player]
/ai ml export

Safe Action IDs

0  observe
1  smooth_forward
2  smooth_back
3  smooth_strafe_left
4  smooth_strafe_right
5  jump
6  smooth_sprint_forward
7  turn_left
8  turn_right
9  break_target_block
10 place_target_block
11 client_hotbar_1
12 client_hotbar_2
13 client_hotbar_3
14 client_hotbar_4
15 client_hotbar_5
16 client_hotbar_6
17 client_hotbar_7
18 client_hotbar_8
19 client_hotbar_9
20 smooth_jump_forward
21 smooth_jump_sprint_forward
22 smooth_forward_left
23 smooth_forward_right
24 look_up
25 look_down
26 sneak
27 swim_up
28 swim_down
29 eat_food
30 select_best_tool
31 place_torch
32 equip_shield
33 use_item
34 open_close_door
35 look_at_nearest_hostile
36 look_at_nearest_item
37 look_at_nearest_player
38 pickup_nearest_item
39 craft_basic_tools
40 smelt_ore
41 sleep_at_night
42 return_safe_zone
43 return_arena_center
90 retreat
91 extinguish
92 return_to_base
93 coach_ping
94 clear_weather
95 set_day
96 save_world

Notes:

Actions 11 through 19 are client hotbar actions. They only matter when _AI controls the Minecraft client.
Action 92 requires safety.allow-return-to-memory: true.
Actions 94 and 95 require safety.allow-weather: true and safety.allow-time: true.
Server actions are intentionally allowlisted. Raw RCON remains separate.

Native `_AI` Command Reference

Bridge:

minecraft bridge status
minecraft bridge configure <host> <port> <token> [autostart]
minecraft bridge start [host] [port] [token]
minecraft bridge stop
minecraft bridge token <token>
minecraft bridge action <action_id> [player]
minecraft bridge remote status
minecraft bridge remote on
minecraft bridge remote off
minecraft bridge remote max-length <characters>
minecraft bridge chat status
minecraft bridge chat on
minecraft bridge chat off
minecraft bridge chat cooldown <seconds>
minecraft bridge chat model <model>
minecraft bridge chat system <profile>
minecraft bridge chat clear [player]
minecraft bridge chat metrics
minecraft bridge chat say <target> <message>

DQN:

minecraft dqn status
minecraft dqn player <selector-or-name>
minecraft dqn observe
minecraft dqn eval
minecraft dqn train [interval_ms]
minecraft dqn off
minecraft dqn step
minecraft dqn dry-run
minecraft dqn qvalues
minecraft dqn explain [top_n]
minecraft dqn interval <milliseconds>
minecraft dqn epsilon <0.0-1.0>
minecraft dqn reward <value> [terminal]
minecraft dqn save [path]
minecraft dqn load [path]

Control mode and client controller:

minecraft dqn control server
minecraft dqn control client
minecraft dqn control both
minecraft dqn wall-guard on|off|status
minecraft dqn unstuck on|off|status
minecraft dqn client status
minecraft dqn client focus on|off
minecraft dqn client foreground on|off
minecraft dqn client hold <milliseconds>
minecraft dqn client mine-hold <milliseconds>
minecraft dqn client use-hold <milliseconds>
minecraft dqn client mine
minecraft dqn client place
minecraft dqn client slot <1-9>
minecraft dqn client look-up
minecraft dqn client look-down
minecraft dqn client action <id>
minecraft dqn client release
minecraft dqn client title <window-title-fragment>

MathNN:

minecraft dqn net on
minecraft dqn net off
minecraft dqn net status
minecraft dqn net save <path>
minecraft dqn net load <path>

RCON fallback:

minecraft status
minecraft configure <host> <port> <password>
minecraft test
minecraft list
minecraft seed
minecraft rcon <raw server command>
minecraft confirm <dangerous raw server command>
minecraft script <path>
minecraft script confirm <path>

Important Config Switches

Safety:

safety:
  enabled: true
  block-unsafe-ai-actions: true
  allow-teleport-nudges: true
  allow-effects: true
  allow-weather: false
  allow-time: false
  allow-save: true
  allow-return-to-memory: false
  restrict-build-to-arena: false

Actions:

actions:
  dry-run: false
  smooth-server-movement: true
  smooth-move-ticks: 8
  smooth-move-speed: 0.28
  sneak-ticks: 30

Chat:

chat:
  enabled: true
  require-mention: true
  listen-all: true          # record all chat into transcripts for LLM context
  listen-forward: true      # passive-forward overheard lines to _AI (no reply)
  trigger: "!ai"
  mention: "@ai"
  scope: "private"
  allow-broadcast: true
  cooldown-seconds: 3
  global-cooldown-seconds: 0
  proximity-radius: 32
  model-hint: ""
  system-profile: "survival_coach"
  allow-action-commands: true
  auto-checkin: false
  clickable-buttons: true
  actionbar: true
  transcript-lines: 50
  blocked-words: []
  muted-players: []
  allow-players: []

Chat modes:

mention — only !ai / @ai is ingested or answered
listen (default with listen-all) — read all chat, reply only on mention
all — reply to every chat line (use cooldowns; can spam)

Arena:

arena:
  allow-world-edit: false
  max-radius: 32
  auto-reset-on-death: true
  leash-to-arena: true

Replay and ML:

replay:
  enabled: false
  directory: "replay"

ml:
  enabled: true
  replay-train-max-files: 25
  replay-train-max-lines: 20000

Runtime Files

Plugin data folder:

plugins/AugmentedIntelligenceBridge/

Important files:

config.yml
memory.yml
replay/*.jsonl

Native _AI local config files:

minecraft_spigot_bridge.local.txt
minecraft_rcon_config.local.txt

DQN files are written under the configured gaming RL log directory. Common files include:

minecraft_dqn_checkpoint.txt
minecraft_dqn_transitions.csv

Safe Startup Checklist

In Minecraft:

/ai status
/ai safety on
/ai coach on
/ai hud on
/ai replay start
/ai dryrun on
/ai observe
/ai chat status

In _AI:

minecraft bridge status
minecraft bridge chat metrics
minecraft dqn player YourMinecraftName
minecraft dqn control client
minecraft dqn client focus on
minecraft dqn client hold 900
minecraft dqn client mine-hold 1800
minecraft dqn client use-hold 350
minecraft dqn wall-guard on
minecraft dqn unstuck on
minecraft dqn observe
minecraft dqn dry-run

Quick end-to-end chat test:

!ai what should I do next?
minecraft bridge chat metrics
/ai chat transcript YourMinecraftName 8

When dry-run and manual input tests are correct:

/ai dryrun off
minecraft dqn step

Use autonomous training only after single-step behavior is sane:

minecraft dqn train 1000

Stop immediately:

minecraft dqn off
minecraft dqn client release

Troubleshooting

Bridge not connected:

minecraft bridge status
/ai status
Test-NetConnection 10.0.0.151 -Port 8765

Common causes:

wrong bridge.host in config.yml
token mismatch
EARTH firewall blocking TCP 8765
_AI bridge not started
old plugin jar still loaded

DQN does not move:

minecraft dqn status
minecraft dqn client status
/ai dryrun off