FlabaNpcFramework

Flaba's NPC Framework

Add quest NPCs to How to Fish by writing a text file.

No modding experience. No Unity. No C#. Drop a JSON file in a folder and there is a new

character standing on an island, with dialogue, a fish they want, and something they give

you when you bring it.

The whole thing, in one file

{

"name": "My first NPC",

"npcs": [

{

"island": 0,

"lines": [ "Nice weather for it." ]

}

]

}

Save that as mynpc.json in BepInEx/plugins/FlabaNpcFramework/packs, start the game,

sail to the first island. That is genuinely all that is required: an island, and one line of

dialogue. Everything else has a sensible default.

What you can build with it

• Real quests. Ask for a specific fish, in a specific quantity, and give out a reward

the game already understands: reveal an island, unlock the grill, unlock the boat, or pay

out money.

• Progress counters. Write ({count}/{total}) in a line and it reads (1/3), then

(2/3) as the player hands things over.

• Coloured text. The dialogue box takes rich text, so

PEAK works.

• Pick their face. Name any NPC in the game and your character is built from that one.

Set their skin colour with a hex code.

• Put them anywhere. Including on scenery built by a different mod, with no dependency

between the two.

Made to be edited, not fought

• Turn on the reload key and press F8 to re-read your files without restarting the game.

Writing dialogue is a hundred small edits, and a restart for each one is miserable.

• Mistakes do not crash you. Misspell an NPC name and the log tells you the real names

and carries on. Point at scenery from a mod that is not installed and your NPC stands on

the ground instead. Break your JSON and the other packs still load.

• Your save stays safe. Quest results use the game's own quest types, so nothing new is

written to your save file. Remove the mod later and your save still loads.

Full documentation is on GitHub

The package page cannot hold a proper field reference, so the real documentation lives here:

You will find:

• The NPC framework guide

Every field, every default, every dialogue stage, the C# API, and a table of every warning

the mod can print and what it means.

• The map framework, for adding islands, terrain and structures. Early days, but the

example island is built entirely with it.

• The full source, MIT licensed. Read it, fork it, take pieces of it.

If you are making something with this and get stuck, open an issue on GitHub. Questions

about what a field does are usually a sign the documentation is unclear, and that is worth

fixing.

Installing

• Install BepInEx 5.4.x (x64, Mono) and run the game once so it creates its folders.
• Drop FlabaNpcFramework into BepInEx/plugins.
• Start the game.

Windows only for now.

Multiplayer: everyone in the lobby needs the same mod and the same packs.

A worked example is included: a hidden trader on the volcano who wants a rare fish and

reveals a new island in return. Delete the pack file if you do not want him in your game.

For mod developers

There is a C# API that does everything the JSON does. Reference the DLL, add

[BepInDependency("com.flaba.npcframework")], and register in Awake:

NpcFramework.Add(new NpcDefinition {

IslandId = 4,

Lines = new { "Yo", "How did you find me?" },

WantedItem = "BingBong",

WantedAmount = 3,

Reward = NpcReward.UnlockIsland,

UnlocksIsland = 6,

});

NPCs registered this way are left alone when packs reload, and adding one does not shift

anything the network cares about.

A note on how this was made

Generative AI (Claude) was used to narrate and document the existing code: the guides, the

commented templates, the in-game log messages, and the explanatory notes throughout the

source.

All of it was tested in-game by a human before release, and anything still unverified is

labelled as such in the documentation rather than quietly presented as working.

Licence

MIT. Build on it, ship mods with it, including commerc