opx_infinityneeds
Client
Last updated on
The needs contract on the client — read the needs the server sent, add and remove status chips.
local needs = OPX.Api.Get('needs')From client code inside opx_infinity. Every function answers a Result ({ ok = true, value } or { ok = false, error, detail }). None yields. Codes: Refusal codes.
- The needs are read only here: the client draws what the server sends. To move one, use the server contract (or, from another resource, the server exports
AddNeeds/SetNeeds).SetNeedsandAddNeedsare no longer on the client contract. owneris the caller's own name (1–64 characters of letters, digits,_ : - .). It groups chips and lets the module drop them when the owner stops. Ifownernames a running Open77 resource, its chips are dropped when that resource stops or reloads. A module name inside opx_infinity is never swept this way.
GetNeeds
The values as the server last sent them.
needs.GetNeeds()Returns
Result— value{ values, citizenId, ready = true };valuesis a copy- errors
no_character,not_loaded(detail= the citizen id)
- errors
AddEffect
Adds a chip, or replaces the owner's chip with the same id (start time and countdown restart).
needs.AddEffect(owner, spec)Parameters
- owner:
string - spec:
table— see Effect spec
Returns
Result— value{ id }
local r = needs.AddEffect('mymodule', {
id = 'bleeding', label = 'Bleeding', tone = 'bleed',
priority = 80, durationMs = 30000, event = 'mymodule:bleedEnded',
})
if not r.ok then print(r.error) endUpdateEffect
Patches one of the owner's chips. Absent fields keep their value. Without durationMs the countdown keeps running; with it, it restarts.
needs.UpdateEffect(owner, id, patch)Parameters
- owner:
string - id:
string - patch:
table— any effect spec fields
Returns
Result— valuetrue
needs.UpdateEffect('mymodule', 'bleeding', { tone = 'warn', progress = 0.5 })RemoveEffect
Removes the chip and raises its removed event.
needs.RemoveEffect(owner, id)Parameters
- owner:
string - id:
string
Returns
Result— valuetrue
ClearEffects
Removes every chip of the owner. Raises no event.
needs.ClearEffects(owner)Parameters
- owner:
string
Returns
Result— value{ removed }
Effect spec
The chip format.
| Field | Type | Rule |
|---|---|---|
id | string | Required. 1–64 characters of letters, digits, _ : - .. Unique per owner. |
label | string | Required. Cleaned and cut to 32 characters; empty after cleaning is refused. |
icon | string | Optional. Cut to 2 characters. |
tone | string | Optional. One of ok, warn, bad, accent, bleed, burn, shock, chem. |
priority | number | Optional, default 0. Higher draws first. |
durationMs | number | Optional. 1..3600000. The chip expires on its own after this. |
progress | number | Optional. Clamped to 0..1. |
event | string | Optional. A local event name (max 96 characters) raised when the chip is removed or expires. |
data | table | Optional. Opaque data handed back in the event. At most 64 nodes and 4 levels deep. |
- One owner may hold 24 chips.
- The strip is ordered by
priority(highest first), then newest first. - Only
MAX_VISIBLEchips are published; the rest are counted inhidden.