Custom Item Framework

⚠ This mod is still in active development. Bug reports and feature requests are very welcome!

Features

• []Create consumables, head/torso/feet armor, passive enhancements, and utility items[/]

  []Add healing, temporary buffs, and stat bonuses[/]

  []Cure negative status effects on use[/]

  []Give players ammo, currency, or stamps[/]

  []Control loot drop weights globally or per environment[/]

  []Drop items from specific enemy factions[/]

  []Add items to shop inventories - globally or for specific shopkeepers[/]

  []Create custom crafting recipes[/]

  []Use custom PNG artwork for inventory icons[/]

  []Full localization support - translate items into any language inline[/]

  []Third-party mod support - other mods can ship their own items without touching the framework folder[/]

  []Fully data-driven and lightweight - zero impact when not in use[/]

  ---

  Documentation

  Full reference documentation is available at:

  CIF Wiki

  This covers all item keys, attribute lists, loot tables, shop integration, enchantments, crafting, localization, and sound setup.

  ---

  Installation

  • []Install BepInEx 5.x if you have not already[/]

    []Drop the CustomItemFramework folder into BepInEx/plugins/[/]

    []Launch the game once - the framework will create the Items/ folder automatically[/]

    []Add your item folders inside BepInEx/plugins/CustomItemFramework/Items/[/]

    []Launch the game - your items are live immediately[/]

    No further setup is required. The framework patches the game at runtime and leaves no permanent changes.

    ---

    ⚠ Uninstallation - Read Before Removing

    Sulfur's save system stores item IDs directly in your save file. If you remove the framework while any custom item is still in your inventory, stash, or any container in the world, the game will fail to load that save entirely. This is a limitation of how the base game handles unknown item IDs - it is not something the framework can protect against once it is no longer installed.

    How to safely uninstall:

    • []Launch the game with the mod still installed[/]

      []Remove every custom item from your inventory, stash, and any containers you care about[/]

      []Save and exit the game[/]

      []Remove the CustomItemFramework folder from BepInEx/plugins/[/]

      If you already removed it and your save won't load:

      • []Reinstall the framework[/]

        []Load the save - it will work again[/]

        []Remove all custom items from your inventory[/]

        []Save and exit[/]

        []Uninstall the framework cleanly[/]

        ---

        Quick Start

        Create a folder inside BepInEx/plugins/CustomItemFramework/Items/ and add a .txt file:

        id          = MyCoolFood

        display_name = My Cool Food

        slot_type    = Consumable

        flavor      = Found in a dumpster. Probably fine.

        add          = Stat_HealthRegen Flat 5 10

        loot_weight  = 8

        loot_table  = scavenge

        Place an artwork.png in the same folder for the inventory icon. Launch the game - your item will appear in loot drops automatically.

        For the full reference covering all keys, item types, multi-file items, localization, shop integration, loot tables, enchantments, and sound setup, see the documentation.

        ---

        Third-Party Mod Support

        If you are shipping your own items as a separate mod, you do not need to place files inside the CustomItemFramework folder. Create a cif_items/ subfolder inside your own plugin directory:

        BepInEx/plugins/YourMod/cif_items/YourItem/base.txt

        The framework will discover it automatically. No registration, no manifest file, just the folder.

        ---

        Troubleshooting

        If your item does not appear, check BepInEx/LogOutput.log and search for . The framework logs exactly what it found and why something was skipped.

        ---

        Compatibility

        []Requires BepInEx 5.x[/]

        []No known conflicts with other mods[/]

        []Save-compatible while installed - custom items use a stable ID range derived from the item name[/]

        [*]⚠ Not safe to remove while custom items are present in any save - see Uninstallation