v0.4.0GitHub—

docs / reference / options

Options reference

Every SwarmTroopersOptions field, its default, and the behavior it controls.

Pass these options to create(options) or new SwarmTroopers(options). The IIFE’s JSON initializer accepts the same serializable fields plus its own controls configuration. DOM elements, functions, and plugin objects require JavaScript.

##Content and startup

OptionTypeDefaultBehavior
rootElement | string | nulldocument.bodyScan descendants of this element or selector. An explicitly missing selector throws before host mutations; it never falls back to body.
selectorstring"[data-swarmtroopers]"Which descendants carry annotations. Annotation values still come from data-swarmtroopers.
autobooleanfalseAutomatically classify eligible descendants.
trigger"immediate" | "scroll" | "manual""immediate"Start on initialization, first scroll/wheel/touchmove/keydown/pointerdown, or start().
oncefalse | "session"falseAfter completion, skip another build using the same storage prefix in that browser session.
maxTasksnumber400Maximum enrolled tasks (integer 0–10000). Overflow stays visible. Each scan reads the style of at most max(100, maxTasks × 8) candidates that are not enrolled yet.
storageKeystring"swarmtroopers"Storage prefix; quality uses localStorage and completion uses sessionStorage.

##Rendering and pacing

OptionTypeDefaultBehavior
quality"auto" | "full" | "light" | "off""auto"Initial rendering budget; a saved preference takes precedence. See resolution order.
agents.maxnumber6 full; 3 lightInteger 1–32; Light mode still caps workers at 3.
speednumber1Gesture speed multiplier. Finite multiplier from 0.01 to 100; larger values finish gestures faster.
patiencenumber2.4 seconds; 1.4 on narrow screens or light modeHow long visible pending work waits before simply appearing. Blocking parent tasks can appear sooner.
scalenumber1.2; 1.05 below 600pxFinite pointer, task-caption, bubble, and label size multiplier from 0.25 to 4.
zIndexnumber2147483000Overlay canvas stacking level. The built-in controls have their own fixed stacking level.

##Appearance and language

OptionTypeDefaultBehavior
palettestring[] | PaletteSpecSwarm Troopers paletteCSS colors for agent identities and section survey outlines, or an OKLCH palette specification.
inspectbooleanfalseAfter construction, pointer hover brings an agent to label a finished element.
labelsbooleanfalseShow labels during construction. They remain suppressed on narrow screens; inspection can still label.
namesboolean | string[]trueBuilt-in first names, a custom pool, or no name tags. A custom array must contain at least one non-empty name.
leadNamestringLocalized “Orchestrator”Override the orchestrator’s name.
localestringDocument lang, then enLanguage for tasks, section-role names, and completion text. English and French are built in.
chatboolean | ChatOptionsfalseSpeech bubbles and optional localized text overrides. An options object enables bubbles unless bubbles: false.
finalebooleantruePlay the completion celebration after a natural build. finish() does not play it.
pluginsArray<SwarmTroopersPlugin | "tokens">[]Plugin instances or the built-in "tokens" shorthand.

##PaletteSpec

The default agent colors are the lead in page ink (#0d0e11 on light pages, #eceef2 on dark ones), then blue #7db4ff, violet #b98cff, teal #5fe3d0, and pink #ff7eb6. Named agents keep a stable color based on their position in the name pool, even across sections. Section survey outlines use a separate color from the same palette. A custom list replaces these colors. The supplied completion artwork keeps its own blue and orange colors.

javascript
create({
  root: 'main', auto: true,
  palette: { hue: 210, count: 6, lightness: 0.68, chroma: 0.16 },
});

FieldDefaultMeaning
hue40First hue in degrees; subsequent hues use golden-angle steps.
count8Integer number of generated colors from 1 to 64.
lightness0.6 light page; 0.76 dark pageOKLCH lightness from 0 to 1 when generating through Swarm Troopers.
chroma0.16Requested OKLCH chroma; it decreases until a color fits sRGB.

Numeric options are bounded: speed 0.01–100, scale 0.25–4, nonnegative finite patience, integer agents.max 1–32, integer maxTasks 0–10000, and integer zIndex 0–2147483647. Palette specifications accept count 1–64, lightness/chroma 0–1 and finite hue from -360000 to 360000. Options are read at construction. To change an option without a setter, destroy the instance and create another. Object shape, enums, selector syntax and bounded numeric fields are validated before host mutations. Invalid script initialization logs a diagnostic without hiding content; direct JavaScript creation throws for invalid configuration.