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 <color=yellow>PEAK</color> 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:

https://github.com/Lhunna/htf-frameworks

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

1. Install BepInEx 5.4.x (x64, Mono) and run the game once so it creates its folders.
2. Drop FlabaNpcFramework into BepInEx/plugins/.
3. 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 commercially.

This covers the framework only. It does not cover How to Fish or any of its assets, which belong to their developers. No game files are included in this package.