acdream/docs/research/2026-07-29-vtank-plugin-automation-requirements.md

Virindi Tank as the requirements model for acdream's plugin-automation milestone

User-requested research (2026-07-29): the plugin API's north star is that a user can write automation state machines as acdream plugins with VTank-class power (the famous Decal automation plugin for original AC — http://virindi.net/wiki/index.php/Virindi_Tank). The live wiki is effectively unreachable (self-signed TLS; the HTTP wiki returns a database error); this report was built from Wayback Machine snapshots of the wiki pages plus primary source code (metaf's .met/.nav encodings, VTClassic's loot-rule classes) — full citation list at the end.

The architectural conclusion up front: VTank's meta state machine, expression language, and loot-rule engine are PLUGIN-land, not host-land — VTank built them on Decal's primitives. acdream's milestone ships the primitive layer; a VTank-compatible meta/nav/loot engine can then be an acdream plugin — even file-compatible with .met/.nav/.utl, all of whose encodings are decoded below. And the K2 headless-bot triad (Tick(IGameRuntimeView, IGameRuntimeCommands) + IRuntimeEventObserver) is already exactly the right substrate: synchronous borrowed reads, generation-gated typed commands with attempt semantics, an ordered delta stream. The milestone is largely a bridging + query-surface exercise, not a new architecture.

---

1. Capability inventory

1.1 Combat macro

• Attack styles: melee, missile, mage, full hybrid templates; two-handed; Void; Summoning; harm/martyr mage mode; alchemical grenades; lenses; cast-on-strike debuffing weapons; war/void streak spells. VTank auto-selects the best attack type from the configured weapon list (Items tab: wands/melee/missile/shields/pets, per-monster weapon+offhand overrides).
• Target selection: per-monster priority -1 (ignore) through 0–4; TargetSelectMethod = by range / by angle / both (angle when near, range beyond TargetSelectAngleRange); TargetLock; blacklisting of unhittable targets (BlacklistMonsterAttemptCount/TimeoutSeconds); ghost-monster detection two ways (N failed cast starts, or no HP updates for N seconds) with a forced client-side delete.
• Monster list = a rule table, first-match-wins after DEFAULT, keyed by name or by monster expressions over: true, false, name, typeid, species, maxhp, range (dynamic), hasshield (dynamic), setting_<OptionName> (dynamic), metastate (dynamic) with a full operator set (( ) % / * + - # != == > < >= <= && || and \ escape; # is regex-match). Per-entry action matrix: Fester, Broadside, Gravity Well, Imperil, Yield, Vuln, Attack, Ring, Streak, void curses (WC/FC/Cp/DC/Cs), damage type (or <Auto>), extra vuln element, weapon/offhand/pet damage type per monster.
• Debuff sequencing: DebuffEachFirst = one / same-priority-group / all-before-attacking; DebuffSelectionMethod = by spell level or by (buffed) skill; DebuffPrecastSeconds re-application window; SwitchWandToDebuff.
• AoE logic: ring when ≥ MinimumRingTargets within RingDistance; arcs over bolts beyond ArcRange.
• Melee specifics: attack height (high/mid/low), auto attack-power by weapon damage type, power-bar slider (/vt setattackbar 0..1), recklessness, multi-step weapon-swap state machine with peace-mode retry counting (/vt equipitemsfor <monster> executes one step per call).
• Pets: summon when ≥ PetMonsterDensity targets within pet range; per-monster pet element; idle/combat refill thresholds; /vt testpet.

1.2 Buffing engine

• Auto-buffs every trained attribute/skill plus protections and banes — derived from the character's skills, spellbook, and available components (the Buffs tab only adds untrained-skill buffs or exclusions). Prot/bane sets All/None/B/BPS/BPSA/ALFC/Custom via BuffProfile_Prots/_Banes.
• Rebuff below 5 minutes remaining (RebuffTimeRemainingSeconds); idle early-rebuff (IdleBuffTopoff); force-buff/cancel; level 8s; item-buff durations persisted across logins; buffing with consumables (items under 5-minute duration rejected).
• Skill gating with signed thresholds SpellDiffExcessThreshold-Buff/-Hunt (negative = attempt above-skill spells) — exposed to expressions as getcancastspell_buff/hunt (scarab count + buffed skill + spellbook).

1.3 Vitals / heal / restam management

• Three recharge tiers, each per-vital: in-combat trigger percentages (Recharge-Norm-*), idle top-off (Recharge-NoTarg-*), and fellowship helper (Recharge-Helper-* + per-vital max distances; requires fellow panel open or a VI2 fellowship).
• Healing kits (minimum success chance, optional drop-to-peace first), stamina→health and mana→health spell multipliers, post-switch recharge boost, Healer's Heart support.
• Dispel-on-vuln: detects a level-7 vuln landing and responds with dispel gems/potions and/or Eradicate self.

1.4 Inventory upkeep and crafting

AutoStack (stack toward bottom-most so the partial stack burns first), AutoCram (main pack → side packs), pea splitting with three priority tiers, auto-crafting consumables (kits, foods, arrowheads, special ammo), mana-stone economy (loot stones to a count, fill from loot above a mana floor, drain onto worn items at a refill percentage, even while the macro is off), lockpicks for auto-picking doors with a skill-vs-difficulty threshold.

1.5 Looting — VTClassic and the loot-plugin seam

VTank's looting is plugin-based: the host macro does corpse approach/open/wait; a loot plugin classifies each item (VTClassic canonical; Alinco3/GearFoundry use the same uTank2 LootPlugins seam). Macro-side knobs: approach ranges, open retry + blacklist, CorpseItemAppearanceTimeoutSeconds / CorpseItemIDTimeoutSeconds (wait for items, then for IDs), loot all/fellow/rares-only, priority boost, read-unknown-scrolls, salvage combining per-profile workmanship ranges.

From VTClassic source: profile = ordered rules; rule = name + action + AND-ed requirements; first match classifies, evaluated against the item's retail appraisal property bags (LongValueKeys, DoubleValueKeys, StringValueKeys, spell list — what /vt propertydump prints).

• Actions (eLootAction): NoLoot=0, Keep=1, Salvage=2, Sell=3, Read=4, User1–User5=5–9, KeepUpTo=10.
• Requirement types (eLootRuleType): SpellNameMatch(0), StringValueMatch(1), LongValKeyLE(2), LongValKeyGE(3), DoubleValKeyLE(4), DoubleValKeyGE(5), DamagePercentGE(6), ObjectClass(7), SpellCountGE(8), SpellMatch(9), MinDamageGE(10), LongValKeyFlagExists(11), LongValKeyE(12), LongValKeyNE(13); armor color: AnySimilarColor(14), SimilarColorArmorType(15), SlotSimilarColor(16), SlotExactPalette(17); character-state: CharacterSkillGE(1000), CharacterMainPackEmptySlotsGE(1001), CharacterLevelGE(1002), CharacterLevelLE(1003), CharacterBaseSkill(1004); computed buffed-value: BuffedMedianDamageGE(2000), BuffedMissileDamageGE(2001), BuffedLongValKeyGE(2003), BuffedDoubleValKeyGE(2005), CalcdBuffedTinkedDamageGE(2006), TotalRatingsGE(2007), CalcedBuffedTinkedTargetMeleeGE(2008).
• The buffed/calced family means the loot engine needs the character's current buffed skills and tinkering math, not just item properties; color rules need item palette data.
• .utl file: text — UTL header, version, rule count, rule blocks, extra blocks (salvage-combine workmanship ranges like 1-5,6-7,8,9,10).

1.6 Navigation

Route types (NavTypeID): Circular=1 (ABC-ABC, enter at closest point), Linear=2 (ABC-CBA ping-pong), Follow=3 (chase a named player; FollowAroundCorners = replay leader's path vs run straight), Once=4 (points consumed as reached; runback routes).

Nav point vocabulary (NTypeID — the exact .nav wire order):

Type	ID	Payload
Point	0	x, y, z
Portal (deprecated)	1	x, y, z, portal GUID
Recall	2	x, y, z, exact recall-spell name (fixed ~30-entry list)
Pause	3	x, y, z, milliseconds
Chat	4	x, y, z, arbitrary chat/slash text
Open Vendor	5	x, y, z, vendor GUID, name
Use Portal/NPC	6	own x,y,z + target x,y,z + target ObjectClass + name
NPC Talk	7	same as 6 — use repeatedly until a tell is received
Checkpoint	8	x, y, z — wait for SERVER-confirmed position
Jump	9	x, y, z, heading, shift bool, charge ms (+strafe variant)

.nav file: plain text, uTank2 NAV 1.2 header, route-type int, node count, node records (verified against a real route file). Runtime knobs: arrival radius (NavCloseStopRange), off-course abort (NavFarStopRange), nav-before-combat priority boost, door opening en route, reverse-route. Routes embed inside meta files (metaf EmbedNav, optional transform).

1.7 Fellowship behaviors

Auto-recruit on tell, waiting-list management, leader queries, AFK-leader replacement votes — all via chat tells. Plus helper healing (1.3), fellow-corpse looting, and (via Virindi Integrator 2) out-of-band fellow coordination (prefer already-vulned targets, avoid double-vulning).

1.8 The Meta system — the state machine

Named states (start = "Default"); rule = (state, condition, action); rules checked only in their state; each rule fires once per state entry (re-armed by re-entry). Conditions evaluated ~every 293 ms plus whenever the macro decides what to do next. Call stack: Call Meta State pushes a return state, Return From Call pops (empty stack = error + meta disabled). Watchdog: per-state "if not moved ≥ distance in N seconds, call state S."

Conditions (CTypeID 0–28): Never(0), Always(1), All(2), Any(3) (nesting combinators), ChatMatch(4) regex, MainSlotsLE(5), SecsInStateGE(6), NavEmpty(7), Death(8), VendorOpen(9), VendorClosed(10), ItemCountLE(11)/GE(12), MobsInDist_Name(13) (count, distance, name-regex), MobsInDist_Priority(14), NeedToBuff(15), NoMobsInDist(16), BlockE(17), CellE(18), IntoPortal(19)/ ExitPortal(20), Not(21), PSecsInStateGE(22) (persistent timer), SecsOnSpellGE(23) (enchantment time remaining), BuPercentGE(24) burden, DistToRteGE(25), Expr(26), ChatCapture(28) — regex with named capture groups saved to variables (capturegroup_<name>, capturecolor) plus chat-color filtering.

Actions (ATypeID 0–15): None(0), SetState(1), Chat(2) (the universal escape hatch — /vt commands, tells, other plugins), DoAll(3), EmbedNav(4), CallState(5), Return(6), DoExpr(7), ChatExpr(8), SetWatchdog(9), ClearWatchdog(10), GetOpt(11)/SetOpt(12) (read/write ANY host option — the macro reconfigures itself), CreateView(13), DestroyView(14), DestroyAllViews(15) — Meta Views: XML-defined control panels (controls with actionexpr/setstate attributes) so a meta ships its own UI.

1.9 Meta Expressions — the scripting language

Numbers (doubles; booleans 0/1), strings, objects (coordinates, world objects, stopwatches, view controls). Operators by precedence: \ ( ) % / * + - #(regex) != == > < >= <= && || ^ ;. Variables persist to relog (setvar/getvar/testvar/touchvar/clearvar/clearallvars). 67 functions documented in the 2016 snapshot (UtilityBelt's compatible dialect grew it to ~200):

• Raw property reads by retail key id: getcharintprop, getchardoubleprop, getcharquadprop, getcharboolprop, getcharstringprop (wiki ships key tables: Level=25, Deaths=43, augmentations 218–328, luminance auras 333+, TotalExperience quad 1, FellowshipName string 10, …).
• Vitals/skills: getcharvital_base/current/buffedmax(1|2|3), getcharskill_traininglevel/base/buffed(skillId).
• Spells: getisspellknown, getcancastspell_hunt, getcancastspell_buff.
• Location: getplayerlandcell, getplayercoordinates (from the PHYSICS prediction model), coordinate objects (coordinategetns/getwe/getz/tostring/parse, coordinatedistancewithz/distanceflat).
• World-object queries: wobjectgetphysicscoordinates, wobjectgetname, wobjectgetobjectclass, wobjectgettemplatetype, wobjectgetisdooropen, wobjectfindnearestmonster, wobjectfindnearestdoor, wobjectfindnearestbyobjectclass, wobjectfindnearestbynameandobjectclass, wobjectfindininventorybytemplatetype/byname/bynamerx, wobjectgetselection, wobjectgetplayer — ObjectClass enum 0–43 (Monster=5, Portal=14, Corpse=27, Npc=37, Salvage=39, Ust=40, Scroll=42, CombatPet=43).
• Action functions (async attempt semantics — 0 not-yet / 1 begun / 2 impossible): actiontryselect, actiontryuseitem, actiontryapplyitem, actiontrygiveitem, actiontryequipanywand, actiontrycastbyid, actiontrycastbyidontarget.
• Chat/UI: chatbox, chatboxpaste, statushud, statushudcolored, uigetcontrol, uisetlabel.
• Utility: iif, istrue/isfalse, randint, cstr/cstrf/cnumber, strlen, floor/ceiling/round/abs, stopwatch*, getobjectinternaltype.
• Testing: /vt mexec <expr>, /vt listmetafunctions, /vt metafunchelp.

1.10 Commands, profiles, files

/vt surface: per-subsystem profile save/load (settings|nav|loot|meta, per-character variants), opt list/get/set/setinall (every internal variable scriptable), macro start/stop, forcebuff, setmetastate, fakedeath (test hook), testitem (dry-run loot classification), propertydump, testmonster, testspell, getdb (spell/species/material tables), nav editing (addnavpt/addnavjump/addnavcheckpoint/reverseroute), jump/tapjump/ setattackbar, dump commands, typed debug logging channels. Persistence: profile directory with .settings (global + [Char]), .nav, .utl, .met; every UI change auto-saves; all four profile kinds hot-loadable from chat/meta (how metas compose: /vt nav load runback).

1.11 The companion-plugin bundle

VTClassic looter + out-of-game rule editor; Virindi Integrator 2 (account-based cross-world groups/tells, fellow coordination); Reporter; Chat System 5 (rule-based chat filter/recolor/sounds); Item Tool (bulk give, buy/sell, mule transfer, comp purchasing — other plugins call into it); Follower; HUDs (status HUD writable from expressions, VTank remote, vitals bars); Hotkey System; Sense (spawn alerts); Window Tool; Global Inventory (cross-character item index); GoArrow; SSSort. Ecosystem: metaf (text ↔ .met/.nav compiler), UtilityBelt (modern superset). Multi-account orchestration is built on metas + chat tells — no special API.

---

2. The implied plugin-API surface

Game-state reads: (1) world-object table with full property bags — id, name, ObjectClass-style classification, weenie/template type, PHYSICS position, heading/distance, container/wielder links, door state, vendor identity; query verbs (nearest-by-class, name-regex+class, in-range counts, inventory filters). (2) appraisal surface — per-object retail property bags (int/bool/double/string/quad + spell list + palette + material/workmanship), ID-request command + ID-arrived event. (3) character sheet — vitals (base/current/buffed max), skills (training/base/buffed), burden, pack slots, level/XP/luminance, augmentations, spellbook, component counts. (4) enchantment table with remaining seconds per spell id (+item-buff timers persisted). (5) spatial identity — landblock/landcell, portalspace flag, coordinate conversions. (6) target combat state — per-monster HP stream, equipment reads. (7) fellowship state. (8) vendor/trade state.

Commands (attempt semantics + busy arbitration): select, examine/ID, use object, use X on Y, give to NPC/player, loot specific item from container, salvage, read scroll, equip weapon-set (multi-step), combat mode + height/power, attack, cast (self/on-target) with pre-flight checks, move-to / follow, jump(heading, shift, charge, strafe), vendor open + buy/sell, split/stack/move items, lockpick, chat injection, and runtime option get/set on the automation host itself.

Events: chat (channel/color, capture-friendly), death, vendor open/close, portalspace enter/exit, cast begun/landed/fizzled (and never-started), item appeared on corpse, ID arrived, target HP update, server-confirmed position (checkpoint semantics), nav arrival, fellowship changes.

Scheduling & persistence: ~3 Hz decision tick interleaved before the host's own arbitration; subsystem priority (heal > combat > nav > loot with boosts); per-subsystem hot-loadable profiles (global + per-character); a persisted per-character key/value store.

UI: declarative runtime panels (markup), button → action/state bindings, a writable status-HUD channel.

---

3. Mapping to acdream today

Already-strong seams: the K2 headless triad (IHeadlessBotPolicy.Tick (view, commands) + IRuntimeEventObserver) is precisely the loop a VTank-class engine needs — synchronous borrowed reads, generation-gated typed commands (RuntimeCommandResult ≈ VTank's attempt semantics), ordered delta stream (VTank's 293 ms meta tick maps onto Tick). Event coverage already spans lifecycle, command receipts, entity, inventory, chat, movement, portal deltas (IntoPortal/ExitPortal fall out for free), combat. Command coverage: Selection/Combat/Magic/Movement/Chat/Portal/Spellbook/Character/ Social. Character reads: vitals/attributes/skills incl. FormulaBonus (≈ buffed), KnowsSpell; the enchantment registry exists Runtime-side (M3). IUiRegistry.AddMarkupPanel is already a better-typed Meta Views.

The gap: AcDream.Plugin.Abstractions today exposes only IPluginHost { Log, State (4-field entity snapshots), Events (EntitySpawned), Selection, Ui }. Everything VTank-class lives Runtime-side but is not plugin-visible:

Cluster	Status
Bot loop (tick+commands+ordered events)	Exists (K2); not bridged to plugins
Entity queries w/ classification/name/distance	Deltas exist; snapshots lack name/class/type; no query verbs
Property bags / appraisal	M4 Slices 1–3 landed assessment client-side; no plugin surface
Enchantment table w/ remaining time	State exists (M3); no enumerating view
Cast-on-target with outcome events	Command exists; outcomes implicit only
Use/apply/give/loot-item/salvage/vendor	Use+PickUp exist; vendor = M4 Slices 5–6 in flight; apply/give absent
Move-to / follow / jump / routes	Absent — movement is WASD-intent-shaped; no point-goal primitive
Fellowship state	Not in Runtime views yet
Plugin persistence/options	Untyped (plugins can own files; low urgency)

---

4. Milestone shape — dependency-ordered API additions

1. Plugin↔Runtime bridge (the enabler): mirror the K2 triad into BCL-only Plugin.Abstractions — per-plugin Tick(view, commands), generation-gated command groups, ordered event observer. Upgrades plugins to headless-bot parity; chat in/out unlocks the VTank composition idiom.
2. Entity/property query surface: enrich plugin entity snapshots (name/class/weenie type/physics position); query verbs; per-object property bags in the retail key space; ID-request command + ID-arrived event. Rides on the landed M4 assessment work.
3. Spell/enchantment surface: enumerable active enchantments (spell id, layer, seconds remaining), can-cast prediction (components + skill vs difficulty — the getcancastspell pair), explicit cast-on-target, cast-outcome events.
4. Interaction/transaction commands: use-by-id, apply-on, give, container take-specific, salvage, vendor buy/sell — over the existing one-transaction gate, with receipts as events. After M4 Slices 4–6.
5. Nav/move-to layer: point-goal movement with arrival/stuck/off-course events + a server-confirmed-arrival variant (checkpoint semantics; position-ack tracking exists), follow-entity, jump. The route types and nav-point vocabulary are then pure plugin data; optional .nav import.

(1) gates everything; (2)/(3) independent after (1); (4) depends on M4's in-flight slices; (5) last — route automation needs combat/loot reads to decide when to move.

---

Sources

Wiki content via Wayback Machine snapshots (live site: self-signed TLS / database error): Virindi_Tank (rev. 2024-01-12), Virindi_Tank_Meta_System, Meta_Expressions, Meta_ChatMessageCapture_Condition, Meta_Views, Virindi_Tank_Commands, Virindi_Tank_Standard_Options, Virindi_Tank_Advanced_Options, Virindi_Tank_Monster_List_Matching, Virindi_Tank_Fellowship_Commands, BeginnerBundleGuide, VTClassic_Tutorial, Virindi_Tank_Changelog — all under http://www.virindi.net/wiki/index.php/….

Code/format ground truth: github.com/JJEII/metaf (CTypeID/ATypeID/ NavTypeID/NTypeID encodings + metafReference.af payload tables); github.com/leo-duran/virindi-public-clone (VTClassic LootRules.cs); github.com/aquafir/ACE.BaseMod (vendored eLootAction); github.com/lino-ranta/vtank-routes + vtank-loot-profiles (on-disk .nav / .utl verification); utilitybelt.gitlab.io/docs (modern ecosystem).

acdream grounding: src/AcDream.Plugin.Abstractions/*, src/AcDream.Runtime/GameRuntime{Commands,Events,Views,GameplayViews}.cs, src/AcDream.Headless/Policies/HeadlessBotPolicy.cs.