🌊 River

Documentation relating to the spooni_river.

Download Now

1. Installation

spooni_river works only with VORP.

To install spooni_river:

• Download the resource
  • On Github
• Ensure that all requirements are installed
  • spooni_libs
• Drag and drop the resource into your resources folder
  • spooni_river (the folder must stay named exactly this — the server checks it)
• Add this ensure in your server.cfg (after spooni_libs)

    ensure spooni_libs
    ensure spooni_river

• Register the canteen (empty_can), bottle (glassbottle/water) and any wash items in your inventory
• Now you can configure and translate the script as you like
  • config.lua
  • language.lua
• At the end, restart the server

If you have any problems, you can always open a ticket in the Spooni Discord.

2. Usage

Walk up to a river, lake or town water pump to drink, wash yourself, fill a canteen, fill bottles, or pan for gold. Water carries a purity value (rivers are random, pumps are pure, the sea is salted and undrinkable), and the canteen stores a capacity you drink down over time. Every interaction can be driven either by classic prompt buttons or by the spooni_libs interaction system (hold ALT + E), switched with one config option.

3. For developers

Reference

Buttons vs Interactions

The main switch is Config.UseSpooniTarget.

UseSpooniTarget = false, -- classic prompt buttons (default)
                         -- true = spooni_libs interactions (hold ALT + E)

UseSpooniTarget	How you interact near water / a pump
false	Hold the engage key (G by default) to bring up the action prompts, then press the per-action keys (wash / drink / fill / fill bottle / search gold).
true	Hold ALT, the options appear on you, scroll if needed and press E – exactly like the spooni_police interactions. The options shown depend on where you stand (in water vs next to a pump).

Both modes call the same underlying actions, so behaviour (purity, salt check, item requirements, timings) is identical – only the trigger differs. The unused mode creates no background threads at all.

---

How each feature works

Drinking from a river / lake

• Plays the drinking scenario (DrinkScene for males, DrinkSceneFem for females), runs a progress bar for DrinkTime, plays a sound, calls METABOLISM() and fires Spooni-Medic:Client:DrinkWaterRiver.
• Sea water is salted → drinking is blocked with a notification.

Washing

• Works in rivers / lakes and at water pumps (the sea works too – washing has no salt restriction).
• Runs a progress bar for WashTime with the wash animation, then calls WASHFACE() and a few clean-up natives.
• If RequireWashItems is not empty, the server checks you own those items first; otherwise you get a "missing item" notification.
• In button mode the river wash uses WashKey (MOUSE1); the pump wash uses WashPump (E), since MOUSE1/MOUSE2 are the pump fills. In ALT mode it's just an option in the list.

Filling the canteen

• Requires you to own the canteen item (Canteen). The server gives you a fresh canteen with:
  • capacity = CanteenCapacity (stored as durability),
  • purity = random between RiverPureLevel[1] and RiverPureLevel[2] for rivers, or PumpPureLevel for pumps.
• The item description shows Capacity: X / Purity: Y.

Drinking from the canteen (using the item)

• Using the canteen item plays the canteen-drink animation and reduces capacity by RemoveWhenUse each time.
• When capacity hits 0 the empty canteen is replaced and you're told it's empty.
• If the water's purity is at/below RiverPureLevel[2] (i.e. river-grade), it fires the disease event.

Filling bottles

• Asks how many bottles with a keyboard input. Requires that many empty bottles (EmptyBottle), consumes them and gives the same number of full bottles (FullBottle). Time scales with the number of bottles.

Gold panning

• Fires Spooni-GoldPanning:Server:CheckPan for your external gold-panning script (only if Config.GoldPanning = true).

---

Config reference

All options live in config.lua unless noted otherwise.

General & controls

Option	Default	Meaning
Language	"EN"	UI language fallback (RO, EN, DE, IT, FR, ES, PT). spooni_libs overrides it when a language is set there.
UseSpooniTarget	false	Master switch. false = prompt buttons (G + action keys); true = spooni_libs ALT interactions.
GoldPanning	true	Enable the "Search gold" option (needs an external spooni_goldpanning).
UseWaterPumps	true	Enable filling from town water pumps.

Keys

RedM control-action hashes – keep the 0x........ format.

Option	Default	Meaning
PressKey	0x760A9C6F (G)	Engage key in button mode (hold near water/pump to reveal the action prompts). Unused in ALT mode.
WashKey	0x07CE1E61 (MOUSE1)	Wash (button mode).
DrinkKey	0xF84FA74F (MOUSE2)	Drink (button mode).
FillKey	0xCEFD9220 (E)	Fill canteen (button mode).
FillBotKey	0xE30CD707 (R)	Fill bottle (button mode).
SearchGold	0xD9D0E1C0 (SPACE)	Search gold (button mode).
FillCanPump	0xF84FA74F (MOUSE1)	Fill canteen at a pump (button mode).
FillBotPump	0x07CE1E61 (MOUSE2)	Fill bottle at a pump (button mode).
WashPump	0xCEFD9220 (E)	Wash at a pump (button mode). A separate key because MOUSE1/MOUSE2 are taken by the pump fills.

In ALT mode these per-action keys are not used – you select from the interaction list with E.

Water pumps

Option	Default	Meaning
PumpHash	{"p_waterpump01x"}	List of pump prop models to detect. Add more if your map uses other models, e.g. {"p_waterpump01x", "p_waterpump02x"}.

Animations & timings

Option	Meaning
WashAnim	{animDict, animName} played while washing.
DrinkCanteen	{animDict, animName} played when drinking from the canteen item.
DrinkScene	Scenario played when drinking from water (male).
DrinkSceneFem	Scenario played when drinking from water (female).
FillScene	Scenario played when filling from a river.
PumpScene	Scenario played when filling at a pump.
DrinkTime	Progress-bar time (ms) to drink.
FillTime	Progress-bar time (ms) to fill (per bottle when filling bottles).
WashTime	Progress-bar time (ms) to wash.

Items & water

Option	Meaning
CanteenCapacity	Capacity a freshly filled canteen holds (stored as durability).
RemoveWhenUse	Capacity removed each time you drink from the canteen.
Canteen	Canteen item name (default empty_can). Registered as usable automatically.
EmptyBottle	Item required to fill a bottle (default glassbottle).
FullBottle	Item received when a bottle is filled (default water).
RiverPureLevel	{min, max} purity range for water filled from rivers/lakes. Also the threshold for "dirty water" disease on the canteen.
PumpPureLevel	Purity for water filled from a pump (default 100).

Required wash items

RequireWashItems = {
    -- Items the player MUST have to wash. Leave empty {} to require nothing.
    -- Example:
    -- {item = "soap", label = "Soap"},
},

• Leave {} to require nothing (default).
• Add {item = "<inventory_name>", label = "<shown name>"} entries to require items. The player must own all of them to wash; the labels are shown in the "missing item" notification.
• This is a possession check – the items are not consumed.

---

Other editable files

language.lua

• Config.Locales – every UI string for all 7 languages. Edit the strings under your language.
• Config.Text is built automatically from the selected locale (English as fallback), based on the language from spooni_libs or Config.Language. Use Config.Text["key"] in code.

functions.lua

• NOTIFY(text) – how notifications are shown (uses spooni_libs:Notify).
• METABOLISM() – wire your thirst/metabolism script here (called after drinking).
• WASHFACE() – wire your dirt/blood-cleaning script here (called after washing).

c/c.lua

• WashItem / DrinkItem (near the top) – item image names used only as the progress-bar photo (purely cosmetic).

---

Items you need in your inventory

Register these in your inventory database/config:

Item	Role
empty_can (Config.Canteen)	The canteen. Uses metadata durability (capacity) and purity. Registered as a usable item.
glassbottle (Config.EmptyBottle)	Empty bottle, consumed when filling.
water (Config.FullBottle)	Filled water bottle, received when filling.
any items in RequireWashItems	e.g. soap, if you require items to wash.

An empty_can.png image is included in EXTRA/ for the canteen item.

---

External integrations

These events are fired for other resources to hook into:

Event	Direction	When
Spooni-GoldPanning:Server:CheckPan	client → server	You start panning for gold.
Spooni-GoldPanning:Client:CheckAction	server → client	Gold-panning script locks/unlocks river actions while it runs.
Spooni-Medic:Client:DrinkWaterRiver	server/client	You drank river / low-purity water (medic hook).