This guide explains how the _AugmentedIntelligence Minecraft Spigot plugin, bridge, Minecraft DQN, client controller, and MathNN neural policy fit together.

Related documentation:

[text]
docs/MinecraftPluginOperations.md = quick operator reference, full command list, config switches, troubleshooting
docs/MinecraftIntegration.md      = bridge vs. RCON integration overview
docs/ReinforcementLearning.md     = RL hub (MathNN, curriculum, executive plans)
docs/MathNN.md                    = neural policy modes and rl net commands
minecraft_spigot_plugin/README.md = plugin build/deploy quick reference

The recommended architecture for your current lab is:

[text]
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 AI/training server later

The practical target is:

[text]
JUPITER plugin observes world/player state
JUPITER plugin sends rewards/events to _AI
_AI DQN/MathNN chooses an action
EARTH client controller presses keys/mouse in your Minecraft client
JUPITER plugin keeps providing safety, arena, goal, and replay data

Components

Spigot Plugin

Location:

[text]
minecraft_spigot_plugin/

Runtime command aliases:

[text]
/ai
/aibridge

Required permission:

[text]
augmentedintelligence.admin

The plugin runs on the Minecraft server. It is responsible for:

[text]
observations
events and rewards
safety checks
training arenas
goal profiles
coach mode
memory markers
replay logging
manual safe actions
optional context from common Spigot plugins such as Vault, WorldGuard, Citizens, Jobs, Quests, Towny, Factions, mcMMO, CoreProtect, PlotSquared, and BentoBox

It is not meant to run heavy neural training. Training belongs in _AI.

Native Bridge

The bridge is inside _AI. It listens for the Spigot plugin and receives JSON-lines messages.

Useful commands:

[text]
minecraft bridge configure 0.0.0.0 8765 YOUR_TOKEN true
minecraft bridge start
minecraft bridge status
minecraft bridge stop

Minecraft DQN

Minecraft DQN is inside _AI. It reads the latest Minecraft state, chooses actions, records transitions, and trains from rewards.

Useful commands:

[text]
minecraft dqn status
minecraft dqn player YourMinecraftName
minecraft dqn observe
minecraft dqn eval
minecraft dqn step
minecraft dqn train 1000
minecraft dqn off

Client Controller

Client control lets DQN play through the Minecraft client running on EARTH.

Useful commands:

[text]
minecraft dqn control client
minecraft dqn client status
minecraft dqn client focus on
minecraft dqn client foreground on
minecraft dqn client hold 900
minecraft dqn client mine-hold 1800
minecraft dqn client use-hold 350
minecraft dqn client mine
minecraft dqn client place
minecraft dqn client slot 1
minecraft dqn client look-up
minecraft dqn unstuck on
minecraft dqn wall-guard status

Client control sends local keyboard/mouse input to the Minecraft window. Movement actions hold their keys for movement_hold_ms so walking and sprinting feel continuous while _AI waits for the next server observation. The Spigot plugin still provides observations, rewards, wall/collision sensors, safety events, arenas, goals, and replay logs.

MathNN / RLAgentNet

MathNN is the in-process neural-network backend. RLAgentNet wraps it as a reusable DQN learner for agents such as Minecraft, driving, gaming FPS, and strategy.

Useful commands:

[text]
minecraft dqn net on
minecraft dqn net status
minecraft dqn net save minecraft_mathnn_checkpoint.txt
minecraft dqn net load minecraft_mathnn_checkpoint.txt

MathNN brings:

[text]
neural Q-value prediction
better generalization than simple tables or tiny hardcoded models
shared RL infrastructure
save/load checkpoints
future offline replay training
metrics such as loss and observe count

MathNN does not press keys. It decides actions. The client controller executes those actions.

Executive Functions planner (high-level steps)

Minecraft DQN can advance Executive Functions plan steps alongside low-level

motor actions. Setting a goal seeds a Minecraft-tagged plan (wall-guard, net on,

observe, vision status, etc.). Each train/eval step advances one executive

step by default (setup/safety only — nested train/step from the planner is blocked).

[text]
minecraft dqn plan on
minecraft dqn goal mine iron_ore
minecraft dqn plan detail
minecraft dqn plan next 2
minecraft dqn train 1000
minecraft dqn plan status
minecraft dqn plan steps 1
minecraft dqn plan off

Build

Build The Spigot Plugin

From the repo root:

[powershell]
cd minecraft_spigot_plugin
gradle jar

If Gradle is not on PATH, use the local Gradle launcher:

[powershell]
.\gradle\bin\gradle.bat jar

The jar is written to:

[text]
minecraft_spigot_plugin/build/libs/AugmentedIntelligenceSpigotBridge-2.0.0.jar

Copy that jar to JUPITER:

[text]
<minecraft-server>/plugins/

Restart the Minecraft server after replacing the jar.

Build _AI

Build the Visual Studio project after native code changes. In this workspace the project is:

[text]
_AugmentedIntelligence.vcxproj

The Minecraft client controller is included in the project as:

[text]
MinecraftClientController.cpp
MinecraftClientController.hpp

For a focused bridge compile after editing Minecraft bridge code, use MSBuild’s selected-file target:

[powershell]
& “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

Use the full Visual Studio build before shipping a complete _AI binary. The selected-file compile only proves that the bridge source compiles against the current project settings.

Network Setup

EARTH

EARTH runs _AI and the Minecraft client.

Inside _AI:

[text]
minecraft bridge configure 0.0.0.0 8765 YOUR_LONG_SHARED_TOKEN true
minecraft bridge start
minecraft bridge status

PowerShell as Administrator on EARTH:

[powershell]
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

JUPITER

JUPITER runs the Minecraft/Spigot server.

In:

[text]
plugins/AugmentedIntelligenceBridge/config.yml

Set:

[yaml]
bridge:
  host: “10.0.0.151”
  port: 8765
  token: “YOUR_LONG_SHARED_TOKEN”
  server-id: “jupiter-survival”

Then restart the Minecraft server or run:

[text]
/ai reload
/ai connect
/ai status

Test from JUPITER:

[powershell]
Test-NetConnection 10.0.0.151 -Port 8765

You want:

[text]
TcpTestSucceeded : True

Plugin Configuration Reference

The plugin config is generated at:

[text]
plugins/AugmentedIntelligenceBridge/config.yml

The bridge section should point from JUPITER to EARTH:

[yaml]
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: “”

Important safety and action defaults:

[yaml]
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:
  dry-run: false
  smooth-server-movement: true
  smooth-move-ticks: 8
  smooth-move-speed: 0.28
  sneak-ticks: 30

Keep these defaults conservative during early training:

[text]
safety.enabled=true
safety.allow-return-to-memory=false
safety.allow-weather=false
safety.allow-time=false
arena.allow-world-edit=false
chat.require-mention=true
chat.listen-all=true
chat.listen-forward=true

Only enable arena.allow-world-edit when you are ready for /ai arena build

to place blocks in the world. Only enable safety.allow-return-to-memory when

you want action 92 to teleport a player to /ai memory mark base.

Plugin Commands

Bridge

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

Plugin Integrations

[text]
/ai integrations status
/ai integrations scan
/ai integrations list
/ai integrations payload [player]
/ai integrations observe on|off
/ai integrations events on|off
/ai integrations commands on|off
/ai integrations args on|off

Use integration fields as curriculum context, not as direct control. WorldGuard, GriefPrevention, Towny, Factions, Residence, and PlotSquared explain protected regions or claims. Vault, Jobs, Quests, mcMMO, Citizens, and MythicMobs can become reward or objective signals. Command observation is off by default; enable it only when you want metadata about allowlisted plugin commands included in bridge events.

Manual Actions

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

Current plugin-side action IDs:

[text]
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

Actions 11 through 19 are client hotbar actions and only have an effect when _AI is controlling the Minecraft client. Action 92 is disabled by default. Enable:

[yaml]
safety:
  allow-return-to-memory: true

only if you want the plugin to teleport players to /ai memory mark base.

Actions 94 and 95 require safety.allow-weather: true and

safety.allow-time: true. These stay disabled by default so training cannot

silently change server weather or time.

Safety

[text]
/ai safety
/ai safety on
/ai safety off
/ai safety build-zone on
/ai safety build-zone off

Safety checks include:

[text]
low health
low food
nearby hostiles
near lava
fall risk
burning
dead player

Coach

[text]
/ai coach on
/ai coach off
/ai coach status
/ai coach explain [player]
/ai explain [player]

Coach mode gives local survival advice and is useful during early training.

LLM Chat

The plugin can forward player chat to _AI, where the configured LLM/router generates a concise Minecraft chat reply. Each chat prompt includes the player message plus Minecraft context: health, food, biome, selected item, active goal, arena, safety state, nearby players, nearby hostiles, nearest memory, player preference, and recent transcript.

Default player usage:

[text]
!ai what should I do next?
@ai where is base?

Core plugin controls:

[text]
/ai chat status
/ai chat on
/ai chat off
/ai chat trigger !ai
/ai chat mention @ai
/ai chat require-mention on
/ai chat scope private
/ai chat scope nearby
/ai chat scope team
/ai chat scope global
/ai chat cooldown 3
/ai chat model llama3
/ai chat system survival_coach
/ai chat ask what should I do next?
/ai chat transcript YourPlayer 12
/ai chat clear-memory YourPlayer
/ai chat mute PlayerName
/ai chat unmute PlayerName
/ai chat preference YourPlayer short tactical survival advice
/ai chat metrics

_AI bridge controls:

[text]
minecraft bridge chat status
minecraft bridge chat metrics
minecraft bridge chat on
minecraft bridge chat off
minecraft bridge chat cooldown 3
minecraft bridge chat model llama3
minecraft bridge chat system survival_coach
minecraft bridge chat clear YourPlayer
minecraft bridge chat say @a hello from _AI

Training use:

[text]
!ai collect wood
!ai mine iron
!ai return to base
!ai survive
!ai start flatwalk training
!ai next phase
!ai good
!ai bad
!ai try turn left when blocked
!ai remember this as base
!ai what happened last run
!ai why did you do that

With chat.require-mention=true, the bot only replies when a player uses !ai / @ai. With chat.listen-all=true (default), ordinary player chat is still read: it is stored in transcripts and passively forwarded to _AI for context (expect_reply=false), so the next mention can use recent server chat. Use /ai chat mode listen for that setup, /ai chat mode mention to ignore unmentioned chat entirely, or /ai chat mode all to answer every line. Use chat.scope=private while training one player, nearby for small co-op testing, and global only for operator announcements.

Memory

[text]
/ai memory mark base
/ai memory mark mine
/ai memory mark village
/ai memory list
/ai memory nearest
/ai memory remove base

Memory markers are stored per player in:

[text]
plugins/AugmentedIntelligenceBridge/memory.yml

Replay Logging

[text]
/ai replay start
/ai replay status
/ai replay stop
/ai replay file
/ai replay export

Replay logs are JSONL files under:

[text]
plugins/AugmentedIntelligenceBridge/replay/

These logs are useful for offline training and debugging.

Goals

[text]
/ai goal list
/ai goal set survive_60 [player]
/ai goal set mob_avoidance [player]
/ai goal set collect_wood [player]
/ai goal set mine_iron [player]
/ai goal set return_to_base [player]
/ai goal status [player]
/ai goal clear [player]
/ai goal suggest [player]

Goal profiles currently include:

[text]
survive_60
mob_avoidance
collect_wood
mine_iron
return_to_base

Quests

[text]
/ai quest suggest [player]
/ai quest start [player]

Quest commands choose a goal based on the player state.

Follow Mode

[text]
/ai follow <target-player> [follower]
/ai follow stop [follower]
/ai follow status [follower]

Follow mode is useful for guided data collection. Let the bot follow a real player through routes you want it to learn, keep replay logging enabled, then repeat the same area without follow mode during DQN training.

HUD

[text]
/ai hud on
/ai hud off
/ai hud status

The HUD shows training-relevant state in-game, including goal, arena, follow status, health, food, held item, target block, and position.

Curriculum, Teaching, And Metrics

[text]
/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]
/ai metrics status [player]
/ai metrics actions [player]
/ai metrics reward [player]
/ai metrics recent [player]
/ai metrics prometheus
/ai metrics export
/ai metrics dashboard
/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 coach [player]
/ai ml death [player]
/ai ml roles
/ai ml anomaly
/ai ml grief [player]
/ai ml memory [player]
/ai ml mathnn [player]
/ai ml vision request [player]
/ai ml quest [player]
/ai ml council [player]
/ai ml export
/ai ml dashboard

The curriculum runner creates/starts phase arenas and applies the matching goal profile. Teaching commands write replay records and send small reward/correction events. Metrics track action distribution, repeated-action loops, reward totals, death snapshots, and dashboard export data.

The /ai ml commands add lightweight server-side models around that data. They do not replace the DQN or MathNN learner in _AI; they provide live summaries and bridge requests:

[text]
replay trainer = scans bounded replay JSONL files and summarizes observations/actions/events
behavior cloning = counts demonstrated and successful actions into action priors
reward model = summarizes events, rewards, and teach good/bad feedback
stuck classifier = detects low-motion and blocked-direction states
navigability model = scores forward/left/right/back and terrain signatures
hierarchical planner = chooses a local plan from safety, stuck state, goal, and memory
player model = tracks chat intent, preferences, rough skills, spam/toxicity signals
roles/council = suggests miner/builder/guard/coach/explorer roles for online players
anomaly/grief = watches server tick timing and rapid block edits outside arenas
coach/death = sends structured bridge requests for LLM session coaching and death review
mathnn/vision = sends bridge requests for `_AI`/EARTH-side neural or screenshot systems

Arenas

[text]
/ai arena create survival 12
/ai arena start survival survive_60 YourMinecraftName
/ai arena status YourMinecraftName
/ai arena reset YourMinecraftName
/ai arena stop YourMinecraftName

By default, arena creation only records an arena marker. It does not edit blocks.

The command below edits the world only if enabled:

[text]
/ai arena build survival flat
/ai arena build survival hallway
/ai arena build survival wall
/ai arena build survival steps
/ai arena build survival bridge
/ai arena build survival pit
/ai arena build survival obstacle
/ai arena build survival random

To enable block editing:

[yaml]
arena:
  allow-world-edit: true

Keep this off until you are ready to let the plugin place floor/fence/torch blocks.

Use flat for first movement tests, wall and hallway for stuck recovery, steps and pit for jump timing, bridge for block placement and path correction, and obstacle for mixed navigation.

Operator Utilities

[text]
/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]

Kits are training aids for controlled sessions. path reports why forward,

left, right, or back is blocked from the player’s current yaw. route measures

distance between two memory markers in the same world. mob spawn is for

controlled survival-pressure tests; keep counts low and use arenas.

DQN Commands

Observation and Planning

[text]
minecraft dqn status
minecraft dqn player YourMinecraftName
minecraft dqn observe
minecraft dqn eval
minecraft dqn dry-run
minecraft dqn qvalues
minecraft dqn explain 10

Meanings:

[text]
observe = read latest state
eval    = choose/check current policy mode
dry-run = choose action without sending it
qvalues = show the compact DQN’s top legal action values
explain = show planned action plus top legal Q-values

Single-Step Training

[text]
minecraft dqn step

step does one RL cycle:

[text]
observe current state
choose one action
send that action
observe next state
collect reward/event feedback
store transition
train once if mode=train
stop

Use step for early testing.

Autonomous Training

[text]
minecraft dqn train 1000

train [interval_ms] starts a background loop that repeatedly runs step.

Stop it with:

[text]
minecraft dqn off

or:

[text]
minecraft dqn eval
minecraft dqn observe

Change the delay:

[text]
minecraft dqn interval 2000

Check whether it is running:

[text]
minecraft dqn status

Look for:

[text]
mode=train
auto_train=running

Control Modes

Server Control

[text]
minecraft dqn control server

Actions are sent to the Spigot bridge or RCON. This is useful for server automation and safe allowlisted actions.

Client Control

[text]
minecraft dqn control client

Actions are sent as keyboard/mouse input to your local Minecraft client on EARTH.

Client action mapping:

[text]
0 observe
1 W / forward
2 S / back
3 A / strafe left
4 D / strafe right
5 space / jump
6 ctrl+W / sprint forward
7 mouse turn left
8 mouse turn right
9 left click / attack
10 right click / use or place
11 hotbar slot 1
12 hotbar slot 2
13 hotbar slot 3
14 hotbar slot 4
15 hotbar slot 5
16 hotbar slot 6
17 hotbar slot 7
18 hotbar slot 8
19 hotbar slot 9
20 W+space / jump forward
21 ctrl+W+space / sprint jump forward
22 W+A / forward left
23 W+D / forward right
24 mouse look up
25 mouse look down

Useful client commands:

[text]
minecraft dqn client status
minecraft dqn client focus on
minecraft dqn client foreground on
minecraft dqn client title Minecraft
minecraft dqn client hold 900
minecraft dqn client mine-hold 1800
minecraft dqn client use-hold 350
minecraft dqn client mine
minecraft dqn client action 9
minecraft dqn client place
minecraft dqn client action 10
minecraft dqn client release
minecraft dqn wall-guard on
minecraft dqn wall-guard status

Recommended for client control:

[text]
Minecraft window open on EARTH
Minecraft connected to JUPITER
Minecraft window in foreground
_AI running on EARTH
Spigot bridge connected
wall_guard=on
movement_hold_ms=900

When wall_guard=on, DQN avoids choosing client movement actions that the plugin reports as blocked. Blocked movement attempts are also penalized in the reward function so the policy learns to turn, back up, strafe, jump, or attack instead of holding forward into a wall.

minecraft dqn client hold <milliseconds> controls how long movement keys stay down for forward, back, strafe, and sprint actions. Sprint holds W plus left control for this duration. minecraft dqn client mine-hold <milliseconds> controls how long the left mouse button is held for the client_mine_hold action, which is what lets the DQN break blocks instead of only tapping attack. minecraft dqn client use-hold <milliseconds> controls how long right mouse is held for the client_place_hold action. Use minecraft dqn client mine or minecraft dqn client action 9 to manually test mining, minecraft dqn client place or minecraft dqn client action 10 to manually test right-click block placement/use, and minecraft dqn client slot <1-9> to test hotbar selection. Use minecraft dqn client release if you ever need to force held movement or mouse input up.

Server-side movement actions can be smoothed by the Spigot plugin instead of teleporting one block at a time:

[text]
/ai movement status
/ai movement smooth on
/ai movement ticks 8
/ai movement speed 0.28

Additional plugin features:

[text]
/ai follow <target-player> [follower]
/ai hud on
/ai safety build-zone on
/ai replay file
/ai arena build <name> hallway|wall|steps|bridge|pit|obstacle

The plugin observation includes target block, target distance/hardness, placeable-face, hotbar slot, selected item count, inventory tool flags, food/block availability, wood/cobblestone/torch counts, yaw/pitch, and local block-grid signals. These fields give the DQN enough context to learn when to mine, place, switch hotbar slots, jump, or turn.

Hybrid Control

[text]
minecraft dqn control both

This sends client actions and server actions. Use this only for debugging because it can double-apply effects.

MathNN Training

Enable MathNN-backed neural DQN:

[text]
minecraft dqn net on
minecraft dqn net status

Save/load:

[text]
minecraft dqn net save minecraft_mathnn_checkpoint.txt
minecraft dqn net load minecraft_mathnn_checkpoint.txt

MathNN is useful because it can learn a state-to-Q-values function:

[text]
state -> Q(action 0), Q(action 1), … Q(action N)

That lets the agent generalize across similar states. The built-in compact DQN can work for smoke tests, but MathNN is the better long-term backend.

Recommended MathNN workflow:

[text]
1. Run plugin replay logging.
2. Train with single-step DQN in a controlled arena.
3. Enable MathNN with minecraft dqn net on.
4. Run short autonomous training windows.
5. Save checkpoints after stable behavior.
6. Later, train offline on NEPTUNE from replay logs.

First Safe Training Run

Use this sequence when starting fresh.

In Minecraft

[text]
/ai status
/ai safety
/ai coach on
/ai memory mark base
/ai replay start
/ai dryrun on
/ai arena create survival 12
/ai arena start survival survive_60 YourMinecraftName
/ai goal status YourMinecraftName

In _AI

[text]
minecraft bridge status
minecraft dqn player YourMinecraftName
minecraft dqn control client
minecraft dqn client status
minecraft dqn client focus on
minecraft dqn client hold 900
minecraft dqn client mine-hold 1800
minecraft dqn client use-hold 350
minecraft dqn client mine
minecraft dqn client place
minecraft dqn observe
minecraft dqn dry-run

If dry-run looks sane:

[text]
/ai dryrun off

Then run single steps:

[text]
minecraft dqn step
minecraft dqn status

Repeat manually 10 to 20 times.

If it behaves safely:

[text]
minecraft dqn train 1000

Stop it:

[text]
minecraft dqn off

Training Curriculum

Train one behavior at a time. Do not start in open survival and expect useful learning: the action space includes movement, camera control, mining, placing, and hotbar selection, so the early reward signal must be simple and repeatable.

Use this rule for promotion:

[text]
Promote only when the agent completes the current phase 3 runs in a row without death, safety intervention, or repeated wall pushing.

Use this rule for rollback:

[text]
If the agent dies twice in 10 minutes or gets stuck for more than 30 seconds, stop training, reset the arena, and go back one phase.

Standard Session Setup

Run this at the start of every training session.

In Minecraft:

[text]
/ai status
/ai safety on
/ai coach on
/ai hud on
/ai replay start
/ai memory mark base
/ai integrations status

In _AI:

[text]
minecraft bridge status
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 status

Use MathNN once the basic loop is stable:

[text]
minecraft dqn net on
minecraft dqn net status

Keep training windows short. Start with minecraft dqn train 1000, stop after 2 to 5 minutes, inspect behavior, then continue. Faster intervals such as 250 or 500 are useful only after observations are clearly updating and the client is responding correctly.

Phase 0: Bridge And Sensor Baseline

Goal:

[text]
prove the plugin, bridge, observations, rewards, and replay logging work before learning starts

Commands:

[text]
/ai observe
/ai debug YourMinecraftName
minecraft bridge status
minecraft dqn observe
minecraft dqn dry-run

Watch for:

[text]
connected=yes
observations increasing
health and food correct
target_block_type present
hotbar_slot present
blocked={…} present
plugin_integrations_count present

Promote when:

[text]
three consecutive observe calls show fresh state
dry-run selects an action without sending it
replay logging is active

Phase 1: Manual Client Calibration

Goal:

[text]
prove every physical input works through your Minecraft client on EARTH

Commands:

[text]
minecraft dqn control client
minecraft dqn client status
minecraft dqn client focus on
minecraft dqn client action 1
minecraft dqn client action 6
minecraft dqn client action 7
minecraft dqn client action 8
minecraft dqn client action 20
minecraft dqn client action 21
minecraft dqn client look-up
minecraft dqn client look-down
minecraft dqn client slot 1
minecraft dqn client slot 2
minecraft dqn client mine
minecraft dqn client place
minecraft dqn client release

Promote when:

[text]
forward and sprint move smoothly
turn actions rotate the camera
look up/down changes pitch
hotbar slots change
left mouse holds long enough to break a soft block
right mouse places or uses the held item

If movement is choppy, raise the hold time:

[text]
minecraft dqn client hold 1100

If mining only taps, raise the mine hold:

[text]
minecraft dqn client mine-hold 2400

Phase 2: Flat Arena Locomotion

Goal:

[text]
learn that forward, turn, strafe, jump, and sprint affect position without danger

In Minecraft:

[text]
/ai arena create flatwalk 12
/ai arena build flatwalk flat
/ai arena start flatwalk survive_60 YourMinecraftName
/ai goal set survive_60 YourMinecraftName

In _AI:

[text]
minecraft dqn observe
minecraft dqn step
minecraft dqn status

Run 10 to 20 manual steps first. Then:

[text]
minecraft dqn train 1000

Promote when:

[text]
the player moves around the arena instead of idling
health remains stable
blocked movement is rare
no death or safety intervention occurs for 3 short runs

Save a baseline checkpoint:

[text]
minecraft dqn save
minecraft dqn net save minecraft_phase02_flatwalk.txt

Phase 3: Wall And Hallway Recovery

Goal:

[text]
learn not to hold forward into walls and learn to turn, back up, strafe, jump, or mine when blocked

Use a simple wall first:

[text]
/ai arena create walltest 10
/ai arena build walltest wall
/ai arena start walltest survive_60 YourMinecraftName
/ai goal set survive_60 YourMinecraftName

Then use a hallway:

[text]
/ai arena create hallway 12
/ai arena build hallway hallway
/ai arena start hallway survive_60 YourMinecraftName

In _AI:

[text]
minecraft dqn wall-guard on
minecraft dqn unstuck on
minecraft dqn train 1000

Watch for:

[text]
blocked_forward changing correctly
turn_left or turn_right after blocked_forward
back, strafe, jump_forward, or break_target_block when blocked
stuck_ticks staying low in minecraft dqn status

Promote when:

[text]
the agent recovers from a wall contact within 5 seconds
it does not repeatedly press forward into the same wall
it can travel through the hallway for 3 runs without manual rescue

Phase 4: Jump Timing And Uneven Terrain

Goal:

[text]
learn jump_forward, sprint_jump_forward, pitch control, and recovery around ledges

Use steps first:

[text]
/ai arena create steps 12
/ai arena build steps steps
/ai arena start steps survive_60 YourMinecraftName

Then use a pit:

[text]
/ai arena create pit 12
/ai arena build pit pit
/ai arena start pit survive_60 YourMinecraftName

Train slowly:

[text]
minecraft dqn train 1000

Promote when:

[text]
the agent climbs simple steps
the agent avoids repeatedly falling into the pit
fall-risk safety events are rare
the agent uses jump_forward or sprint_jump_forward when elevation changes

Phase 5: Target Block Mining

Goal:

[text]
learn when looking at a breakable block should trigger mining instead of movement

Manual setup:

[text]
put a wooden, dirt, stone, or low-hardness target block inside the arena
put the correct tool in hotbar slot 1 or slot 2
face the player toward the target block

Commands:

[text]
minecraft dqn client slot 1
minecraft dqn client mine
minecraft dqn observe
/ai goal set collect_wood YourMinecraftName
minecraft dqn train 1000

Watch for:

[text]
target_block_type is not air
target_block_breakable=true
target_block_distance is reasonable
has_pickaxe or has_axe is true when the tool is carried
block_break events appear in replay logs

Promote when:

[text]
the agent breaks visible soft blocks reliably
it does not mine air for long periods
it switches away from movement when a useful target block is directly in front

Phase 6: Block Placement And Bridging

Goal:

[text]
learn hotbar selection, right-click placement, and correction around gaps

Manual setup:

[text]
put blocks in hotbar slot 2 or slot 3
stand near a safe gap or bridge arena

Commands:

[text]
/ai arena create bridge 12
/ai arena build bridge bridge
/ai arena start bridge survive_60 YourMinecraftName
minecraft dqn client slot 2
minecraft dqn client place
minecraft dqn observe
minecraft dqn train 1000

Watch for:

[text]
has_placeable_blocks=true
target_placeable_face=true near usable faces
block_place events in replay logs
fewer falls after placement begins

Promote when:

[text]
the agent places blocks only near valid faces
it crosses or repairs simple gaps in 3 consecutive runs
it does not spam right-click into empty air

Phase 7: Resource Goals

Goal:

[text]
connect movement, camera control, hotbar, mining, and inventory changes to goal rewards

Start with wood:

[text]
/ai goal set collect_wood YourMinecraftName
minecraft dqn train 1000

Then use stone or iron when tools and target blocks are available:

[text]
/ai goal set mine_iron YourMinecraftName
minecraft dqn train 1000

Watch for:

[text]
wood_count or cobblestone_count increasing
block_break events with positive rewards
less random movement after target blocks appear

Promote when:

[text]
inventory counts increase during training
the agent faces and mines useful blocks more often than empty space
the agent survives the resource task without repeated rescue

Phase 8: Survival Pressure

Goal:

[text]
learn to avoid damage, hunger, hostiles, lava, fire, and fall risk

Start on easy, controlled terrain:

[text]
/ai goal set mob_avoidance YourMinecraftName
/ai safety on
minecraft dqn train 1000

Increase difficulty gradually:

[text]
add one hostile nearby
train for 2 minutes
reset the arena
repeat

Watch for:

[text]
nearby_hostiles
health changes
food changes
safety events
death events
retreat or evasive movement

Promote when:

[text]
the agent avoids repeated damage
it moves away from danger more often than toward it
death does not dominate replay logs

Phase 9: Return To Base And Follow Mode

Goal:

[text]
learn recovery behavior around a known base marker and player-guided sessions

Commands:

[text]
/ai memory mark base
/ai goal set return_to_base YourMinecraftName
/ai follow YourMinecraftName BotPlayer
/ai follow status BotPlayer
minecraft dqn train 1000

Use follow mode as a guided data collection tool. Walk routes that demonstrate useful behavior, keep replay logging on, then train in the same area without follow mode.

Promote when:

[text]
the agent stays near the player during guided sessions
the agent recovers toward base after wandering
follow mode can be stopped without the agent immediately getting lost

Phase 10: Mixed Obstacle Arena

Goal:

[text]
combine movement, mining, placing, hotbar use, survival sensors, and stuck recovery

Commands:

[text]
/ai arena create mixed 16
/ai arena build mixed obstacle
/ai arena start mixed survive_60 YourMinecraftName
/ai goal suggest YourMinecraftName
minecraft dqn net on
minecraft dqn train 1000

Training pattern:

[text]
2 minutes train
minecraft dqn off
minecraft dqn status
/ai replay status
/ai arena reset YourMinecraftName
repeat 3 to 5 times

Promote when:

[text]
the agent survives the mixed arena
it uses several different actions instead of one dominant action
stuck recovery works without constant manual intervention
reward trend improves over repeated runs

Phase 11: Open Survival Trials

Goal:

[text]
test whether arena skills transfer to normal gameplay

Rules:

[text]
keep safety on
keep replay logging on
start close to base
train in 2 to 5 minute windows
stop after any death
save checkpoints only after stable runs

Commands:

[text]
/ai memory mark base
/ai goal suggest YourMinecraftName
minecraft dqn train 1000
minecraft dqn off
minecraft dqn save
minecraft dqn net save minecraft_open_survival_candidate.txt

Promote when:

[text]
the agent can move, recover from obstacles, mine simple targets, place blocks, and survive short windows near base

Checkpoint Discipline

Use a checkpoint per phase. Do not overwrite the last good checkpoint during experiments.

Suggested names:

[text]
minecraft_phase02_flatwalk.txt
minecraft_phase03_hallway.txt
minecraft_phase04_steps.txt
minecraft_phase05_mining.txt
minecraft_phase06_placement.txt
minecraft_phase10_mixed.txt
minecraft_open_survival_candidate.txt

Save after stable behavior:

[text]
minecraft dqn save
minecraft dqn net save minecraft_phase03_hallway.txt

Load the last stable checkpoint after a bad run:

[text]
minecraft dqn off
minecraft dqn net load minecraft_phase03_hallway.txt

Reading Training Health

Good signs:

[text]
observations increase every step
actions vary by context
wall contacts become shorter
block_break and block_place rewards appear when expected
death events are rare
reward improves over repeated short runs

Bad signs:

[text]
same action repeats forever
obs counter does not change
dry-run is still enabled
Minecraft client is not foreground
wall_guard is off during obstacle phases
replay is mostly death, damage, or blocked movement

When behavior degrades:

[text]
minecraft dqn off
minecraft dqn client release
/ai arena reset YourMinecraftName
minecraft dqn observe
minecraft dqn dry-run

Then return to the last phase that was stable.

Plugin ML Systems

The current system supports client movement, hotbar selection, looking, mining, placing, target-block observations, inventory observations, unstuck recovery, arenas, follow mode, HUD, replay logging, plugin integration context, MathNN-backed DQN in _AI, and plugin-side ML telemetry.

Run these after a training session:

[text]
/ai ml train replay
/ai ml status YourMinecraftName
/ai ml behavior YourMinecraftName
/ai ml reward YourMinecraftName
/ai ml stuck YourMinecraftName
/ai ml nav YourMinecraftName
/ai ml planner YourMinecraftName
/ai ml death YourMinecraftName
/ai ml export

Use these during multiplayer or open-survival tests:

[text]
/ai ml roles
/ai ml council YourMinecraftName
/ai ml anomaly
/ai ml grief YourMinecraftName
/ai ml coach YourMinecraftName

Use these to hand work back to _AI or the EARTH client controller:

[text]
/ai ml mathnn YourMinecraftName
/ai ml vision request YourMinecraftName

/ai ml mathnn packages replay and model context for the _AI process where MathNN checkpoints and neural training belong. /ai ml vision request packages a request for client-side screenshot/OCR/object/minimap perception; a headless Spigot server cannot see the Minecraft client window.

Troubleshooting

Bridge Not Connected

Check _AI:

[text]
minecraft bridge status

Check plugin:

[text]
/ai status

Test from JUPITER:

[powershell]
Test-NetConnection 10.0.0.151 -Port 8765

Common causes:

[text]
wrong plugin host
token mismatch
EARTH firewall blocking TCP 8765
_AI bridge not started
plugin not loaded
duplicate or malformed bridge section in config.yml

DQN Does Not Move

Check:

[text]
minecraft dqn status
minecraft dqn client status
/ai dryrun off
/ai safety

Common causes:

[text]
mode is not train
auto_train is stopped
control mode is server instead of client
Minecraft window is not foreground
dry-run is enabled
safety is blocking actions
chosen action is observe/no-op

Client Control Fails

Run:

[text]
minecraft dqn client status

If no window is found:

[text]
minecraft dqn client title Minecraft

If the window is not foreground:

[text]
minecraft dqn client focus on

Then click into the Minecraft client and try:

[text]
minecraft dqn step

DQN Walks Into Walls

Stop the loop first:

[text]
minecraft dqn off

Verify that the plugin is sending blocked-direction sensors:

[text]
minecraft dqn observe

Look for:

[text]
obs=123
blocked={f:yes,l:no,r:no,b:no}

Then make sure the client wall guard is on:

[text]
minecraft dqn wall-guard status
minecraft dqn wall-guard on

Test one action at a time:

[text]
minecraft dqn dry-run
minecraft dqn step

If blocked={…} never appears in observe, rebuild and reinstall the Spigot plugin jar on JUPITER, restart the server, and reconnect the bridge.

If obs= does not change between steps, the DQN is training faster than the server is sending observations. The native step loop waits for a fresh observation after executed actions, but you should still prefer minecraft dqn train 500 or minecraft dqn train 1000 until behavior is stable.

Training Gets Player Killed

Stop immediately:

[text]
minecraft dqn off

Reset:

[text]
/ai arena reset YourMinecraftName
/ai safety

Then return to single-step testing:

[text]
minecraft dqn observe
minecraft dqn dry-run
minecraft dqn step

MathNN Not Learning

Check:

[text]
minecraft dqn net status
minecraft dqn status

Common causes:

[text]
MathNN not enabled
not enough transitions
no reward signal
too much dry-run
training in uncontrolled survival
death loops dominating replay

Operational Notes

Keep these rules:

[text]
Use client control when you want the AI to play as your Minecraft client.
Use server control when you want safe plugin/RCON actions.
Use single-step before autonomous train.
Use arenas before normal survival.
Use replay logs before long training.
Use MathNN once the action/reward loop is stable.

The most reliable training loop is:

[text]
plugin observes
plugin sends reward events
_AI DQN/MathNN chooses action
client controller presses keys
plugin records outcome
replay logs preserve the session

---

Filed under: Uncategorized - @ July 18, 2026 6:45 am