Held model

This page uses Mesh from Unity. The glossary says what each one is.

An item shows in the player’s hand through a model the game attaches to the item’s equipment action. A mod item can borrow another equippable item’s hand model with ItemDefinition.WieldTemplateId (see Registry). A mod can also give any equippable item, from the game or from a mod, its own hand model.

ItemRegistry give an item your hand model

Call SetHeldModel to give an item your hand model. Build the model first with ModelRegistry.LoadObj and pass its handle in. The framework puts your picture into the item’s own hand model, which keeps its positions.

public static class ItemRegistry
{
    public static bool SetHeldModel(string modGuid, int itemId, ModelHandle model);
}
Method Returns What it does
SetHeldModel(modGuid, itemId, model) bool Gives the item your model in the hand. true when it was recorded.

Example

This whole mod loads a model from a file and gives it to the pickaxe (item 10710) once a save has loaded.

using ObenseuerCore;

[ModInfo("example.heldmodel", "Torch Pickaxe", "0.1.0")]
[ModDependency("obenseuer.moddingframework", "0.11.0")]
public sealed class TorchPickaxe : FrameworkMod
{
    protected override void OnLoad()
    {
        Events.WhenReady(() =>
        {
            ModelHandle held = ModelRegistry.LoadObj("example.heldmodel", "pickaxe-held", @"C:\Mods\TorchPickaxe\pickaxe.obj", null, null);
            if (!ItemRegistry.SetHeldModel("example.heldmodel", 10710, held))
            {
                Log.Warn("The hand model was refused, see the limits section of this page");
            }
        });
    }
}

SetHeldModel gives false when the item registry is not available or when another mod already set that item’s hand model, so the example logs a warning. See Limits below.

Things to know

  • The framework uses the item’s own hand model as a template and swaps the picture in it. The first-person and the third-person objects of the template keep their positions. Your model replaces the main shape (the largest one) in each of them, and every other shape in those two objects is hidden. Your model is scaled to fit the template’s longest side. Scale, EulerOffset, PositionOffset and Pivot still apply. (The template is the item’s held model, or its wieldPrefabPath when that is not loaded yet. The mesh replaces the mesh of the largest renderer, and the fit is the same as FitToTemplate does for world models.)
  • The hand model is built once for each item and reused every time the item is equipped. It stays when the item database reloads. Only a new handle from a later SetHeldModel builds it again.
  • SetHeldModel can be called at any time. It returns true when the model is recorded. Before the item database has loaded, the model is used once the items load. After that, it is used at once. (It needs ItemRegistry.IsAvailable.)
  • A copy made with WieldTemplateId is made when the item loads. A later SetHeldModel on the source item does not change that copy.
  • Nothing is saved. The save keeps the item’s template path, which does not change, so no save refers to your model. Without your mod, a game item shows its template model, and a mod item is treated as a missing item. (The save keeps the item’s wieldPrefabPath.)

Limits

  • Pass a model made by ModelRegistry.LoadObj. Any other handle throws an ArgumentException, and null throws an ArgumentNullException. An invalid modGuid, or an itemId below 0, also throws an ArgumentException.
  • You can’t use a hand model that did not come from ModelRegistry.
  • You can’t set a custom animation. The template’s own animation stays as it is.
  • If the model cannot be used, the item keeps the template’s hand model. That happens when the handle is not ready, when the template has no hand item or no shape, or when the model cannot be built. The framework writes one line about it to the log for that item.
  • One mod can set the hand model of an item at a time. If a second mod tries, its call returns false and the log names both mods. The same mod can call again to replace its own model.
  • SetHeldModel returns false when the item registry is not available, or when another mod already set that item’s hand model.