Warcraft III for AgentEnv

An LLM agent plays a melee game of Warcraft III: The Frozen Throne against the game's own AI, through raw wc3env orders served as MCP tools. Games are graded and their native replays saved. This repository is an environment plugin for the AgentEnv Framework.

Unofficial, offline, and bring your own game. This project is not affiliated with or endorsed by Blizzard Entertainment; Warcraft is their trademark. It contains no game files: wc3env runs your own licensed Warcraft III Legacy (1.29.2) installation, offline only, never on Battle.net. The env image you build holds your game files: keep it private. Whether this use fits your license agreement is your responsibility.

Status: first milestone. One agent against the built-in AI. Everything below the game is tested against wc3env's fake game: the unit tests (tests/), and the image and a whole agent-env run wc3 --task smoke on a stand-in for wc3env's image (scripts/standin.sh, in CI). The real game has not yet been run through this plugin.

What it needs

• An x86-64 Linux Docker host whose kernel runs Wine (wc3env's docker/platform_probe.py checks it). Apple Silicon and arm64 hosts can't run it.

• wc3env's worker image, built from your own installation as its docker/README.md describes. That needs a Windows machine once, for the game hook and the prepared data, then any Linux builder: docker build --platform linux/amd64 --target environment -t wc3-worker:local build/docker-context.

• Your activation files, roc.w3k and tft.w3k, from the same installation, in ~/.wc3-license (or the directory license_dir names in [plugins.agentenv-wc3] of .agentenv/config.toml, or $WC3_LICENSE_DIR). They never enter an image: the wc3_match step sends them to the env when a game starts.

Related MCP server: llmpvp

Run it

uv tool install agentenv-framework --with-editable ./agentenv-wc3-plugin
cd agentenv-wc3-plugin
agent-env wc3 check                      # the host, your wc3env image, your activation files
agent-env wc3 setup                      # build the env on top of wc3-worker:local and register it as "wc3"
agent-env run wc3 --task smoke           # no model: a 2-minute game runs with no orders, is graded and replayed
agent-env run wc3 --task vs-ai-quick     # your default agent against the easy AI, 5 game minutes

agent-env wc3 serve serves the env on this machine against wc3env's fake game (a Town Hall, five Peasants and a distant enemy hall), to try the tools or an agent without Warcraft III.

How it works

flowchart LR
    agent["agent (A2A)"] -- "MCP: get_state, act, advance ..." --> server
    subgraph env["the env container: your wc3env image + this plugin"]
        server["agentenv_wc3.server<br/>(Linux Python)"] -- "JSON lines" --> worker["worker.py<br/>(Windows Python, Wine)"]
        worker -- "wc3env GameSession" --> game["Warcraft III + wc3hook.dll"]
    end
    runner["agent-env"] -- "new-game, idle, replay, data/get" --> server

wc3env holds the game's clock, so time passes only when the agent calls advance: an agent may think as long as it likes between steps. Orders given with act are checked against wc3env's own rules (the unit is yours, the target is in view, the arguments are well formed) and wait in a queue; advance sends them with the step and reports what the game refused, the sites it chose for buildings, and what happened.

docs/protocol.md is the worker's protocol.

Not done yet

• A run against the real game. The worker drives wc3env's GameSession as wc3env's own tests and Docker smoke do, but this plugin has only met the fake game. The first smoke run on a real setup is the test.

• Container options. wc3env runs its worker with --shm-size 256m and --init; agent-env's server provider sets neither, and whether Wine needs them here is untested.

• Several agents in one game, seats and a turn barrier, as the OpenCiv3 plugin has.

• Video and streaming: the game draws to Xvfb inside the container; recording it, or a replay played back, is the next step after a working game.

• A Linux-only build of wc3env's inputs, so no Windows machine is needed (the hook with MinGW, StormLib on Linux).

Development

scripts/standin.sh path/to/wc3env builds wc3-worker:standin, wc3env's image layout on its fake game, so agent-env wc3 setup --base wc3-worker:standin and agent-env run wc3 --task smoke run anywhere with Docker.

scripts/ci.yml is the CI workflow (the tests, and the image and smoke on the stand-in); copy it to .github/workflows/ to turn it on.

uv venv && uv pip install -e ".[dev]" -e path/to/wc3env   # wc3env from a checkout: tests use its fake game
.venv/bin/pytest
.venv/bin/ruff check .