Atrinik playtester is an autonomous, headless end-to-end player for Atrinik. It connects through ordinary player protocols, observes live game state, and runs navigation, quest, combat, equipment, economy, and survival policies without privileged server access. The one exception is the owner-triggered operator assist, which autoplay never uses.
The product goal is one reproducible unattended campaign from a new account and character through a versioned full-game completion contract. The initial golden path is tracked by issue #1: complete all 16 formal quests, reach level 115, defeat Zechna, verify every outcome from authoritative game state, and emit a machine-readable result.
The migrated implementation provides pinned, encrypted Classic QUIC transport, account and character setup, a live world model, content-derived navigation, 16 formal quest executors, adaptive farming through level 115, persistent memory, and a loopback operator dashboard.
The current autoplay command completes the introductory flow and then levels;
the all-quest runner remains separate, and Zechna is not yet an automated
completion gate. The roadmap issues track the work needed to turn these pieces
into the single start-to-finish campaign described above.
Design notes: COMBAT.md describes how she fights, and the proposal docs/LEARNING_AND_FEEDBACK.md covers learning from doors, books and fights, and an owner-approved playtester feedback queue.
Build and install the wheel from the repository root in any clean Python 3.11+ environment. The protocol wheel and native pathfinding archive are selected by the compatibility lock; the project does not bundle or relicense either dependency. Preflight and install the protocol wheel from that lock before building the package:
python3 -m venv /path/to/playtester-environment
/path/to/playtester-environment/bin/python scripts/install_locked_protocol.py
/path/to/playtester-environment/bin/pip install .The installer verifies the locked repository, release tag, exact commit, asset,
download URL, and SHA-256 digest before invoking pip. The
atrinik-playtester preflight command repeats that remote availability check,
while doctor --preflight reports the same check alongside local cache and
installed-input diagnostics. When GITHUB_TOKEN is set, these GitHub API
requests are authenticated (the token is sent only to api.github.com), which
avoids the anonymous rate limit that shared CI runners hit.
For a coordinated unreleased Classic protocol change, retain the immutable lock and point only the development process at that checkout's generated bindings:
export ATRINIK_PLAYTESTER_PROTOCOL_SOURCE=/path/to/classic/protocol/generated/pythonThe source directory must contain atrinik_protocol. Playtester requires the
protocol revision 1085 and rejects an older installed wheel. The immutable
v5.106.0 lock identifies the matching released wire-1085 wheel, so normal
installation and doctor require no source override. Do not use the override
for a released run; it validates the exact generated-source module origin
rather than relabeling an installed artifact.
Install the exact content compiler/catalog and Classic runtime selected by
dependencies.lock.json. The default cache is
$XDG_CACHE_HOME/atrinik/playtester or ~/.cache/atrinik/playtester and can be
overridden with --cache or ATRINIK_PLAYTESTER_CACHE.
/path/to/playtester-environment/bin/atrinik-playtester dependencies
/path/to/playtester-environment/bin/atrinik-playtester doctor
/path/to/playtester-environment/bin/atrinik-playtester preflightdependencies downloads the content source and Classic-runtime archives, the
farming analyzer release asset, and the Classic server source archive over
HTTPS. It verifies their immutable SHA-256 coordinates, validates their bounded
layouts, and installs all four as one atomic cache generation. To seed a machine
from already downloaded files without network access:
atrinik-playtester dependencies \
--source-archive /media/atrinik-content-1.14.0.tar.gz \
--runtime-archive /media/atrinik-content-1.14.0-classic-runtime.tar.gz \
--analyzer-archive /media/atrinik-tools-farming-analyzer-3.10.0.tar.gz \
--server-archive /media/atrinik-classic-server-5.99.0.tar.gz \
--offlineAfter one successful installation, atrinik-playtester dependencies --offline
verifies and reuses the cache. doctor performs a full tree-integrity check and
diagnoses missing, mismatched, or corrupt content, protocol, and pathfinding
inputs. Gameplay commands discover the verified content tooling and runtime
from that cache; no aggregate repository or ambient sibling checkout is needed.
Requirements are Python 3.11+, CMake 3.21+, Ninja, and a C17 compiler. The
native adapter uses the checksum-pinned Classic libatrinik pathfinding release.
Run scripts/install_locked_protocol.py with the Python environment that will
build the package before configuring CMake. Install the required aioquic
transport dependency in that environment for the live TLS regression tests.
cmake -S . -B build/playtester -G Ninja -DBUILD_TESTING=ON
cmake --build build/playtester --parallel
ctest --test-dir build/playtester --output-on-failureThe complete Python suite uses the same installed bundle. Build the package, acquire it once, configure the verified paths through the package API, and run the regression suite:
PYTHONPATH=build/playtester/python python3 -m atrinik_bot dependencies
PYTHONPATH=build/playtester/python python3 -m atrinik_bot doctor
PYTHONPATH=build/playtester/python python3 - <<'PY'
import unittest
from atrinik_bot.compatibility import (
configure_cached_bundle,
default_cache_root,
load_lock,
)
configure_cached_bundle(default_cache_root(), load_lock())
result = unittest.TextTestRunner(verbosity=2).run(
unittest.defaultTestLoader.loadTestsFromName("atrinik_bot.test_bot")
)
raise SystemExit(not result.wasSuccessful())
PYRun commands from the build directory so the assembled atrinik_bot package,
including its native extension, takes precedence over the source files at the
repository root.
Install the package or invoke the assembled package. Credentials and mutable state belong outside the source tree and should be supplied through environment variables or a private launcher:
ATRINIK_BOT_ACCOUNT=playtester-account \
ATRINIK_BOT_PASSWORD='replace-me' \
ATRINIK_BOT_CERTIFICATE_SHA256='replace-with-server-certificate-sha256' \
ATRINIK_BOT_CHARACTER=Playtester \
ATRINIK_BOT_RUNTIME_STATE=/private/state/playtester.sqlite3 \
atrinik-playtester autoplay--runtime-content remains available as an explicit runtime override for
diagnostics, but ordinary runs use the locked cached runtime by default.
Use atrinik-playtester --help for transport, registration, character,
dashboard, navigation, quest, farming, banking, selling, and storage options.
The dashboard binds to loopback and rejects cross-origin control requests; use
an authenticated local tunnel instead of exposing it directly. Every response
carries a Content-Security-Policy (default-src 'self'; script-src 'self'; object-src 'none'; frame-ancestors 'none'; base-uri 'none'): the page loads
nothing from elsewhere, runs no inline script, and sets element styles
through CSSOM rather than inline style attributes, which the policy refuses.
The dashboard's Stop outlives a restart. It is stored in the runtime state
database for the configured --character, and the autoplay command then
starts idle (survival only) until Start autoplay clears it, so a service
manager that restarts the bot does not undo the owner's Stop. Other
dashboard tasks (quests, navigation, farming and so on) do not clear it, so
after one of them a restart still starts idle. Without --character
nothing is stored: the bot logs a warning once, and the dashboard's last
task says the Stop is not kept across a restart.
atrinik-playtester --version, the startup log line, and the dashboard header
name the build: its release tag (with +N when the commit is N commits past
it) and short commit, linked to GitHub. CMake records them from Git on every
build; a tree without Git metadata reports an unknown build.
The dashboard serves GET /metrics in the Prometheus text format 0.0.4
(text/plain; version=0.0.4; charset=utf-8), so a scraper can record what the
bot does over hours for analysis. The endpoint has the same access rules as
/api/state: it listens only on loopback, rejects a non-loopback Host
header, and needs no other credential. It is read-only and holds no secrets.
It never includes the account, password, invite code or certificate. Scrape it
from the same machine or through the same authenticated tunnel as the
dashboard. Deploying Prometheus or Grafana (scrape configuration and
dashboards) is out of scope here.
Every series is named atrinik_playtester_* and carries character (in lower
case) and server labels. Counters are kept in memory and start again from zero when
the process restarts, which rate() and increase() handle. Every other
label comes from a bounded set: server-named monsters (at most 300), skills,
attacks, damage types, spells, potions, action kinds (at most 200) and task
types each have a fixed cap. Values past a cap are counted as other. Chat and
other player-typed lines are never parsed into labels; a PvP kill's victim is
the one character name that can appear, within the monster cap.
Gauges, read from live state on each scrape:
connected(1 while playing),hp,maxhp,sp,maxsp,food,level,experience,regen_hp,regen_sp,depletion_points;skill_level{skill},skill_experience{skill};money_carried_copper,money_banked_copper(only once a balance is known);farm_predicted_xp_per_hour{objective}: the farming analyzer's estimate for the spot autoplay farms (its usable pick, not always the first-ranked);task_info{task}andphase_info{phase}: 1 for the running top-level task type and autoplay phase;operator_assisted: 1 once an operator assist has given her coins, so progress from then on is not all earned in play;operator_assist_copper(copper given in total),operator_assist_last_timestamp_seconds(when the last run whose coin left the operator ended) andoperator_assist_running(1 while one holds her still).
Counters:
| Metric | Labels | Counts |
|---|---|---|
kills_total |
monster |
"You killed …" lines |
experience_gained_total |
skill |
experience from "You got N exp in skill …" |
damage_dealt_total, hits_dealt_total |
attack |
"You hit … for N with …"; the server sends one line per attack type of a swing, so hits count damaging lines, not swings |
damage_taken_total, hits_taken_total |
type |
"… hit you for N … damage", one damaging line per attack type |
spells_cast_total |
spell |
spell casts ordered (including any the server refuses) |
mana_spent_total |
each ordered cast's listed spell cost | |
heals_total |
source |
her own healing spells on herself (spell) and healing potions applied (potion) |
healed_hp_total |
health restored by her healing spells on herself | |
potions_used_total |
potion |
potions applied |
deaths_total |
cause |
deaths, by the post-mortem cause |
rests_total |
rests started to regain spell points | |
actions_total |
kind |
every recorded action and decision, such as retreat, melee-kite or farm-pack-split |
purchases_total, sales_total |
shop purchases and sales | |
money_spent_copper_total |
reason |
money paid in shops (purchase) |
money_gained_copper_total |
source |
money received for sales (sale) |
item_moves_total |
direction |
item moves ordered: store, retrieve, loot (corpse moves and /take commands), pickup, drop |
chat_lines_total |
direction, channel |
player chat heard and answered |
connections_total, reconnects_total, disconnects_total |
game server connections; a failed attempt also counts as a disconnect | |
tasks_started_total |
task |
top-level tasks started |
tasks_finished_total |
task, status |
top-level tasks that completed, failed or were stopped from the dashboard (stopping counts as failed); a task replaced by another is not counted |
state_seconds_total |
state |
seconds fighting, resting, travelling, shopping (shops, temple, NPC dialogue), busy, idle or disconnected (not playing) |
observations_total |
source |
observations stored, by source kind; a repeat of a stored reading counts again |
facts_total |
kind, status |
facts first stored, by kind (tile-property, key-name, ...) and status (candidate, confirmed) |
fight_positions_total |
feature, outcome |
fights recorded by terrain: corridor, doorway, room, open or unknown, and won, retreated, recalled or died |
observations_dropped_total |
reason |
readings the ingestion filter refused: chat, player-link, who-list, player-name, signed-book, unmatched-book, book-unverified, renamed-item, examine-interrupted, unauthored-item, examine-unverified, book-examine |
The time in each state follows the latest recorded action that marks one. For
example, a target or a kite step means fighting, and a step or route decision
means travelling. Actions that mark none, such as applying an item, keep the
current state. A task that has not yet done anything that marks a state is
busy; with no task running, she is idle.
She keeps what she reads or is told in the observations table of the
runtime state database (observations.py, memory.py; the design is
docs/LEARNING_AND_FEEDBACK.md 4.2 and
4.3.1, phase F1). Recording changes nothing she does.
- Only her own observations. Player chat channels, lines carrying a
player-name link,
/whoroster lines, books a player signed, unsigned books whose text matches no authored text, renamed items and any line naming another character she has seen (chat senders,/who, players in view) are never stored. Her own name becomes{activator.name}, as in authored text. Other players' names are held only in memory, to filter with, so after a restart only players seen since then are known. - Only exact matches with authored content. Sign, door and
magic-mouth text must equal the authored message of an object on or next
to her square (
timingwhen her own bump, apply or step in the previous 1.5 seconds reached it, elsecontent-match; a broadcast she did not cause, with another player in view, is not hers). A fixed server phrase ("You open the door with the key.", "You turn the lever.", "Nothing is written on it.") is kept only when an authored door, lever or sign of that name stands where her one bump or apply in the window reached. Books are kept when their text is authored, under the authored title, never the one received, and as the normalized authored form, never the received spacing. Examines of books are not kept (a player can name a book anything); an examine is kept only when the item's shown name is an authored name and every line is one of the forms the server's examine sends; one soulbound to someone is dropped. Dialogue pages are not kept (NPC scripts build them from player data; see the design's phase F13). An unattributed line is stored, assystem:<map>, only when it is a fact line (the server's no-magic and no-harm refusals, such as "Something blocks your spellcasting."). The same text from the same source raises the row'sseencount. - The authored-text index is scanned from the locked content (maps,
archetypes, artifacts, materials and the book message file, about 1.3
seconds) when the
weborautoplaycommand starts. Without it only fact lines are kept. - Bounded. At most 50,000 rows a character, 4,000 characters of text a row; when full, the least recently seen rows that no later table refers to are evicted first. Writes wait at most 0.25 seconds for a locked database and otherwise drop the reading, never the game line.
The dashboard's read-only Knowledge tab lists her facts and recent
readings by kind and source (GET /api/knowledge?kind=SOURCE&limit=N&fact_kind=KIND&fact_limit=N, newest
first, up to 1000 each, under the same loopback and Host rules as
/api/state).
Fixed parsers (facts.py, the design's 4.3.2, phase F2) read facts out of
each stored observation into the facts table: key names a lock asks for,
key holders engraved on a door, lock colours, NPCs that mention a key,
passwords (an empty value when the text promises one and gives none),
directions, trap warnings, creature weaknesses and immunities, quest-gate
hints, quest-part places, doors that say they do not open, and lock texts
that name nothing. They are regular expressions over the stored text and
the authored names; no model, network or chat is involved, and nothing
but a kept observation is read. Each fact cites its observation
(facts.observation_id), which is then never evicted. Every parsed fact
is a candidate: a hint, never an unlock. One row per kind, subject and
value; a repeat refreshes it. At most 20,000 a character, the least
recently updated candidates evicted first.
Tile facts. When the server refuses her magic ("Something blocks your
spellcasting.", "Powerful countermagic cancels all spellcasting here!") in
answer to her own recent cast, the square of the cast (or the whole map)
is kept as a confirmed tile-property: no_magic fact, besides the one-hour
mark idle survival already sets; "Powerful countermagic cancels all
harmful magic here!" is kept as no_harm and changes nothing. A fact is
kept only when the refusal certainly belongs to the cast: no step was in
flight when she cast (sent after a map update last moved her), and for a
square she still stands where she cast,
for a map she is still on the cast's map. Anything else (a potion drunk
after an exit, a cast in the same tick as a step) is kept as nothing.
Tile facts lapse after 7 days unless a refusal refreshes them, and count
only under the content revision they were seen with (the locked
atrinik/content revision, in the fact's inputs).
A remembered fact never blocks anything by itself; idle survival's
one-hour mark still alone stops casts, the emergency recall included.
With --persist-tile-facts (or ATRINIK_BOT_PERSIST_TILE_FACTS=1), a
remembered no-magic square or map only reorders healing: a potion or
other non-magical heal comes before a spell, scroll, rod or wand there
(tile-fact-no-magic, once a square). With no other heal she casts
anyway, at any health: a refused cast costs nothing, and that cast tests
the fact. Off (the default), healing is unchanged and a
tile-fact-no-magic-shadow decision records once a square where she
would have put another heal first.
A fact is refreshed only by another no-magic refusal attributed to its square or map; nothing refutes it, since a cast the server drops without a word (her action timer, a device it refuses first) looks the same as one that worked. So with the flag on, a stale fact can make her drink a potion instead of casting on that square until it expires, at most 7 days after the last refusal (or at once, when the content revision changes).
She works out what each piece of gear really adds when worn
(equipment.py; the design is
docs/LEARNING_AND_FEEDBACK.md 4.8, phase
F3). This changes no choice yet: the name-based gear_score still decides
what she wears and buys.
- The "+N" rules follow the Classic server. "+N" adds N to each of AC,
block and absorb the item has a base value for and, unless it is a
launcher, to WC and damage likewise; a base of zero gets nothing, so a
silk cape +2(capes have no AC) adds no AC. A launcher's "+N" goes to each arrow it fires, and its protections do not count. A light adds nothing. Protections, attacks and a weapon's damage scale with condition. - Examining carried gear. On a quiet farm tick (no threat in view, the recall-wand rule) she examines each identified gear item she carries once a session, what she wears first: one at a time, at least 2 seconds apart, waiting up to 5 seconds for each. Recall-wand and mana-crystal examines wait for its answer and it for theirs, so normally only one examine is in flight. The walk out of a farm, waiting for her wands' charges, abandons a waiting gear examine instead; the gear examiner then pauses for 7 seconds, so its late answer, read by nothing, comes before her next gear examine is asked. The observation ledger may then pair that late answer with the wand's examine; the row still carries the item's name from its own line, and the wand's answer may go unrecorded. Examine shows the base stats without the "+N"; until an item is examined its archetype's base stats are used.
- Shadow logging. At most every 30 seconds she compares, per gear
family, what the current score and the effective-stats score would put
on. Each change in where they disagree is a
gear-shadowdecision with both items and both scores, for the owner's review before phase F4 switches the scoring.
The dashboard's read-only Equipment tab lists each gear family she carries: what she wears and the best candidate, with both scores, the effective stats, per-stat differences and notes such as "+2 on a cape adds no AC", and the recent shadow log.
She records where she stood in each fight (terrain.py, memory.py; the
design is docs/LEARNING_AND_FEEDBACK.md
4.7, phase F10). Recording changes nothing she does.
- A fight starts at the first combat line of hers in a while (a hit or
miss on her, a block, dodge or parry, her own hit or kill) and ends 10
seconds after the last one, when she leaves the map (crossing a tile
seam to the next map keeps it), or 2 seconds after her death (hits until
then still count, as in the failure review); a fight longer than 15
minutes is cut there. It ends
diedon her death,recalledafter her emergency recall,wonwhen she killed something, andretreatedotherwise. Damage over time from her own poisoning or disease ("poison hit you for ...", or a symptom under its disease's name, "flu hit you for ...", from the authored diseases in the locked content) names no attacker and starts no fight. - The square is read when the fight starts, and again where she stands
when a second attacker hits her within 8 seconds. Its
reachis how many of her 8 neighbours a walking monster could stand on, from the authored walkability she plans with (a door counts; the server lets a monster hit a diagonal neighbour past a wall corner; off the map counts only toward a tiled neighbour). Its feature iscorridor(reach 2, opposite each other),doorway(a door on or next to her, or a one-wide gap into a room),open(reach 7 or 8 and at least 20 standable squares within 2),room(anything else), orunknownoff the world graph. - Counts only. Peak attackers (the most distinct attackers within 8
seconds, counted exactly as the failure review counts packs), ranged
monsters in view and how many a wall or door covers (on the cells an
aimed bullet crosses, as
bullet_ray_cleartests them), creatures and players in view, kills, damage taken and seconds. No attacker's or player's name is stored. - Bounded. The recorder reads only new server lines each engine step and looks at the creatures in view only during a fight; a fight keeps at most 2,000 hits. A row waits at most 0.25 seconds for a locked database and is otherwise dropped; at most 20,000 rows a character, oldest evicted first. An error in the recorder forgets the fight and never reaches the game loop; it is logged once, then counted every 10 minutes until a step works again.
The read-only Terrain panel on the dashboard's Farming tab lists her
recent fights and the rates learned per feature, peak attackers and
ranged monsters in view: fights, damage a second and deaths, each day's
fights weighted with a 7-day half-life (GET /api/terrain?limit=N, up to
200, under the same loopback and Host rules as /api/state).
She collects what confuses her as deduplicated drafts in a local queue
(feedback.py, feedback_producers.py; the design is
docs/LEARNING_AND_FEEDBACK.md 4.10, phases
F5 and F6). Nothing leaves the machine until the owner approves an item with
the CLI on CT130: the game process and the queue's code open no socket and
never see the GitHub credential. Only the separate filer (feedback file,
its own systemd unit) files approved items, as issues signed by a small
GitHub App; see "Approval and filing" below.
- Producers. "+N with no effect": an examined item of hers whose name
shows "+N" on a type and base that gain nothing from it (a
silk cape +2), one aggregate draft foratrinik/classiclisting the archetype families she met. Book experience at low Int: an authored book she read at Int 10 or lower, where the server'sbook_exp_modis negative, one draft foratrinik/classic. Typos (a small list of common slips such as "a the", "the the" and "recieve") in authored door, gate, lever, sign and magic-mouth text, one draft a source foratrinik/content. They read only her stored observations, her own stats and skills and her own gear, never chat; the typo producer also reads the stored lock and sign texts once a login. - Deduplication. Each draft has a fingerprint, the sha256 of its kind,
repository, subject and claim, shown as
pt-and 12 hex digits. The same fingerprint never makes a second draft, across restarts too; a new occurrence raises its count, and a draft's body is rendered again from its evidence each time; its day count is the number of distinct dates. At most 500 drafts a character: a new draft evicts the one with the fewest occurrences, then the least recently seen. Drafts carry dates, never times of day, and name a map only by its authored path, never a player's own map. - Privacy. A draft holds only authored text and her own state. Game
text appears only in a fenced code block longer than any backtick run in
it, with HTML comment markers and invisible characters removed, so a
@name,#123, link or copied fingerprint line in it does nothing; names are inline code. An excerpt line naming another character she has seen (in view, in/who, or any chat sender her memory keeps) is dropped. A draft whose title or body would contain her account, character or the server's address, the password, the invite code, her party, the operator character or another character's name is not stored at all. Every reader checks stored items again against the names known now: one that names a private term is withheld, shown with no text, and stays withheld; it can only be rejected.
The dashboard's read-only Feedback tab lists the items, filtered by
kind and repository, with the exact body that would be filed (the Markdown
copy), the issue once filed, the filer's error and an item's possible
duplicates (GET /api/feedback?kind=KIND&repo=OWNER/NAME&status=STATUS&limit=N).
It has no write route: approving, rejecting and editing are CLI-only (owner
decision, 2026-11-19). Items filed without their labels or type, waiting on
a duplicate review, or failed raise dashboard alerts. On CT130:
# With the service's ATRINIK_BOT_ACCOUNT, ATRINIK_BOT_CHARACTER and
# ATRINIK_BOT_RUNTIME_STATE, and its --host and --port:
atrinik-playtester --host HOST --port 1728 feedback list
atrinik-playtester --host HOST --port 1728 feedback show pt-4f1c2a9b0d3e--host, --port, --account and --character select her rows as the
bot stores them; list takes --kind, --repo and --status, and
list --json and show --json print JSON. The command opens the database
read-only, whether or not the bot is running, and needs no network and no
game inputs. It knows fewer names than the running bot (none it saw in
play), so it shows an item's text only once the running bot has screened
it since it last changed; otherwise it prints "(not yet screened by the
running bot)" and the metadata. Run it as the bot's service user: SQLite
may create the database's -wal and -shm files even for a read-only
reader when the bot is stopped, and files created by another user can then
stop the bot from opening its database.
The owner decides on CT130, as the bot's service user (with its
environment, so the CLI knows the account, character and the other private
terms; for example sudo -u playtester and the release's full path, as for
operator assist below):
atrinik-playtester --host HOST --port 1728 feedback approve 12
atrinik-playtester --host HOST --port 1728 feedback reject 13
atrinik-playtester --host HOST --port 1728 feedback reject 14 --duplicate https://github.com/atrinik/content/issues/9
atrinik-playtester --host HOST --port 1728 feedback approve 14 --file-anyway
atrinik-playtester --host HOST --port 1728 feedback edit 12 --title "..." --labels bug,maps --type Bug
atrinik-playtester --host HOST --port 1728 feedback edit 12 --body-file body.md
atrinik-playtester --host HOST --port 1728 feedback show 12 --markdownapprovetakes only an item that is not withheld and that the running bot has screened with her full private terms since it last changed (the bot screens approved and edited items every minute); it prints the Markdown copy.--file-anywayfiles an item the filer held inneeds-reviewdespite its possible duplicates. Approving afaileditem is the retry.rejectends an item;--duplicate URLmarks it a duplicate of an existing issue. A withheld item can only be rejected.editchanges the title, body (-reads standard input), labels, type (defaultchooses by kind), repository or target (new-issue, or an issue URL in the item's repository to post it as a comment). The body keeps its fingerprint footer, is screened before it is stored, and the item becomes a draft again, to be screened by the bot and approved again.
The filer, atrinik-playtester feedback file, files approved items one at
a time: it refuses an item that is withheld or that the running bot has not
screened since its approval (checked again when it claims the item, so one
withheld or edited meanwhile is never filed), screens it again itself, checks GitHub for an
issue with the same fingerprint or the same map in its title (holding a
match in needs-review), creates the issue with the item's labels, the
playtester label and the type (Bug, Feature or Task), reads it
back, and marks it filed, or filed-unlabelled when GitHub dropped a
label or the type. A comment: target is posted as a comment instead. It
files at most 5 items an hour and 20 a day, 60 s apart, honours GitHub's
Retry-After and secondary limits with a back-off from 10 minutes, and
stops while GitHub's remaining core quota is under 50. It never follows a
redirect, and an item an earlier run already filed goes to needs-review.
The commands run only as the user that owns her memory database. Every request is a row in her memory's
feedback_filings audit table. Without the App key (or with --dry-run)
it sends nothing, leaves the items approved and prints their Markdown
copies.
The key is read only by the filer, from its systemd credential
($CREDENTIALS_DIRECTORY/feedback-app.pem) or --app-key-file, which
must be readable by nobody else. The filer signs a short-lived RS256 JWT
with it (the cryptography package, already required by aioquic), mints
an installation token for the one repository it files to with
issues: write, revokes it when done, and never prints, logs or stores
the key, its path, the JWT or the token. One-time setup before live filing:
-
Create a GitHub App owned by the
atrinikorganization with repository permissions Issues: read and write and Metadata: read-only, nothing else, no webhook; install it onatrinik/content,atrinik/classicandatrinik/playtesteronly. Note its App ID and generate a private key. -
On CT130, place the key as
/etc/atrinik-playtester/feedback-app.pem,root:root, mode0400, so that only systemd can read it and hand it to the filer's unit. -
Create the
playtesterlabel in each of the three repositories (the filer never creates labels; without it items are filedfiled-unlabelled). -
Add the filer's units next to the bot's service, with the bot's user and runtime state. Give the filer its own environment file with only what it needs:
ATRINIK_BOT_ACCOUNTandATRINIK_BOT_CHARACTER(they select her rows),ATRINIK_BOT_RUNTIME_STATE, and for its own screenATRINIK_BOT_PARTY,ATRINIK_BOT_OPERATOR_CHARACTERandATRINIK_BOT_CERTIFICATE_SHA256. It does not need the game password or invite code: it never logs in, and the running bot's screen with every private term, which the filer requires after each approval, covers them.# atrinik-playtester-feedback-file.service [Service] Type=oneshot # The bot's service user, and the bot service's own environment file # (account, character, runtime state and the other private terms). User=playtester EnvironmentFile=/etc/atrinik-playtester/feedback-filer.env Environment=ATRINIK_PLAYTESTER_FEEDBACK_APP_ID=APP_ID LoadCredential=feedback-app.pem:/etc/atrinik-playtester/feedback-app.pem ExecStart=/opt/atrinik-playtester/current/venv/bin/atrinik-playtester --host HOST --port 1728 feedback file NoNewPrivileges=yes LimitCORE=0 PrivateTmp=yes ProtectHome=yes ProtectSystem=strict # The directory of ATRINIK_BOT_RUNTIME_STATE (her memory and its lock). ReadWritePaths=STATE_DIRECTORY # atrinik-playtester-feedback-file.timer [Timer] OnBootSec=10min OnUnitActiveSec=15min [Install] WantedBy=timers.target
The game's own unit must not have the
LoadCredential=line or the key path in its environment.
The owner can have an operator character hand the played character gold. This is the one, narrow exception to playing only through ordinary player capabilities (owner decision, 2026-11-16, when Sera was 1,827 copper short of the temple's remove-depletion fee). Nothing automatic ever starts it: autoplay, tasks, the client and the task engine hold no reference to it.
It is disabled until ATRINIK_BOT_OPERATOR_CHARACTER (or
--operator-character) names another character on the same account. Grant
that character exactly the two commands it needs, from a game master's
session:
/cmd_permission <name> add tp
/cmd_permission <name> add create
Do not give [OP] or * to any character this bot logs into: those grant
every command, including /console, a server Python console.
When enabled, the bot creates an owner-only key at start-up, if none exists:
operator-assist.key (mode 0600, owned by the service user) next to its
runtime state (ATRINIK_BOT_RUNTIME_STATE), else in
/var/lib/atrinik-playtester, or at ATRINIK_BOT_OPERATOR_KEY_FILE.
POST /api/operator-assist requires that key in the
X-Playtester-Operator-Key header (compared in constant time) and a
Content-Type: application/json body; reaching the dashboard is not enough.
Requests without the right key are refused with 403, write no audit record,
and are logged at most once a minute. As defence in depth, the lab's
reverse proxy should deny /api/operator-assist outright.
With the bot running (web or autoplay), the owner stops autoplay from
the dashboard and runs, on the same machine, as the bot's service user so
the command can read the key (for example sudo -u playtester):
sudo -u playtester /opt/atrinik-playtester/current/venv/bin/atrinik-playtester \
operator-assist --give-gold 1 --to Sera --web-port 8765 --then-autoplayThe full path is the release installed by the home-lab role. That role puts
no atrinik-playtester on sudo's secure PATH.
Give --key-file when the key is elsewhere. The command posts to the
running bot's loopback dashboard, prints the audit record, and exits 0 only
when the coin reached her. The running bot then:
- refuses unless the feature is enabled,
--tonames the character it plays, the amount is 1 gold coin (the cap), the last run that reached/createwas more than 24 hours ago, and she is idle at a safe square: logged in, no task or idle food trip, no target or combat, nothing hit her in the last 10 seconds, health at least 90% and food at least 300; and she can carry the coin (the server refuses a pickup unless what she carries plus the coin stays under her weight limit, which depletion lowers with Str: on 2026-11-18 Sera carried 40.6 kg against 25 kg, so shed weight first); - holds her still (
TaskEngine.operator_hold: no task, idle survival or inventory upkeep acts; dashboard tasks other than Stop and manual actions are refused) and cancels her queued movement; - logs the operator character in on a second connection. The Classic server
lets one account play several characters at once; it only replaces a
second session of the same character (
player_login). She stays logged in throughout. If the owner is playing the operator character at that moment, that session is disconnected, and after the run the operator character stays saved on her square; - as the operator, sends
/tp Sera(onto her exact square), waits until the operator is on her square and her sub-layer (a drop lands on the dropper's sub-layer, and/tpdoes not set it), then sends/create goldcoin(one gold coin, 10,000 copper, into the operator's inventory), drops exactly that coin and logs out; - has her pick the coin up from her square, then releases the hold. The
ground window sends no item types, so the coin underfoot is the item
named
gold coin.
Each step has a timeout, and before every order and on every poll it checks
that holding her is still safe (no target or combat, no hit on her, health
at least 90%), because the hold also suspends her idle healing. Any failure
aborts the run: the operator is logged out, the hold is released, and the
record says which step failed and where the coin is (none,
operator-inventory, ground on her recorded square and sub-layer,
character, or unknown). After an abort past /create it looks once
more, a second later, at the operator's inventory and her square; a coin
neither accounts for, such as one whose /create went unanswered, is
unknown. If her own connection drops meanwhile, her normal reconnect
restores her and the pickup waits for her. A run that failed before
/create, or whose /create the server refused (no permission, or
'/create' is not a valid command.), does not count toward the daily
limit; a run whose counted record cannot be saved never sends /create.
Every run and refusal while enabled is an audit record in her memory
database (memory.sqlite3, kind operator_assist) and in the decision log
(operator-assist). The list keeps 200 records, trimming only refusals and
runs that never reached /create, so the daily limit and the assisted mark
can never be pushed out. Gold counts as given once the coin left the
operator (it reached her square or her pack) or may have (unknown). From then on, the dashboard shows
an Operator-assisted since … header notice and the coins given next to her
wealth, and the metrics above mark her as assisted: progress after it is not
counted as earned.
Autoplay and the dashboard rank farm spots with the locked atrinik/tools
farming analyzer instead of hard-coded level bands. The dependency installer
caches its release asset and the Classic server source whose experience tables
it reads. During web and autoplay, a background task checks the character
every 30 seconds. When the killing weapon school's level, the player doll's DAM,
WC, weapon speed, movement speed, max HP, AC or protections change materially, or the last
ranking is six hours old, it starts one nice analyzer process with
--ranking all --json (about 10 to 30 seconds) while the bot keeps playing.
Runs are at least ten minutes apart, failures back off for fifteen minutes, and
a failed run keeps the previous ranking. Only melee weapon schools are
simulated so far.
A spot is only as safe as the way there. Once her savebed is known and exists
in the locked content, each run passes it as --approach-origin MAP --approach-origins-only, and a savebed move triggers a new run. The analyzer
then charges the most dangerous pack crossed between the savebed and the spot
against her live maximum HP (--max-health), and reports the spot's
safety_score as the lower of the spot's own safety and that approach safety.
Otherwise the analyzer's default origins apply. A spot the analyzer finds no
path to is capped at an approach safety of 0.5
(--unreachable-approach-safety), because its walk does not model ships,
scripts or keys. Autoplay farms spots with a known approach safety of 100%
before any spot whose approach is unknown or expected to cost more than her
whole health bar, keeping the analyzer's order within each objective's ranking. A risky
approach is taken only when nothing else is usable, and then the safest one
first (unreachable counts as 0.5). An apartment savebed is judged from its
recorded return, since the apartment is left only through a script the
analyzer does not follow, and an origin the analyzer rejects is retried once
from the default origins and not passed again. Raw rankings list every
circuit permutation, so each run keeps the top 40 per objective. The Farming
tab shows each spot's approach: its safety, worst map and danger, or that it
is unknown, and marks the spot autoplay farms with its rank.
The dashboard's Farming tab shows the run status, the simulated profile and the top spots for the preferred objective: XP, money or loot per hour, balanced, or safety. The choice is saved per character and needs no new run, because one run ranks every objective. The rates are model estimates for comparing spots, not live measurements.
Autoplay farms the preferred objective's #1 usable spot. The exception is depletion: while the live depletion force is present and her depletion count is at the temple-service threshold (3), it farms the safety ranking instead, until the depletion is removed. If no safety spot is usable, it keeps the preferred objective's spot, because the circuit removes depletion before any farming whenever an item or the temple fee allows, and farming is what pays that fee. The Farming tab then shows the ranking she actually farms, and notes the depletion override; the objective toggle keeps showing your choice.
There are no level bands or curated spots: the analyzer result's map paths become the circuit's legs (a multi-map circuit rotates through every map), and its listed monsters become the targets. Spots whose residents include aggressive spawns get cautious recovery margins (flee at 80% HP, heal at 95%) and isolated pulls from squares outside other residents' detection radii; other spots use 75% and 90%. Until the first ranking exists, autoplay holds position safely. The Tasks tab's Farm picker lists the same ranked spots.
A death or emergency recall at the spot does not make autoplay give it up. Instead it reviews the last minute of combat messages and decisions to find out why, and adapts:
- pack: two or more monsters were hitting at once;
- resources: spell points ran short of the next heal;
- damage-type:TYPE: one non-physical damage type dealt most of the damage;
- out-damaged: a single attacker simply hit harder than she could recover;
- route: the failure happened on the way there, not at the spot.
Each failure raises the spot's adaptation level (up to 4). Each level raises the flee threshold by 3% and the heal threshold by 2%, capped at 90% and 98%. The lessons are persisted per character, and the dashboard's Farming tab shows them, together with improvement goals aggregated across spots (area spells, protection types, offence, healing). Only when the spot keeps failing at the maximum level (three failures there within an hour) does autoplay pause it for an hour and farm the next-ranked spot meanwhile.
A spot is still quarantined for six hours, and autoplay moves to the next-ranked spot, after:
- ten minutes there without any character XP;
- a route there that the world graph cannot plan.
Explicitly configured circuits keep the old behaviour: a death or emergency recall there quarantines the spot.
Before farming a circuit, autoplay moves the character's savebed (the "bed to reality" a death respawns at) to the usable bed with the shortest walk to the circuit's maps, when that saves at least 20 tiles over the current one. Inn and tavern beds work for anyone; apartment and house beds only in the starter apartment. The walk is estimated along the world graph's route from the bed, and the search spreads its routes over ticks so it never stalls combat. A bed that cannot be reached or applied is skipped for the next-nearest one. The dashboard's Farming tab shows where she respawns.
When the analyzer gets a spot wrong, the fix belongs in the analyzer.
Navigation plans over a world graph compiled from the locked content: tile
seams, exits, apartments, locked doors and inventory checkers. Checkers
follow the server: one requires or forbids a matching object, matched by its
slaying or its name, and some use the object up as she passes. The keys she
carries are read from her inventory and from containers her client currently
lists: a key in a closed key ring counts once she opens it. Keys that no
map places, such as quest rewards and NPC gifts, are recognised from their
key archetypes and artifacts. A generic key name shared by several locks,
such as "strange key", opens none of them in planning. Every plan, savebed choice and map-level route uses
this one unlock state, so a keyed shortcut such as Morg'eean's ship counts
only while she carries its key. The Tasks tab's Unlocks section shows the
keys she carries, where, how many gated tiles each opens, and any ambiguous
key names. A map where
she recently died on the way somewhere is avoided for a while when another
route exists.
The owner can block a map, an exit or a tile seam from the Tasks tab's
Owner blocks section, for 1 hour to 7 days; the list shows each block's
expiry and removes it early. A block is a wall for transit on every trip; a
blocked map stays usable as a destination. Blocks are stored per character
in the runtime state database (route_blocks) and are written only through
POST /api/route-blocks: loopback only, a loopback Host, no foreign
Origin, and application/json only, which an HTML form cannot send
cross-site. Only an essential trip (food while she is hungry or starving, a
cure, the depletion service, a savebed move, a trip that funds one of them,
and the recovery phase's recall shopping and walk home) crosses a block, and
only when every route does; a block never sends a trip through a hazard
the planner otherwise avoids. It waits at a safe place (her savebed, or a
map without hostile spawns, with no hostile in view; on a map
with hostile spawns she walks to her savebed first) for full HP and SP, or
HP and SP that have stopped rising for a minute, and a ready recall when she
owns one, then holds fire until the block is behind her. That wait has no
limit and raises a dashboard alert after 10 minutes, and a non-food trip
gives way to a food trip once she is hungry. A food trip, hungry or
starving, waits only for a ready recall, since waiting to regenerate burns
food. Each crossing is recorded (essential-route-override, plus
essential-care-food or essential-care-starving for a food trip, which is
also alerted) and listed under Care crossings.
On every trip she records what the way cost her, in the runtime state
database (route_events, route_traversals and route_requirements, per
character): deaths, emergency recalls and disengages, and the damage she
took on each map she crossed, each against the map and, when it happened
within 3 tiles of her planned path, its 8x8 cell; exits held by a pack and
crossings that failed, against the exit or seam; and each exit, seam and map
she crossed, with the time it took. Subjects use the same map:, exit:
and seam: names as owner blocks, plus cell:. Deaths to other players and
their hits are not recorded, nor is damage on a PvP map, and no row holds a
player or creature name. A respawn is never taken for a crossing,
and a recall only when it lands right beside the next map's arrival square.
Writes are best effort: they wait at most a quarter second for a locked
database, keep a failed write's rows in memory for the next attempt, and
never hold up play. Each signal keeps its own cap (deaths 1,000, damage
5,000), so a flood of one never evicts another, and rows older than 7 days
are deleted. Her route deaths and learned hazards from before this were
migrated once, and her decision ledger's map visits seed the crossing
counts. The Tasks tab's Learned routes section lists the 25 subjects
with the highest provisional cost (one death costs 30 minutes of travel,
halving every 6 hours), their signals, the last event and when the cost
falls below half. It is read-only.
Those events become learned route costs (route_costs.py), in seconds:
each crossing's travel time (her measured crossing times once she has
them) plus the danger of the map it enters, one death counting 30 minutes
and halving every 6 hours, a recall 15 minutes and a full health bar of
damage 5. A death stops counting once her survivability (health, armour,
protections, level) has genuinely improved since, and each safe crossing
cuts a map's or exit's recall, damage and held-exit cost by 30 %, never its
deaths. Today's hazard tiers become graded content costs that steer the
route but never stop a trip. Behind the owner's learned_route_costs flag
(--learned-route-costs or ATRINIK_BOT_LEARNED_ROUTE_COSTS=1), off by
default, a trip takes the cheapest route by those costs; an errand whose
cheapest route carries one expected death or more of learned danger (a
death counts in full until it is 6 hours old) is declined and retried later, while an essential trip goes anyway with the
owner-block care rules, waiting at most 10 minutes
(route-budget-override, route-strict-override, then
essential-care-timeout). With the flag off, plans and farm choices are
exactly as before, and the learned plans run in the shadow: at most
20 ms a task-engine step, at most one trip every 15 seconds and the farm score
every 5 minutes. Where they differ she records route-shadow-diverge or
route-shadow-decline, keeps every comparison for 7 days in the runtime
state database (route_shadow), and the Tasks tab's Shadow routes
section lists the counts per trip kind and the last 20 differences. The
route-shadow command (--hours, --json) prints the same report from
her memory database, read-only, for the owner's divergence report before
any flip. The farm score in the shadow is the analyzer's rate over an hour
minus the learned danger on the spot's route and maps; one fresh death on
the way moves her to any spot rated within half of the top one, and a spot
pauses at 3000 s (4500 s behind a chokepoint).
NPC voyages and quest-gated exits wait behind the owner's dialogue_edges
flag (--dialogue-edges or ATRINIK_BOT_DIALOGUE_EDGES=1), off by default:
the owner turns it on after one supervised voyage. With it off, plans are
exactly as before. With it on, the planner adds the content's dialogue
teleports, such as Sam Goodberry's voyages between Incuna and Brynknot, and
closes the Underground City lake portal until her journal shows Portal of
Llwyfen's "A Strange Portal" done. A voyage is offered only when its quest
state holds in her journal (Sam's Incuna voyage needs Lost Memories
completed; an unloaded journal offers none), when its dialogue only talks
and teleports (no quest step, purchase, enemy or typed text), and when its
arrival has a known way back to where she boarded or to her savebed. The
three voyages that move her savebed are never offered. She takes one by
walking beside the NPC and following its authored pages exactly: a page
that differs, a voyage that does not leave or lands elsewhere is refused
for a day or until her keys or journal change, and is never clicked
through. An owner block can name a voyage as
talk:SOURCE:NPC>DESTINATION, and her route events record each voyage
she takes, or fails to start, under that name. The Tasks tab's Voyages section shows
the flag, each voyage and why it is or is not offered, and the quest-gated
exits. The design for alternative routes, unlocks such as keys, quests and
NPC voyages, and costs learned from her own experience is in
docs/ROUTING.md.
The playtester source is independent of its external protocol, pathfinding,
content-tooling, farming-analyzer, and game-runtime inputs. Their immutable coordinates and licenses are recorded
in dependencies.lock.json and
THIRD_PARTY_NOTICES.md. In particular, a wheel or
binary linked with GPL libatrinik pathfinding is not an MIT-only artifact and
must satisfy the GPL's corresponding-source and notice requirements.
The playtester source is distributed under the MIT License. The
imported atrinik_bot project code was generated and iteratively developed by
OpenAI Codex under Zoey Rose's direct supervision and steering, then reviewed
and accepted by her. Zoey directs its MIT release and grants all rights she
holds in that code. The precise development record, retained history mapping,
and excluded material are recorded in PROVENANCE.md.
The playtester uses atrinik/2 QUIC with a typed game-stream preface.
The locked Classic protocol receives an authenticated admission-policy announcement before setup
or account login. Open servers need no code. Protected servers take one
16-character invite code from an owner-only regular file using
--access-code-file /private/path; the code never belongs in command arguments,
environment variables, dashboard state or checkpoints. The server certificate
pin is required for both modes. Account credentials remain separate. The old
join-password option and setup subtype are removed; old peers fail version
negotiation. Codes grant ordinary admission and never operator capabilities.
The MAP decoder follows the coordinated Classic wire contract, including framed linked depths, ordered continuations and Q5.11/timed-light payloads. It retains every advertised depth from -6 through +6 atomically; the depth-zero view remains the navigation compatibility surface, while target selection uses the authoritative linked-depth actor count. Colored lighting and timed interpolation are consumed for framing rather than rendered.