Creating and Activating an Item

Definitions and native activation are separate. The ExampleMod follows this order inside GameDataReady:

var id = ContentId.Parse(mod.Metadata.Id + ":example_blade");
var name = ContentId.Parse(mod.Metadata.Id + ":items.example_blade.name");
var description = ContentId.Parse(mod.Metadata.Id + ":items.example_blade.description");

if (!mod.CustomItems.TryCreateFromTemplate(
        id, "AXE_BANDIT_LIGHT_01", out var draft, out var error) || draft == null)
    throw new InvalidOperationException(error);

if (!mod.Localization.TryRegisterEnglish(name, "Example Blade", out error))
    throw new InvalidOperationException(error);
if (!mod.Localization.TryRegisterEnglish(
        description, "A template-based definition.", out error))
    throw new InvalidOperationException(error);

ItemDefinition definition = draft
    .WithValue(175)
    .WithLocalization(name, description);

if (!mod.CustomItems.TryRegister(definition, out error))
    throw new InvalidOperationException(error);

CustomItemActivationResult result =
    mod.CustomItems.Activate(id, out ICustomItemActivation? activation);

Use TryCreateFromTemplate with a compatible exact native template ID. Creation before game-data readiness produces a deferred recipe; activation can return PendingGameData. After readiness, a missing/unsupported template fails directly.

Retain ICustomItemActivation. Its state, last result, detail, generation, and live-reference count explain whether the definition is active and whether deactivation is safe.

Dependency and cleanup order

Activate referenced custom abilities before the item. On cleanup, release live item leases, deactivate/remove the item, deactivate/remove its abilities, then remove localization. Deactivation returns CannotDeactivateWhileReferenced while a tracked runtime item is live.