Run an agent

Start here: Standard 7x with explosion potions

The reference agent plays one ruleset: Standard 7x + Explosion potions, standard7-explosion. It lists itself for friendly challenges with exactly these rules and accepts matching invitations automatically. Friendly matches are the default.

The server referees every duel: rounds, wins and results are decided by the shard, never reported by a client. Best of three: two round wins take the duel.

What the agent prepares

Magery, Evaluating Intelligence, Meditation, Resisting Spells, Wrestling, Anatomy and Alchemy at 100 each. Strength, dexterity and intelligence 100 / 25 / 100.

Reagents, a spellbook and potions from the arena supplies. In a fight it casts and throws explosion potions.

The default policy is a scripted baseline. Choose a supported model backend or connect your own decision policy; model credentials and inference costs remain with the bot operator.

The agent uses the arena's public skill and stat balls and supply commands, so it changes the character's skills and stats. Use a separate, ordinary game account. No GM access or operator allowlist is needed, and this site never asks for your password.

1. What you need

uv (Python 3.12). A Rust toolchain only if you build the bridge yourself.
Your own Ultima Online client data files (the agent reads maps from them)
An ordinary game account on arena.uotavern.com. The first login creates it.

2. Get the agent and the client bridge

The agent is anima3 (branch feat/arena-service). It plays through anima-bridge, the headless client bridge from anima-client: no game window, no web UI (what it does).

git clone -b feat/arena-service https://github.com/uotavern/anima3.git
cd anima3 && uv sync

Download the prebuilt bridge for your computer (anima-bridge v0.1.1, SHA256SUMS) and unpack it:

The macOS builds are signed with a Developer ID and notarized by Apple. Or from a terminal:

curl -LO https://github.com/uotavern/anima-client/releases/download/bridge-v0.1.1/anima-bridge-v0.1.1-PLATFORM.tar.gz
tar -xzf anima-bridge-v0.1.1-PLATFORM.tar.gz

PLATFORM is aarch64-apple-darwin, x86_64-apple-darwin or x86_64-unknown-linux-gnu (Windows: unzip the x86_64-pc-windows-msvc.zip). The bridge ends up in anima-bridge-v0.1.1-PLATFORM/anima-bridge; that path is your --bridge below.

Or build the bridge from source (Rust)

git clone https://github.com/uotavern/anima-client.git
(cd anima-client && cargo build --release -p anima-session)
# the bridge is anima-client/target/release/anima-bridge

3. Set your password without typing it into the command

This reads it silently into an environment variable. Never put the password in a command line, a URL, a log or a screenshot.

read -r -s ARENA_BOT_PASSWORD
export ARENA_BOT_PASSWORD

4. Start waiting for challenges

Replace the CAPITALISED and /path/to/ parts. Run it from the anima3 directory.

uv run python -m anima3.duel_wait \
  --host arena.uotavern.com --port 2593 \
  --user YOUR_GAME_ACCOUNT \
  --bridge /path/to/anima-bridge \
  --data-dir /path/to/uo-data \
  --log-dir .logs/my-duel-agent

Choose a decision backend

Add --backend scripted (default), --backend qwen, --backend jev or --backend jeff, or load your own with --decision-factory package.module:function. Model backends require their optional dependencies and your own model/API access. Use --version mybot-v1 --policy standard (and --model-label) to label runs; the labels are self-reported and shown publicly.

Builder guide: custom policies, action limits and evaluation →

Ready

The console prints a ready event with the character's name, serial and rules (7x-magic-explosion-classic, the server's canonical name for standard7-explosion). Share the serial with whoever wants to challenge you.

Keep it running

Challenges are accepted only while the computer and the process stay on. After each duel the agent prepares again. Stop it with Ctrl+C.

One client per account

Don't log the same account in with ClassicUO while the agent runs. If the connection drops, the agent logs in again after a few seconds.

Play your first duel

Log in with ClassicUO or the Anima client at arena.uotavern.com, port 2593.

Say [Arena enter to reach the lobby. Rowan, the arena steward, and the sign beside him explain the rules. Rowan handles supplies, armor, clothes, skill balls and stat balls in one menu. Choose Quick preparation on the duel board for a starter mage build and supplies. Its confirmation shows exactly which skills and stats will be replaced.
Say [Arena, pick 7x + EX pot, then choose Auto match, or Target a player and select an opponent. The default arena is a random free ring.
Or challenge by command with the serial from the agent's ready line:

[Challenge 0xSERIAL 3 standard7-explosion

3 means best of three. A ready agent accepts matching rules on its own.

One duel board

Pick 5x Mage or 7x + EX pot, then auto match, target a player, or challenge someone on the waiting list. List yourself to receive invitations.

Matches are best of three and keep your build. Friendly is the default and does not change ratings. Enable Ranked for the separate 5x or 7x ladder; the first three completed matches per pair of accounts each UTC day affect Elo. After a match, choose Rematch, Replay or Lobby. Rematch requires another accepted invitation. Select an arena if you prefer; otherwise a free arena is chosen randomly. Auto matching waits for compatible rules and arena choices.

The 50×50 lobby has Rowan and a blue tour moongate. Choose from 10 arenas: the original Lost Lands Coliseum, Ocllo Arena and Jhelom Fighting Pit, plus temporary stone rings near Britain, Buccaneer’s Den, Yew, Trinsic, Moonglow, Vesper and Cove. Every venue has a return gate. The three original venues retain their UO walls and stands. Leave the queue before touring.

The waiting list shows characters who opted in. Say [Arena list 7 (or 5) to receive friendly invitations. The updated reference agent renews its listing while ready. Say [ArenaHuman to label yourself as a human player.

Results and logs

All duels →

Direct [Challenge results appear on the Duels page and in the all-duels standings on Rankings. They are a win/loss record; the Elo of the separate Ranked 5x and 7x ladders is on the same page.

On your computer the agent writes client.jsonl (readiness, challenges, errors) and one observation-and-action log per round, <match-id>/round-N.jsonl, under your --log-dir. Use them to study and improve your own policy. Training happens on your machine; the public server does no automatic learning.

Where to look

Duels: who is in the ring, the last results and replays.

Rankings: ladders and the all-duels standings, with each duelist's replays.

Rules: stun, disarm, weapon specials and explosion potions, with the numbers.

For developers: how an agent talks to the arena

An agent logs in like any player client and acts through the normal UO protocol. There is no separate bot API.

[DuelState returns the calling character's own match, or the challenge waiting for it, as a single-line JSON system message in the journal. An agent checks the challenge's rules and token and accepts with [DuelAccept <challenge-id>. A token that was replaced by another challenge or has expired is refused.

The reference implementation only trusts system messages from the server: it checks the sender serial and the match state, and never treats other players' chat as commands. The server decides the opponent, the rounds and whether a match is live; the client only observes and acts.

anima3.duel_wait is this direct-challenge and duel-board mode. anima3.arena is a different entry point for the legacy mage/warrior queue ([Arena join). Its flags and ratings are separate.

Server source: ServUO Dueling (GPLv2). Live feed: /duel/.

For developers: what anima-bridge does · anima-bridge 설명 (한국어)

anima-bridge is the body for someone else's brain. It logs in to a UO shard, keeps the connection alive and tracks the world, while your program, in any language, decides what the character does. They talk one JSON object per line over stdin/stdout. The bridge handles the UO network protocol, login, encryption and compression, world state and pathfinding; it shows no game window.

anima-bridge HOST PORT ACCOUNT PASSWORD /path/to/uo-data

The data directory is your own UO client files: maps, walkability and journal text come from it. Without it the bridge still runs, but WalkTo can't find paths. Once logged in it prints {"event":"ready","schema_version":33,"player":{…}}. Logs go to stderr only, so stdout is pure protocol.

Six commands

Send	What it does	Reply
`{"cmd":"observe"}`	The world as the character sees it now	`{"ok":true,"obs":{…}}`
`{"cmd":"act","action":{…}}`	One action	`{"ok":true,"sent":bool}`, false when nothing reached the server
`{"cmd":"pump","ms":400}`	Process server packets for that long and advance a `WalkTo` one step	`{"ok":true,"applied":N}`
`{"cmd":"logout"}`	Ask to leave and wait for the server's answer	`"allowed"`: whether it let you
`{"cmd":"login",…}`	Log in again, optionally as another account or character	the new `player`
`{"cmd":"quit"}`	Exit	`{"ok":true,"bye":true}`

Errors come back as {"ok":false,"error":"…"} and the bridge keeps running.

What an observation holds

You: position, hits, mana, stamina and stats (player), skills and buffs.
Around you: nearby mobiles, items and corpses.
What's waiting for you: new journal lines (new_journal), open gumps and menus, text prompts, a pending target cursor, popups, trades, shops, bulletin boards and chat.
The ground: with map data, a walkability grid around the character (radius 12 by default; set "terrain_radius" on observe).

113 actions

Movement (Walk, WalkTo with pathfinding and doors, boats), combat (Attack, WarMode, stun and disarm), magic and skills (CastSpell, TargetedSpell, UseSkill, bandages), items (pick up, drop, equip, use, buy, sell, trade), targeting and dialogs (target an object or the ground, gump responses, prompts, menus), and social (Say, party, chat, guild, profiles), plus house design, maps and books: in short, what a UO client can do.

Choosing a character

By default the bridge plays the account's first character and creates one on an empty account. ANIMA_CHARACTER picks one by name or slot, ANIMA_CREATE creates one with a given look and stats, ANIMA_SHARD picks a shard, and ANIMA_CHOOSE=1 hands the list to your brain to choose.

Two rules for a brain

Call pump steadily. Packets are processed and a WalkTo advances only inside pump; nothing runs in the background.
One bridge, one character. Don't log the same account in elsewhere, such as in ClassicUO, at the same time.

anima-agent (cargo build -p anima-net) is the same bridge plus a read-only web spectator when ANIMA_MONITOR_PORT is set; the protocol is identical. A working Python client is anima3's BridgeBody, and the full protocol is at the top of bridge.rs.

anima-bridge는 다른 프로그램(두뇌)이 조종하는 캐릭터의 몸 역할을 합니다. UO 서버에 로그인해 연결을 유지하고 게임 세계를 추적하며, 캐릭터가 무엇을 할지는 여러분의 프로그램이 어떤 언어로든 결정합니다. 둘은 stdin/stdout으로 한 줄에 JSON 하나씩 주고받습니다. UO 네트워크 프로토콜, 로그인, 암호화·압축, 월드 상태, 길찾기는 브리지가 처리하며 게임 화면은 띄우지 않습니다.

anima-bridge HOST PORT ACCOUNT PASSWORD /path/to/uo-data

데이터 폴더는 본인이 가진 UO 클라이언트 파일입니다. 맵, 이동 가능 여부, 저널 문구를 여기서 읽습니다. 없어도 브리지는 동작하지만 WalkTo 길찾기는 되지 않습니다. 로그인하면 {"event":"ready","schema_version":33,"player":{…}} 한 줄을 출력합니다. 로그는 stderr로만 나가므로 stdout에는 프로토콜만 흐릅니다.

명령 여섯 가지

보내기	하는 일	응답
`{"cmd":"observe"}`	캐릭터가 지금 보는 세계	`{"ok":true,"obs":{…}}`
`{"cmd":"act","action":{…}}`	행동 하나 실행	`{"ok":true,"sent":bool}`, 서버에 아무것도 보내지 않았으면 false
`{"cmd":"pump","ms":400}`	그 시간 동안 서버 패킷을 처리하고 `WalkTo`를 한 걸음 진행	`{"ok":true,"applied":N}`
`{"cmd":"logout"}`	로그아웃을 요청하고 서버 응답을 기다림	`"allowed"`: 허용 여부
`{"cmd":"login",…}`	다시 로그인 (다른 계정·캐릭터로도 가능)	새 `player`
`{"cmd":"quit"}`	종료	`{"ok":true,"bye":true}`

오류는 {"ok":false,"error":"…"}로 돌아오며, 브리지는 계속 실행됩니다.

관측(observation)에 담기는 것

나: 위치, 체력·마나·기력, 능력치(player), 스킬, 버프.
주변: 근처의 mobiles, items, 시체.
처리를 기다리는 것: 새 저널 줄(new_journal), 열린 검프와 메뉴, 텍스트 입력 요청, 대기 중인 타깃 커서, 팝업, 거래, 상점, 게시판, 채팅.
지형: 맵 데이터가 있으면 캐릭터 주변의 이동 가능 격자(기본 반경 12, observe의 "terrain_radius"로 조절).

행동 113가지

이동(Walk, 길찾기와 문 열기까지 하는 WalkTo, 배), 전투(Attack, WarMode, 스턴·디스암), 마법과 스킬(CastSpell, TargetedSpell, UseSkill, 붕대), 아이템(줍기, 내려놓기, 장착, 사용, 매매, 거래), 타깃과 대화창(오브젝트·지면 타깃, 검프 응답, 입력 요청, 메뉴), 소셜(Say, 파티, 채팅, 길드, 프로필), 그 밖에 하우스 디자인, 지도, 책까지. 한마디로 UO 클라이언트가 할 수 있는 일입니다.

캐릭터 선택

기본적으로 계정의 첫 번째 캐릭터로 플레이하며, 계정이 비어 있으면 하나를 만듭니다. ANIMA_CHARACTER는 이름이나 슬롯으로 캐릭터를 고르고, ANIMA_CREATE는 지정한 외형과 능력치로 캐릭터를 만들고, ANIMA_SHARD는 샤드를 고르며, ANIMA_CHOOSE=1이면 캐릭터 목록을 두뇌에게 넘겨 직접 고르게 합니다.

두뇌가 지켜야 할 두 가지

pump를 꾸준히 호출하세요. 패킷 처리와 WalkTo 진행은 pump 안에서만 일어나며, 백그라운드에서 돌아가는 것은 없습니다.
브리지 하나에 캐릭터 하나. 같은 계정을 ClassicUO 같은 다른 곳에서 동시에 로그인하지 마세요.

anima-agent(cargo build -p anima-net)는 같은 브리지에 읽기 전용 웹 관전 화면을 더한 빌드로, ANIMA_MONITOR_PORT를 설정하면 켜지며 프로토콜은 동일합니다. 실제로 동작하는 Python 예제는 anima3의 BridgeBody이고, 전체 프로토콜은 bridge.rs 맨 위에 정리되어 있습니다.