acdream/docs/research/2026-08-26-mosstank-vtank-utilitybelt-research.md

# MossTank research: Virindi Tank parity and UtilityBelt expressions

Date: 2026-08-26

This report is the requirements baseline for turning MossTank from the small
self-buffing sample into acdream's full automation plugin. The product target is
deliberately broad: **all Virindi Tank functionality**, with UtilityBelt's more
capable expression dialect as the scripting baseline. File compatibility is a
separate decision; behavioral capability is not.

## 1. Evidence and limits

The following primary VTank pages were read and cross-checked (the live wiki
and its indexed historical revisions were both used where a mirror was
temporarily unavailable):

- `http://virindi.net/wiki/index.php/Virindi_Tank`
- `http://virindi.net/wiki/index.php/Virindi_Tank_Standard_Options`
- `http://virindi.net/wiki/index.php/Virindi_Tank_Advanced_Options`
- `http://virindi.net/wiki/index.php/Virindi_Tank_Commands`
- `http://virindi.net/wiki/index.php/Virindi_Tank_Meta_System`
- `http://virindi.net/wiki/index.php/Meta_Expressions`
- `https://utilitybelt.gitlab.io/docs/expressions/`

The 2026-08-27 MT2 follow-up also verified the exact documented distinctions
that drive the combat scheduler:

- A+R requires `MinimumRingTargets` inside Ring Range; R without A rings with
  any configured target inside range and falls back to standard war outside;
- `UseArcs` prefers an arc over a bolt only at/above `ArcRange`;
- `Void Basic`, `Drain Auto`, and `Harm` are distinct Monsters damage choices;
- `GhostMonsterSpellAttemptCount` counts spell attempts which never start,
  while `BlacklistMonsterAttemptCount` counts successful attacks which miss;
- the health-tracker ghost detector is independent and applies to melee,
  missile, and magic.

Sources: the official `Virindi_Tank_Standard_Options`,
`Virindi_Tank_Advanced_Options`, `Virindi_Tank_FAQ`, `Options_List`, and
`Virindi_Tank_Changelog` pages listed above.

For UtilityBelt, documentation was checked against the primary source rather
than relying on the generated web page alone. The inspected repository was
`https://gitlab.com/utilitybelt/utilitybelt`, commit
`5fe9825a82f38047737768fd92c61dd47d88e467` (2026-03-05). The grammar is
`UtilityBelt/Lib/Expressions/MetaExpressions.g4`; every method carrying an
`ExpressionMethod` attribute was enumerated. The source is MIT licensed.

This report extends, rather than replaces,
`2026-07-29-vtank-plugin-automation-requirements.md`. That earlier report
already decoded VTank's `.met`, `.nav`, and `.utl` structures from primary
sources and remains the format reference.

## 2. Complete VTank capability map

### 2.1 Combat

VTank is a priority-driven combat controller, not merely an auto-attack loop.
Its supported combat family includes:

- melee, missile, mage, hybrid, two-handed, Void and Summoning characters;
- Life harm/martyr attacks, grenades, lenses, cast-on-strike weapons, streaks;
- automatic damage/weapon choice and monster-specific weapon, offhand and pet
  element overrides;
- monster rules with `DEFAULT` plus ordered first-match expressions;
- per-rule priority from ignore (`-1`) through `4`, attack/debuff flags,
  damage type, attack height, ring/streak choices, and void curses;
- target selection by distance, angular deviation, or the hybrid method using
  angle inside a configurable cutoff and distance outside it;
- target lock, blacklist/retry behavior, and ghost-target retirement after
  failed casts or missing health updates;
- debuff scheduling by one target, priority group, or all targets before
  attack; spell-level versus skill-based debuff choice and reapply windows;
- automatic ring use by nearby-target density and arc/bolt choice by range;
- melee high/middle/low attacks, automatic or explicit power, Recklessness;
- pet density, element, refill and test behavior.

VTank's macro scheduler checks multiple action lists in priority order. Combat
therefore cannot be implemented as an isolated timer: healing, buffing,
navigation, looting, fellowship assistance and combat all need one arbiter.

### 2.2 Buffing and vitals

- automatic trained attribute/skill buffs, protections, banes, auras,
  regeneration and configured extra buffs;
- protection/bane profile sets, exclusions, level/tier selection, signed
  skill-over-difficulty thresholds, force buff and idle top-off;
- time-remaining rebuff and persisted item-buff duration knowledge;
- combat, idle and fellowship-helper vital thresholds;
- kits, vital transfers, post-switch recharge behavior and special healing
  items;
- self-dispel in response to high-level vulnerabilities.

MossTank's current buff engine already owns the first useful subset: known
self buffs, tier/difficulty choice, in-force enchantment timing, force buff,
and stamina/mana upkeep. It remains plugin policy over host primitives.

### 2.3 Inventory and crafting

- AutoStack and AutoCram;
- pea splitting and priority rules;
- crafting of kits, foods, arrowheads and special ammunition;
- mana-stone acquisition, filling and application to equipped items;
- lockpick selection and use;
- component, consumable, tool and ammunition upkeep.

### 2.4 Looting

- corpse approach/open/retry/timeout/blacklist;
- all/fellow/rare loot modes and priority boosts;
- appraisal/ID wait, unknown-scroll reading and salvage combining;
- a loot-plugin seam, with VTClassic as the canonical ordered, first-match
  rule engine over raw and computed item properties;
- actions including no-loot, keep, keep-up-to, salvage, sell, read and custom
  user actions.

The host must expose object property bags, appraisal completion and
transaction primitives. Rule ordering and loot-profile policy belong in
MossTank.

### 2.5 Navigation

- circular, linear, once/runback and follow routes;
- points, portals, recalls, pauses, chat, vendor, repeated NPC talk/use,
  server-confirmed checkpoints and charged/shift/strafe jumps;
- closest-entry, reversal, arrival/off-course ranges, door use and
  follow-around-corners;
- combat/nav priority interaction.

Route storage belongs to the plugin. The host owes move-to, follow, turn,
jump, use and authoritative-arrival primitives.

Direct inspection of the official assembly on 2026-08-27 pinned the route
contract more tightly:

- `eNavType` is Circular, Linear, Target and Once; Once destructively removes
  its first completed row and Linear deliberately visits each endpoint once
  while flipping direction;
- `eWaypointType` assigns Point/Portal/Recall/Pause/ChatCommand/OpenVendor/
  Portal2/UseNPC/Checkpoint/Jump to numeric ids 0..9;
- `fd.cs` turns outside 4°, moves while turning only within 45° beyond 3 m or
  15° inside 3 m, and stops at `NavCloseStopRange` (default 2 m);
- `gr.cs` compares the checkpoint against the last server position rather
  than client prediction and nudges forward after 15 seconds without an
  acknowledgement;
- `gl.cs` records the followed player's path by approximately 9.6 cm and
  drops old breadcrumbs when the follower comes within 2.4 m of a later path
  segment, preserving follow-around-corners;
- `e9.cs` and `fa.cs` reacquire exact-name/class objects within 2.5 m of the
  stored position. Portal2 retries when portal exit remains within 15 m of
  its origin; UseNPC repeats until the named NPC tells or gives to the player;
- `b7.cs` is a rule independent of the route node list. `OpenDoors` defaults
  false; it IDs doors at 20 m, opens at 4 m, and accepts a lock when Lockpick
  is at least `difficulty - 50` using an owned lockpick.

These are plugin policies over additive canonical projections, not a second
movement model. The host applies semantic movement intent through Runtime's
existing command interpreter and supplies the accepted server position needed
only by Checkpoint.

### 2.6 Fellowship and social automation

- tell-driven recruitment and waiting lists;
- fellowship leader/member/state queries and leader replacement voting;
- fellowship healing, corpse permissions and coordinated target/debuff policy;
- multi-client composition through chat rather than a privileged macro API.

### External loot-classifier seam

VTank loads one `LootPluginBase`, asks `DoesPotentialItemNeedID`, and then
calls `GetLootDecision(GameItemInfo)`. Its public result vocabulary is
NoLoot, Keep, Salvage, Sell, Read, User1–User5 and KeepUpTo with `Data1` as the
limit. MossTank modernizes discovery into a host-owned classifier registry:
plugins register a namespaced classifier for their own lifetime, while
MossTank remains the corpse/appraisal/pickup/action executor. The selected
engine is durable policy; if it unloads, MossTank returns no classifier match
instead of silently applying the built-in profile.

Direct inspection of the official `hv.cs` also shows that a custom loot
plugin's per-item action is retained only after the item enters owned
inventory and is removed when the item leaves. The modern registry therefore
has matching `OnLooted` and `OnItemRemoved` callbacks. MossTank invokes them
only from authoritative inventory publication/removal, never when pickup is
merely dispatched.

### Options-page scheduler findings

The official Options controls are not merely presentation aliases:

- `fz.cs` runs the ordinary `RebuffTimeRemainingSeconds` rule before combat;
- `cLogic.cs` runs a second `IdleBuffTopoffTimeSeconds` pass only behind
  `IdleBuffTopoff`, after attack/loot work has gone idle;
- the PRETARGETAPPROACH `g8` rule navigates only between `AttackDistance` and
  `ApproachDistance`, and requires both combat and navigation to be enabled;
- `cm.cs` changes to Peace only as the final no-target/no-work fallback.

The UI displays AC-distance settings multiplied by 240. MossTank stores metres
in its typed controllers and converts only at the VTank option boundary.

### 2.7 Meta state machine

- named states beginning at `Default`;
- state-local rules, each firing once per state entry;
- nested conditions (`All`, `Any`, `Not`) and conditions for chat regex,
  inventory, timers, nav state, death, vendors, monsters, buffs, coordinates,
  portals, burden, route distance, expressions and captured chat groups;
- actions for state transition, chat, grouped actions, embedded navigation,
  call/return stack, expression execution, expression-derived chat, watchdogs,
  option read/write and runtime-created views;
- a roughly 293 ms decision cadence plus evaluation when the macro asks for
  its next action.

### 2.8 Profiles, commands and companion behavior

- independent settings, navigation, loot and meta profiles; global and
  per-character variants; hot loading and automatic persistence;
- command parity for macro state, options, buffing, meta, item testing,
  property dumps, monster/spell diagnostics, route editing, attack power and
  debug output;
- extensibility equivalent to VTClassic, VI2, item tools, follower/status HUD,
  alerts and cross-character inventory. Some belong as separate acdream
  plugins, but MossTank's API must permit them without privileged host code.

## 3. Expression language target

### 3.1 Why UtilityBelt is the baseline

VTank expressions are enough to power classic metas, but UtilityBelt preserves
the familiar syntax while adding typed lists and dictionaries, slicing,
higher-order collection functions, broader object queries and more action
primitives. MossTank should implement the UtilityBelt-compatible semantic
superset and offer a VTank compatibility mode for old expressions.

### 3.2 Grammar and evaluation semantics

The audited UtilityBelt grammar supports:

- multiple `;`-separated statements, returning the final result;
- session (`$`), persistent (`@`) and global (`&`) variables;
- decimal and hexadecimal numbers, booleans and two string forms;
- function calls using `name[...]`;
- typed values: number, string, boolean, list, dictionary, coordinate, world
  object, stopwatch and UI control;
- list/string/dictionary indexing, slices and negative indices;
- complement, shifts, bitwise operators, exponentiation, arithmetic, regex
  match (`#`), comparison, short-circuit `&&` and `||`;
- registered function metadata, arity/type validation and documented return
  types;
- collection creation/mutation/copying plus map/filter/reduce/sort/range.

Implementation requirements follow directly: parse into an immutable AST;
compile or interpret without ambient reflection; use explicit value kinds;
short-circuit logical nodes; attach cancellation and an instruction budget;
make all world/action functions capabilities supplied by the MossTank engine;
and serialize only persistent/global variable stores.

### 3.3 Audited UtilityBelt function catalog (260 declarations)

The declaration count includes aliases/overloads. Grouped by capability, the
public names are:

- **language/conversion/math:** `abs`, `acos`, `asin`, `atan`, `atan2`,
  `ceiling`, `chr`, `cnumber`, `cos`, `cosh`, `cstr`, `cstrf`, `floor`,
  `hexstr`, `iif`, `ifthen`, `isfalse`, `istrue`, `lumavg`, `lumtotal`,
  `ord`, `randint`, `round`, `sin`, `sinh`, `sqrt`, `strlen`, `tan`, `tanh`,
  `tostring`, `vitae`;
- **variables:** `getvar`, `setvar`, `testvar`, `touchvar`, `clearvar`,
  `clearallvars` and the corresponding `pvar` and `gvar` families;
- **execution/chat:** `exec`, `delayexec`, `clearexec`, `echo`, `chatbox`,
  `chatboxpaste`;
- **lists:** `listcreate`, `listadd`, `listinsert`, `listremove`,
  `listremoveat`, `listgetitem`, `listcontains`, `listindexof`,
  `listlastindexof`, `listcopy`, `listreverse`, `listpop`, `listcount`,
  `listclear`, `listfilter`, `listmap`, `listreduce`, `listsort`,
  `listfromrange`;
- **dictionaries:** `dictcreate`, `dictgetitem`, `dictadditem`, `dicthaskey`,
  `dictremovekey`, `dictkeys`, `dictvalues`, `dictsize`, `dictclear`,
  `dictcopy`;
- **time/location:** `getdatetimelocal`, `getdatetimeutc`, `getunixtime`,
  `getworldname`, `getplayercoordinates`, `getplayerlandblock`,
  `getplayerlandcell`, coordinate parse/get/distance/string functions,
  stopwatch functions, and the eleven `getgame*`/day/night functions;
- **character:** raw typed property reads, base/buffed skills, training level,
  base/current/buffed-max vitals, base/buffed attributes, burden, free slots,
  cooldown expiration, account hash and character index;
- **spells/components:** `getknownspells`, `getisspellknown`,
  `getcancastspell_buff`, `getcancastspell_hunt`, `getspellexpiration`,
  `getspellexpirationbyname`, `spelldata`, `spellname`, `componentdata`,
  `componentname`;
- **world objects:** validity/data/ID-time, raw typed properties, identity,
  health/vitals, spells, coordinates, selection/player/open-container, door
  state, nearest monster/door/by class/name/template, and `wobjectfindall*`
  variants over world, landscape, inventory and containers;
- **actions:** select, use, apply, give, equip wand, cast, cast-on-target,
  move, split and drop;
- **combat/movement:** combat state get/set, busy state, equipped weapon type,
  heading/get-heading-to, motion get/set/clear and portal-state query;
- **inventory/loot/salvage:** counts by name/regex/type, give-profile,
  unopened corpse queries, `ustadd`, `ustopen`, `ustsalvage`;
- **fellowship/quest/XP:** thirteen fellowship queries, quest state/progress,
  seven XP-meter operations;
- **UI/options/network/login:** status HUD, view/control get/set/visibility,
  VT option/meta get/set, macro status, UtilityBelt options, regex capture,
  network clients and next-login control.

This catalog is a compatibility test ledger. Each name must eventually be
implemented, deliberately aliased, or marked unsupported with a documented
reason; silent omission is not acceptable.

## 4. acdream mapping after the 2026-08 campaigns

The 2026-07 report's architecture remains correct, but its gap table is stale.
The Runtime now owns inventory transactions, selection, combat mode and power
state, casting, fellowship, allegiance, vendor and secure-trade state. MossTank
already consumes a small BCL-only `IAutomationSurface` for vitals, skills,
spells, enchantments, casting and local chat.

The gaps relevant to the first autocombat milestone are narrower:

| Need | Canonical owner today | Plugin gap |
|---|---|---|
| hostile query and live position | `RuntimeEntityDirectory` + `ClientObjectTable` | no target snapshot/query |
| health and selected target | `RuntimeActionState` | no combat view |
| melee/missile charge/release | `RuntimeCombatAttackState` | no command surface |
| combat-mode transition | `RuntimeCombatModeState` | no command surface |
| known offensive spells | `Spellbook` | only self buffs are enumerated |
| target-specific cast | selection + `RuntimeSpellCastState` | possible only by composing two old services |
| polished plugin controls | retained `IUiRegistry` markup | markup lacks bound visibility/enabled/style affordances |

The first implementation therefore does not need a second runtime bridge or a
second object model. It needs a narrow additive projection of those exact
owners.

## 5. Decisions for MossTank

1. MossTank remains an ordinary plugin. It never references App, Runtime,
   rendering, networking or DAT assemblies.
2. The host API exposes snapshots and attempt-style commands; MossTank owns
   target scoring, rule ordering, spell/attack choice and timing.
3. The first combat milestone supports melee, missile and direct offensive
   magic, target lock, range/angle/hybrid scoring, priority rules, attack
   height and power. Navigation, weapon swapping, debuffs, vulnerabilities,
   pets and monster expressions are later combat slices, not hidden stubs.
4. Expressions will use UtilityBelt's richer typed semantics. Compatibility
   is defined by parser/evaluator tests and the audited function ledger, not by
   copying UtilityBelt implementation code.
5. Native MossTank profiles will be versioned JSON. Importers for VTank files
   can be added later without constraining the internal model.
6. The UI uses acdream's retained plugin UI contract. Missing generic controls
   should improve that contract/markup rather than making MossTank depend on a
   presentation implementation.

### 5.1 Follow-up implementation findings (2026-08-27)

VTank's official `e0.d(name)` first looks in `MonsterDamageOverrides`, then
maps the monster to `SpeciesDamages`; `ga.g(...)` walks that ordered preference
list and finally tries the unlisted elements 0..6. acdream already projects
retail `CreatureType` as `PluginCombatTarget.SpeciesId`, so MossTank can bypass
VTank's name-to-species compatibility table while preserving the same ordered
damage result. Exact name overrides still win. The imported official feed has
59 overrides and 103 species rows.

### 5.2 Official inventory and loot findings (2026-08-27)

The official VTank assembly and its GameInfoDB were inspected rather than
inferring behavior from the UI labels:

- `el.cs`/`cf.cs` supply 757 exact craft rows; prerequisites are recursive and
  share the canonical item-use transaction;
- `fo.cs` identifies every corpse before selection, parses `Killed by ...`,
  admits the player's own corpse immediately, admits a Share Loot fellow
  immediately, waits 100 seconds for a non-sharing fellow or unrelated public
  corpse, and never crosses ownership on another player's rare-generating
  corpse;
- the default corpse-open retry contract is 30 attempts, then a 200-second
  blacklist; completed corpse records expire after 60 minutes;
- `hv.cs` applies the ordered loot rule first, then falls back to readable
  unknown scrolls and automatic mana-stone/tank acquisition;
- `dy.cs` proves that ManaTank is a mana-bearing donor target, not a worn-item
  recharge consumable. A ManaStone is used on that donor when its mana is at
  least `ManaTankMinimumMana` (default 1000);
- `c7.cs` combines only same-material salvage bags in exact workmanship bands
  `<7`, `7–<9`, `9–<10`, and exactly `10`; one bugged source is abandoned after
  40 failed combine attempts;
- `gmSalvageUI::Salvage` calls
  `CM_Inventory::Event_CreateTinkeringTool`: game action `0x027D`, tool id,
  then `PackableList<unsigned long>` (count plus ordered item ids). This same
  operation handles ordinary source salvage and salvage-bag combination.

The native implementation keeps settings, loot, route, and meta documents
independent, matching VTank's profile model while using versioned JSON as the
working format. It also emits and imports exact compatibility files: `uTank2
NAV 1.2`, CondAct `.met`, and VTClassic `UTL 1` (plus legacy UTL v0 reads).
The UTL port preserves unknown length-delimited requirement and extra-block
payloads, executes the complete 31-type requirement vocabulary, and carries
the `SalvageCombine` material ranges/value modes into the live combine planner.
VTClassic's color rules use the original ordered ObjDesc subpalettes and the
original sample index `length*16 + offset*32 + 8`, resolved from portal DAT
palette colors rather than approximated from icon pixels.

Profiles are implemented over manifest-scoped JSON with exact VTank files as
an interchange/export layer: `By char` hashes the canonical character name into a distinct
document, named profiles are explicit shared snapshots, and the index records
owner plus per-character active selection. Create/copy/clear/select all hot-
load the same mutable policy owners already borrowed by the controllers. The
generic retained markup contract gained editable fields and retail dropdown
menus for this editor; later Monsters, Loot, Route, and Meta editors reuse the
same controls.

## 6. Acceptance boundary for “autocombat ported”

The milestone is complete when an in-world MossTank panel can enable/disable
combat, periodically capture canonical hostile targets, preserve a valid
locked target, choose a target by configured range/angle/hybrid policy and
priority, enter the equipped default combat mode, drive retail's physical
press/charge/release state machine at configured height/power, or cast the
best usable learned direct offensive spell in magic mode. It must stop cleanly
on session loss, invalid/dead/out-of-range targets, and user disable; it must
not duplicate Runtime state or issue overlapping requests.

Full VTank parity is the campaign target. This acceptance boundary is only the
first executable slice requested for this work session.

## 7. Official binary combat-item findings (2026-08-27)

The official `vt.tar.gz` update was decompiled for behavior research and the
live GameInfoDB v9 feed was read directly. The decisive implementations are
`dz.cs` (debuff source selection), `ga.cs` (item classification), `gs.cs`
(caster-item confirmation), `bo.cs` (physical/proc confirmation), and `hi.cs`
(attack-power policy).

- `dz.b.CompareTo` ranks spell quality then source skill/spellcraft for
  `SpellLevel`, reverses those two for `Skill`, and gives a learned spell the
  final tie. Spell quality is normally spell difficulty.
- Caster items activate on the target. Melee/missile proc weapons are equipped
  and repeatedly attack at power 0/1 respectively. Neither path counts as
  applied until color-7 combat chat matches `^You cast (.*) on .*$`.
- Grenades are missile-class items with CombatUse 0 and `Phial` in the name;
  the official database contains exactly 72 names across eight material tiers,
  with Alchemy requirements 75..400 and spellcraft 100..520.
- Normal physical attack power is not a smooth heuristic. `hi.cs` emits the
  exact 0, .2, .49, .5 or 1 values for slash/pierce hybrid arrangements, then
  clamps to .11..90 when trained Recklessness is enabled.

These findings require three host facts VTank formerly obtained through
Decal: retained per-item appraisal SpellBooks, ordered transcript capture, and
an explicit combat-mode command. They are additive BCL plugin contracts;
MossTank retains all source-choice and retry policy.