Glossary

Code names in monospace. The guide that covers a term is linked at the end of its entry.

The wheel#

Wheel: the Container the builder returns: its rings, one event emitter, shortcuts to the main ring.

Ring: one spinning disc with its sections, pointers and skin. A wheel has one or more around the same centre. Rings

Main ring: the ring the wheel’s shortcut methods address. 'main' unless a config names it otherwise.

Section: one wedge: id, label, value, weight, style, tags, optional rich content. Also sector, segment. Sections

Weight / arc: a section’s relative share of the ring; its arc is that share of 360 degrees. Default weight 1.

Divider: the line between two sections. A pointer crossing one fires pointer:tick.

Start angle: where section 0 begins, wheel-local degrees. Default -90 (twelve o’clock); sections lay out clockwise from there.

Hub / rim: the centre of the wheel and its outer edge. radius(outer, inner) sets both; inner is the hub radius.

Disc / overlay: a ring’s two containers. The disc rotates (sections, labels, face); the overlay does not (bezel, hub cap, pointers).

Dynamic sections: weights that change at run time, animated, with labels re-centring. Cosmetic: the landing is decided by setResult(), never by the geometry. Step: one authored set of weights in a dynamic config. Dynamic sections

Labels#

Label: the text a label-drawing skin writes for a section. Defaults to the id; '' draws nothing.

Content: a rich label: any Container, or a factory that builds one from a LabelContext (section, radii, slot, a bound fit()). Sections

Slot: the box a section offers a label at its label radius: the chord across the wedge and the radial room around it. labelSlot() computes it.

Fit mode: how content meets its slot: 'contain' (default), 'cover', 'width', 'height', 'none'. Helpers scaleToFit, fitContainer, fitText.

Label orientation: 'radial' (hub to rim), 'tangential' (along the arc, top toward the rim), 'tangential-in' (top toward the hub, for wheels read from six o’clock), 'upright' (stays upright as the disc turns).

Spinning#

Profile: a SpinProfile: cruise speed, wind-up, stop duration, ease, turn range. Only spinSpeed is required. Registered by name, switched with setSpeed(). Presets: NORMAL, TURBO, CINEMATIC, QUICK. Profiles

Wind-up / cruise: the acceleration to spinSpeed, then the constant-speed phase while the result is awaited. spin:cruise marks the hand-over.

Planned stop: the list of legs computed when the stop may begin. One deceleration whose ease starts at the cruise speed, plus any tease and settle legs; playback is deterministic. Spin lifecycle

Leg: one piece of a plan: a distance, a duration, an ease. Kinds: decel, creep, hesitate, push, dwell, skip, settle, bounce, bounce-return. No plan has a reverse leg before the rest.

Turns: full rotations in the stop. The planner picks the count in minTurns..maxTurns whose duration is closest to stopDuration.

Ease: the curve a leg follows: a GSAP-style name (power3.out, sine.inOut) or a function. The stop ease must be an ease-out.

Idle: a slow rotation while nothing happens. wheel.idle.start() / stop(), ring.idle.isActive; spin() takes over and idle resumes after. Idle

Result timeout: resultTimeoutMs on spin(): reject the promise and land on the current section when no result arrives in time.

Landing#

Target: a WheelTarget: { section }, { index }, { value }, { angle } or { position }, the first three with an optional offset. Adapters

Landing angle: the wheel-local angle that ends under the pointer. Fixed at setResult(); skips, slams and weight changes never move it. Landing

Landing mode: where inside the section: 'center', 'random' (kept margin off the dividers), or 'exact' (the offset or angle you passed).

Settle: the move after landing: 'none', 'center' (glide to the middle after delayMs) or 'bounce' (overshoot bounceDeg, spring back).

Skip: skip(): a fast-forward to the landing over the profile’s skipDuration, at least a third of a turn. Throws before the result is in; requestSkip() holds the press until it is allowed. Slam: slamStop() snaps to the final position synchronously.

Anticipation / near-miss: a planned tease: the pointer heads for the bait, lands on the target, rests by the line the two share. The wheel comes to rest once, on the result. Anticipation

Bait: the section the player is meant to hope for. Must neighbour the landing in the spin direction, else the tease is dropped with a warning.

Creep / stutter / stall: the three styles. Creep crawls through the bait and barely crosses the line; stutter all but stalls short of the line, then slips over; stall enters the target and dies just short of the bait’s line. 'auto' picks by geometry.

Rest: where the pointer ends after a tease, as a fraction of the target’s arc from the shared divider (0.22 creep and stutter, 0.15 stall). 'keep' leaves the landing mode in charge.

Protected skip: protectSkip: the first press fast-forwards to the start of the crawl and lets the tease play; the second lands. skip:requested reports protectedByAnticipation.

The pointer#

Pointer: the fixed mark a ring is read against. Also tongue, flapper, stopper, needle. Results are read against the first one. Pointers

Pin / tip: the point the pointer pivots around, and its far end. A skin draws with the pin at its origin and the tip at +length on x. tipInset is how far the tip reaches past the rim.

Facing: 'inward' sits on the rim with the tip toward the hub; 'outward' sits at the hub pointing out.

Peg: a small circle on the disc the tongue touches, one per divider by default. pegs.inset defaults to tipInset + size - 2, a 2 px bite into the blade. The tongue

Blade / flap: the tongue as the contact model sees it, a triangle hinged at the pin; the flap is its deflection: the smallest swing from where it stands that keeps the peg outside the blade, sprung back by stiffness and damping, never past maxAngle. elasticity and friction pad the peg.

Reach: whether the peg ring runs between a pointer’s pin and tip. A pointer out of reach warns once and stays still.

Drag: flap.drag: how hard the tongue holds the ring back while a peg climbs it. Drawn only: ring.visualRotationDeg moves, rotationDeg never does, and it relaxes to zero at rest.

Tick: a divider passing under a pointer. pointer:tick carries the pointer, the sections either side, the speed and the direction.

Skins and art#

Skin: what a ring looks like. The ring owns motion; the skin owns pixels. graphics (default), debug, texture, spine, headless, or your own RingSkin. Skins

Skin config: the serialisable form, { type: 'graphics', ... }. Instances are recorded as { type: 'custom' } by toConfig().

Asset resolver: { texture(key) }, what fromConfig() uses to turn texture keys into loaded textures.

Face: the painted disc as one texture. Plate: one wedge as its own sprite, authored upright with its outward edge at the top. Bezel: the fixed frame round the rim, on the overlay. The disc

Decoration: a per-section sprite in TextureRingSkin, placed from the section’s midAngle and kept there when weights move.

Bone: in SpineRingSkin, the skeleton bone the engine rotates. The rest of the skeleton stays fixed and keeps animating.

Highlight: a skin’s emphasis on one section. wheel.highlight(id) / highlight(null).

Angles#

Clockwise positive: degrees increase clockwise on screen, as in PixiJS.

Local angle: an angle on the disc, rotating with it. Screen angle = local angle + rotation, so the pointer at screen angle p reads local p - rotation. A clockwise spin sweeps decreasing local angles under the pointer.

Entry / exit edge: the divider a pointer meets first and last for a spin direction. Clockwise, the entry edge is the section’s endAngle.

Normalised angle: folded into 0..360 with normalizeDeg. Sections keep unnormalised, increasing angles so section i’s endAngle equals section i+1’s startAngle.

Tooling#

Config: WheelConfig, the JSON twin of a builder: toConfig() / fromConfig(), checked by assertWheelConfig. Template: a ready-made config from WheelTemplates. Configs

Adapter: createTargetAdapter(config): turns a server response into a WheelTarget. Adapters

Ticker: the PixiJS Ticker the wheel advances on. Everything moves by deltaMS, so FakeTicker makes spins deterministic. Testing

Harness: createTestWheel and friends: a headless wheel, seeded randomness, expectPointerOn, captureEvents.

Notice: a console warning with a stable code (bait-too-far, ease-slope, landing-moved) for a legal but suspicious call. setLogLevel() silences them.

Debug overlay / snapshot / arc: debugOverlay() draws the geometry over the wheel, debugSnapshot() is the state as JSON, debugArc() the ring as a text strip. enableDebug() puts all three on window.__PIXI_WHEELS_DEBUG. Debugging