LEVI-Achaea

A comprehensive Mudlet automation and combat system for Achaea, an Iron Realms Entertainment MUD.

The repo also holds an Achaea knowledge base (kb/): the game's own data on all 203 afflictions, every class's 1,929 abilities, curing, defences and mechanics, cross-checked against the code.

Download

Get the latest release:

Download Levi_Ataxia.mpackage

See all versions on the Releases page.

Also in this repo: Dementia Mapper — a standalone Mnemosyne map + auto-explorer package with no LEVI dependency (released under dmap-v* tags).

Installation

Download Levi_Ataxia.mpackage from the link above
In Mudlet, go to Package Manager (toolbox icon)
Click Install and select the downloaded .mpackage file
Connect to Achaea — the system will load automatically

Auto-Update

Once installed, the system checks for updates on login. When a new version is available, type SYSUPDATE in-game to download and install it automatically.

Credits

The GUI system (zGUI Redux) was originally created by Zulah. It has been enhanced and extended with additional features including namespace migration, configurable vital bars, channel-colored chat, and movable window management.

Features

Combat System (Ataxia)

Feature	Description
Affliction Tracking	Branching probability tracker (V3) — models multiple possible world states, resolves ambiguous cures via probabilistic branching and verification collapse
Automated Curing	SSC integration with custom priority management, curingset profiles
Defense Management	Automatic defense rekeeping, parry system, anti-class priority adjustments; Monk and Blademaster keep DEAF and BLIND up with their timed skills (one send per trance) instead of spending herb balance
Limb Tracking	Self limb counter (SLC) with percentage-based damage, auto-parry, threshold alerts, party callouts
Target Affliction Tracking	V3 probability engine with branching cure prediction, lock detection at configurable confidence thresholds; enemy salve applications count as one cure each; timed afflictions (hamstring, dazzle, hellsight, ...) expire on the game's own duration
Curing Priority Sync	The curing priority table re-sends itself to your `normal` curingset after it changes (at login, as about 8 multi-set commands to stay under the server's 5-a-second limit)

Class Offense Modules (18+ Classes)

Class	Command	Kill Route
Serpent	`ek`	Ekanelia lock, darkshade, scytherus, hypnosis
Shaman	`zz`	Tzantza, affliction locks, bleed, relapse jinx
Blademaster	`bmd`/`bmbs`	Limb prep, brokenstar, lightning/ice
Infernal DWC	`zz`	Vivisect (4-limb / 2-limb), damage kill, riftlock
Apostate	`ll`/`corr`	Lock, corrupt, vivisect, sleep
Monk (Shikudo)	varies	Limb prep, spinkick, telepathy lock
Psion	`zz`/`psmind`/`psflurry`	Mana kill (Psi Excise), unweave execute (Deconstruct), damage burst (Flurry)
Magi	`zz`/`xx`/`vv`/`cc`	Elementalism: salve push, fire burns, water freeze, lock, group, stormhammer
Snipe	`snt`	Class-agnostic snipe with auto-scan
+ 10 more		Bard, Depthswalker, Pariah, Earth Lord, etc.

Automated Basher (PvE Hunting)

Feature	Description
20+ Class Support	Class-specific attack builders with optimal ability selection (incl. Infernal hyena maul / Runewarden falcon rake pet attacks)
Area Pathing	Mapper-integrated speedwalking through configured target lists
Auto-Learn	Adds room denizens to the area target list on entry; `bash mine` excludes your own pets/allies (falcons, your Baalzadeen, etc.) without skipping the room -- and they no longer inflate the swarm count
Your Mounts	`bash mounts` -- mounts are skipped as targets by their ID (a wild dire wolf is still fair game); VAULT makes that mount your active one; while mounted every tactical jump is a MOUNTJUMP, and a refused jump in either direction is re-sent with the right verb
Safety System	Layered danger levels (shield/flee/wait), death recovery with safe-room retreat, stuck detection
Bashing HUD	Live combat panel — target name, mob health bar, colored HP/WP/EP read straight from GMCP, DPS and session stats (kills/crits/gold/time)
No-Flee Areas	World Tree & Mnemosyne shield instead of fleeing (nowhere to run) and keep attacking
Battlerage	Generic and crowd-control handlers with rage conservation
Stormhammer	Dirty-flag cached AoE target list for multi-target rooms
Legend Deck	Data-driven pre-combat card draws for dangerous rooms
Shield Retarget	Per-mob configurable shield durations with target swapping
Glass Lilies	`lily` -- DROP LILY every hour (crit-severity boost), timed from the game's own drop line so a missed drop retries in 5 minutes; `lily on/off/now`, `lily count <n>` (default 3)
Armour Paragons	Profile-based paragon/trait swapping with auto-swap on basher enable/disable

Mnemosyne Suite (`mnem`)

Full tooling for the Mnemosyne, Achaea's endless tower-climb PvE challenge — see the deep dive below.

Feature	Description
Run Telemetry	Reports ripples, monsters, bosses, affixes, boons, and deaths to a community run tracker (opt-in, off by default)
Ripple Mini-Map	Per-ripple 4×4 grid map with click-to-walk — the Mnemosyne is invisible to Mudlet's own mapper
Run History	Local record of every boon offered/claimed and every affix seen, plus an all-time affix library
Auto-Explorer	`mnem explore` sweeps each ripple hands-free: clears rooms, hunts the boss, pauses at boon screens
Swarm Tactics	Crowded rooms (3+ mobs) get pulled, walled, or kited instead of stood in — hit-and-run continues while it works, walls get leapt, plus a vitals-driven low-HP escape ladder
Boon Integration	`BOON CLAIM` intercept auto-reports your pick and adapts to claimed boons — class rotations, Bloodscent per-ripple recon
Affix Handling	Splinterbark turns tree curing off; Haemophiliac slows the sweep until post-kill bleeds are clotted
Boss Tactics	Per-boss counters — Seasone's phial truelock is met with a tree tattoo held in reserve for exactly that moment
Dementia Mapper	Standalone `dmap` package — the map + explorer with no LEVI dependency

Gear & Equipment

Gear Audit & BiS Analysis (`gearaudit`)

Automated gear inventory scanner and PvE Best-in-Slot scoring system. Collects all gear via GEAR LIST ALL + GEAR PROBE, then scores items for PvE damage output.

Command	Action
`gearaudit`	Start new gear audit (scans all gear)
`gearaudit show`	Display all collected gear
`gearaudit detail <id>`	Full details for a gear ID
`gearaudit set/slot/effect <filter>`	Filter by set, slot, or effect keyword
`gearaudit bis`	PvE Best-in-Slot analysis (all slots, per-set + overall)
`gearaudit bis <slot>`	BiS analysis for a specific slot
`gearaudit score <id>`	Detailed score breakdown with weights
`gearaudit scrap`	Scrap recommendations — auto-sends `GEAR SCRAP <id> CONFIRM`, one per balance
`gearaudit scrap <set>`	Scrap recommendations for a specific set

BiS scoring ranks items by weighted stats: Additional/Bonus Damage (10x), Celerity (8x), Burst Damage (7x), Ignore Resistance (6x), Crit Chance (5x), Crit Damage (4x), HP (3x), Battlerage Damage (3x), HP Regen (2.5x), Damage Reduction (2x), Rage Generation (2x), Bleed Damage (2x), Resistance (1.5x). Conditional gear discounted 30-50%. Scrap threshold: items below 50% of set BiS.

Display: gearaudit show and gearaudit bis never truncate. Columns auto-size to the widest value and long effect text wraps onto continuation rows, fitted to the console width (gearAudit.config.display — width to pin it, minEffects for the narrowest Effects column). An effect the summarizer has no pattern for prints its full raw game text rather than a stub.

gearaudit scrap is destructive — it auto-sends GEAR SCRAP <id> CONFIRM for every recommendation, one per balance, with no confirmation prompt.

Armour & Paragon Management (`armour`)

Configurable profile system for armour paragon slots (1-3), trait selections, and armour morphing. Replaces 8+ hardcoded aliases with a single armour command.

Command	Action
`armour`	Show all profiles and auto-swap status
`armour <name>`	Swap to a named profile (e.g., `armour bash`, `armour pvp`): probes the armour and `ii paragon` first, swaps only the embrasures that change, inserts the paragon of that type you hold (by its id), changes nothing if the game does not answer the probe, reports any paragon you don't have (that embrasure is left alone, never emptied), then probes again to verify
`armour probe [profile]`	Show what's in the armour and your inventory, and what a profile would need — without changing anything
`armour add <name>`	Create a new profile
`armour set <n> slot1 <paragon>`	Set the paragon for embrasure 1 (slot1/slot2/slot3) — a type name like `crucious`, or an id
`armour set <n> traits <...>`	Set trait list (space-separated)
`armour set <n> armourtype <t>`	Set morph target (`fullplate`, `cloth`, `auto`, `none`)
`armour auto on/off`	Toggle auto-swap on basher enable/disable
`armour bash <name>`	Set which profile activates when basher starts
`armour pvp <name>`	Set which profile activates when basher stops
`armour morph <type/auto>`	Manually morph armour type (10min cooldown)
`armour scan`	Register every paragon you own: the inventory via `ii paragon` and the ones in the armour via `probe armour`
`armour paragons`	Show all known paragons
`armour types`	Show all 24 paragon types with effects

Pre-configured profiles: bash, pvp, stickpvp, magepve, serppve, stickpve, pariahpve, bmpve

Auto-swap: When armour auto on is set, the system automatically swaps to your bash profile when the basher starts and your PvP profile when it stops. No manual intervention needed.

Armour morphing: If a profile has armourType = "auto", the system looks up the correct armour type for your current class (e.g., fullplate for knights, cloth for magi) and morphs automatically. Auto-detects current armour type on load.

Paragon lookup: Built-in reference for all 24 paragon types with effects. Raw game names from ii paragon are automatically resolved to clean display names (e.g., "an aeneaous paragon" → "aeneaous (absorption)").

Item Catalog (`catalog`)

Comprehensive inventory cataloging system for artefacts, talismans, promo items, and special equipment. Scans via ARTEFACT LIST and TALISMAN LIST, cross-references each item against a 200+ entry knowledge base, and auto-probes unknown items for review.

Command	Action
`catalog scan`	Full scan — ARTEFACT LIST + TALISMAN LIST + auto-probe unknowns
`catalog quick`	Quick scan — ARTEFACT LIST + TALISMAN LIST only (no probing)
`catalog show`	Display all items grouped by type and category
`catalog show artefacts`	Show only artefacts
`catalog show talismans`	Show only talismans (grouped by set)
`catalog show promo`	Show only promo items
`catalog search <keyword>`	Search by name, power, effect, set, or category
`catalog info <id>`	Full details for a specific item
`catalog note <id> <text>`	Add/update a manual annotation
`catalog unknowns`	List unidentified items needing review
`catalog help`	Command reference

Knowledge base covers all credit artefacts (combat stats, offense, defense, utility, travel, crafting, shop of wonders, paragons, housing) and all known talisman sets (Marks, Death, Wonders, Blackwave, Underworld, Contender, Races, Seafaring, Conclave, Eldergods, Moderngods, Wanderer). Items not in the KB are auto-probed and flagged as unknown for manual review.

Persistence: Catalog data persists per-profile — anyone who downloads the package gets the KB, and their personal catalog survives package updates.

Vial Inventory Summary (`elist` / `vlist`)

Compact summary views for elixir and venom inventories. Instead of scrolling through pages of individual vial listings, get a grouped count with total sips/doses per type.

Command	Action
`elist`	Summarise all elixir vials (sends `elixlist`, auto-pages through MORE prompts)
`vlist`	Summarise all venom vials (sends `venomlist`, auto-pages through MORE prompts)

Example output:

--- Elixir Summary ---
health:           15 vials  (2,849 sips)
mana:             22 vials  (4,200 sips)
restoration:       8 vials  (1,520 sips)
empty:            16 vials
speed:             5 vials  (300 sips)
-------------------------------
TOTAL:            66 vials  (8,869 sips)

Automatically handles paginated output (MORE prompts), extracts fluid/venom names from raw descriptions (e.g., "an elixir of mana" → "mana", "the venom prefarar" → "prefarar"), and includes a 30-second safety timeout.

GUI System (Enhanced zGUI Redux)

Originally created by Zulah, enhanced with additional features.

Feature	Description
Draggable Windows	~20 `Adjustable.Container` windows with auto-save/load positions
Tabbed Chat	All, City, House, Order, Party, Clans, Tells, Market, Misc tabs
Native MUD Colors	Preserves original ANSI colors from the server via `ansi2decho()` + `decho()`
Movable Vital Bars	Configurable floating gauges for Health, Mana, Willpower, Endurance, Cape (`ataxiabars`)
Health/Mana Gauges	Gradient-styled gauges with clear overlays in the bottom panel
XP Progress Bar	Purple gauge showing progress to next level
Deathcape Tracker	Kill counter (0-50) with 240-second timer bar
Balance Indicators	Visual bal/eq icons in the bottom panel
Map Display	Integrated Mudlet mapper window
Pop-Out Windows	Double-click any window to pop into a separate OS window
Window Reset	`zfix <name>` to reset any window to default position
Hunting Stats	Session kill count, gold earned, XP/hour tracking

Movable Vital Bars (`ataxiabars`)

Individually movable, configurable gauge bars that float anywhere on screen:

Command	Action
`ataxiabars`	Show status of all bars
`ataxiabars on` / `ataxiabars off`	Master toggle
`ataxiabars health`	Toggle health bar
`ataxiabars mana`	Toggle mana bar
`ataxiabars willpower`	Toggle willpower bar
`ataxiabars endurance`	Toggle endurance bar
`ataxiabars cape`	Toggle cape tracker bar
`ataxiabars reset`	Reset all bar positions to defaults

Defaults: health, mana, and cape enabled; willpower and endurance off. Drag bars to reposition; positions auto-save.

Player Database (ataxiaNDB)

Feature	Description
API Integration	Fetches online player data from `api.achaea.com`
City Highlighting	Color-coded player names by city affiliation
Enemy Tracking	Enemy formatting (bold/italic/underline), priority over city color
Threat Intelligence	`an marks`, `an army`, `an dauntless`, `an threats` queries
Auto-Honours	Automatically honours hidden-city players to resolve affiliation
Bulk Refresh	`an refresh [city]` to update mark/army/dauntless for all tracked players
Player Notes	`an noteadd/noteshow/noteremove` per-player notes

Navigation (Mudlet Mapper / mmp)

Feature	Description
Speedwalking	`mmp.gotoRoom(id)` with optimized pathing
Fast Travel	Wings, tarot, harness, pebble integration
Balance-Aware	Movement waits for balance recovery
Multi-Game	Supports Achaea, Aetolia, Lusternia, Imperian
Area Navigation	`mmp.gotoArea(name)`, `mmp.gotoFeature(name)`

Auto-Update System

Feature	Description
Version Check	Automatic check on login — compares local version against GitHub `version.txt`
One-Command Update	Type `sysupdate` to download, uninstall old, install new, and clean up
Async Downloads	Uses Mudlet's `sysDownloadDone` event pattern (no fragile timer delays)
Error Handling	Reports download failures via `sysDownloadError`

Configuration & Setup

Feature	Description
Setup Wizard	`ataxia setup` — guided configuration for all subsystems
Per-System Install	`atinstall`, `abinstall`, `aninstall` for targeted setup
Config Guides	`ataxia setup guide ataxia/basher/ndb` for comprehensive option walkthrough
Settings Persistence	Fault-isolated resilient loader (cycle-safe, GUI-safe); per-file `.bak` rotation + `_ataxia_backup` profile-backup fallback; `table.save`/`table.load`

Achaea Knowledge Base

kb/ is a reference to Achaea built from the game's own output and checked against this package's code. Afflictions and cures are at its core, because Achaean combat comes down to giving afflictions and curing them. Start at kb/INDEX.md; kb/README.md explains how it works.

What's in it

Area	Contents	Source
Affliction database	All 203 afflictions: cures, the line you see when it hits you and when it is cured, the DIAGNOSE text, durations (45 wear off on their own), and the game's flags (116 cannot be removed by random cures). Old names are mapped (disfigurement = disloyalty). Machine copy: `afflictions.json`	In-game `AFFLICTION SHOW`, `WHATCURES`
Affliction catalog	Every affliction's cure next to what our code believes: the herb the target tracker expects and our PvP and bashing curing priorities. Flags any disagreement	HELP 13.7.2, live WHATCURES, the code (generated)
How afflictions work	The give-and-cure loop from both sides, cure channels and what blocks them, locks, limb damage	HELP files, guides
Class cures	Each class's own cures (fitness, shrugging, passives...), what blocks them, the line that shows them, and our trigger for each	HELP, community guide, code
Expiry lines	Timed afflictions leaving a target: the lines we catch, and the ones still wanted from combat logs	Code, AFFLICTION SHOW
Classes	One page per class (21): every ability of every skill (60 skills, 1,929 abilities) with syntax, cost, cooldown, target and the afflictions it names. Machine copy: `abilities.json`	Achaea wiki
Curing	Every herb, mineral, elixir and salve; server-side curing commands, limits, and a snapshot of a live curing setup	HELP 13.7.x, live output
Defences	The game's 279 defence names, and how ours map to them	Live `DEF` list
Mechanics	Balance, equilibrium and the server queue (including the 10-command limit across all queues)	HELP 4.6, 4.6.1
Conflicts	Every place two sources, or a source and the code, disagree, and how each was settled	--

How it stays accurate

Raw text is kept as evidence. Everything pasted or captured is saved unedited in kb/raw/ (HELP files, live command output, wiki pages, logs), and every curated page lists its sources.
Every claim carries a confidence level: live game output > HELP files > the code > the wiki > community guides > unverified. Live output wins when they disagree; HELP 13.7.2, for example, still says hypochondria is cured by kelp.
Generated pages are rebuilt, never hand-edited, so they cannot drift from their sources.
It is checked against the code. That has already found and fixed real bugs: a target tracker that erased four afflictions on every salve application and never saw head cures, timed afflictions that never expired, a Serpent offense that never saw monkshood land, an Infernal group lock that sent euphorbia for impatience and "plague" as a venom, curing priorities that had not reached the server in two months, and an AI venom reference with 12 wrong venom-to-affliction mappings.

Adding to it

Paste anything (HELP files, AB output, combat logs, announcements) into the knowledge base text file, then run /kb-ingest in Claude Code. It files the new text, updates the pages, cross-checks the code, and logs any conflict.

Capture straight from the game with kbcapture in Mudlet, then /kb-ingest (or python tools/kb_capture_import.py):

Command	What it does
`kbcapture afflictions`	`AFFLICTION LIST`, then `AFFLICTION SHOW` + `WHATCURES` for every affliction (about 400 commands, ~8 min, output hidden; refuses while the basher is on)
`kbcapture help cures \| help heal`	Capture any commands, separated by `\|` (not `;`, which Mudlet splits before the alias sees it)
`kbcapture` / `kbcapture stop`	Progress / stop after the current answer

Refresh the class abilities from the wiki with python tools/kb_wiki_skills.py --refresh.

Tools

Tool	Purpose
`tools/kb_inbox.py`	What is new in the paste file since the last ingest
`tools/kb_capture_import.py`	File `kbcapture` output into `kb/raw/live/` (routes each answer by its content, so lag cannot misfile it)
`tools/kb_affliction_db.py`	Build the affliction database from the captured `AFFLICTION SHOW` answers
`tools/kb_catalog.py`	Build the affliction catalog (game cures joined to our code)
`tools/kb_prio_diff.py`	Compare a captured `CURING PRIORITY LIST` with the code's priority table
`tools/kb_wiki_skills.py`	Fetch every class skill from the Achaea wiki and build the class pages

Affliction Tracker (V3 Branching Probability Engine)

The affliction tracker is the core combat intelligence system. It tracks what afflictions the target currently has, resolving the fundamental problem in Achaea combat: ambiguous cures. When a target eats an herb that could cure any of several afflictions, which one was actually cured?

The Problem

In Achaea, each herb cures multiple possible afflictions. For example, eating kelp cures one of: asthma, weariness, clumsiness, sensitivity, hypochondria, parasite, or healthleech. When the target eats kelp and we've given them both asthma and clumsiness, we see the cure happen but don't know which affliction was removed.

A simple boolean tracker must guess — and guessing wrong means our offense works against a fiction, wasting attacks or missing kill windows. The V3 system eliminates guessing entirely.

How It Works: Branching States

Instead of tracking afflictions as simple true/false values, V3 maintains multiple possible world states simultaneously, each with a probability weight. All probabilities always sum to 1.0.

Core data structure:

afflictionStatesV3 = {
    {affs = {asthma=true, paralysis=true}, prob = 0.6},
    {affs = {paralysis=true},              prob = 0.4},
}
-- "60% chance target has both asthma+paralysis, 40% chance only paralysis"

Definite Operations (No Branching)

When we inflict an affliction (confirmed by a hit trigger), it's added to every branch:

Before:  {asthma=T} @ 60%  |  {} @ 40%
Apply paralysis →
After:   {asthma=T, paralysis=T} @ 60%  |  {paralysis=T} @ 40%

When we confirm a cure (unambiguous removal), it's removed from every branch:

Before:  {asthma=T, paralysis=T} @ 60%  |  {paralysis=T} @ 40%
Remove paralysis →
After:   {asthma=T} @ 60%  |  {} @ 40%

Ambiguous Cures: The Branching Step

When the target eats an herb that could cure multiple afflictions they have, the system splits each branch into sub-branches — one for each possible cure outcome — dividing the probability equally:

Before:  {paralysis=T, slickness=T} @ 100%
Target eats bloodroot (cures paralysis OR slickness) →

After:
  Branch A: {slickness=T}  @ 50%   (paralysis was cured)
  Branch B: {paralysis=T}  @ 50%   (slickness was cured)

A more complex example with multiple pre-existing branches:

Before:
  {asthma=T, paralysis=T, slickness=T} @ 60%
  {paralysis=T, slickness=T}            @ 40%

Target eats bloodroot (cures paralysis OR slickness):

After:
  {asthma=T, slickness=T}  @ 30%   (from 60%, paralysis cured)
  {asthma=T, paralysis=T}  @ 30%   (from 60%, slickness cured)
  {slickness=T}             @ 20%   (from 40%, paralysis cured)
  {paralysis=T}             @ 20%   (from 40%, slickness cured)

Verification Signals: The Collapse Step

Branches are resolved by verification signals — observable in-game events that prove an affliction's presence or absence:

Signal	Proves	Example
Target fumbles	Clumsiness present	`collapseAffPresentV3("clumsiness")`
Target vomits	Nausea present	`collapseAffPresentV3("nausea")`
Target smokes	Asthma absent	`collapseAffAbsentV3("asthma")`
Target applies salve	Slickness absent	`collapseAffAbsentV3("slickness")`
Target stumbles	Dizziness present	`collapseAffPresentV3("dizziness")`
Target has seizure	Epilepsy present	`collapseAffPresentV3("epilepsy")`
Target paralysis fires	Paralysis present	`collapseAffPresentV3("paralysis")`

Collapse algorithm: Eliminate all branches that contradict the observation, then renormalize:

Before:
  {clumsiness=T, asthma=T}  @ 60%
  {asthma=T}                 @ 40%

Observation: target fumbled (proves clumsiness present)
→ Eliminate branches without clumsiness (40% branch removed)
→ Renormalize: 60% → 100%

After:
  {clumsiness=T, asthma=T}  @ 100%

This is mathematically equivalent to Bayesian updating — each observation narrows the probability distribution.

Querying Affliction State

The system provides probabilistic queries instead of binary answers:

Function	Returns	Usage
`haveAffV3(aff)`	Boolean (prob >= 30%)	Standard combat decisions
`haveAffV3(aff, 0.9)`	Boolean (prob >= 90%)	High-confidence gates
`getAffProbabilityV3(aff)`	Float 0.0–1.0	Exact probability
`getStateProbabilityV3(affList)`	Float 0.0–1.0	Joint probability of multiple affs
`getAllAffProbabilitiesV3()`	Table {aff=prob, ...}	Full state snapshot

Lock detection uses joint probabilities:

Softlock  = P(anorexia AND asthma AND slickness)
Hardlock  = P(anorexia AND asthma AND slickness AND impatience)
Truelock  = P(anorexia AND asthma AND slickness AND impatience AND paralysis)

Locks display at 30%+ probability, with color intensity increasing at 90%+.

Performance: Keeping Branch Count Manageable

Without constraints, branches would grow exponentially. Three mechanisms prevent this:

Deduplication: After branching, identical affliction sets (same affs, different histories) are merged by summing their probabilities. This is the primary reduction — most cures produce duplicate states.
Pruning: Branches below 1% probability are eliminated and their probability mass is redistributed proportionally to surviving branches.
Hard cap: If branches exceed 50 (configurable), the lowest-probability branches are dropped and probability is redistributed.

All queries use a pre-computed cache (affCacheV3) rebuilt after every state change, providing O(1) lookups regardless of branch count.

Simple Tracking (Non-Branching)

Some afflictions never need branching because they're cured through unambiguous channels (limb restoration, writhing, etc.). These are tracked as simple booleans for efficiency:

Limb damage states (broken/damaged/mangled legs, arms, head)
Status effects (prone, stun, unconscious, sleeping)
Sensory (blindness, deafness)
Defenses tracked as afflictions (rebounding, shield)

Architecture

V3 is the single source of truth. The legacy boolean table (tAffs) is maintained as a synchronized read cache for backward compatibility with 89+ direct-access sites across 30+ files.

                    ┌─────────────────────────┐
                    │    V3 Branching Engine   │
                    │  afflictionStatesV3[]    │
                    │  affCacheV3{}            │
                    └────────┬────────────────┘
                             │ syncToOldSystemV3()
    ┌────────────────────────┼────────────────────────┐
    │                        │                        │
    ▼                        ▼                        ▼
 tarAffed()              erAff()                 haveAff()
 (apply aff)          (remove aff)            (query aff)
    │                        │                        │
    ├─ tAffs[x]=true         ├─ tAffs[x]=false       ├─ haveAffV3()
    ├─ applyAffV3()          ├─ removeAffV3()         └─ fallback: tAffs
    └─ raiseEvent            └─ raiseEvent

Key files:

affliction_tracking_core/007_Branching_State_Tracker.lua — V3 engine (branching, collapsing, cache, sync)
affliction_tracking_core/008_V3_Integration.lua — Verification handlers, cure lists, lock detection, wrappers
017_Affliction_Management.lua — Public API (haveAff, tarAffed, erAff)

Mnemosyne Suite

The Mnemosyne ("tides of memory") is Achaea's endless tower-climb PvE challenge: each ripple (level) is a fresh 4×4 room layout you fight through wave by wave, choosing boons between waves, until you die out of lives or wade away — there is no win condition, only depth. The ataxia.mnemosyne subsystem gives the climb full tooling: run telemetry, a live mini-map, local run history, and a hands-free explorer.

Run Telemetry (Community Run Tracker)

Reports run progress to an external community run tracker as you play: ripple depth, monster waves, bosses, ongoing effects (affixes), boons offered (with the rarity, quote, category and combo status your local boon catalogue knows) and selected, and deaths. Opt-in and off by default — nothing is sent until you set a token and enable it:

mnem token <your-token>
mnem on

(or use the guided ataxia setup reporting). The tracker URL is configurable in settings, and mnem test pings the server to verify connectivity.

The reporting layer is built for reliability:

Mechanism	What it does
Serial POST queue	One request in flight at a time — guarantees event ordering (a ripple always lands before its monsters, boss, and effects)
Gated reporting	Run events only fire during a tracked run, so Mnemosyne-flavoured text elsewhere in the game can never post
Error recovery	A 20s watchdog force-advances stuck requests, idempotent endpoints retry once, and a failed run-start rolls back cleanly
Lifecycle-aware	Death ≠ run end (you lose a life, the run continues); run-end is confirmation-guarded against false positives; pausing the Mnemosyne suspends the run and the next wade resumes it — no duplicate runs
Reload-safe	HTTP handlers survive package updates mid-run; run state re-syncs from the server on load

Per-Ripple Mini-Map (`mnem map`)

The Mnemosyne is an unmapped instance — Mudlet's own mapper draws nothing there. The suite builds its own: every GMCP room arrival feeds a per-ripple room graph, coordinates are re-derived each step by BFS over the accumulated exit graph (so rooms that couldn't be placed on arrival snap into position once a connecting link is known), and a draggable widget renders the fixed 4×4 grid:

Green — your current room
Gold ? — visited room with unexplored exits
Grey — fully explored room
Dim placeholder — unvisited grid position

Click any cell to auto-walk there (BFS over walked edges). The map wipes and re-seeds on every ripple change, since each ripple is a fresh layout. Works independently of telemetry.

Run History & Reports

A local, persisted record of everything each run surfaces — no server required:

Command	Shows
`mnem boons`	This run's claimed boons with rarity, echo counts, ripple, and description
`mnem affixes`	This run's active affixes (ongoing effects)
`mnem library`	The all-time affix catalogue — every affix ever seen, with descriptions
`mnem boondb [filter]`	The all-time boon catalogue — every boon ever seen with its effect, rarity, echo cap and combo status (`export` / `import` for backup)
`mnem boonfill`	Keep the boon catalogue current via `BOON CONTEMPLATE`, 8 at a time: boons with no effect text first, then the rest, stalest first — the game keeps changing boons, and any text that changed is updated and called out (`all` for everything, `recheck` to start the cycle over). Every boon on an offer screen is also contemplated automatically once the offer is reported

History lives in its own profile file (mnemosyne_history.lua) and survives package updates. mnem quiet silences the automatic per-claim/per-affix echoes while still recording.

Auto-Explorer (`mnem explore`)

Hands-free ripple sweeping. The explorer drives the basher in manual mode for combat and handles navigation itself: when a room is clear it steps through an unexplored exit, or backtracks to the nearest room that still has one. On a fully swept boss ripple it patrols cleared rooms to find the late-spawning boss. It pauses at the boon screen (basher stays on), auto-resumes on GO!, refuses to give up while an unexplored room is still reachable, handles ice-slip rooms, and restores your saved basher state when it stops.

Lava is passed through, never retreated from: the entry damage is already paid, and stepping back only means paying it again, so the explorer takes the next door forward. Before stepping into a room it has never walked, it GLANCEs in first (free, and on by default — mnem explore glance off to disable), so a lava room's exit is planned before the splash rather than worked out under fire.

Boon → Class Integration

A passthrough intercept of BOON CLAIM <name> forwards your command, auto-reports the selection, and flips combat flags so the basher adapts to the boons you take — Bard Warmarch, Blademaster Shattered Star / Bladed Reflexes (keeps the Shindo augment up for 20% damage reduction), and Magi Aspect of Kkractle / Hot Springs reshape their class's attack logic, and the class-agnostic Hammer and Anvil (attacks bypass denizen shields) turns off razing and shield-swapping entirely for the rest of the run. Bloodscent turns each ripple entry into parsed recon (below). Boons are called out: the offer screen notes each boon that is a combo boon, how many times it can echo, and what it conflicts with (red for a boon you already hold, yellow for another on the same screen); BOON CONTEMPLATE highlights the same lines and adds a one-line summary. After every offer, the boon advisor summarises the options -- what each does, anything wrong with it (already immune, a conflict, a drawback) -- and recommends one, defence first and judged against the boons you already hold (mnem advise re-prints it; it never claims for you). mnem boondb shows and filters by category (mnem boondb offence). Boon combos are tracked too: a set of boons unlocks another one, 24 recipes ship known (from contemplate blocks players pasted), and mnem combos shows each recipe, which parts you hold and how far along you are — the advisor counts a boon that carries a combo forward (one chain's worth, even if it feeds several), scores a boon far lower when its cost is an affliction you cannot block — and back up again once you hold that immunity, the components are contemplated one per offer screen until the recipe is filled in, and the granted reward is recorded, flagged and reported when the mist bestows it. Monk/Shikudo gets two more: Kai Unleashed fires a room-wide KAI CHOKE burst (25k+ magical observed) alongside the combo in crowded rooms on its 30-second cooldown — confirmed by the burst's own game line, so an eaten choke never wastes the window — and Senseless Flurry keeps the numbness defence up in thin rooms for 30% faster balance (crowd-gated: numbness defers damage and would blind the safety nets in a swarm). Any Monk holding Sharp Mind (critical strikes restore mana, and the Monk strikes three times a balance) transmutes mana into health as a top-up at 90% HP rather than a 70% gap-filler. Psion's Panoply swaps the bash to WEAVE FLURRY (60–200% scaling per strike); Bloodletter's Fury and Razor Clarity keep the rupturesight and clarity defences up on idle equilibrium, and every full transcendence is cashed in for a free PSI SHATTER ahead of the weave -- or, with Psiwave, a PSI RADIATE that hits every denizen in the room. The weaves are the rotation; shatter is the reward for keeping them going. The Psion's emergency heal is ENACT WRATH below half health -- or, with the Roth combo boon (Razor Clarity + Bloodletter's Fury), below 75% every ~30 seconds. Prophet of Creation opens the round with a free PSI FORESIGHT on the target every ~30 seconds, so its next attack misses (only while the target is at half health or more -- a foresight that never comes true stuns you). Earthquake adds ENACT UPHEAVAL on spare equilibrium in a crowd above half health (its rubble blocks your own exits, so the explorer waits out the clamber instead of calling the move failed). Apostate necromancy boons: Dead Breath belches at 2+ denizens and Deathtempest soulstorms each denizen once, both riding the round on equilibrium beside the deadeyes swing; Army of the Dead summons gravehands once per room, taking that round's balance in place of the swing; Graveborn makes that every room, and Necrotic Aura keeps DEATHAURA up. The Rimewrought affix takes tattoo defences off keep-up until it clears; Famine eats to full every room. After a reimport mid-run, the first ripple re-latches every boon you hold from boon claimed. The Haemophiliac affix (kills bleed thousands) automatically slows the sweep: after each room clears, movement holds until the bleed is clotted and HP recovers. Boss tactics are per-boss scripted: against Seasone the Industrious the tree tattoo is held in reserve from the moment her objective appears and released the instant her phial truelock lands — a fresh tree breaks the lock immediately.

Swarm Tactics & Low-HP Escape (`mnem swarm`)

Deep ripples pack 3-4+ roaming denizens per room. Instead of standing in the swarm, the explorer fights on chosen ground:

Pull & funnel: at 3+ mobs (mnem swarm assess <n>, depth-scalable via mnem swarm deep <ripple> <n>), swing once and step back to the just-cleared room as one atomic queued line, kill what follows, re-enter, repeat. Hit-and-run continues as long as it works: any cycle that kills a mob or chips the target refunds the pull budget, so non-chasing packs get whittled down one free swing at a time until the room is cleared or below threshold — only truly stalled cycles (mobs healing back up between visits) spend the 3-pull budget and fall back to fighting in place.
Indoors: the escape also raises an icewall on the door (Bracers of Frost) and leaps it (chitin greaves). The wall then STAYS — re-entry just leaps back over it, and later escapes skip the re-cast entirely (faster exits); it's only melted (Bracers of Flame) once the room is cleared. Without the Maklak's Promise boon denizens walk through walls — the wall paces the fight; with it, they're impeded.
Outdoors swarm-followed: fly-kite — FLY, then every attack becomes land;attack;fly, touching ground only for the swing; lands when the pack thins.
Roll Hide panic (boon): at panic HP, tumble out — sheds all pursuers.
A swarm that follows is fought, not fled: if a retreat lands in a swarm again, no more ground retreats or pulls for that fight — standing and swinging beats spending the fight attack-held in doorways. Going back into a room you just fled needs 85% health and no afflictions.
Ice: once you slip in a room, tactical moves out of it tumble instead of jumping.
Wrath and Righteousness (boon): when it saves you from death, the package re-raises your defences and leaves the room.
Entangled: a move the game refuses ("too tangled up") is re-sent the moment you are free, and the escape messages say why you are not leaving rather than claiming you are.
After an escape, heal where you land (to 85% and cured) instead of exploring on; a last-resort escape takes a room you've cleared before an unexplored one; both legs broken is treated like being bound (wait, then leave the moment a leg is mended).
Mindseye: while you're blind, the mindseye tattoo is kept up so you can still see the room.
Low-HP escape ladder (any mob count, default 35%): outdoors fly and hover — works with every limb broken, unlike touch shield — landing only when FULLY healed (95%+ and affliction-free). The hover re-checks its own premise every tick: knocked out of the sky, a denizen in the air with you, or a fly that never took ends it at once and hands back to fighting instead of holding your attacks. Indoors, retreat to the cleared room; when dying fast with no known route back, any safe door beats standing still. While webbed or otherwise bound it doesn't try to fly or leap at all. Shield stays as the last resort.
Bloodscent recon (boon): every ripple entry senses out all denizens — the rows are parsed into per-room counts with crowded rooms called out before you take a step (recon: 8 denizens across 6 rooms -- crowded: Beneath an ancient tree (3)).
Sleuth recon (boon): fullsense on each GO reveals every denizen in the ripple (mnem sense to re-scan).
Haemophiliac pacing (affix): kills bleed thousands, so after each room clears the sweep stands still while the bleed clots and HP recovers, then moves on.

Any icewall that blocks a walk — yours or the tower's — is simply leapt (chitin greaves), so walls never derail navigation. Tactical moves never blacklist real exits, a server-side hold protects every queued escape from being overwritten by the attack loop (escape mode is only announced on a path that is really leaving, and flushes the queue first so a committed swing can't take the escape's balance), and a vitals-driven watchdog fires the panic/escape ladder on the very prompt your HP crosses the threshold. The standalone Dementia Mapper mirrors the pull/funnel core via dmap swarm <n|off>.

Command Reference

Command	Action
`mnem` / `mnem status`	Show tracker URL, token/auto/contemplate state, and current run state
`mnem token <t>`	Save your API token (persisted)
`mnem on` / `mnem off`	Master auto-report toggle (`on` also re-syncs a live run)
`mnem map [on\|off\|status]`	Toggle or diagnose the ripple mini-map
`mnem boons` / `mnem affixes` / `mnem library`	Run history reports (see above)
`mnem explore [on\|off\|status]`	Start/stop/inspect the auto-sweep
`mnem explore glance [on\|off]`	Glance into never-walked rooms before stepping (lava pass-through; default on)
`mnem swarm`	Swarm-tactics status (state, thresholds, branch toggles, recon)
`mnem swarm assess <n>` / `deep <r> <n>`	Pull threshold (default 3) / depth-scaled threshold
`mnem swarm icewall\|kite\|panic\|escape on\|off`	Per-branch toggles
`mnem swarm panicat\|escapeat\|recoverat <hp%>`	Panic (35) / escape (35) / recovery-land (95) thresholds
`mnem sense`	Manual fullsense recon (Sleuth boon reveals all denizens)
`mnem contemplate`	Toggle boon-description enrichment (`BOON CONTEMPLATE`)
`mnem quiet [on\|off]`	Silence automatic boon/affix echoes (still records)
`mnem test` / `mnem health`	Ping the tracker to verify connectivity
`mnem start` / `end` / `check` / `ripple <n>` / `boss <name>` / `monsters <text>` / `death [killer]`	Manual reporting overrides (work even with auto-report off)
`mnem debug`	Verbose diagnostics (session-only)
`mnem help`	Command reference

Key files (src_new/scripts/levi_ataxia/levi/ataxia/mnemosyne/):

001_HTTP_Client.lua — serial POST queue, gating, error recovery
002_Reporter_API.lua — per-endpoint reporting functions + run state
003_Commands.lua — mnem command dispatch
004_Parsers.lua — game-text parsers, monster buffering, boon capture
005_Ripple_Map.lua / 006_Ripple_Map_Window.lua — room graph + grid widget
007_History.lua — local run history + reports
008_Explorer.lua — auto-sweep state machine

Full documentation: .claude/projects/mnemosyne/ — architecture, reporting endpoints, parsing triggers, ripple map, commands, history, and explorer, each in its own doc.

Dementia Mapper (Standalone Package)

The Mnemosyne map + explorer is also available as Dementia Mapper, a second, fully self-contained Mudlet package built from this repo — no LEVI dependency. It carries its own denizen tracking, a dementia-tolerant map (BFS relayout, known-exit-graph routing, instant wall detection via Room.WrongDir, ice-slip handling), and an auto-sweep where combat is an optional pluggable hook: by default it waits for you to clear each room, or plug in any attack with dmap attack <cmd>.

Command	Action
`dmap map` / `show` / `hide`	Toggle the 4×4 mini-map
`dmap explore`	Start/stop the auto-sweep
`dmap attack <cmd>`	Plug in an attack command (optional)
`dmap status`	Diagnostics

Download Dementia_Mapper.mpackage from Releases (dmap-v* tags) or build with ./dmap_build.sh. See dmap_src/README.md.

Quick Install

Option A — Download the latest release:

Go to Releases and download Levi_Ataxia.mpackage
- Direct link: https://github.com/haterade22/LEVI-Achaea/releases/latest/download/Levi_Ataxia.mpackage
Open Mudlet → Package Manager → Install
Select the .mpackage file

Option B — Build from source (see Building from Source below)

Note: The packages/ directory contains legacy XML builds. Always use a release download or build from source for the current version.

Updating

The system includes a built-in auto-updater. On every login, it checks for new versions automatically.

Scenario	What happens
Up to date	Shows "Levi Ataxia vX.Y is up to date"
New version available	Shows notification with the new version number
To update	Type `sysupdate` in-game

The sysupdate command downloads the latest .mpackage from GitHub Releases, uninstalls the old package, installs the new one, and cleans up automatically.

Building from Source

Prerequisites

Requirement	Details
Python 3	For the conversion script
Java 8+	For Muddler (the Mudlet package builder)
Muddler	Download from demonnic/muddler

Quick Build

cd LEVI-Achaea
./build.sh                 # Full convert + Muddler build
./build.sh --convert-only  # Convert only (skip Muddler)
./build.sh --dry-run       # Preview without writing

VS Code: Press Ctrl+Shift+B to run the default build task.

Manual Build

# Step 1: Convert source to Muddler format
python tools/convert_to_muddler.py --src ./src_new --output ./muddler_project

# Step 2: Build with Muddler
set JAVA_HOME=C:\Path\To\Java
cd muddler_project
/path/to/muddler/bin/muddle.bat     # Windows
/path/to/muddler/bin/muddle         # Linux/macOS

Output: muddler_project/build/Levi_Ataxia.mpackage

Step 3: Install in Mudlet

Open Mudlet → Package Manager
Install muddler_project/build/Levi_Ataxia.mpackage
One-time: add a saved variable _ataxia_backup (type: table) in Mudlet's Variables panel. Settings live per-profile on disk; _ataxia_backup is the redundancy layer the resilient loader falls back to if a disk file goes missing or corrupt — add it before configuring anything.
Reconnect to Achaea (GMCP must be enabled under Settings → Protocols). Installing already loads your settings automatically (no reconnect needed just to load) — reconnecting is for GMCP.
Run the in-game setup wizard (see below)

Getting Started In-Game

After installing the package and connecting to Achaea, use the built-in setup wizard to configure everything:

ataxia setup

First-Time Install

Run these three commands to initialise the subsystems:

Step	Command	What it does
1	`atinstall`	Configures server-side curing (priorities, sipping, batching), prompt, and loads defaults. Type it twice within 5s to confirm.
2	`abinstall`	Initialises the basher (target lists, flee thresholds, shield timers)
3	`aninstall`	Sets up the player database (API integration, city-based name highlighting)

Or use ataxia setup install for a guided walkthrough.

Configuration Guide

After installing, ataxia setup guide shows every configurable option across all three subsystems:

Command	Section
`ataxia setup guide ataxia`	Separator, system toggle, custom prompt, defence profiles, curing priorities, item highlighting, sipping, room shortening, GUI, raid mode
`ataxia setup guide basher`	Target lists, flee/shield thresholds, danger mobs, ignore lists, gold pack, shield swap/timer, rageraze, tree blackout
`ataxia setup guide ndb`	City highlight colours, highlight toggle/priority, enemy formatting, player notes, whois lookup

Quick Reference

Command	Purpose
`ataxia setup`	Main menu — all setup categories
`ataxia setup class`	Set your class
`ataxia setup separator`	Set command separator (default `;`)
`ataxia setup weapons`	Configure weapon IDs (auto-scan via `ataxia setup weapons scan`, or manual `set <slot> <id>`)
`ataxia setup basher`	Basher settings
`ataxia setup sipping`	Health/mana sip thresholds
`ataxia setup tracking`	Affliction tracking settings
`ataxia setup combat`	Combat toggles (party relay, looting, etc.)
`ataxia setup gui`	Toggle the GUI
`ataxia setup ndb`	NDB highlighting colours
`ataxia setup status`	Overview of all current settings

Player Database (ataxiaNDB)

The ataxiaNDB system tracks player information from the Achaea API and provides city-based name highlighting, enemy tracking, mark/army/dauntless detection, and player notes.

Installation

Run aninstall in-game (or ataxia setup install ndb) to initialise the database. This fetches the online player list from the Achaea API and begins populating player records.

How It Works

API Population — On qwp, the system fetches http://api.achaea.com/characters/ to get the online player list, then queues honours lookups for unknown players
Honours Capture — When you honours <player>, triggers capture city, house, class, level, XP rank, player kills, mark membership, army rank, and Dauntless status
Auto-Honours — Players with hidden cities are automatically queued for honours lookup (2s spacing) to resolve their city
Name Highlighting — Once a player's city is known, their name is highlighted in the configured city colour whenever it appears in game text
Persistent Storage — Player data is saved to disk and persists across sessions

Quick Reference

Online & Lookup

Command	Description
`qwp`	Fetch online players from API, display by city
`qwp <city>`	Show online players from a specific city only
`whois <name>`	Look up a player's full profile (city, class, house, level, kills, mark, army, dauntless)
`honours <name>`	Query honours for a player and add/update in database

Database Queries

Command	Description
`an show <city>`	List all tracked players from a city
`an class <class>`	List all tracked players of a class
`an classes`	Show player count per class
`an cclasses <city>`	Show class distribution for a specific city
`an citymembers`	Show tracked player count by city

Threat Intelligence

Command	Description
`an marks [city]`	List Ivory and Quisalis Mark members (optional city filter)
`an army [city]`	List players with army rank (sorted by rank, optional city filter)
`an dauntless [city]`	List Dauntless members (optional city filter)
`an threats [city]`	Combined view: marks + army rank 3+ + dauntless (optional city filter)

Player Notes

Command	Description
`an noteadd <name> <text>`	Add a note to a player
`an noteshow <name>`	Show all notes for a player
`an noteremove <name> <id>`	Remove a note by ID

Database Maintenance

Command	Description
`an recreate`	Re-query API data for every player in database
`an redo <city>`	Re-query API data for all players from a specific city
`an refresh`	Send `honours` for all players to update mark/army/dauntless
`an refresh <city>`	Send `honours` for players from a specific city only
`an remove rank <num>`	Remove players with XP rank above threshold
`an remove level <num>`	Remove players with level below threshold

Highlighting Configuration

Name highlighting colours players by their city affiliation. Toggle and configure via:

Command	Description
`anhl`	Toggle highlighting on/off
`anhl <city> <colour>`	Set highlight colour for a city (e.g., `anhl Mhaldor red`)
`anss`	Show all current NDB settings
`an prio enemies`	Prioritise enemy colour over city colour
`an prio city`	Prioritise city colour over enemy colour
`aneh i`	Toggle italic formatting for enemies
`aneh u`	Toggle underline formatting for enemies
`aneh b`	Toggle bold formatting for enemies
`highlight <name> <colour>`	Override colour for a specific player
`highlight <name> none`	Remove per-player colour override

Available cities: Ashtan, Cyrene, Eleusis, Hashan, Mhaldor, Targossas, Rogues

Or use the setup wizard: ataxia setup ndb for a guided menu.

Data Tracked Per Player

Field	Source	Description
Name	API / Honours	Player name
City	API / Honours	City affiliation (or Rogues)
House	Honours	House membership
Class	API / Honours	Current class
Level	Honours	Player level
XP Rank	Honours	Experience ranking
Player Kills	Honours	PK count
Mark	Honours	Ivory Mark or Quisalis Mark membership
Army Rank	Honours	Army rank (1–5)
Dauntless	Honours	Member of The Dauntless
Notes	User	Custom player notes

Note: The Achaea API provides name, city, class, and basic stats. Mark, army rank, and Dauntless are only available from in-game honours output. Use an refresh to bulk-update these fields for all tracked players.

Conversion Script Options

python tools/convert_to_muddler.py --help

  --src, -s          Source directory (default: ./src_new)
  --output, -o       Output Muddler project directory (default: ./muddler_project)
  --verbose, -v      Enable verbose output
  --dry-run, -n      Scan and report without writing
  --package-name     Package name (default: Levi_Ataxia)
  --package-title    Human-readable title
  --package-version  Version string (default: read from version.txt)
  --package-author   Author name (default: Leviticus)
  --include-roots    Root group names to include from _groups.yaml
  --include-dirs     Source subdirectory names to scan

Building a Custom Sub-Package

You can build a standalone package from a subset of the source tree:

python tools/convert_to_muddler.py --src ./src_new --output ./my_package_project \
  --package-name My_Package --package-title "My Package" --include-roots My_Package

cd my_package_project
/path/to/muddler/bin/muddle.bat

Repository Structure

LEVI-Achaea/
├── src_new/                    # Canonical source (YAML-header Lua files)
│   ├── aliases/                #   Command aliases
│   ├── keys/                   #   Key bindings
│   ├── scripts/                #   Lua script modules
│   │   └── levi_ataxia/levi/
│   │       ├── ataxia/         #     Core combat system, basher, curing, GUI
│   │       └── levi_scripts/   #     Class-specific offense modules (18+ classes)
│   ├── tests/                  #   Unit tests (mock_mudlet.lua, test_runner.lua)
│   ├── timers/                 #   Timer definitions
│   └── triggers/               #   Game text pattern matching (1800+ triggers)
├── muddler_project/            # Generated Muddler build project (build/ gitignored)
│   └── mfile                   #   Package metadata
├── dmap_src/                   # Dementia Mapper standalone package source
│   └── README.md               #   dmap documentation
├── tools/
│   ├── convert_to_muddler.py  #   Source → Muddler project converter
│   ├── flatten_groups.py       #   Flatten intermediate wrapper groups in _groups.yaml
│   ├── flatten_alias_hierarchy.py  # Bulk alias hierarchy remapping
│   ├── compare_builds.py       #   Compare XML vs Muddler output
│   ├── mudlet_extract.py       #   Extract XML package → src_new format
│   ├── kb_*.py                 #   Knowledge base tools (see Achaea Knowledge Base)
│   └── lib/                    #   Shared library code (hierarchy, YAML parsing)
├── kb/                         # Achaea knowledge base (start: kb/INDEX.md)
│   ├── afflictions/            #   The core: database, catalog, cure channels, class cures, locks
│   ├── classes/                #   Every class's abilities (generated from the wiki)
│   ├── curing/                 #   Curatives, server-side curing
│   ├── defences/, mechanics/   #   Defence names; balance, equilibrium, the queue
│   ├── raw/                    #   Verbatim evidence: HELP, live output, wiki pages, logs
│   ├── CONFLICTS.md            #   Disagreements found, and how each was settled
│   └── INDEX.md                #   One line per page
├── docs/
│   ├── plans/                  #   Project plans and reviews
│   ├── legend-deck.md          #   Legend Deck card reference
│   └── artefacts-reference.md  #   Artefact effects reference
├── .claude/
│   ├── agents/                 # Custom subagents (offense-system, build-and-version, team)
│   ├── classes/                # 26 class mechanic files + lock_types.md
│   ├── projects/               # Per-system deep-dive docs (mnemosyne, basher, ...)
│   └── skills/                 # Slash commands (/build, /version-bump, /kb-ingest)
├── .github/workflows/          # CI/CD (syntax check, tests, tagged release builds)
├── .vscode/tasks.json          # VS Code build/test tasks (Ctrl+Shift+B)
├── build.sh                    # One-command build script
├── dmap_build.sh               # Dementia Mapper build script
├── version.txt                 # Package version (fetched by auto-updater on login)
├── dmap_version.txt            # Dementia Mapper package version
├── .gitignore                  # Excludes build artifacts, .vs/, __pycache__
├── .gitattributes              # LF line endings, binary markers
├── .luacheckrc                 # Lua 5.1 linter config
├── stylua.toml                 # Lua formatter config
├── CLAUDE.md                   # Full system documentation (AI assistant guide)
├── GETTING_STARTED.md          # Setup and usage guide
├── CHANGELOG.md                # Change history
└── README.md                   # This file

Source File Format

Each .lua file in src_new/ has a YAML metadata header followed by Lua code:

--- # YAML header
name: My Script Name
hierarchy: [Levi_Ataxia, System-related, Combat]
isActive: 'yes'
---
-- Lua code starts here
function myFunction()
  -- ...
end

Files use numbered prefixes (e.g., 001_, 002_) for load ordering within each group.

Group hierarchy is defined in _groups.yaml files at each item type root (e.g., src_new/scripts/_groups.yaml).

IDE Setup

VS Code (Primary)

Open the LEVI-Achaea/ folder. Press Ctrl+Shift+B to build, or use Terminal > Run Task for:

Task	Description
Build Levi_Ataxia	Full convert + Muddler pipeline (default)
Convert Only	Run conversion without building
Convert Only (Dry Run)	Preview conversion output
Clean Build Output	Remove `muddler_project/build/`
Run Tests	Execute unit tests via test_runner.lua

Claude Code: /build runs the full pipeline. /version-bump <version> updates all 3 version locations. /kb-ingest files new Achaea material into the knowledge base.

Custom subagents (.claude/agents/): offense-system for class offense development, build-and-version for release automation, team-class-offense for parallel class work.

Visual Studio 2022 (Legacy)

Build tasks are in .vs/tasks.vs.json. Right-click the root folder in Solution Explorer to run.

Documentation

Document	Purpose
kb/INDEX.md	Achaea knowledge base: afflictions, cures, classes, curing, defences, mechanics
kb/afflictions/database.md	The game's own record of all 203 afflictions
kb/classes/	Every class's skills and abilities
kb/CONFLICTS.md	Source and code disagreements, and their resolutions
GETTING_STARTED.md	Setup guide, system overview, common tasks
CLAUDE.md	Full technical reference (architecture, APIs, combat mechanics, development guidelines)
CHANGELOG.md	Change history with dates and details
CONTRIBUTING.md	Contribution guidelines
docs/legend-deck.md	Legend Deck card reference and PVE guide
docs/artefacts-reference.md	Achaea artefact effects reference
docs/limb-damage-mechanics.md	Limb damage thresholds and mechanics
.claude/projects/mnemosyne/	Mnemosyne suite deep-dive (architecture, reporting, map, explorer)
dmap_src/README.md	Dementia Mapper standalone package
.claude/classes/	Per-class combat mechanic documentation (26 classes)
.claude/agents/	Custom subagent definitions for Claude Code
.claude/skills/	Slash command skills (`/build`, `/version-bump`)

Technology

Language: Lua 5.1
Platform: Mudlet MUD Client
Build Tool: Muddler (Java)
Conversion: Python 3
Target Game: Achaea (Iron Realms Entertainment)

License

Private use.

Name		Name	Last commit message	Last commit date
.claude		.claude
.github/workflows		.github/workflows
.serena		.serena
.vscode		.vscode
dmap_src		dmap_src
docs		docs
kb		kb
muddler_project		muddler_project
src_new		src_new
tools		tools
.claudeignore		.claudeignore
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.luacheckrc		.luacheckrc
.mcp.json		.mcp.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
EXTRACTION_REPORT.md		EXTRACTION_REPORT.md
GETTING_STARTED.md		GETTING_STARTED.md
README.md		README.md
UpgradeLog.htm		UpgradeLog.htm
build.sh		build.sh
dmap_build.sh		dmap_build.sh
dmap_version.txt		dmap_version.txt
stylua.toml		stylua.toml
version.txt		version.txt

Latest commit

History

Folders and files

Repository files navigation

LEVI-Achaea

Download

Installation

Auto-Update

Credits

Features

Combat System (Ataxia)

Class Offense Modules (18+ Classes)

Automated Basher (PvE Hunting)

Mnemosyne Suite (mnem)

Gear & Equipment

Gear Audit & BiS Analysis (gearaudit)

Armour & Paragon Management (armour)

Item Catalog (catalog)

Vial Inventory Summary (elist / vlist)

GUI System (Enhanced zGUI Redux)

Movable Vital Bars (ataxiabars)

Player Database (ataxiaNDB)

Navigation (Mudlet Mapper / mmp)

Auto-Update System

Configuration & Setup

Achaea Knowledge Base

What's in it

How it stays accurate

Adding to it

Tools

Affliction Tracker (V3 Branching Probability Engine)

The Problem

How It Works: Branching States

Definite Operations (No Branching)

Ambiguous Cures: The Branching Step

Verification Signals: The Collapse Step

Querying Affliction State

Performance: Keeping Branch Count Manageable

Simple Tracking (Non-Branching)

Architecture

Mnemosyne Suite

Run Telemetry (Community Run Tracker)

Per-Ripple Mini-Map (mnem map)

Run History & Reports

Auto-Explorer (mnem explore)

Boon → Class Integration

Swarm Tactics & Low-HP Escape (mnem swarm)

Command Reference

Dementia Mapper (Standalone Package)

Quick Install

Updating

Building from Source

Prerequisites

Quick Build

Manual Build

Step 3: Install in Mudlet

Getting Started In-Game

First-Time Install

Configuration Guide

Quick Reference

Player Database (ataxiaNDB)

Installation

How It Works

Quick Reference

Online & Lookup

Database Queries

Threat Intelligence

Player Notes

Database Maintenance

Highlighting Configuration

Data Tracked Per Player

Conversion Script Options

Building a Custom Sub-Package

Repository Structure

Source File Format

IDE Setup

VS Code (Primary)

Visual Studio 2022 (Legacy)

Documentation

Technology

Mnemosyne Suite (`mnem`)

Gear Audit & BiS Analysis (`gearaudit`)

Armour & Paragon Management (`armour`)

Item Catalog (`catalog`)

Vial Inventory Summary (`elist` / `vlist`)

Movable Vital Bars (`ataxiabars`)

Per-Ripple Mini-Map (`mnem map`)

Auto-Explorer (`mnem explore`)

Swarm Tactics & Low-HP Escape (`mnem swarm`)