Specialist jams, reservations, pulses

Weapon faults internals

An opt-in firearm malfunction service with deliberate faults, specialist repairs under server-owned timed reservations, and finite expanding pulses that disable weapons over an area.

FF_Utils 5 related functions

1. Model

Enabling the service never randomly faults a weapon. A fault is always an explicit application by a pulse or by mission code. Faults follow firearm class on that player's body through reloads and weapon switching — never a dropped weapon changing hands. Launchers are excluded. Native state and names are distinct from the mission's own service, so do not run both on the same player.

// server
[true, createHashMapFromArray [
    ["duration", 10], ["range", 2.5], ["timeout", 30],
    ["traits", ["engineer"]], ["classes", []]
]] call FF_utils_fnc_weaponFaultStart;

[unit] call FF_utils_fnc_weaponFaultApply;          // held rifle or pistol
[unit, true] call FF_utils_fnc_weaponFaultApply;    // rifle and pistol
[unit] call FF_utils_fnc_weaponFaultClear;
[getPosASL _source, serverTime, 500, 50, false] call FF_utils_fnc_weaponFaultPulse;
call FF_utils_fnc_weaponFaultStop;

2. Configuration

Key	Default	Bounds / meaning
`duration`	10	1–300 s repair time
`range`	2.5	0.5–10 m interaction range
`timeout`	30	5–600 s reservation lifetime; raised to at least duration + 5
`traits`	`["engineer"]`	Up to 64 nonempty traits; a true unit trait qualifies a specialist
`classes`	`[]`	Up to 64 exact class names; a specialist matches class OR trait

Both lists empty disables specialist repairs while curator clear keeps working. Supplying configuration through the CBA setting reads the same map from FF_utils_weaponFaultSettings. Restarting a running service updates policy and cancels pending repairs; existing faults stay. Stopping removes native faults and finite pulses.

3. Repair reservation

Begin

weaponFaultBeginRepair checks that specialist and target are alive, on foot, in range and conscious, that the specialist still holds the configured role, and that one repair per target and one per specialist exist. It returns a token.

Hold

The server re-checks active sessions every 0.1 s. Token, firearm, revision, owner and duration must match the private record.

Finish

weaponFaultRepairWeapon completes only for the matching token before the timeout. A new fault, policy update, death, role change, disconnect or invalid physical condition cancels the reservation first.

ACE clients get self and other repair interactions with the ACE progress bar; without ACE a vanilla action and timed notification speak the same protocol. ACE's default-fire interceptor blocks a faulty weapon, and a local FiredMan handler removes projectiles from an already-running burst. Without ACE that fallback can consume a round and play the firing animation. ACE's own jam lists, jam types and clearing are never touched, and ordinary ACE jam clearing does not remove a native fault.

4. Expanding pulse

weaponFaultPulse takes [originASL, startTime, radius, speed, includeVehicles]. It keeps the original square-root progression with a five-metre front margin, applies once per player body, includes vehicle occupants, caps radius at 50 km and duration at ten minutes, allows at most 32 concurrent pulses, and never hits early for a future start time. No names, coordinates or story consequences are built in.

5. State and authority

Fault authority and reservations are private server records; clients receive display snapshots through weaponFaultSync / weaponFaultState with a monotonic revision.
Only the dedicated repair request, curator request, activation, snapshot, progress and feedback functions are network entry points; internal mutators reject remote execution.
Optional FF_Zeus controls apply or clear faults for a targeted player, or for everyone when placed on empty ground. The server authenticates the requesting curator.
Activation is JIP-persistent with monotonic generations; body changes replace local firing handlers and departed bodies lose their repair actions.

6. Failure paths and limits

Verified offline: policy normalisation, fault transitions, pulse front and repair token/timing helpers, including immutable inputs, carried-weapon selection, independent clearing, deduplication, bounds, stale or expired completion and delayed pulse starts. Not verified: independent Utils loading, hosted and dedicated repair races, JIP/reconnect/respawn, ACE interaction paths, bursts and FFV, the vanilla fallback, and cleanup.

Related functions

FF_utils_fnc_weaponFaultStart — Starts or stops the opt-in server-authoritative fault service.
FF_utils_fnc_weaponFaultApply — Explicitly faults a player firearm; both firearms can be selected.
FF_utils_fnc_weaponFaultPulse — Starts a finite server-owned expanding malfunction front in ASL coordinates.
FF_utils_fnc_weaponFaultRepairWeapon — Selects a carried faulty firearm, preferring the held weapon.
FF_utils_fnc_weaponFaultStop — Stops server workers, removes faults and cancels repairs and pulses.

↑ Back to top