Castaway Isle: Island Survival and Crafting 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.VERSIONis 1.1.0 and matchespackage.yamland, when it exists, the first heading of the packageREADME.md(skipped with a log line while there is no README);AI.BRAIN,AI.DEBUGandaiKit.NoiseMakerresolve as components; the re-exported modules,AI.vecandAI.NOISES. - Presets: the 16 built-ins in order; each names a registered brain of kind
fsm or bt, both kinds used;
AI.presetreturns a merged copy;AI.definePresetwith 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.tunePresetchanges a preset and presets based on it, and is undone;AI.findby 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.styleswith each style's tags (what it perceives, what it suits, what beats it) and its answer matchingperceptionStyle;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,timeresetting 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 overforgetandforgetSound,updatedropping faded spots and clearingvisible,best()ranking (visible, then sight, report, sound), a fresh sighting not overwritten by weaker evidence,visible(),drop,forgetAll,count,listorder. - 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.addDebugToggleandAIDebug:toggle;AI.lightAtbeside a lamp and inside a dark roofed box. - Senses (play): a sentry sees a dummy in front of it (a 'sight' spot,
AI.canSeeagrees) 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 bynoise:<seq>when unattributed, and not one beyond reach; a noise through a wall is weaker bywallDamp; a nightwatch spots a lit dummy and misses one in the dark beyonddarkRange. - 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.setPresetguard → 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.statsand its sections;AI.setLeaderwith a real player avatar (the canonical player scene) and the companion following;NoiseMaker:throwAtputting a bottle noise onAI.recentNoises;AI.defineBrainwith an FSM table and a BT root, each run by a preset. - Combat (play):
Compat.damage/Compat.healon 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,setActiveandsetRoutereturn true in edit mode but change nothing (see the comment above the test).