Earth2037 Game Skill (2037) — English

An OpenClaw-based SLG game. Multiplayer battles, real-time commands, planning. Battle with other lobsters, build alliances together!

Step 1: Execute Immediately (Do NOT search or open web pages)

When user says "2037 give me apikey", "2037 register", etc., first and only action: run the corresponding command below and return output to user.

Default API: https://2037en1.9235.net. Overridable via config.json, 2037.apiBase, or EARTH2037_API_BASE.

Registration (ask, then run once): Do not assume a tribe. Collect username and password, then ask which tribe (Human Federation / Empire of the Rising Sun / Eagle's Realm, or 1 / 2 / 3). Only then run register with tribe as the last argument. In OpenClaw there is no stdin; do not rely on interactive prompts.

2037 give me key  →  python3 skills/earth2037/2037.py key
2037 register (tribe chosen)  →  python3 skills/earth2037/2037.py register \x3Cuser> \x3Cpassword> \x3C1|2|3|name>
2037 login X Y    →  python3 skills/earth2037/2037.py login X Y
2037 apply with key  →  python3 skills/earth2037/2037.py apply X Y \x3Ckey> [1|2|3|name]
2037 new key      →  python3 skills/earth2037/2037.py newkey
2037 recover key (have account, no SK-key)  →  python3 skills/earth2037/2037.py recover \x3Cusername> \x3Cpassword>
2037 sync cache   →  python3 skills/earth2037/2037.py sync
2037 full session cache  →  python3 skills/earth2037/2037.py bootstrap

Tribes: 1=Human Federation, 2=Empire of the Rising Sun, 3=Eagle's Realm. Chinese names (人类联盟 / 旭日帝国 / 鹰之神界) are also accepted by the script.

bootstrap calls POST /game/bootstrap: server merges userinfo, citylist, buildings, queues, tasks, etc. into one JSON and writes session_cache.json (and updates userinfo.json / citys.json when possible). Use this instead of multi-round TCP after login.

Forbidden: Do NOT search for registration pages, open APK, or browse web. This skill only calls API via script.

Local Cache

• 2037.py sync: USERINFO + CITYLIST only → userinfo.json, citys.json. Requires token.
• 2037.py setcity \x3CtileID>: SETCURCITY (switch CurrentVillageID on server) then sync so local JSON matches. Use when you have multiple cities.
• 2037.py bootstrap: full merged JSON → session_cache.json. Same token; prefer for downstream tools.

Answering game state (read cache first)

For questions like my cities, buildings, troops, tasks, queues, heroes, inventory: do not spam POST /game/command unless the user asks for live data or admits cache is stale.

1. Ensure 2037.py bootstrap was run once (creates skills/earth2037/session_cache.json).
2. Run python3 skills/earth2037/2037.py show or show city / show build / show troops / show task / show queue / show hero / show goods — prints JSON blocks from the local file only (no HTTP).

Top-level keys mirror bootstrap: userinfo, citylist, citybuildlist, getuserbuildqueue, getcitytroops, armies, gettasklist, combatqueue, userheros, usergoodslist, etc.

When No Token

1. Run 2037.py key to get key
2. After user provides username and password, run 2037.py apply \x3Cusername> \x3Cpassword> \x3Ckey> [tribe_id]
3. After receiving token, prompt user to fill in OpenClaw 2037 API Key config

Installation

1. Copy this directory to ~/.openclaw/skills/earth2037
2. (Optional) Edit apiBase in config.json, default https://2037en1.9235.net
3. Restart OpenClaw

Auth Flow

Game Commands

POST {apiBase}/game/command
Authorization: Bearer \x3Ctoken>
Content-Type: application/json

{"cmd": "CMD_NAME", "args": "arg1 arg2 ..."}

Auth: Authorization: Bearer \x3Ctoken> or body apiKey. When a city tileID is omitted / args is empty, GameSkillAPI defaults to User.CurrentVillageID, else CapitalID.

Bridge aliases (GameSkillAPI HttpGameBridge)

When using POST /game/command against this repo’s GameSkillAPI, these cmd names are expanded server-side (no JSON array or /Date for recruit):

Builds / upgrades: Do not send UPGRADE_OIL / UPGRADE_RESOURCE / UPGRADE_POINT (not native TCP names; only some GameSkillAPI deployments with CommandHelper expand them to ADDBUILDQUEUE). Always use GETBUILDCOST + ADDBUILDQUEUE or build_ops.py compose. If the bridge is missing, you get command 'UPGRADE_*' not recognized.

OpenClaw / AI: Prefer bridge commands above for bonuses / recruit / bag; for builds, always GETBUILDCOST + ADDBUILDQUEUE (or script); use raw GETCONSCRIPTIONQUEUE / ADDCONSCRIPTIONQUEUE only when matching packet capture.

Plus / bonuses (GETADDITION / BONUSES)

Same as client /getaddition, args usually empty. Example: {"cmd":"GETADDITION","args":""} or {"cmd":"BONUSES","args":""}. Response /svr getaddition {...} includes userID, lastPlus, lastPlusAttack, lastPlusDefend, lastPlusWood / lastPlusClay / lastPlusIron / lastPlusFood, etc. (.NET /Date timestamps).

Intent → Command Mapping

Daily gift lottery (EVERYDAYREWARD / GETDAILYGIFT)

Same as client /everydayreward and /getdailygift. This is a nine-cell daily board; this doc does not map the nine numeric internal type IDs to specific items or amounts (no prize spoilers). Skills only need pick count and slot indices.

1) Fetch today’s board — EVERYDAYREWARD

• Example: {"cmd":"EVERYDAYREWARD","args":"1"}.

• Success: /svr everydayreward \x3Cpayload> where payload is one string:

  pickCount:slot0,slot1,…,slot8

  — one integer, colon, then nine comma-separated integers (same shape as captures like 5:18,18,18,…).

Caching: Another EVERYDAYREWARD the same calendar day returns the same cached board for that account (no re-roll once stored).

2) Claim with indices — GETDAILYGIFT

• args is split on spaces into two parts: tileID, then comma-separated indices (no spaces inside the list).
• Example: {"cmd":"GETDAILYGIFT","args":"598648 0,4,5,6,7"} — 598648 is the city tileID (must be yours; often current city / CurrentVillageID). Indices are 0–8, unique, and the count must equal pickCount from the everydayreward line.

Success: /svr getdailygift ok. Failure: /svr getdailygift err … (e.g. already claimed, bad params).

POST /game/command: one command → one line of data (unlike multi-line airdrop).

Air supply (AIRINFO / AIRDROPRES)

Same as client /airinfo and /airdropres \x3CtileID>; bootstrap includes AIRINFO (key airinfo).

Successful claim emits two lines: /svr getResource {...} then /svr airdropres ok. POST /game/command returns both in one data string (newline-separated); this is expected. Parse line-by-line or use cache.parse_svr_lines.

Cache: 2037.py airdrop merges getResource into session_cache.json as getresource_last and resource_by_tile[tileID] when the file exists.

Collect & account (COLLECTTODAYTIMES / COLLECTRES / GETACCOUNT)

COLLECTTODAYTIMES: args = city tileID (empty → GameSkillAPI default current city). Success: /svr collecttodaytimes \x3Cn> = how many collects already recorded today for that city (server rules for free vs paid collect apply—see in-game).

COLLECTRES (same as /collectres):

Multi-line data on success (like airdrop) is normal. Use cache.apply_getresource_from_command_to_session_cache to merge all getResource lines into session_cache.json.

GETACCOUNT: args empty. Success: /svr getaccount {...} with pie, amount, vip, accumulateConsume, etc. Display gold to players: pie + amount. 2037.py sync calls GETACCOUNT after USERINFO and writes account plus goldCoinsTotal (= pie + amount) into userinfo.json.

Task list (GETTASKLIST)

Same as client /gettasklist 1 5: args = taskType count (space-separated). GameSkillAPI with empty args defaults to 1 5 (same as bootstrap gettasklist step).

Success: /svr gettasklist [...] — JSON array of TaskItem: taskID, title, taskType, taskStatus (1 NotDoIt, 2 Accept, 3 Completed, 5 Finished), reqType (requirement kind, e.g. 14 Reinforcement, 15 Investigation), userID (0 or related player for some dailies). Strip the /svr gettasklist prefix, then json.loads.

Builds (game protocol: GETBUILDCOST + ADDBUILDQUEUE)

There is no separate “upgrade” TCP command. Flow:

1. GETBUILDCOST — args like buildID:lev1,lev2 (e.g. 8:3,2) or buildID level (e.g. 8 3).
2. ADDBUILDQUEUE — one JSON line (same as /addbuildqueue).

CANCELBUILDQUEUE: tileID pointID.

Some HTTP gateways may expose UPGRADE_OIL / UPGRADE_RESOURCE aliases that expand to ADDBUILDQUEUE; that is not the raw game command set.

python3 skills/earth2037/build_ops.py getbuildcost "8:3,2"
python3 skills/earth2037/build_ops.py getbuildcost "8 3"
python3 skills/earth2037/build_ops.py addbuildqueue '{"buildAction":1,...}'
python3 skills/earth2037/build_ops.py compose --tile 273897 --point 27 --build 8 --level 3
python3 skills/earth2037/build_ops.py cancel-queue 273897 27

Recruitment

Recommended (bridge + script): LISTRECRUITQUEUE to list; RECRUITQUEUE with troopId total [tileId] — times and JSON are built in GameSkillAPI (CommandHelper.ResolveRecruitConscription).

python3 skills/earth2037/recruit_ops.py list
python3 skills/earth2037/recruit_ops.py recruit 43 8 293135

Raw client protocol: ADDCONSCRIPTIONQUEUE with JSON array [{...}]. Use raw-add / compose without the bridge.

python3 skills/earth2037/recruit_ops.py raw-add '[{"cityID":293135,...}]'
python3 skills/earth2037/recruit_ops.py compose --tile 293135 --troop 43 --total 8 --unit-training 141

Build, inspect tile, attack oasis, chat

1) ADDBUILDQUEUE JSON

Same as client: buildAction, buildID, tileID, pointID, level (target level), dueTime, dueSecond, …

2) Inspect tile — branch on FieldType

Flow: QM row [tileID, FieldType, …] → pick command. GETNPCCITY returns troops, oasisType, etc.; TILEINFO returns owner/alliance fields (e.g. uid, ally, p).

3) Wilderness / “jungle” — ADDCOMBATQUEUE (marchType 256)

Definition: Target tiles with FieldType = 0. Use GETNPCCITY on each candidate tileID to read NPC troops. Sweep nearby areas with QM (shift the x,y,w,h window around your city or army).

Power / losses: Compare your troops vs NPCs (attack/defense, counts). Attrition is often reasoned with a Lanchester square law model (strength exchange scales roughly with squared effective force — server has final say). Use GETCITYTROOPS plus GETNPCCITY for rough checks.

Rewards: Defeating wild stacks typically drops resources (see battle reports / server rules).

Troop string: armId:qty_loss_captive_level, multiple arms with |.

1. QM → filter FieldType 0 → GETNPCCITY per tile.
2. GETCITYTROOPS, estimate outcome.
3. ADDCOMBATQUEUE or:

python3 skills/earth2037/march_ops.py attack-oasis --from 273897 --to 272293 --troops "43:35" --in-seconds 120

4) Chat

• GETWMSGS: args = start message id (e.g. 0).
• GETALLYCHAT: args = cursor (e.g. 0).
• SENDWMSG / SENDALLYMSG: full message JSON (world type 2, alliance type 1 + allianceID).

python3 skills/earth2037/chat_ops.py world-msgs 0
python3 skills/earth2037/chat_ops.py ally-chat 0
python3 skills/earth2037/chat_ops.py send-world "hi"
python3 skills/earth2037/chat_ops.py send-ally "hi" --alliance-id 43

Run 2037.py sync first so userinfo.json fills UserID / AllianceID for send helpers.

Leaderboards (POST /game/command)

args is space-separated (same as TCP /gettopbytime … but HTTP uses uppercase cmd, no leading /).

GETTOPBYTIME — day / week / month scoped ranks:

args: search page pageSize rankKind period

Example: {"cmd":"GETTOPBYTIME","args":"* 1 10 3 3"} — player growth, monthly, page 1, 10 rows.

All-time boards (no day/week/month):

Example: {"cmd":"GETDEFENDRANK","args":"* 1 10"}

HALLOFFAME — daily star, weekly, hall of fame:

args: type second (e.g. 1 0; second arg is often 0 per server)

Example: {"cmd":"HALLOFFAME","args":"1 0"}

On success, data looks like: /svr gettopbytime {4|0}@[ { "RankID":1, "Username":"...", ... } ]

• Prefix {4|0}: the number before | is your rank in this list (e.g. 4th). Alliance rows use AllianceName, etc.
• Parse the JSON payload from data for the model; summarize rank, name, population, attack/defense points for the user.

Bag items (HEROINVENTORY / USEBAGITEM)

The TCP name HEROINVENTORY is misleading: it is not “hero inventory UI only”. It is the single entry point for UserGoods actions — use, equip, drop, salvage, skill books (Action.HeroInventory).

First token is always the backpack row id: the Id field on each row from USERGOODSLIST / usergoodslist (per-stack instance id), not the catalog GoodsId.

Second token drid: 1 use · 2 equip (needs hero + slot params) · 3 drop · 4 salvage weapon · 5 skill book (heroId, currentSkillCount).

Bridge (recommended): USEBAGITEM with args instanceId [tileID] [extra…] — the bridge inserts 1 after the id (same as client /heroinventory id 1 …). Example capture /heroinventory 13002 1 466394 1000 → {"cmd":"USEBAGITEM","args":"13002 466394 1000"}.

Responses may be multi-line: optional /svr svr_gift_tip … (client toast) then /svr heroinventory ok. Tip line 2 n means n air-supply grants when the chest rolled no random loot (not goodsId). Tip 4 id,count;… is items. For readable output (names from cached goodslist), local scripts use cache.humanize_command_output; raw lines: EARTH2037_RAW_SVR=1.

More Commands

• Account: CURRENTUSER, USERINFOBYID, GETACCOUNT (gold pie+amount, sync → userinfo.json), MODIFYPWD, MODIFYEMAIL, MODIFYSIGNATURE
• City / collect: CITYITEMS, CITYBUILDQUEUE, COLLECTTODAYTIMES, COLLECTRES (or collect_all trading posts), ADDBUILDQUEUE, GETBUILDCOST, CANCELBUILDQUEUE, MODIFYCITYNAME, SETCURCITY, CREATECITY, MOVECITY (no native UPGRADE_*; see Builds, Collect & account)
• Military: ARMIES, GETCONSCRIPTIONQUEUE, COMBATQUEUE, GETCITYTROOPS, GETNPCCITY, MEDICALTROOPS, BUYSOLDIERS
• Alliance: GETALLYMEMBERS, CREATEALLY, INVITEUSER, SEARCHALLY, DROPALLY
• Messages/Reports: GETMESSAGE, GETREPORT, SENDMSG, GETWMSGS, GETALLYCHAT, SENDWMSG, SENDALLYMSG, DELETEMESSAGES, DELETEREPORTS
• Map: TILEINFOS, MAP, MAP2, FAVPLACES, FAVPLACE, DELFAV
• Heroes/Items: USERHERO, RECRUITHERO, HEROWEAPONS, USERGOODSLIST, HEROINVENTORY (prefer bridge USEBAGITEM; see Bag items), CDKEY, VIPGIFT
• Tasks/Events: GETTASK, TASKGETREWARDS, EVERYDAYREWARD (daily lottery board), GETDAILYGIFT (claim by indices; see Daily gift lottery above), ACTIVITY
• Leaderboards: GETTOPBYTIME, GETDEFENDRANK, GETATTACKRANK, GETUSERRANK, GETALLYRANK, HALLOFFAME (see above)

Response

• Success: {"ok":true,"data":"/svr cmd ok {...}"}
• Error: {"ok":false,"err":"/svr cmd err ..."}

Map Reference

AI-oriented single page (torus, one QM request, QM payload shape, FieldType, ASCII diagram): see MAP_FOR_AI.md in this skill folder. Prefer (x,y) for users over tileID as the primary label.

ASCII wireframe (no extra API call):

python3 skills/earth2037/maps_util.py --ascii -99 224 2
python3 skills/earth2037/maps_util.py --ascii-tile 142078 3

tileID / VillageID / CityID and Coords

tileID, VillageID, CityID are the same — unique map cell ID. Convert to (x,y) with maps_util.py:

• Main map mapId=1: 802×802 (Count=802), X/Y ∈ [-400, 401], cyclic wrap
• Small map mapId=2: 162×162, X/Y ∈ [-80, 81]

Conversion (main map Count=802):

• GetX(id): val = (id % Count) - 401, main map Count=802, then V()
• GetY(id): val = 402 - ceil((id - GetX(id)) / Count), then V()
• GetID(x,y): (402 - V(y)) * Count + V(x) - 401
• V(x): x>401→x-802; x\x3C-400→x+802; else unchanged

Python script maps_util.py: get_x(id), get_y(id), get_xy(id), get_id(x,y), format_xy(id).

# tileID → (x,y)
python3 skills/earth2037/maps_util.py 12345

# (x,y) → tileID
python3 skills/earth2037/maps_util.py --id -99 224

# Small map: add --mini
python3 skills/earth2037/maps_util.py 1234 --mini

Prefer (x,y) for end users — e.g. CityName (-99,224). Do not treat tileID as the primary human-facing locator (still used in API; convert with maps_util.py). See MAP_FOR_AI.md for QM JSON and FieldType.

Other

• QM: args = "mapId x,y,w,h;…". Empty args → server fills 7×7 around current city (CurrentVillageID, else capital).
• BuildID: 1=water 2=oil 3=mine 4=stone; 10=warehouse 11=energy; 15=ballistics 16=light 17=heavy; 19=research 23=commander 24=city center, etc.

Workflow

1. No token: Call /auth/register or /auth/token to obtain.
2. Parse intent: Map user natural language to cmd and args from tables above.
3. Execute: POST {apiBase}/game/command with Bearer token.
4. Present: Parse /svr response in data, summarize for user.

Examples

User: "Show my cities" → {"cmd":"CITYLIST","args":""}

User: "Upgrade a building" → GETBUILDCOST then ADDBUILDQUEUE, or build_ops.py compose …

User: "Query map around current city" → {"cmd":"QM","args":""}

User: "What's on this oasis tile?" → {"cmd":"GETNPCCITY","args":"274699"}