On this page

Modding

Mod API reference

Updated 21 November 2026

The reference for mod makers: what a mod folder holds, the data files, and the code API. New to modding? Start with Making mods.

Players install mods on the website (their account's mods sync to every PC they sign in on, see Account mods) or by putting folders in the Mods folder, and switch them on and off on the website or in main menu ▸ Mods. In multiplayer everyone plays with the host's mods: a joining player gets the mods they're missing from the host (after saying yes), keeps their own client-side mods, and goes back to their own mods when they leave.

Where mods go

FolderWhat
<persistent data>/Mods/<any name>/The player's mods (%USERPROFILE%\AppData\LocalLow\Seeds & Circuits\Seeds & Circuits\Mods on Windows, ~/.config/unity3d/Seeds & Circuits/Seeds & Circuits/Mods on Linux). the folder button in the Mods screen opens it
<game folder>/Mods/<any name>/Mods shipped next to the executable (in the editor: Mods next to Assets)
<persistent data>/Mods/.downloaded/<id>-<hash>/Mods downloaded from hosts
<persistent data>/Mods/mods.jsonWhich mods the player turned on or off

The player's own mods start on; downloaded ones start off (they're used in that host's games only, unless the player turns them on). Start the game with -nomods to load no mods at all.

What a mod is

A folder with a mod.json:

{
    "id": "someone.coppertools",
    "name": "Copper Tools",
    "version": "1.0",
    "author": "Someone",
    "side": "both",
    "description": "Copper axe, pickaxe and shovel.",
    "dependencies": ["someone.coremod", "someone.library >= 1.2 < 2.0"]
}

id (letters, digits, . _ -; the folder name if left out) must be unique: two mods with one id can't both be on. Mods load after their dependencies; a mod whose dependency is missing, or there in a version it can't use, stays off and the Mods screen says why ("Needs Core Mod 1.2 or newer (1.0 is installed)"). A dependency is an id, optionally followed by version rules (>=, >, <=, <, =), compared part by part as numbers (1.10 is newer than 1.9). Example: Jam Bread needs Berry Jam ("example.berryjam >= 1.0"). The dependency game is the game itself: "game >= 0.3" (or "game >= 0.3 < 0.5") means the mod needs one of those game versions. On any other version it stays off ("Needs game version 0.3 or newer (this is 0.2.1)."), the account sync doesn't install it, and the website marks it. gameVersion (written by the Mod Kit) is the game version a code mod was built for: the Mods screen and the website note "made for game version X" when that isn't the current version (its code may not work; data mods don't care).

Dependencies the player doesn't have are installed with the mod and belong to it: they don't show in the Mods list or the account's mods, they're on while a mod that needs them is on, and uninstalling the mod uninstalls them (unless another installed mod still needs one; it then belongs to that one). Installing such a mod yourself makes it your own.

Modpacks: a mod with nothing in it but mod.json (plus an icon, pictures or text) and dependencies is a modpack. The website marks it and lists the mods in it under its description; installing it installs them, uninstalling it removes the ones it installed. Example: Example Pack (every example mod).

side says where the mod runs in multiplayer (default both):

SideRuns onIn multiplayerFor
bothHost and every playerEveryone must have it: joiners download it from the hostItems, recipes, shared gameplay (Waypoint Map)
clientWherever the player has itWorks on any host. A host's client-side mods are offered to joiners (ticked by default, they can untick)HUD, UI, compass, cosmetics (Trader Compass)
serverOnly on the hostNever sent to or required from players; a joiner's own server mods are off while joinedAdmin tools, rules (Ban Hammer)

Everything else in the folder is optional, and any mix works:

FileWhat it does
items.jsonAdds items or changes the game's items (below)
recipes.jsonAdds crafting recipes (below)
*.dllCode (below)
Burst/lib_burst_mod.dllThe code's Burst jobs compiled to native code (below; not loaded as an assembly)
images, AssetBundles, anythingUsed by the above (icons, models)

Files and folders starting with . are ignored. The mod's hash (SHA-256 of every file's path and bytes) tells whether two machines have the same mod. A mod may be up to 512 MB. A mod never writes into its own folder (that would change its hash): code mods keep their saved data in Mod.DataFolder.

Items (items.json)

{
    "items": [
        // New item (id prefixed with the mod's name), starting from cooked pork (a food), with the clay pot's model and icon.
        { "id": "myfood.berry_jam", "copy": "cooked_pork", "name": "Berry Jam", "food": 30, "spoilDays": 0,
          "stackSize": 10, "model": "clay_pot" },
        // Same id as a game item: only the fields named here change.
        { "id": "rope", "stackSize": 50 }
    ]
}

// comments and trailing commas are allowed.

Field
idItem id. A game item's id changes that item; a new item's starts with your mod's name (myfood.berry_jam, see below)
copyStart from this item (any id, also another mod's)
modelUse this item's held, drop and place prefabs (and icon, unless icon is given)
name, descriptionShown in the UI
typeTool, Block, Building, Resource, Station, Parts, Clothing
categoryWhere it is listed (crafting tabs, the creative picker, the wiki): Tools, Clothing, Food, Farming, Materials, Building, Furniture, Stations, Vehicles, Other. Default: from type
tierWhen players get to it: 0 found/gathered, 1 Stone, 2 Scrap, 3 Steel, 4 Alloy, 5 Industrial. Lists show lower tiers first (default 0)
stackSize1, 5, 10, 20, 50, 100 or 500 (the game's sizes)
iconicons/jam.png (PNG/JPG in the mod), item:<id> (a game item's icon) or bundle/path:Asset
heldPrefab, dropPrefab, placePrefabbundle/path:Asset Name, from an AssetBundle in the mod
food, poison, keepOnDeath, spoilDays, durabilityAs the Items table
fuel, burnTemperature, burnsInto, burnYieldCampfire fuel
cooksInto, cookTime, byproduct, smeltsInto, smeltTime, smeltTemperatureCooking and smelting
equipSlot (Hat, Top, Bottom, Boots, Backpack), bagSlots, armor, warmthClothing
blockType (normal, roof, glass, mesh: decides the shapes), blockHealth, blockMaterial (bundle/path:Material)Blocks

Prefix new ids. Give everything your mod adds (items, recipes, effects, crops, also from code with AddItem and the like) an id that starts with a short name for your mod and a dot: myfood.berry_jam, not berry_jam. An id the game doesn't have adds a new thing, but if a later game update adds berry_jam too, your entry silently turns into a change to the game's item, and two mods using the same id change each other's. On the website, your item's wiki page then becomes the game's. Ids you use to change the game's own items (rope above) stay as they are.

The game's Items table loads with the world, after the mods. Mod items are rebuilt and put back every time the item list changes, so copy, model and changes to game items work in the world even though those items don't exist in the main menu yet. Turning a mod off puts the game's own item back.

AssetBundles must be built with this game's Unity version (6000.6). Prefabs used as item models are only looks (networked objects: see Network prefabs).

Recipes (recipes.json)

{
    "recipes": [
        { "result": "myfood.berry_jam", "count": 1, "craftTime": 3,
          "ingredients": [ { "item": "blueberry", "count": 5 }, { "item": "clay_pot", "count": 1 } ] }
    ]
}

id (default: the result), result, count, station (e.g. Workbench; empty = by hand), stationTier, craftTime, requiresBlueprint, ingredients. A recipe with a game recipe's id replaces it. Recipes are listed under their result item's category.

Data files (no code)

Besides items.json and recipes.json, a mod without code can bring these (all optional, // comments allowed). Each entry can start from a game one (copy) and change only what it names. Everything goes when the mod is turned off. New entries' ids start with your mod's name, as for items (myfood.sugar_rush).

FileListsFields
effects.jsoneffectsid, copy, name, description, icon (PNG, item:<id>, bundle ref), buff, seconds, maxSeconds, stacking (refresh / extend), healthPerSecond, regenMultiplier, stopsRegen, hungerDrainMultiplier
fooditem, effect, seconds: eating the item gives the effect
crops.jsoncropsid, copy (a game crop: its growth models), name, seed, produce, growMinutes, yield / seeds ([min, max]), regrows, seasons (["Spring", "Summer"]), stages (bundle prefab refs)
trades.jsontradesnpc (otto, margit, viggo, rosa, gunnar, ylva, pell, sabine), item, price, stock, buys (the NPC buys it instead)
dialogue.jsonlinesnpc (empty = every NPC), text: another "Tell me more." line
optionsnpc, text (the player), answer (the NPC)
worldtypes.jsonworldTypesid, name, startsFrom (Island, Archipelago, Highlands, Lakelands), flat, hills, mountains, erosion, lakeSize, caves (times the shape's), mountainShare, land (0..1), rivers, lakes
assets.jsonFrom the mod's AssetBundle ("Bundles/content:Assets/.../X.asset"): materials, biomes, scatter ([{ "set": ref, "biome": "Pine Forest" }]), animals (their stage prefabs are registered as network prefabs), birds, fish, npcTypes, npcs, music, sounds ([{ "set": "Tools/Axe/Chop", "clips": [refs] }])
// trades.json
{ "trades": [ { "npc": "viggo", "item": "sulfur", "price": 6, "stock": 20 } ] }

Worlds and mods

A world's save remembers the mods it was played with (id, name and version; players' own client mods left out). Loading it from Play when one of them is off or another version asks first: their items, blocks and other things may be lost when the world is saved.

Code (*.dll)

The easiest way to make code mods is the Mod Kit: a Unity package with the game's API, so mods are made in Unity with prefabs, models and networked components, and built with one button.

The game uses Mono, so mods can be C# assemblies. Every .dll in the folder is loaded; each non-abstract class deriving from SeedsAndCircuits.Mods.Mod is created once (parameterless constructor) and gets:

MethodWhen
OnLoad()The mod is turned on: at start, in the Mods screen, or when joining a host that has it
OnWorldLoaded()The world is running (host and players)
OnUpdate()Every frame while the mod is on
OnGUI()Unity's immediate-mode GUI (GUI.*): simple screens and overlays (the Waypoint Map draws its map here)
OnWorldUnloaded()Leaving the world
OnUnload()The mod is turned off (or the game quits): undo everything OnLoad did
OnPlayerConnecting(ModConnection)Host: someone asks to join (ClientId, PlayerId, PlayerName, AccountId: their checked website account, null without one). Return a reason to turn them away
OnPlayerJoined(clientId) / OnPlayerLeft(clientId)Host: a player is in (the host itself too) / left
OnSavingWorld()Host: the world is about to be saved; put the latest state in WorldData

Helpers on Mod:

Info, Foldermod.json (id, side, hash...) and the mod's folder
DataFolder<persistent data>/ModData/<id>/ for the mod's own saved files
IsServer, IsClient, IsHost, IsDedicatedServer, LocalClientIdWhere this copy runs in the current game (a dedicated server is a server with no player of its own)
WorldNameThe save this machine hosts (null on players)
AccountIdOf(clientId)Host: the website account a connected player joined with (null for the host, or without accounts)
WorldDataHost: the mod's data in the world save (below)
AddKey(name, keyboard, gamepad)A rebindable key (below)
AddToggle / AddSlider / AddChoiceSettings on Settings ▸ Mods (below)
OnMessage(name, handler)Receive messages this mod sends from other machines (msg.Sender, msg.Data, msg.Text)
SendToServer(name, data)To the host (works on the host too)
SendToClients(name, data) / SendToClient(id, name, data)Host: to every player (the host included) / one player
RegisterNetworkPrefab(name, gameObject), SpawnNetworkPrefab(name, pos, rot)Networked objects (below)
Log, LogWarning, LogError, GetPath, ReadText, LoadTexture, LoadAssetBundle, LoadAsset<T>Logging and the mod's files (textures and bundles are freed with the mod)
Json.ToJson(obj, pretty), Json.FromJson<T>(text)Save/send your own classes as JSON (static, in SeedsAndCircuits.Mods)

Use Json, not Unity's JsonUtility, for classes in a mod: JsonUtility only knows types from assemblies Unity compiled, so a mod's classes silently come out as {}. Json works by reflection: public and [SerializeField] fields, strings, numbers, bools, enums, lists, arrays, string-keyed dictionaries, nested classes, Vector2/3/4, Quaternion, Color.

Messages take byte[] or a string; names are per mod (two mods can both use "sync"). They're reliable and ordered.

Mods may use any public game API (SeedsAndCircuits.*.dll, e.g. ItemCatalog, RecipeCatalog, PlayerSpawn, TownNpc, Compass.CollectMarkers), Unity and Netcode. Static [ConsoleCommand] methods become console commands while the mod is on (outside the console's namespace write [ConsoleCommandAttribute(...)]); commands without Local = true run on the host (for the host, and for players it gave the console with op).

  • Assemblies are loaded from bytes (the files stay unlocked, and two versions of a mod can be loaded in one run). They can't be unloaded: a mod turned off stops getting calls, but its code stays in memory until the game quits.
  • An exception in a mod is logged and shown on its row in the Mods screen; it doesn't stop the game. OnUpdate and OnGUI errors are logged once per mod.
  • Several assemblies in one mod (or a mod depending on another mod's assembly) find each other by name.
  • Prefer the Mod calls over your own MonoBehaviours: classes from DLLs loaded at run time can't always be added as components.

World data (saved with the world)

WorldData is the mod's part of the host's world save: text or any object (as JSON) by key. It's loaded with the world (read it in OnWorldLoaded), saved with it (OnSavingWorld runs just before), and moves, copies and gets deleted with the world. A new world starts empty. Only the host has it: send players what they need.

public override void OnWorldLoaded() { if (IsServer) _stats = WorldData.Get("stats", new Stats()); }
public override void OnSavingWorld() => WorldData.Set("stats", _stats);

Data of mods that are off stays in the save. Things a player keeps for themselves (their own waypoints) go in DataFolder instead.

Game events

SeedsAndCircuits.GameEvents (static events, assembly SeedsAndCircuits.GameEvents) tells mods what happens in the world. All fire on the host only, once per thing:

EventArguments
PlayerDied / PlayerRespawnedplayer GameObject, cause (Damage, Hunger, ...)
FoodEatenplayer, item id
ItemCraftedplayer (null: a station on its own), station id (null: by hand), item id, count
ItemPickedUpplayer, item id, count
BlocksPlaced / BlocksBrokenitem id, block-grid cells
PropPlaceditem id, position, player (or null)
TreeFelledtree kind, position
AnimalKilledanimal, species, killer (player or null)
DayStartedday number (also when sleeping past midnight)
SeasonChangedSpring / Summer / Autumn / Winter

Subscribe in OnLoad, unsubscribe in OnUnload. A handler that throws is logged and doesn't stop the others.

Keys

AddKey("Open Map", "<Keyboard>/m") (optional gamepad binding) returns an InputAction: check WasPressedThisFrame(). Each mod's keys are listed on Settings ▸ Controls as "Waypoint Map: Open Map" and rebound like the game's keys (a player's bindings are kept while the mod is off). They're only on while the game's own Player keys are and the mouse is captured, so not in menus, the inventory or other item windows, the console or while loading.

Screens

A mod that shows its own screen over the game (a map, a menu) sets ScreenOpen = true while it's up: the cursor is freed and the game's controls are off like in its own screens (moving, looking, tools, hotbar keys and mouse wheel, interacting, opening the inventory). Escape, and the keys that close the game's own menus (Inventory and Interact: Tab, E, the gamepad's inventory button, as rebound, and the gamepad's B), call OnCloseScreen() instead of opening the pause menu or the inventory (not while the player types in a text field). ScreenOpen goes back to false then, and when the mod turns off. To match the game's look, build the screen with uGUI: CraftingUIBuilder.WindowLook(go) gives a panel the game's window look, and InventoryUI.Current.style has its font and colours (the Waypoint Map does this).

World map

TerrainWorld.Instance.MapArea(center) is the world's rectangle (or a square around center in a flat world) and RenderMap(area, size, pixels, firstRow, rowCount) draws a top-down map of it into a Color32[] (ground colours, water, hill shading) from the terrain data, so it works for unloaded land and on clients. Burst job: a 512² map is ~20 ms; draw some rows per frame for big maps (the Waypoint Map does 128 rows of 1024 a frame).

Settings

AddToggle(key, label, default), AddSlider(key, label, min, max, default, step) and AddChoice(key, label, options, default) put rows on Settings ▸ Mods (a header per mod), in both the main menu and the pause menu. Read .Value (.Index for a choice) and listen to .Changed. Values are stored per player with the game settings, so they follow the settings screen: changes show at once, Apply keeps them, Back undoes them.

Network prefabs

RegisterNetworkPrefab("beacon", go) in OnLoad (on every machine, so only in both mods) makes a prefab Netcode can spawn; the host calls SpawnNetworkPrefab("beacon", position, rotation) and every player sees it. A GameObject built in code becomes a hidden template (it gets a NetworkObject); an AssetBundle prefab needs a NetworkObject already. The prefab id comes from the mod id and the name, so it's the same everywhere.

Netcode's own components (NetworkTransform, NetworkRigidbody...) work on them. NetworkBehaviours of your own (RPCs and NetworkVariables) need Unity's code generation: they work in mods built with the Mod Kit, not in mods built with dotnet build. Without the kit, sync your own state with messages.

Adding content from code

Everything a Mod adds with these is taken out again by itself when the mod turns off (WhenTurnedOff(action) does the same for your own registrations). Assets (species, biomes, clips, prefabs) come from the mod's AssetBundle (LoadContent<T>) or are made in code. Content everyone has to agree on (items, species, crops, world generation, music) belongs in a both mod, added in OnLoad, so the host and every player have it.

CallAddsGame side
AddItem(ItemDefinition), AddRecipe(CraftingRecipe)Items and recipes from code (items.json / recipes.json are simpler and can change game items)ItemCatalog, RecipeCatalog
AddResearch(ResearchDefinition)A blueprint researchable at the research tableResearchCatalog
AddStatusEffect(StatusEffectDefinition), AddFoodEffect(item, effect, seconds)Buffs and sicknesses; food that gives themStatusEffectBook.AddEffect/AddFoodEffect
AddCrop(CropDefinition)A farm crop (its seed item plants it)FarmingSettings.AddCrop
AddTool(ToolStats), AddArrow(ArrowStats)Make an item a tool or weapon of a kind the game has (axe, pickaxe, spear, bow, rod...)ToolSwing.AddTool/AddArrow
AddAnimal(AnimalSpecies), AddBird(BirdSpecies), AddFish(FishSpecies)Wildlife (register its prefabs with RegisterNetworkPrefab first)Wildlife/Birds/Fishes.AddSpecies
AddNpcType(NpcType), AddNpc(NpcDefinition), AddTrade(character, item, price, stock, sells)Town roles, characters, trade lines (after the character's own, so saved stock still matches)Town.AddType/AddCharacter/AddTrade
AddSounds(set, clips), AddMusic(clip)A new sound set or one of the game's replaced (Resources/Sfx folder names); music tracksSfx.AddClips, Music.AddTrack
AddBiome, AddScatter, AddWorldType, AddTerrainMaterialWorld generation (below)TerrainModding
AddNpcJob, OnNpcSpawned, AddDialogueOption/Opening/Line, AddAnimalBehaviourBehaviour of NPCs and animals (below)Town, Dialogue, AnimalAgent

Anything else is plain Unity code: a mod's MonoBehaviours, its own prefabs (also as placeable items: placePrefab with a component implementing IInteractable / IAttackUse is interacted with like the game's objects), messages, world data and game events make whole new systems.

World generation

Generated worlds are worked out on every machine from the seed, so a mod can change them as long as it does the same everywhere (a both mod) and takes its randomness only from world.seed. In order, while a world starts:

HookWhenChange
OnConfigureWorld(world, ref landscape)Before the map is made (also for previews)ProceduralWorldParams: hill/mountain heights, mountain and land share, erosion, rivers, lakes, lake sizes
OnMapGenerated(world, map)The map is made, nothing has read it yetProceduralMap: Heights (640 × 640, index x + z * 640, cell x, z at map.Origin + (x, z) * map.Cell, metres), Moisture (0..1), Kinds (Land, Sea, LakeCell, RiverCell), Lakes, Sites. Edit in place; the map's hash (desync check) is redone after
OnBiomesGenerated(world, biomes)Climate biomes are placedTerrainBiomePainter: SetCell(x, z, biome) / Paint(center, radius, biome) over 4 m cells, GetCell
OnConfigureGround(world, ref ground)Every world's ground (play mode)TestGeneratorParams: caves (CavesEnabled, CaveDensity, CaveCellSize...), strata, ores, surface noise
  • AddWorldType(id, name, startsFrom, flat) adds a choice to New World ▸ World. The world saves world.type = id; the mod checks it in the hooks. A world of a type whose mod is gone loads as the type's starting shape.
  • AddBiome(TerrainBiomeDefinition) adds a biome after the game's (climate biomes grow where their moisture/height/slope ranges hold; natural ones by noise; any can be painted). AddScatter(TerrainScatterSet, biomeName) adds trees, plants, rocks, pickups and grass to a biome (null: every biome). TerrainModding.FindBiome(name) finds the game's.
  • AddTerrainMaterial(TerrainMaterialDefinition) adds ground a biome, strata layer or ore can be made of: textures of any size (top, and optional sides; albedo, normal, height), tint, tiling, smoothness, hardness, tool tier, drops. When a world starts, the game makes a play-time copy of its material database with the mods' materials after its own, and texture arrays with a slice for each (the game's slices copied on the GPU, the mods' scaled in). Ids follow the game's in mod order, so host and players need the same mods, and digging/building saved with a mod material keeps its id (without the mod it shows as another material).
  • Generated worlds also have outer islands: OnMapGenerated / OnBiomesGenerated run once for each, when it's made (also during play), with that island's seed and size. Its map starts at map.Params.Offset (zero for the start island; the painter's cell (0, 0) is the island's corner).
  • Set things up before the world starts (OnLoad); a running world keeps what it was made with.
  • Code that isn't a mod can use SeedsAndCircuits.Terrain.TerrainModding (the same events and lists) directly.

NPC and animal behaviour

Behaviour runs on the host; everyone sees the result.

  • NPC jobs. AddNpcJob(roleId, npc => new MyJob()) gives every town NPC of a role ("citizen", "shopkeeper"...; null = all) an INpcJob: WantsToWork(npc) is asked every frame, and while it's true Work(npc, deltaTime) runs instead of the NPC's own day (bedtime still sends it home to bed). Return null from the maker to leave an NPC to the game (shopkeepers keep their shop). NPCs already in the world get the job at once. OnNpcSpawned(npc => ...) runs for each NPC as it comes into the world; Town.Agents lists them.
  • What NPCs can do (TownNpc, host): WalkTo(point), StandAt(spot, yaw), Say(text, seconds) (a speech bubble everyone sees), PlayAction(state, seconds, speed) (a state of the character animator's Actions layer: Tool_Chop, Punch_R, Punch_L...), LookAt(point) / StopLooking(), Hold(itemId) (the item's held model in its right hand; null = nothing), SetWorking(bool), HoldForTalk(playerPosition).
  • Dialogue (each player's machine): AddDialogueOption(text, npc => answer, npc => shows) adds a choice to the talk window (the answer replaces the NPC's text; send a message to the host to change the world), AddDialogueOpening(npc => line or null) what NPCs say first, AddDialogueLine(characterId, line) more "Tell me more." lines (null = every NPC).
  • Animals. AddAnimalBehaviour(speciesId, animal => new MyBehaviour()) (null = every species): its Think(animal, now) runs five times a second before the animal thinks itself; return true to decide for it this time (GoTo(point, run), Stop(), LieDown(sleep), FaceTowards(point)), false to let it be. Its own state (Species, IsDead, IsMoving, herd and taming) stays as it is.
  • Generated towns (host; SeedsAndCircuits.Town). TownReputation.Of(town) / Change(town, delta) / TierOfTown(town) (one standing per town key, shared by all players); TownTrade.Quote / Store / Take trade with a town's storehouse the way its shops do (prices follow what it has); TownRequests.All lists its open requests. Talk choices can give their text per NPC (Dialogue.Option.Label). The town catalog and the trade tables (Town Trade/<type>) can't be changed by data mods yet.

Sharing and ownership

A world shares blueprints, towns and the rest (waypoints, visited islands) with everyone, keeps them per player, or per group (SeedsAndCircuits.Inventory.WorldSharing; console world.sharing, a dedicated server's server.json). Everything here runs on the host.

  • Groups (guilds, teams). Set WorldSharing.GroupOf = playerId => groupName or null. Categories set to group share among players with the same group; players in no group keep their own. Call WorldSharing.NotifyGroupsChanged() when someone joins or leaves a group.
  • Towns (SeedsAndCircuits.Town.TownOwnership). A placed banner claims its town for whoever placed it (or their group). OwnerOf(town) / PlacerOf(town) / MayManage(town, playerId); Release(town) makes it nobody's (banners that expire), Transfer(town, playerId) hands it over; Changed tells you when a claim changes.
  • Building rules (SeedsAndCircuits.Building.BuildPermissions). Add((position, playerId) => reason or null) refuses players building, breaking or placing things somewhere (a reason string = refused). PropPlacers.Of(id) says who placed an object.

Changing the game's code (Harmony)

The game ships Harmony (0Harmony.dll, using HarmonyLib;) for changing what the game's own methods do, public or not, when there's no hook for it. Each mod has its own Harmony (id mod.<mod id>):

public sealed class SlowHunger : Mod
{
    public override void OnLoad() => PatchAll();   // every [HarmonyPatch] class in this mod's assembly
}

[HarmonyPatch(typeof(PlayerVitals), "Update")]
static class HungerPatch
{
    static void Prefix(PlayerVitals __instance) { /* runs before the game's method */ }
}
  • PatchAll() applies the mod's [HarmonyPatch] classes; Harmony.Patch(...) patches by hand (prefix, postfix, transpiler, finalizer). Call it once: every Mod class of a mod shares the same Harmony.
  • Everything the mod patched is unpatched when it turns off (after OnUnload), so mods still toggle without a restart.
  • Private members: name them as strings ([HarmonyPatch(typeof(X), "Method")], AccessTools.Method, AccessTools.Field). The Mod Kit's API copies list public members only, but patches run against the real game.
  • Patches break more easily than the API when the game updates (renamed or rewritten methods): prefer hooks and events where they exist. Burst-compiled jobs can't be patched.
  • The Mod Kit and the example projects (Mod.props) reference 0Harmony.dll already.

Fast code (Burst)

Mods can have [BurstCompile] jobs (IJob, IJobFor, IJobParallelFor... with Unity.Mathematics and Unity.Collections) that run as fast as the game's own. Burst compiles a game's code when the game is built, so a mod brings its jobs already compiled: Burst/lib_burst_mod.dll, a native library made by Unity's Burst compiler.

  • Making it: the Mod Kit's Build does it by itself when the mod's code has [BurstCompile]. A mod built with dotnet build and the examples' Mod.props sets <ModBurst>true</ModBurst> in its .csproj (needs Unity 6000.6.3f1 installed; see Burst Bench).
  • Loading it: the game loads it (BurstRuntime.LoadAdditionalLibrary) before the mod's assemblies, on Windows x64 (.so on Linux x64 when the Mod Kit had Linux Build Support). Without it (another platform, or it fails to load, which is logged), the same jobs still work as plain C#, only slower.
  • Turning the mod off and on: a native library can't be unloaded, so it stays loaded until the game quits, like the mod's assemblies; turning the mod on again uses it again.
  • In the game's Unity editor mod jobs run as plain C# (Burst's editor compiler doesn't see assemblies loaded at run time, and logs "not a known Burst entry point" once per job); time them in a built game.
  • Updating a mod while the game runs: jobs are found by name, so the game keeps the first version's Burst library (and a job first run before its library was there stays plain C#): restart the game to run the new version's Burst code.
  • Burst only compiles the mod's own code into the library. Don't call the game's methods from Burst code: the Mod Kit's copies of them are empty, so they'd be compiled empty. Keep Burst code to your own structs, Unity.Mathematics and NativeArray/Unity.Collections.
  • [BurstDiscard] methods only run when the code runs as plain C#: a quick way to check which one ran.
  • The library is part of the mod's hash and counts as code (the Mods screen, joining a host and the trust prompt treat the mod like any code mod).

Shaders and rendering

Mod Kit mods can bring their own shaders (hand-written HLSL or Shader Graph), compute shaders, render passes and post-processing. They go in the content bundle like any asset. Example: Shader Showcase (below).

What the game draws with: URP 17.6 (Unity 6000.6), Forward+, the GPU Resident Drawer, 4 shadow cascades with soft shadows (High), SSAO, light cookies, light layers, exponential-squared fog; Direct3D 12 on Windows, OpenGL Core and Vulkan on Linux. A bundle only holds the shader variants its own project kept, and URP keeps variants by the project's pipeline settings, so the kit's Set Up Project gives the mod project the game's settings (graphics APIs, the game's URP pipeline and renderer values, its SSAO feature, every fog and instancing variant). It runs by itself once (and once more after a kit update that changes it). Then:

  • Materials on the game's shaders (the kit's stand-ins, e.g. SeedsAndCircuits/StylizedLit) and on URP's own shaders (Universal Render Pipeline/Lit...) get the game's copy of the shader when the bundle loads.
  • Shaders of your own draw with the code in your bundle, with every keyword the game turns on.
  • Before kit 1.5 a new project had URP's defaults (Forward, no GPU Resident Drawer, no SSAO) and automatic fog stripping, so a mod's own shaders kept a handful of variants and drew nothing in the game: the GPU Resident Drawer needs their DOTS instancing variants. The default graphics APIs (Direct3D 12 + 11) were already fine. Rebuild such mods after Set Up Project.
  • Keep your own material toggles as shader_feature_local: only the variants your bundle's materials use are kept (a material made in code at runtime can't turn on a variant nobody used). multi_compile keeps them all.

The game's look in your shaders. The kit's ShaderLibrary/ has the game's own shader code (Game/: stylized lighting, snow, seasons, foliage wind, sky; exported with each kit, so rebuild mods with a new kit) and includes for mods:

#include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl"
#include "Packages/com.seedsandcircuits.modkit/ShaderLibrary/SeedsAndCircuits.hlsl"   // in the UniversalForward pass

StylizedSurface s = StylizedSurfaceDefault(albedo, normalWS);   // gloss, specTint, occlusion, rim, emission
half3 color = SnC_Light(s, positionWS, GetNormalizedScreenSpaceUV(positionCS), fogFactor);   // lit + fog, as StylizedLit
Include / function
SnC_Light, SnC_InputData, StylizedFragmentThe game's lighting: soft wrapped sun and moon with shadows, lamps and torches with the game's falloff, glowing things (fake lights), sky ambient, darker rooms, light haze in caves; plus fog
SnC_Snow(positionWS, normalWS, cover, foot), SnowColour, SnowShare, GroundSnowShareWinter snow on upward faces under the open sky and heaped around the object's foot (roofs and caves stay clear)
SnC_Wetness, SnC_ApplyWetness (Weather.hlsl)Rain: wet, darker, glossier faces under the open sky
SeasonFoliageTint, SeasonGrassColour, SeasonLeafKeepLeaves and grass through the year, falling leaves
FoliageWindMoveThe game's wind (vertex colours as its trees: R trunk, G branch, B phase, A flutter)
PostProcess.hlsl: SnC_Image, SnC_DepthFor post-process shaders (Mod.AddPostProcess)

Copy the forward pass's #pragma block from the example's GlowCrystal.shader (it is the game's StylizedLit's), and give the shader ShadowCaster, DepthOnly and DepthNormals passes (SSAO and the depth prepass need them).

Shader Graph: ShaderLibrary/ShaderGraph/ has sub-graphs: S&C Stylized Lighting (Albedo, Normal, Gloss, Metallic, Occlusion, Rim, Emission → Color), S&C Snow, S&C Wetness, S&C Weather (rain, wetness, snow, ice, season), S&C Foliage Wind (→ Vertex Position), S&C Season Leaves, S&C Season Grass. For the game's lighting use an Unlit graph with Graph Settings ▸ Keep Lighting Variants ticked and plug S&C Stylized Lighting into Base Color (in a Lit graph URP does its own lighting). The same functions are Custom Function nodes in SeedsAndCircuitsNodes.hlsl.

What the game sets for every shader (all 0 in the menus and in your editor, where there is no sky):

Global
_SkySystemOn1 while the sky runs
_WeatherRain, _WeatherWetnessRain now / how wet open ground is (0..1)
_SnowAmount, _IceAmountSnow cover / frozen water (0..1)
_SeasonFoliage (xyzw), _SeasonGrassSpring freshness, autumn colour, winter, leaf fall (0..1)
_SeasonNoFruit, _SeasonFruitYear1 out of fruit season / seasons since spring + 1
_FoliageWindxyz = wind direction × strength, w = 1 while the game drives it
_RainOcclusion, _RainOcclusionRectShelter map round the camera (r = highest surface, g = water height); SkyOpenAt reads it
_SnowTracks, _SnowTracksRectFootprints in snow
_SkyZenithColor, _SkyHorizonColor, _SkyGroundColor, _SkySunDir, _SkyMoonDir, _SkySunColor, _SkyMoonColor, _SkyParams, _SkyFogThe sky's colours and lights (Game/SkyCommon.hlsl)
_FakeLightPosition/Color/Count, _LightFogPosition/Color/Count/DensityGlowing things and light haze (used by the lighting)
_IndoorVolume, _IndoorVolumeMin, _IndoorVolumeInvSize, _IndoorAmbientHow far inside a room a point is (used by the lighting)
_UndergroundAmbient, _UndergroundAmbientScaleSky light underground
_TerrainAlbedoArray, _TerrainNormalArray, _TerrainMatA..D, _TerrainHasTexturesThe terrain's textures and per-material numbers

Keywords: the game turns on none of its own; URP's are the usual ones for the settings above (_MAIN_LIGHT_SHADOWS_CASCADE, _ADDITIONAL_LIGHTS, _ADDITIONAL_LIGHT_SHADOWS, _SHADOWS_SOFT_HIGH, _CLUSTER_LIGHT_LOOP, _SCREEN_SPACE_OCCLUSION, _LIGHT_COOKIES, _LIGHT_LAYERS, FOG_EXP2, DOTS_INSTANCING_ON).

Render passes and post-processing (the mod's assembly definition needs Unity.RenderPipelines.Core.Runtime and Unity.RenderPipelines.Universal.Runtime; New Mod adds them):

AddRenderPass(new MyPass(), RenderPassEvent.AfterRenderingOpaques);   // your ScriptableRenderPass (RecordRenderGraph)
ScriptableRenderPass grade = AddPostProcess(material);               // the image drawn through the material
RemoveRenderPass(grade);
  • The pass goes into every game camera's renderer each frame (the player's view and other cameras drawing to the screen, not the character preview, map or icon cameras); pass a Func<Camera, bool> to pick cameras yourself.
  • AddPostProcess runs before the game's bloom, colour grading and tone mapping by default (AfterRenderingPostProcessing draws over the final image). Its shader reads the image as _BlitTexture (PostProcess.hlsl). Change the material's properties whenever you like.
  • Both are taken out when the mod turns off. A mod can't add a ScriptableRendererFeature to the game's renderer.

Compute shaders load from the bundle like any asset (LoadContent<ComputeShader>("Assets/.../X.compute")) and are compiled for the game's graphics APIs (Set Up Project). Dispatch them in OnUpdate (or from a render pass), write into a RenderTexture with enableRandomWrite, share results with Shader.SetGlobalTexture, and release what you made in OnUnload. Check SystemInfo.supportsComputeShaders first.

Examples

ModSideShows
Berry Jamboth (data)items.json (new item copying another, changing a game item), recipes.json
Jam Breadboth (data)A dependency: needs Berry Jam ("dependencies": ["example.berryjam >= 1.0"]) and uses its berry_jam in a recipe. Installing it from the website installs Berry Jam too
Hello ModbothLifecycle, console commands, OnPlayerJoined greeting, ping/pong messages, a network prefab (hello.beacon), game events counted into world data (hello.stats)
Waypoint MapbothM (rebindable) opens a map of the whole world in a game-styled window (uGUI built in code with CraftingUIBuilder.WindowLook and the inventory's font and colours), drawn from the terrain data (TerrainWorld.RenderMap) right after the world loads, plus a sharp redraw of the part in view; centred on you (arrow = where you look). Drag: pan. Scroll: zoom. Space: back to you. Click: private waypoint (saved on your machine per world). Shift+click: shared waypoint (kept in the world save, WorldData, and sent to everyone). Right-click: remove. Waypoints show on the compass. Settings: waypoints on the compass, map size. Console waypoint.add <name> [shared], waypoint.remove, waypoint.list
Trader CompassclientWandering traders show on the compass as gold diamonds (range on Settings ▸ Mods, default 300 m). Console traders
Volcano IslandbothWorld generation: a world type (New World ▸ World ▸ Volcano Island) whose island gets a volcano with a crater lake (OnMapGenerated), ash fields (a biome and a terrain material made in code, AddBiome, AddTerrainMaterial, OnBiomesGenerated), lower hills elsewhere (OnConfigureWorld) and more caves (OnConfigureGround); Viggo sells sulfur (AddTrade)
Town LifebothBehaviour: NPCs carry a lantern about in the evening (AddNpcJob, Say, Hold), tell you about animals nearby (AddDialogueOption) and a line of gossip (AddDialogueLine); pigs follow anyone holding a carrot (AddAnimalBehaviour)
Example Pack(modpack)Only a mod.json with every example mod in dependencies: one install for all of them
Burst BenchclientA [BurstCompile] job compiled to Burst/lib_burst_mod.dll (<ModBurst>true</ModBurst>). On load and with burst.bench in the console it times the job against the same loop as plain C# and says whether Burst ran it
Shader ShowcaseclientMod Kit project files (Code/, Content/; New Mod "Shader Showcase", then copy them in). Three crystals: a hand-written shader with the game's lighting, snow, rain and wind (ShaderLibrary/SeedsAndCircuits.hlsl), the game's own StylizedLit to compare, and a Shader Graph made of the kit's S&C sub-graphs. A compute shader draws the crystals' glowing ripples every frame; a warm colour grade with frost at the screen's edges in snow is a post-process (AddPostProcess). Console showcase, showcase.grade
Ban Hammerserverban <player name or clientId> [reason] kicks and keeps a player out (OnPlayerConnecting), unban <name or id>, bans. Bans are per host machine, by website account (checked by the host: the ban holds in every world and on every PC); without an account, by player id

Each one is on the website's Mods page (tagged example) to install, and its source is on the wiki (Example mods).

Mods screen

Main menu ▸ Mods: the player's installed mods with a search box. Each has a switch to turn it on or off (at once, no restart; turning one on also turns on the installed mods it needs). The button is Update (the website has a newer version), Uninstall (click twice) or Delete for a copy downloaded from a host. Problems (bad mod.json, missing dependency, duplicate id, load errors) show in red under the mod. Mods the website doesn't have are marked local; their page is built from mod.json (and icon.png in the mod folder, if there is one).

Turning on a code mod that isn't a reviewed version from the website (made or edited by hand, or from a host, so its files match no approved version there) asks first, with a strong warning. The answer is remembered for that exact build: changing its files asks again (ModTrust).

Clicking a mod opens its page: description, Needs (each dependency, its versions and whether it's installed) and Needed by (installed mods that need it); Website opens its page on the site. Browse mods opens the website: mods are found, installed, rated and reviewed there. The folder button next to the title opens the Mods folder. The installed list is read again each time the screen opens.

Account mods

The signed-in account keeps one mod list (GameAccount.Mods.cs, website table gameMods): every PC signed in to the account installs, updates, uninstalls and turns mods on or off to match it, and the website's mod pages change it (Add to game, the on/off switch, Update, Uninstall). A sync runs after sign-in, when the player changes mods, when the game window gets focus and every minute in the main menu (never in a world). It merges the account's list with the PC's mods against the list of the last sync: a change on one side wins over the unchanged side, and the account's wins when both changed. A copy the player changed by hand (its hash isn't the website's for that version) is never replaced. Mods the website doesn't have stay on the list for the PCs that have them. Mods downloaded from hosts are left out.

Wiki pages

Published mods get wiki pages on the website: every item, recipe, status effect and crop the mod adds links to and from the game's own pages, and game items the mod changes list the change. Data files (items.json, recipes.json, effects.json, crops.json and their icons) are read when the zip is uploaded. What code adds (AddItem, AddRecipe, AddStatusEffect, AddFoodEffect, AddCrop) is sent by the author's own game: play with the mod turned on while signed in, with exactly the build you uploaded (same files), and the game sends it (ModCapture). Content registered some other way doesn't show up.

Multiplayer

When a player joins a host:

  • They must run the same both mods as the host (same files). Missing ones are offered for download from the host, and a mod's code is marked so players know it runs code. Code mods whose files aren't an approved version on the mod website are marked not reviewed, with a strong warning (the game asks the website while the prompt is open).
  • The host's client mods are offered too, ticked by default; the player can untick them.
  • The host's server mods are never sent or compared, and the player's own client mods always stay on.
  • A different build of the game can't join ("You have a different version of the game than the host.").
  • Any running mod on the host can turn a player away with a reason (OnPlayerConnecting); the player sees the reason.
  • Leaving the game brings back the player's own mods.

Console

Command
modsInstalled mods: on/off, version, hash, code/downloaded, problems
mods.activeThe mods running now, in load order
mods.declined [clear]Hosts' client-side mods you turned down; clear has hosts offer them again