A headless World of Warcraft client for vanilla 1.12 / Turtle WoW 1.18.1 servers (login build 7272, world build 5875). One process logs one character in, with no game window, and exposes it over a local JSON-RPC API. It was built to test server-side bots (TortoiseBots) on a private test server: log in, hire or invite bots, start a fight, then read back the combat log and what each bot did.
Testing TortoiseBots with it? Follow the maintainer's vision in docs/TORTOISEBOTS-VISION.md and the rules for agents in AGENTS.md.
Use it only on servers you run or are allowed to test on. It has no Warden emulation and does no rendering.
Requirements: Go 1.27.1 or newer (see go.mod), a C++17 compiler for cgo (g++ or clang), and a server whose realmd
and world ports you can reach. CGO_ENABLED=0 still builds; path_to and walk_path then answer that the binary
has no navmesh engine.
make build # bin/turtle-agent
make test # gofmt check, go vet, builds, go test -race ./...Create the settings file (default ~/.config/turtle-agent/settings.json, mode 0600; the agent refuses a file
other users can read) with your server and account in it — placeholders below, never real values:
{
"realmd": "<server>",
"accounts": { "<account>": "<password>" },
"rpc": "127.0.0.1:8765"
}Only realmd and accounts are required. rpc must be a loopback address. See
the settings reference for every key.
Log a character in and keep it online with the RPC server running:
bin/turtle-agent login --rpc 127.0.0.1:8765 <account> <character>bin/turtle-agent rpc <slot-dir> statusIt reads the slot's token file itself and prints only the call's result. See
Drive the agent with RPC.
- Drive one character over RPC: the agent and its RPC.
- Run a bot party through a dungeon: dungeon runs.
- Walk raids, supervise many, regression-check plans: raids.
- Write, check and ship run plans: plans.
- Walk the navmesh and draw the run as a map: navigation.
- Fight with data: rotations, tactics, the brain: combat.
- Watch it live, record and score it: observability.
The manual lives in docs/okf: one topic per page, each starting with a header that says what kind of page it is. The format is described in How this documentation is written, and the README section map shows where every section of the old long README went.
make test must stay green (gofmt, go vet, a no-cgo build, go test -race ./..., a cgo build, staticcheck ./...).
See docs/CI.md for the jobs. Open PRs against dev; main only takes dev after the owner's
review. Contributions that change how the bot plays need the maintainer's decision first — bug fixes go in, behaviour
changes are discussed.
GNU Affero General Public License v3.0 or later, see LICENSE. Versions up to the commit that changed the licence were released under the MIT License (kept in LICENSES/MIT-turtle-agent-before-agpl.txt); copies you already received under MIT stay under MIT. Parts are ported from agent-wow (MIT; the files keep their own MIT headers), and
internal/navmesh/detour is Detour from recastnavigation (zlib, internal/navmesh/detour/License.txt); see
NOTICE. Dungeon event data derived from jrad7/mod-dungeon-clear (AGPL-3.0-or-later) is marked with its source where it appears. World of Warcraft is a trademark of Blizzard Entertainment; this project is not affiliated with it.