playing-the-game
Guide for playing MineClonia/MineClone2 through a running Antilua client — gathering resources, crafting tools, mining, and surviving. Prefers the antilua MCP server's agent tools (agent_ctx/agent_eve
SKILL.mdskills/playing-the-game/SKILL.md
GitHubPlaying The Game via the Antilua MCP Server
Overview
Control a running Antilua client through its MCP server (util/mcp/), which
exposes structured tools over the client's Lua pipe. Requires the client
running with pipe_lua_enable = true (the antilua-mcp server connects via
ANTILUA_PIPE_PATH, default /tmp/antilua_lua).
Prefer MCP tools over raw pipe writes — they handle JSON serialization,
response files, and pacing for you, and screenshot() gives you eyes on the
world. Use the raw Lua pipe (skills/antilua-lua-pipe/SKILL.md, or the
run_lua escape hatch) only for things the curated tools don't cover.
Quick Start
- No client running? Launch one:
scripts/agent_play.sh(defaults to the Oysterity anarchy server asophelia;--headlessfor xvfb,--world Wfor local,--server HOST:PORTto override). Use Shakespearean names for fresh accounts. On Oysterity, readskills/oysterity/SKILL.mdfirst — it has the server's own rules, the greeting flow and the saved-map workflow. - Orient:
agent_ctx()(one call: pos/look/hp/inventory/objects/ping) →screenshot()if the client is rendering. - Prep:
survival(true)(autoeat, autototem, autojump, autorespawn, autotool) — on hostile servers the agent will die otherwise, and deaths scatter the inventory (Oysterity's spawn is creeper-infested). - Act:
goto/dig_at/place_at/use_node/move_item/craft. - Verify:
get_inventory()/agent_events(since)/screenshot().
agent_ctx() replaces the old get_player_pos + get_player_look +
get_inventory triple for orientation; the older tools still work.
Player Info
| MCP tool | Notes |
|---|---|
get_player_pos() |
{x, y, z} node coords |
get_player_look() |
{yaw, pitch} (deg), roll (rad) |
teleport({x, y, z}) |
Move the player; returns new pos |
set_look(yaw, pitch) |
Aim the camera (deg) |
set_time("noon") / "6" / "midnight" |
Server time of day (needs settime priv) |
get_client_status() |
{connected, joined, player_name, chat_buffer} — check first when tools fail |
run_lua("return core.localplayer:get_hp()") |
HP (0-20); also get_name(), get_wielded_item(), get_wield_index() |
World Interaction
| MCP tool | Notes |
|---|---|
get_node({x,y,z}) |
{node: {name, param1, param2}} or {node: null} if unloaded (client map — can lag; cross-check with screenshot()) |
dig_node({x,y,z}) |
Punch/dig a block {digged: true/false} |
place_node({x,y,z}) |
Places the wielded item |
interact(action, pointed) |
Real right-click/use/activate/place/dig — use opens node formspecs (pointed from get_pointed_thing()) |
find_nodes_near(pos, radius, [names]) |
{count, positions} |
find_nodes_near_under_air(pos, radius, [except]) |
{count, positions} — solid surfaces with air above (placement spots) |
get_objects_near(pos, radius) |
{objects: [{id, pos, name, is_player}]} |
get_pointed_thing() |
{type: node|object|nothing, ...} |
Note: place_node places whatever is wielded — use give_and_wield(item)
or wield_item(item) (substring match) instead of the old
move-then-set_wield_index dance.
Waiting for sync
Client state (inventory, wield, node meta) lags a beat behind the server.
Don't hand-roll polling — wait_until(code, timeout, interval) runs a Lua
expression repeatedly and returns {ok, value} when truthy:
-- run via wait_until's `code`:
return core.get_inventory("current_player") and find_stack_name() ~= nil
Server chat commands report their result through the chat log:
run_server_chatcommand("giveme", "mcl_core:stone 1") returns the server's
reply lines in chat (e.g. "…added to inventory."), and get_chat_log(20)
reads recent lines at any time.
Inventory
get_inventory(location?) returns {list: [{slot, name, count}, ...]} for
main (36; 1-9 hotbar), craft (9), craftresult (1), craftpreview (1),
armor, hand — and, with a location, other inventories: player:<name>,
nodemeta:x,y,z (chests/furnaces), detached:<name> (creative). Use
move_item(from_list, from_slot, to_list, to_slot, count) (or
move_items([...]) for batches) — count 0 = whole stack.
Crafting System
Crafting uses inventory moves + the craft action. Without a crafting table
only 2x2 recipes work (craft list indices 1,2,4,5 — it has width 3
internally); place a crafting table for 3x3.
| Step | MCP tools |
|---|---|
| Move items into grid | move_item("main", slot, "craft", grid, 1) |
| Trigger craft | craft(1) |
| Take result | take_craft_result(main_slot) (moves craftresult → main) |
Complete: Get a Stone Pickaxe
Orient first (agent_ctx(), screenshot()), then — the verified-tool
version of the classic progression (fall back to the raw tools noted inline
if a tool is unavailable):
- Wood:
find_nodes_near(pos, 20, ["mcl_trees:tree_pale_oak"])→gototo within ~4 nodes of the log (run_luaagent.open_target(4)if the destination is unknown) →dig_at(log)(returns{ok, state: "done"}once the server confirms removal) → collect the drop immediately: walk/tp onto the item entity, then checkget_inventory(). Drops despawn after a few minutes, and picking up requires being within ~1.5 nodes. - Planks:
move_item("main", log_slot, "craft", 1, 1)→craft()→take_craft_result(slot)—mcl_trees:wood_pale_oakx4. - Crafting table: planks into
craft1,2,4,5 →craft()→ take —mcl_crafting_table:crafting_table;place_at(<air next to the player>, "mcl_crafting_table")(3x3 grid needs the table nearby — and rememberplace_atwants the air node above the surface, not the surface). - Sticks: planks vertical at
craft1,4 →craft()→ take —mcl_core:stickx4. - Wooden pickaxe: planks across
craft1,2,3 + sticks at 5,8 →craft()→ take —mcl_tools:pick_wood. - Stone:
dig_atauto-selects the best tool in the inventory, so no manual wield is needed;find_nodes_near(pos, 20, ["mcl_core:stone"]),gotointo reach,dig_at, collect. - Stone pickaxe: 3 cobble across 1,2,3 + 2 sticks at 5,8 →
mcl_tools:pick_stone.
Verify each step with get_inventory() (and screenshot() for placement).
When dig_at reports timeout, the node is still there: the tool was too
weak (bare-hand stone ≈ 7 s, and the server's dig pool can reject very fast
digs), out of reach, or a mob interrupted the dig.
Respawning
If dead (HP 0), interacts silently do nothing. Respawn via the death screen:
-- run_lua:
core.send_inventory_fields("__builtin:death", {quit = "true"})
Or prevent death during automated play: set_setting("enable_damage", "false")
or keep to a safe area. (core.send_respawn() is a dead legacy packet.)
Cheats & Settings
toggle_cheat(name, enabled) / set_setting(name, value):
jetpack, fullbright, fastdig, autojump, fly, noclip, …
See doc/al_csm_api.md for the full cheat list. survival(true) enables the
survival preset at once (autoeat, autototem, autojump, autorespawn, autotool).
Agent tools (preferred for autonomous play)
The agent clientmod adds verified, non-blocking tools — prefer them over
raw dig/place once a session is running:
| Tool | Notes |
|---|---|
agent_ctx() |
One-call orientation: pos/look/hp/flags/wielded/inventory summary/objects near/ping |
agent_events(since) / wait_event(type) |
Event feed: chat, death, damage, dig/place confirmations, inventory changes, formspecs |
goto(pos, mode) |
walk (A* + lua controls, default), sprint, fly (free_move flight), rtp (burst teleports), tp; returns {ok, state, dist} |
dig_at(pos) / place_at(pos, item) |
Verified with hold-to-dig timing, auto tool selection and server-side confirmation |
use_node(pos) |
Right-click a node (chests/doors/furnaces); returns the opened formspec name |
punch_object(id) / aim_at(pos, velocity, gravity) |
Aim (gravity-compensated for projectiles) and attack an entity |
survival(true) / eat() / respawn() / agent_mem(key, value?) |
Survival preset, persistent memory |
Movement note: open_target(4) (via run_lua) returns a nearby genuinely
walkable target — use it to avoid cliffs when the destination is unknown.
Real-server findings (oy.edgy1.net, mineclonia anarchy)
rtpis throttled by the server's anticheat — burst teleports get the position reset (effective ~1 node/s). Usewalk, orflyon servers that tolerate flight.- Flight recipe (works when the server grants no
flypriv, becausepriv_bypassdefaults to true andcheckPrivilege()honours it):priv_bypass = true,free_move = true, plusnoclip = trueto avoid terrain collision, then drivecore.localplayer:set_velocity(dir * speed)every step.agent.go_to(pos, "fly")does everything exceptnoclip— setset_setting("noclip", "true")yourself when the path may cross terrain (flight still collides with blocks, and progress then stalls withstuck: no progress).free_moveis turned off automatically when the flight ends. free_movealone does not lift — the client'sapplyControlonly mapscontrol.jumpto upward motion, and that field is rebuilt from real keys every frame.set_lua_controlfrom a pipe call lasts one frame;set_autojump(true)is the only Lua path that survives (it is OR-ed intocontrol.jumpinGame::updatePlayerControl).- Never register a
globalstepfrom a pipe chunk — there is no unregister API, so it keeps running forever (a stray autojump pulse will fly the player to the sky). Long-lived behaviour belongs in a clientmod (likeagent) with a guard flag. - Timers (
core.after) registered from a pipe chunk may not fire — chain one action per pipe call instead of scheduling the next step from Lua. - Deaths scatter the inventory and respawn points are far apart; a
gotoin progress reportsfailed: no progresswhen a respawn teleport happens mid-walk. Withsurvival(true)(autorespawn) the loop recovers, but expect to re-gather resources after a death. - Node-level verification is the only reliable one. For your own
placements the server skips
AddNode(it assumes the client predicted), soon_node_addmay not fire — the agent's action sweep therefore confirms placements by reading the actual node state, not by waiting for the event. - Enum cheat settings are crash-fatal when invalid. Writing e.g.
killaura.target_mode = "true"used to kill the client through a nil lookup in a globalstep;resolve_mode()now falls back to a valid mode. Prefertoggle_cheatand documented enum values.
Screenshots
screenshot() returns a scene-only PNG (no HUD). Needs a client that is
rendering — fails if detached/hidden (reattach first). Invaluable for
verifying placements the client map misreports.
Item Names (MineClonia)
| Item | Name |
|---|---|
| Pale Oak Log | mcl_trees:tree_pale_oak |
| Pale Oak Planks | mcl_trees:wood_pale_oak |
| Stick | mcl_core:stick |
| Crafting Table | mcl_crafting_table:crafting_table |
| Wooden Pickaxe | mcl_tools:pick_wood |
| Stone Pickaxe | mcl_tools:pick_stone |
| Stone | mcl_core:stone |
| Cobblestone | mcl_core:cobble |
| Dirt | mcl_core:dirt |
| Dirt with Grass | mcl_core:dirt_with_grass |
| Pale Oak Leaves | mcl_trees:leaves_pale_oak |
Common Pitfalls
| Mistake | Fix |
|---|---|
| New MCP tools don't appear in your tool list | The host caches the tool list at MCP-server start — restart the antilua-mcp server (or the host) after editing util/mcp/server.py. Until then, drive the same API with run_lua("return agent.…") |
place_at says not buildable |
You targeted a solid node. find_nodes_near_under_air returns the surface — build at surface + {0,1,0} |
dig_at times out |
Tool too weak (bare hand on stone ≈ 7 s), out of reach, or a mob interrupted. dig_at picks the best tool in the inventory automatically; re-run it or get a better one |
goto ends failed: no progress/stuck |
Cliffs/water you can't walk up, a respawn teleport mid-walk, or anticheat throttling. Use agent.open_target(n), retry, or switch to fly/tp |
goto on rtp crawls at ~1 node/s |
The server's anticheat resets burst teleports. Prefer walk or fly |
| Everything is ignored after death | Dead players' interacts are dropped. survival(true) auto-respawns; otherwise respawn() |
| Inventory empty after a risky trip | You died — deaths scatter items as drops. Expect to re-gather |
place_node puts the wrong block |
It places the wielded item — use place_at(pos, item), or give_and_wield(item) / wield_item(item) |
get_node disagrees with reality |
Client map lags/predicts; confirm with dig_at/place_at results, screenshot() or re-sync |
| Craft grid indices wrong for 2x2 | Use 1,2,4,5 (not 1,2,3,4) — craft list has width=3 internally |
| Crafting a 3x3 recipe fails | Needs a placed crafting table nearby |
| Items missing after digging | Walk/tp onto the item entity (pickup radius ~1.5) and re-check get_inventory(); drops despawn |
| Server command fails | {ok:false, error:...} — inspect the error, don't assume success |
| Screenshot fails | Client detached/hidden — reattach; needs a rendering frame |
| Setting an enum cheat to a bogus value | Can kill the client (fatal globalstep error). Use documented values / toggle_cheat |
| Need raw Lua | run_lua(code) — same client state, JSON results; see skills/antilua-lua-pipe/SKILL.md |
| Pipe stops responding | Don't delete/recreate the FIFO — the client keeps the old inode; restart the client. One client per pipe path |
Helper Scripts
Gameplay Lua snippets live in skills/playing-the-game/scripts/ (kept for
run_lua / raw-pipe use):
| Script | Purpose |
|---|---|
send_lua.py |
Send a .lua file to the pipe and print response |
check_inv.lua |
Show all inventory contents |
check_hp.lua |
Show HP |
where.lua |
Show position + surrounding blocks |
craft_table.lua |
Craft a crafting table from planks |
craft_sticks.lua |
Craft sticks from planks |
craft_pick.lua |
Craft a wooden pickaxe |
place_table.lua |
Place the crafting table |
dig_stone.lua |
Mine stone with equipped pickaxe |
find_trees.lua |
Find nearby trees |
gather_wood.lua |
Gather wood from nearest tree |
consolidate.lua |
Stack item stacks in inventory |