CustomItemRegistry

BreakoutMods CIR - Custom Item Registry

Part of the BreakoutMods modding suite.

CIR, short for Custom Item Registry, is a Valheim modding API for developers who want to ship custom 3D item prefabs from AssetBundles without rewriting ObjectDB, ZNetScene, recipe, and multiplayer registration glue in every mod.

Repository: BreakoutMods/CIR-CustomItemRegistry

Community: BreakoutMods Discord

Support development: BreakoutMods Patreon

The library is built for BepInEx 5.x, Harmony, and Jotunn. It leans on Jotunn's PrefabManager and ItemManager for multiplayer-safe prefab and recipe registration, while exposing the original small API, the CIR 0.2 raw builder API, CIR 0.3 typed item templates, CIR 0.4 typed recipe helpers, and CIR 0.6 optional YAML/JSON item packs.

Usage

Reference CustomItemRegistry.dll from your mod project and add BepInEx dependencies:

[BepInDependency(CustomItemRegistryPlugin.PluginGuid)]

[BepInDependency(Jotunn.Main.ModGuid)]

Valheim also has a game type named CraftingStation. If your project references Valheim assemblies, add an alias for CIR's enum:

using CIRCraftingStation = ValheimCustomItemRegistry.CraftingStation;

Register a templated item from Awake:

CustomItemRegistry.Item("BM_IronLongsword").FromEmbeddedResource("MyMod.Assets.items", typeof(MyPlugin).Assembly, "BM_IronLongsword").DisplayName("$item_bm_ironlongsword").Description("$item_bm_ironlongsword_desc").Icon("BM_IronLongswordIcon").AsSword(sword => sword.Slash(48f, perLevel: 6f).Block(24f, force: 18f, parry: 2f).Durability(250f, perLevel: 50f).Attack(stamina: 14f, force: 35f).Movement(-0.05f)).Recipe(recipe => recipe.At(CIRCraftingStation.Forge).StationLevel(2).Requires(VanillaItem.FineWood, 4).Requires(VanillaItem.Iron, 10).Requires(VanillaItem.Iron, 0, 8)).Register();

Typed helpers remove most recipe string memorization, but raw prefab strings remain supported:

using static ValheimCustomItemRegistry.ItemRefs;

CustomItemRegistry.Item("BM_MagicBlade").FromBundle(assetBundlePath, "BM_MagicBladePrefab").AsSword(sword => sword.Slash(40f).Spirit(10f)).Recipe(recipe => recipe.At(CIRCraftingStation.Forge).Requires(VanillaItem.Silver, 10).Requires(Modded("com.otherauthor.valheim.magicmod", "MagicCore"), 1)).Register();

You can still use the raw 0.2 builder when you need direct shared-data control:

CustomItemRegistry.Item("BreakoutMaterial").FromBundle(assetBundlePath, "BreakoutMaterialPrefab").Icon("BreakoutMaterialIcon").Gear(gear => gear.Material().StackSize(50)).ConfigureSharedData(shared => shared.m_value = 25).Register();

The original API remains supported:

CustomItemRegistry.RegisterItem(

"MyCrystalSword",

Path.Combine(Path.GetDirectoryName(Info.Location), "myitems"),

"MyCrystalSwordPrefab",

new CraftingRecipe(

new List

{

new Ingredient("FineWood", 8),

new Ingredient("Crystal", 12),

new Ingredient("Silver", 4)

},

"forge",

1));

By default, CIR expects your AssetBundle prefab to already contain the required Valheim item components: ItemDrop, Rigidbody, ZNetView, ZSyncTransform, and a collider. If any are missing, CIR refuses registration and lists the missing components. For simple test items, you can opt into CIR auto-preparation with.PrefabPreparation(...).

YAML/JSON Item Packs

CIR can load raw item definitions from files without making YamlDotNet or Json.NET mandatory. Put item packs in:

BepInEx/config/CustomItemRegistry/packs

CIR scans that folder recursively for.yaml,.yml, and.json on startup. YAML support activates when ValheimModding-YamlDotNet is installed. JSON support activates when ValheimModding-JsonDotNET is installed. CIR does not ship those DLLs inside its own package.

Mods can also load packs from their own folder:

CustomItemRegistry.LoadItemPacksFromDirectory(

Path.Combine(Path.GetDirectoryName(Info.Location), "packs"));

Check optional parser availability with:

ItemPackParserStatus status = CustomItemRegistry.GetItemPackParserStatus();