Log inGet started
World

Watchful Minds: NPC Brains and Perception Kit

README.md

aiKit test suite

Automated tests for the aiKit package: every public call of aiKit.api, the fsm, bt and memory modules, the Brain, AIDebug and NoiseMaker components, and combat and healing through SecondWind.

Run it alone with tools.use("tests", "run", { suite = "aiKit" }) (edit mode; the tests that need brains to think enter play themselves).

What it covers

  • Constants: AI.VERSION (1.3.18) matches package.yaml and, when it exists, the first heading of the package README.md (skipped with a log line while there is no README); AI.BRAIN, AI.DEBUG and aiKit.NoiseMaker resolve as components; the re-exported modules, AI.vec and AI.NOISES.
  • Presets: the 16 built-ins in order; each names a registered brain of kind fsm or bt, both kinds used; AI.preset returns a merged copy; AI.definePreset with a base inherits everything and overrides deep keys (the eagle-eared guard differs from the guard only in hearing sensitivity and search time), unknown bases error; AI.tunePreset changes a preset and presets based on it, and is undone; AI.find by family, tag, brainKind, brain, id, lists of values, and its error on unknown keys; AI.catalog.
  • Perception styles: AI.perceptionStyles / AI.perceptionStyle (names, fields, copies, the error for an unknown style); AI.styles with each style's tags (what it perceives, what it suits, what beats it) and its answer matching perceptionStyle; AI.styles(tag) and a list of tags as filters, loose spelling, unknown tags and bad filters.
  • README: exactly one "Known limits" and one "Version history" section, limits cited by GitHub issue only, and the history naming this version.
  • State machine (AI.fsm): define/get/names, new, update, enter → update → exit → enter order with from/reason, time resetting only on a switch, transitions (from = "*" and named) checked before the state's update, unknown states as errors, label().
  • Behaviour tree (AI.bt): sequence and selector with and without memory, parallel, condition, action (success / failure / running / nil), wait, invert, succeed, cooldown, timeout, repeatUntilFail, tree.active, ticks, last, reset, define/get/names, errors for bad nodes.
  • Memory (AI.memory): saw / glimpsed / heard / told, fading over forget and forgetSound, update dropping faded spots and clearing visible, best() ranking (visible, then sight, report, sound), a fresh sighting not overwritten by weaker evidence, visible(), drop, forgetAll, count, list order.
  • Edit mode: AI.addBrain (fields, update in place, errors), AI.brain, AI.info, AI.isAuthority; the edit-mode command fallback (see Known bugs); AI.debug / AI.debugOn; AI.addDebugToggle and AIDebug:toggle; AI.lightAt beside a lamp and inside a dark roofed box.
  • Senses (play): a sentry sees a dummy in front of it (a 'sight' spot, AI.canSee agrees) but not through a wall or outside its cone; a listener hears a noise in reach as a 'sound' spot at the noise (not at its maker), keyed by the maker or by noise:<seq> when unattributed, and not one beyond reach; a noise through a wall is weaker by wallDamp; a nightwatch spots a lit dummy and misses one in the dark beyond darkRange.
  • Brains (play): a guard walks its route, chases and attacks a dummy that comes into view, searches when it vanishes behind a wall and goes back to patrolling; AI.setPreset guard → turret while running (Sweep, nothing else changed); AI.setActive; AI.setRoute; AI.setTeam / AI.teamOf (brains and plain entities); AI.alert; AI.forget; AI.info; AI.brains; AI.isAuthority; AI.stats and its sections; AI.setLeader with a real player avatar (the canonical player scene) and the companion following; NoiseMaker:throwAt putting a bottle noise on AI.recentNoises; AI.defineBrain with an FSM table and a BT root, each run by a preset.
  • Combat (play): Compat.damage / Compat.heal on SecondWind health; a melee chaser hurting a training dummy; a healer healing a hurt ally.

How it works

Play-mode tests flip this caller's own session into play, build temporary floors and walls at x/z 400..460 (the companion test uses the canonical player scene around the origin), bake a temporary navKit map when something has to walk, and spawn synced characters with AI.addBrain. Targets are a training dummy that never moves (aitest_target, based on dummy) so a test can place it. Every entity, map, test preset and tuned value is removed in cleanup, and the runner discards the play session after each test. Test presets and brains are prefixed aitest_; brains registered with AI.defineBrain stay registered until the module reloads (aiKit has no call to remove one).

What it leaves alone

The look of the bodies, the debug view's drawing, the effects, the multiplayer relay between peers (one peer is all a test has) and the other presets' full behaviours (ranged kiting, sniper, swarm, coward, ambusher, boss phases) beyond resolving to a working brain.

Known bugs it states

  • BUG: commands in edit mode write the fields: AI.setPreset, setTeam, setActive and setRoute return true in edit mode but change nothing (see the comment above the test).