needs
Last updated on
The character's gameplay needs (hunger, thirst, stamina, street cred) and the status-effect registry every module adds a chip to.
Holds two things. The character's needs (hunger, thirst, stamina, streetCred by default): the server owns them. It decays them on its own clock while the character is loaded, raises them, stores them per character and sends every change to the player's client, which only draws them. And the status-effect registry: any module can put a chip (a short label with a tone and an optional countdown) on the player's screen. It draws nothing itself; hud draws both. Use it to feed or drain a need, or to show a temporary state such as "Bleeding" or "Well fed".
| Side | both |
| Requires | character (hard) |
| Contract | needs v1 — server (the values), client (read only, and the chips) |
| Config | config/needs.lua (shared) |
| Data | opx77_character_status (one row per character: citizen_id, needs JSON) |
health,armor,isDeadandinLastStandare not needs. They belong to the character and the engine.- A need goes up only through the server contract: an item whose
USE.STATUSis consumed (the inventory adds it after taking the unit), the staff command/opx.needs.set, or the creator exportsAddNeeds/SetNeeds(SERVER.EXPORTS.WRITERS). A client cannot send a value: there is no push event. - The values load when the character module announces the character on the server, without waiting for the client.
- Nothing downs or kills a player whose need reaches
MIN. - A character deleted through
characteralso deletes its needs row (it listens to the privateopx:in:character:deleted).
Configuration
config/needs.lua sets OPX.Config.MODULES.needs. Shared script.
| Key | Default | Effect |
|---|---|---|
enabled | true | false switches the module off. |
ANCHOR | 'bottom-left' | Corner the chip strip sits in. Sent in the strip payload. |
OFFSET | 120 | Pixels above that corner. |
MAX_VISIBLE | 6 | Chips published at once. |
NEEDS | see NEEDS | Every need, with bounds. A key not listed here is refused and never stored. A need added later is served at its DEFAULT to existing characters. |
DECAY_MS | 60000 | Milliseconds between two decay charges, on the server (minimum 1000). Each charge sends the new values to the player, so this is also how often the gauges move. |
AUTOSAVE_MS | 300000 | Milliseconds between two server writes of the held values (minimum 1000). |
PUSH_MS and PUSH_DELTA were removed with the push event; a copy of them in your config is ignored.
NEEDS
Each entry is name = { MIN, MAX, DEFAULT, DECAY_PER_MINUTE? }. A need without DECAY_PER_MINUTE only moves when a caller moves it.
| Need | MIN | MAX | DEFAULT | DECAY_PER_MINUTE |
|---|---|---|---|---|
hunger | 0 | 100 | 100 | 0.20 |
thirst | 0 | 100 | 100 | 0.28 |
stamina | 0 | 100 | 100 | — |
streetCred | 0 | 100000 | 0 | — |
Commands
Refusal codes
Not translated; they are for the calling code.
| Code | Meaning |
|---|---|
no_character | No character is loaded on this client. |
not_loaded | Client: the server has not sent the values yet. Server: no character is loaded on that player, or its row could not be read. |
bad_player | Server: not a positive integer player id. |
spec_must_be_a_table | The spec or patch is not a table. |
unknown_need | A patch key is not in NEEDS. |
invalid_need_value | A patch value is not a finite number. |
empty_patch | The patch names no need. |
invalid_owner | owner is not a valid name. |
missing_id / invalid_id | The effect id is missing or malformed. |
invalid_label | The label is missing or empty after cleaning. |
invalid_event | event is not a valid name. |
invalid_tone | tone is not one of the eight tones. |
invalid_duration | durationMs is not in 1..3600000. |
invalid_data / data_too_large | data is not a table, or is over 64 nodes / 4 levels. |
invalid_progress | progress is not a finite number. |
owner_limit | The owner already holds 24 chips and the id is new. |
not_found | The owner holds no chip with that id. |