Skip to content
PEAK Modding Wiki

Custom Items

Project Info
CodingOptional
UnityRequired
Project SetupTime-Consuming
Modding LibrariesPEAKLib.Items

Creating custom items involves structuring and configuring your item assets in Unity and using PEAKLib to register them with the game.

Set Up a Unity Project

Section titled “Set Up a Unity Project”

  1. Rip the game into a Unity project (this is easily the most painful step in the whole process)

  2. Download the latest PEAKLib.UnityReferences package from GitHub

  3. Extract it somewhere in the Assets/ directory of your Unity project

  4. You should not see any errors in your Unity project at this point (and if you do, they should be about file names that only differ in casing, which should only appear if your file system is case-sensitive which is most likely the case if you are on Linux). If you have other errors, you should ask for help or start over and follow the instructions more closely.

We rip the game into a Unity project so that making items is considerably easier as the project comes with a lot of metadata from the game, such as layers, tags and shader names, which we all need to match with how the game expects things to be.

Create an Item

Section titled “Create an Item”

  1. Find some Item prefab in the game and copy paste it somewhere, e.g. Assets/_Mod/

  2. To inform PEAKLib.Items to register your item, right click in files in Unity and select Create → PEAKLib → ItemContent.

  3. In the inspector for ItemContent, set Item Prefab to the prefab you copied

  4. At the very bottom of the inspector for ItemContent, set AssetBundle to your bundle, e.g. myitem.peakbundle, or if you do not have a BepInEx plugin, myitem.autoload_peakbundle.

  5. If you do not have a BepInEx plugin to load your item mod when the game loads, select Create → PEAKLib → ModDefinition and fill the information for your mod, and assign it to the AssetBundle from the previous step.

After you’ve finished the next section to make sure you’ve done everything correctly, you can get to modifying the prefab to be yours.

Register Your Item

Section titled “Register Your Item”

  1. Build your Asset Bundle and place it in BepInEx/plugins/. If you do not have a plugin to load your asset bundle, ensure the file name ends in .autoload_peakbundle, and then you are done! If you have a plugin to load your asset bundle, continue as normal.

  2. In your BepInEx plugin project, open the csproj file and reference PEAKLib.Items

    csproj
    <Project Sdk="Microsoft.NET.Sdk">
      ...
    

      <ItemGroup>
        <PackageReference Include="PEAKModding.PEAKLib.Items" Version="*" />
      </ItemGroup>
    

    </Project>

  3. Add BepInDependency attributes to your plugin and load the bundle in your Awake method

    Plugin.cs
    using BepInEx;
    using BepInEx.Logging;
    using PEAKLib.Core;
    

    namespace MyItemMod;
    

    [BepInAutoPlugin]
    [BepInDependency(ItemsPlugin.Id)] // PEAKLib.Items
    [BepInDependency(CorePlugin.Id)] // PEAKLib.Core, a dependency of PEAKLib.Items
    public partial class Plugin : BaseUnityPlugin
    {
        internal static ManualLogSource Log { get; private set; } = null!;
    

        void Awake()
        {
            Log = Logger;
    

            // Load an asset bundle with the specified the name.
            // It must be within the same directory as the plugin assembly,
            // or within a subdirectory.
            // Note: this is an extension method from PEAKLib.Core.BundleLoader
            this.LoadBundleWithName(
                "myitem.peakbundle",
                peakBundle =>
                {
                    // Register all PEAKLib content in the asset bundle
                    peakBundle.Mod.RegisterContent();
                }
            );
    

            Log.LogInfo($"Plugin {Name} is loaded!");
        }
    }

  4. Build your BepInEx plugin and place it next to your asset bundle in BepInEx/plugins.

  5. Run the game and confirm your bundle was loaded.
    In your BepInEx logs, you should see something like:
    [Info :PEAKLib.Core] Loading bundle at '...\BepInEx\plugins\myitem.peakbundle'...
    and a bit later:
    [Info :PEAKLib.Core] Loaded bundle myitem.peakbundle in 5.1s

  6. If your item should have custom behavior, you can attach your MonoBehaviour scripts once the bundle is loaded:

    this.LoadBundleWithName(
        "myitem.peakbundle",
        peakBundle =>
        {
            // Get item prefab
            var testBallContent = peakBundle.LoadAsset<UnityItemContent>("TestBallContent");
            var testBallPrefab = testBallContent.ItemPrefab;
    

            // Attach custom behavior
            testBallPrefab.AddComponent<TestBall>();
    

            // Attach custom action
            var action = testBallPrefab.AddComponent<Action_TestBallRecolor>();
            action.OnCastFinished = true;
    

            // Register all PEAKLib content in the asset bundle
            peakBundle.Mod.RegisterContent();
        }
    );

    This example is taken from PEAKLib.Tests/Plugin.cs (and slightly modified).