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
| Option | Type | Default | Behavior |
|---|---|---|---|
root | Element | string | null | document.body | Scan descendants of this element or selector. An explicitly missing selector throws before host mutations; it never falls back to body. |
selector | string | "[data-swarmtroopers]" | Which descendants carry annotations. Annotation values still come from data-swarmtroopers. |
auto | boolean | false | Automatically classify eligible descendants. |
trigger | "immediate" | "scroll" | "manual" | "immediate" | Start on initialization, first scroll/wheel/touchmove/keydown/pointerdown, or start(). |
once | false | "session" | false | After completion, skip another build using the same storage prefix in that browser session. |
maxTasks | number | 400 | Maximum 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. |
storageKey | string | "swarmtroopers" | Storage prefix; quality uses localStorage and completion uses sessionStorage. |
##Rendering and pacing
| Option | Type | Default | Behavior |
|---|---|---|---|
quality | "auto" | "full" | "light" | "off" | "auto" | Initial rendering budget; a saved preference takes precedence. See resolution order. |
agents.max | number | 6 full; 3 light | Integer 1–32; Light mode still caps workers at 3. |
speed | number | 1 | Gesture speed multiplier. Finite multiplier from 0.01 to 100; larger values finish gestures faster. |
patience | number | 2.4 seconds; 1.4 on narrow screens or light mode | How long visible pending work waits before simply appearing. Blocking parent tasks can appear sooner. |
scale | number | 1.2; 1.05 below 600px | Finite pointer, task-caption, bubble, and label size multiplier from 0.25 to 4. |
zIndex | number | 2147483000 | Overlay canvas stacking level. The built-in controls have their own fixed stacking level. |
##Appearance and language
| Option | Type | Default | Behavior |
|---|---|---|---|
palette | string[] | PaletteSpec | Swarm Troopers palette | CSS colors for agent identities and section survey outlines, or an OKLCH palette specification. |
inspect | boolean | false | After construction, pointer hover brings an agent to label a finished element. |
labels | boolean | false | Show labels during construction. They remain suppressed on narrow screens; inspection can still label. |
names | boolean | string[] | true | Built-in first names, a custom pool, or no name tags. A custom array must contain at least one non-empty name. |
leadName | string | Localized “Orchestrator” | Override the orchestrator’s name. |
locale | string | Document lang, then en | Language for tasks, section-role names, and completion text. English and French are built in. |
chat | boolean | ChatOptions | false | Speech bubbles and optional localized text overrides. An options object enables bubbles unless bubbles: false. |
finale | boolean | true | Play the completion celebration after a natural build. finish() does not play it. |
plugins | Array<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.
create({
root: 'main', auto: true,
palette: { hue: 210, count: 6, lightness: 0.68, chroma: 0.16 },
});| Field | Default | Meaning |
|---|---|---|
hue | 40 | First hue in degrees; subsequent hues use golden-angle steps. |
count | 8 | Integer number of generated colors from 1 to 64. |
lightness | 0.6 light page; 0.76 dark page | OKLCH lightness from 0 to 1 when generating through Swarm Troopers. |
chroma | 0.16 | Requested 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.