0xDocs 0x.limo

Docs / Scripting

Fishing and Environment (0x script v1)

Partly live

The fishing and environment capabilities: the vanilla fishing hook steered by a script, and real water conditions.

#Fishing and Environment (0x script v1)

The vanilla fishing hook is a host primitive: the bite, its timing and the reel stay native (Paper's PlayerFishEvent), and a script steers them and decides what was caught. Capabilities fishing and environment; typings in packages/script/v1/fishing.d.ts.

#Fishing

SignalWhenHook methods that work
Fishing.Cast(hook)the line lands (FISHING)SetWait(minTicks, maxTicks): the vanilla wait before a bite (1..6000)
Fishing.Bite(hook)a fish bites (BITE)HoldOff(): no bite this time, the hook stays in the water for another wait
Fishing.Reel(hook, hadBite)the player reels in (CAUGHT_FISH, REEL_IN, FAILED_ATTEMPT, IN_GROUND, CAUGHT_ENTITY)CancelLoot(): the vanilla catch does not land (the script gives its own)
  • Events reach a sandbox only for hooks inside its granted regions. An event another plugin cancelled (for example FishingGame's own rods) is not delivered, and a throttled sandbox misses it (vanilla plays).
  • Hook methods change that one vanilla event, so they work only while the event is delivered: call them before the handler's first await. Later they throw. Calling one in the wrong stage throws.
  • hook.Rod is the rod in hand as an ItemRef. It is mine (with this experience's tag) only for a sealed item this experience gave, so a creative copy or another plugin's rod is never yours. A vanilla rod should play vanilla: check hook.Rod?.mine first.
  • hook.Depth is the blocks of water under the hook. On Reel after a bite, hook.ReactionMs is the time from the bite to the reel.

#Environment

Environment.GetAsync(position) gives the real conditions at a place from PaperMCP's water and weather services: waterTempC, airTempC, windMs, windFromDeg, waveM, salinity, month, localHour and daylight. A value the world does not know is NaN. Community sandboxes may read only places inside their regions.

#The example game

examples/fishing (x1.json + src/main.ts, about 90 lines) is Lago fishing:

  • /x1 fishing-ada start gives a Lago rod and shows the HUD; stop ends it;
  • inside the lago-pond region a bite shows a BITE! HUD and a splash, and a catch lands as a sealed fish item (species, kg) with a toast and a title;
  • /x1 fishing-ada log opens the catch log panel (tabs: your bag with a quantity on each stack, the last 20 catches) with Sell selected / Sell all;
  • the fishmonger pays SCRIP from the game's funded wallet, never more than one payout's cap, and gives the fish back when the wallet or a cap pays nothing.

Tests: node tests/fishing/js.mjs (the VM side and the example game against a mock host) and the lab e2e.