Fish Configuration

Define fish species, the water types they live in, and the junk and treasure that share their catch tables.

The fishing roster: which species exist, which water type each lives in, and what non-fish entries share that water’s catch table. A biome opts its water into fishing with a single fishing-water-type key (see Biome Terrain Generation); casting there rolls that water’s table.

A catch table is a weighted pick-one built from every species that lists the water, plus the water’s own extras. It is the same weighted machinery as a loot table, so a cast is a single roll: junk is a weight in the pool, not a separate pass.

File Location

Register the file in your mod’s manifest (mods/<YourMod>/<YourMod>.yaml):

fish-config:

Then create the file it points to, relative to your mod’s folder:

mods/<YourMod>/fish-config.yaml

The file has two optional top-level lists, waters and fish:

waters:
  - name: salt
    extras:
      - item: tangled_kelp
        weight: 25.0
        min-amount: 1
        max-amount: 3
      - item: waterlogged_boot
        weight: 8.0

fish:
  - name: reef_sardine
    waters: [salt]
    rarity: common
    min-size: 8.0
    max-size: 18.0

  - name: tidewarden
    waters: [salt]
    rarity: legendary
    min-size: 150.0
    max-size: 260.0
    shiny: true

The roster is loaded after every mod has registered its content, the same as crafting recipes. That is what lets a species name an item another mod defines — or one auto-registered from a block — and lets your mod add species to a water type another mod declared.

fish — species

Rarity bands

Rarity is a catch-odds label, and never a power level — it says how often a species surfaces, nothing more. (Progression tiers are a separate, unrelated axis; that is why these are called bands.) Each band maps to a default weight:

These are engine constants rather than config so that two mods cannot disagree about what rare means. A species that wants different odds sets weight: instead, keeping the tuning local to that entry.

legendary is meant for a water’s single signature catch — the one worth telling a story about — not merely “very rare”.

Shiny is independent of the band

The shiny roll happens after the species pick and is unrelated to it, so a common fish can come up shiny and a legendary one usually will not. Band and shiny are two separate chases.

waters — water types and their non-fish catches

Each extras entry uses the loot-table entry schema: item (a bare item name, or a full itemstack reference), weight, and either amount or min-amount/max-amount. See Loot Table Configuration for the full entry shape.

You only need a waters entry to give a water non-fish catches, or to declare it before any species names it. A water type referenced only by a species’ waters list works fine on its own.

Junk and treasure are deliberately not part of the fish collection log — they are texture on the cast, not species to complete.

Cross-checks at load

Fishing content is spread across three files, so mistakes are cross-checked once every mod is in. Each is a warning, not a failure, so one mod’s typo can never abort a server:

• A species naming an item no mod defines is dropped, and the log names the species and the missing item.
• A biome declaring a fishing-water-type that no fish config defines is reported by name. This matters because the failure is otherwise invisible — a water with no table behaves exactly like water that was never meant to be fishable.
• Two species granting the same item is reported: a catch of that item can only be attributed to one of them.

Unknown keys are load-time errors as everywhere else in the schema, so a misspelled rarty: fails that entry by name rather than silently taking the default.

Fishing, from the player’s side

Content authored here is reached with a fishing-rod item (see Item Configuration). One press of primary-use means something different depending on how far along the cast is, and the server decides which:

1. Cast at water — a bobber lands if the aimed block is fluid, in range, and its biome declares a fishing-water-type. Nothing appears otherwise.
2. Wait — a randomized few seconds. Pressing again here reels the line back in.
3. The bite — the bobber dips hard. Press within the window to hook it; miss and the bobber simply resets and waits again, so the only cost of a miss is the fish.
4. The fight — rare and legendary catches resist for a few timed pulls before landing. Everything commoner lands on the hook alone, which is what keeps routine casts a single beat.
5. The catch — the item goes to the angler’s inventory, and a banner reports the species, its rolled size, and whether it came up shiny.

The catch also goes into the almanac — the collection log, opened with TOGGLE_ALMANAC (J by default). It lists every species in the roster grouped by water, showing the largest one landed and whether a shiny has been found. Species not yet caught are listed too, as ??? with their rarity band: the gaps are the point of a collection log, so an unfound fish is a thing to go and find rather than an absence. Each player fills their own book, per world save. Junk and treasure never appear in it.

Collection is the whole progression — there is no fishing level, and nothing in the book improves your odds.

Nothing about this is client-side: the wait, the window, the roll and the outcome are all decided by the server, so timings cannot be read ahead or widened.

Testing a catch table

Weights only mean anything in aggregate, so author a water by sampling it. Standing in the water, an operator can run:

/rollcatch 100

which rolls that water’s table the given number of times and reports a tally of what came up — species with their band, size and shiny flag, and non-fish entries marked as such. It grants nothing. If it answers that there is no fishable water, either the block you are standing in is not fluid or its biome declares no fishing-water-type.

Example

A two-water roster where one species spans both:

waters:
  - name: fresh
    extras:
      - item: river_reed
        weight: 20.0
  - name: river

fish:
  - name: silver_perch
    waters: [fresh]
    rarity: common
    min-size: 12.0
    max-size: 30.0

  - name: darting_trout
    # Spans two waters — it joins both tables at the same weight.
    waters: [fresh, river]
    rarity: uncommon
    min-size: 25.0
    max-size: 55.0
    shiny: true

  - name: old_stonejaw
    waters: [river]
    rarity: legendary
    min-size: 90.0
    max-size: 180.0
    shiny: true
    shiny-chance: 0.005

Last updated Aug 13, 2026