ZOA Crosshair

CrosshairClass names the canonical archetype categories, and each shipped implementation encodes a readability decision. AssaultRifleCrosshair paints four inward chevrons converging on a bright core, blooming outward as spread climbs. SmgCrosshair is quieter and tighter, four short cardinal ticks close in, so a fast close-range weapon reads as compact. ShotgunCrosshair is a hollow ring that shows the pellet cone widening, with four ticks just outside it. SniperCrosshair is a fine core, tiny inner ticks, outer pips and a faint mil-ring, minimal because aiming is where it does its real work.

EnergyCrosshair and PlasmaCrosshair break the theme tint. Each carries its own weapon-identity colour, cyan for the energy focus ring and violet for the plasma containment diamond, while their ticks stay on the theme accent, so a beam weapon reads as energetic regardless of the HUD palette without falling out of the design language.

The class also drives fallback. When a weapon does not point at a specific definition, it gets the class-default reticle for its CrosshairClass, so an unflagged rifle still shows a rifle reticle. Custom exists for weapon families the built-ins do not cover, and is meant to be paired with a custom IProceduralCrosshair implementation.

Build receives a CrosshairState by in-reference and an ICrosshairStrokeBuilder to append to. Coordinates are normalised to the reticle's bounding box, zero to one on both axes with the centre at 0.5, 0.5, and the view scales that to its configured pixel size at paint time. An archetype therefore never measures the screen, never reads a resolution, and never touches a VisualElement.

CrosshairStroke is a flat readonly struct with four kinds, line, dot, rect and circle, and factory methods for each. WithColor overrides the theme accent for a single stroke, so an energy ring can carry its own tint while the rest of the reticle stays themed. A transparent colour means paint with the state's accent.

CrosshairStrokeList is the builder the view owns: one reusable list, cleared and refilled each repaint, so Build calls allocate nothing on a per-frame path. Implementations are expected to honour that and append rather than build their own buffers.

Since the stroke builder has no native glow or blur, ReticleInk supplies the layered approximation every built-in archetype uses: a wider low-alpha underlay beneath a thin bright stroke, plus a brightened hot core. GlowLine, GlowCircle, GlowDot and GlowChevron keep that consistent across the archetypes without pushing it into the interface.

ZoomMode.None is most weapons: ADS may tighten the reticle but the zoom value stays at one. Analog is a variable-power scope, a continuous value clamped between MinZoom and MaxZoom that the input layer drives through SetZoom. Stepped is a discrete optic, a list of levels the input layer walks with CycleZoomStep, which wraps around and is a no-op in the other two modes.

ClampZoom on the definition is the single validator: it returns one for None, clamps into the range for Analog, and snaps to the nearest entry in StepLevels for Stepped. Every service setter routes through it, so an out-of-range value from a scroll wheel or a save file cannot produce an illegal zoom.

Archetypes see the result as CrosshairState.Zoom and the built-ins all use it the same way, contracting geometry by its inverse so the aim point gets finer as magnification climbs. ScopeFovDriver consumes the same value from the other side, narrowing the camera FOV to base divided by zoom, but only when the mode is not None, the service reports ADS active, and the resolved zoom is above one.

ICrosshairService.Changed fires only when the active definition, the zoom value or the ADS flag changes. Spread and recoil push through their own setters that update fields without raising the event, because they change every frame and an event per frame would be pure noise.

The view's repaint loop reads those fields directly and bakes them into the per-frame CrosshairState alongside the theme-resolved accent colour. RecoilOffset arrives in screen pixels, already projected by the weapon controller from the camera's angular kick through its focal length, so a recoil gain of one makes the reticle track the real ballistics rather than an invented multiplier.

Swapping definitions resets zoom to the new definition's clamped DefaultZoom. A player going from a scoped rifle to a pistol does not carry the rifle's four-times magnification across the swap.

CrosshairService is a plain POCO with no MonoBehaviour and no scene state, and CrosshairView constructs one in Awake and exposes it through its Service property. Consumers on the player rig resolve the nearest view and drive that instance instead of fetching a global registration, so two split-screen rigs each carry an independent reticle, zoom state and ADS flag.

ScopeFovDriver and ScopeFrameOverlay follow the same rule: they read the sibling view's service rather than a global, and each is a separate MonoBehaviour so a project that wants scope FOV without a procedural reticle can drop just the driver.

The view owns its own UIDocument per the per-widget HUD pattern, pins its sorting order to the crosshair tier, and claims the full-screen HUD slot through the shared registry so it coexists with the map and other full-screen overlays instead of fighting them. ScopeFrameOverlay sits five above the crosshair tier so its eyepiece mask paints over the procedural reticle when both are present.

ResolveActiveReticle is where the hipfire-versus-ADS decision is made, and the view calls it once per repaint. Not aiming returns the hipfire reticle. Aiming with an Ads reticle authored returns that. Aiming with no Ads reticle and HideOnAds set returns null, which means paint nothing and let the scope own the view. Aiming with no Ads reticle and HideOnAds clear returns hipfire with the effective spread scaled by one minus AdsTightenFactor.

With no definition active at all the service returns a built-in assault-rifle reticle as a fallback, so an unconfigured rig shows a usable reticle rather than an empty screen.

ScopeFrameOverlay keys off exactly the same condition. It renders only while ADS is active and the active definition has HideOnAds set, which means the eyepiece vignette and mil-dot ladder appear precisely when the procedural reticle has stepped aside, and a non-scoped weapon never gets scope chrome no matter what the player holds.