Templates

Export

Use an Action Template to give a new Character Item the complete, tested action stack from another item. The new item keeps its own identity, slot, models, perspective setup, and prefab choices while reusing the template’s actions and modules.

Choose the right template workflow

Ultimate Character Controller has two separate template workflows:

Workflow Use it for What remains target-specific
Action Template in Item Manager Build a new Character Item from the actions on an existing Character Item Item Definition, Slot ID, Animator Item ID, Character Item settings, models, perspective objects, spawn parents, offsets, Animator Controllers, prefab registration, and loadout
Template Character in Character Manager Copy selected controller components, abilities, item abilities, effects, and Character Items to a new or existing character Target models, perspective choices, Animator Controllers, first-person arms, third-person objects, item slots, and camera

This page focuses on Action Template. Follow Character Templates for the separate Character Manager workflow, including its released Version 3 Copy Items limitation.

Prepare a reliable Action Template

An Action Template is an ordinary, configured Character Item; there is no separate template asset to create.

  1. Finish one source Character Item and verify that it equips, performs every action, completes its animation events or durations, and can be reused after unequip.
  2. Keep only the actions that every destination item should receive. Item Manager copies the whole action list, not selected rows.
  3. Give each action a deliberate ID, Action Name, and module configuration. Use unique module IDs wherever another module or custom code performs an ID lookup.
  4. Identify action-owned helper objects such as muzzle transforms, projectile origins, melee hitboxes, lights, Audio Sources, Attribute Managers, or effect anchors. The destination needs an equivalent object or an intentional shared asset reference.
  5. Save the source prefab before using it as a template. Future source edits do not automatically update items that were already built from it.

Use a small dedicated template when several items share only one action. A Character Item containing unrelated alternate actions will copy all of them.

Build a new item from an Action Template

  1. Open Tools > Opsive > Ultimate Character Controller > Item Manager.
  2. Configure the new item’s Item, Name, Character, Item Definition, Animator Item ID, and supported perspective fields. These values belong to the new item and are not read from the template.
  3. Leave Character empty and enter Slot ID when creating a reusable prefab. Assign an existing scene character and choose its matching first- and third-person Item Parents when building directly into that character’s Item Placement hierarchy.
  4. Under Actions, assign the tested source Character Item to Action Template. The field is empty by default.
  5. Confirm that the displayed action rows match the source. The list is read-only while an Action Template is assigned because the template supplies the complete stack.
  6. Select Build Item. If Reference Resolver opens, resolve its fields before completing the inspection described below.

Item Manager configured to build SuperAssaultRifle with AssaultRifleWeapon assigned as the Action Template and the copied Shootable and Melee rows locked

Choose a reusable prefab or a character-specific item

Target Generated result
Character is empty Item Manager asks where to save the Character Item prefab. Slot ID is entered directly. For a built-in Item Type, Add Item Prefab to Item Definition is enabled by default and adds the saved prefab to that Item Type’s Prefabs list.
Character references an existing scene character Item Manager builds the Character Item for that character and uses its matching Character Item Slots. If the character has the built-in Inventory, Add to Default Loadout initially appears enabled.
The character supports multiple models Prefer a reusable Character Item prefab and test its perspective parents on every model; Item Manager warns against building the item directly onto a multi-model character.

The visible Action Template workflow is a new-item build workflow. Selecting an existing Character Item changes the button to Update Item and hides the build-only template and perspective fields. If an existing item needs a different action stack, duplicate it or build a controlled replacement first. Template application is a one-time replacement, not a merge or live synchronization.

Understand what is copied

Item Manager removes the destination’s action components, sorts the template actions by ID, creates matching built-in action types, and resolves the template’s serialized action data onto them. This includes:

  • action IDs, names, descriptions, States, timing, and other serialized action settings;
  • every action module group, module type, order, ID, enabled state, bindings, and serialized module value; and
  • action-owned perspective reference properties, which Reference Resolver attempts to map to the new item’s hierarchy.

Action Template does not copy:

  • Character Item root settings such as Item Definition, Slot ID, Animator Item ID, equip and unequip triggers, State presets, UI monitoring, or Drop Prefab;
  • First Person or Third Person Perspective Item components, visible models, spawn parents, local offsets, materials, or Animator Controllers;
  • the source item’s Inventory amount, Item Set, default loadout entry, or prefab registration; or
  • custom helper GameObjects that exist only beneath the template and have no equivalent in the destination hierarchy.

Configure those choices on the destination item. This separation allows a rifle and a turret, for example, to share a tested Shootable action without sharing a hand slot, visible model, or Animator Item ID.

Resolve destination references

Reference Resolver tries to replace references into the template with equivalent destination objects. It can map the target root, matching relative child paths, Animator hierarchies, and Humanoid bones. Project assets and prefab references outside the template hierarchy can remain shared.

When a reference cannot be mapped safely, the modal Reference Resolver window lists the action, module group, module, and field path that still points to the template.

Reference Resolver listing five flashlight action fields whose Light and Attribute Manager references still point to children of the template item

For every listed field:

  1. Read the full field path to identify the copied module and perspective value.
  2. Create the required destination helper object when it does not exist, or decide that the optional reference should be None.
  3. Assign the equivalent object from the destination item, character, or perspective hierarchy.
  4. Confirm that the warning stating that the destination is a child of the template item disappears.
  5. Select Close, then inspect the copied action in its normal Inspector.

Object-field changes are applied immediately; there is no separate Apply button. Close does not require every warning to be cleared. Closing while a field still selects a child of the template leaves an unwanted cross-item reference, so resolve or deliberately clear every warning first.

Check the generated result

Before entering Play Mode, select the new Character Item and confirm:

  • its Item Definition, Slot ID, Animator Item ID, first- and third-person objects, and local offsets belong to the destination;
  • its action types, IDs, names, descriptions, module groups, module order, and module IDs match the intended template stack;
  • Use, Reload, Block, or another Item Ability targets the copied Action ID;
  • every projectile origin, hitbox, light, effect, audio, Attribute Manager, and perspective property resolves to the destination or an intentional shared asset;
  • no field references the template scene object or template prefab instance; and
  • the saved prefab appears once in the intended Item Type and Item Set workflow.

Save the destination as a separate prefab. Editing it later does not edit the source template, and editing the source does not propagate to the destination.

Verify in Play Mode

  1. Inspect Inventory and Item Set Manager. Confirm that the destination Item Definition is owned, its Character Item spawns in the intended slot, and its Item Set becomes active.
  2. Equip the item in every supported perspective. Confirm that the destination models and spawn parents are used rather than the template’s hierarchy.
  3. Run every copied action separately. Confirm that the matching Item Ability starts the intended Action ID and that each module reaches its expected runtime state.
  4. Observe projectiles, hits, lights, effects, audio, ammunition, attributes, and animation events. Confirm that helper objects belong to the destination and that no template object becomes active or moves.
  5. Unequip, re-equip, remove, and grant the item again. Confirm that pooled Character Items and module helpers reset correctly.
  6. Check the Console and the action Debug foldout for missing references, blocked modules, and incomplete use or reload events.

Troubleshooting

Symptom Check Fix
Build Item is disabled Check Name, Item Definition, supported perspectives, matching first- and third-person Slot IDs, and whether the template is the same item being edited. Complete the required target fields and choose a different Character Item as the template.
The action rows cannot be edited Check whether Action Template is assigned. This is expected. Clear Action Template to construct the destination action list manually, or edit the source template first and build again.
A copied action starts from the wrong input Compare the copied action IDs with the Use, Reload, Block, or other Item Ability Action ID. Point the ability to the intended copied ID; do not assume every template begins with action ID 0.
A projectile, hitbox, light, or effect uses the template object Inspect Reference Resolver warnings and every perspective-aware module property. Create or select the destination helper and replace the template-child reference before saving.
The action works, but the item is invisible or misplaced Inspect the destination’s perspective objects, layers, spawn parents, and local offsets. Configure the destination perspective setup; Action Template does not copy it.
Custom actions on a destination disappear Check whether an Action Template was applied to an item that already had actions. Restore the prefab from version control or a duplicate, then use a dedicated template containing the complete desired stack. The operation is a replacement, not a merge.
Reference Resolver closes with warnings still visible Reopen the copied action and look for fields that still reference the template. Assign the destination object or None manually. The Close button does not validate completion.
A custom CharacterItemAction becomes a Usable action Check whether the source action is one of the exact built-in types recognized by Item Manager. Do not clone a custom CharacterItemAction subclass with Action Template in released Version 3; add and configure that component through its supported custom workflow.

For runtime equip, animation, perspective, or pooling problems after the copy is structurally correct, continue with Item Troubleshooting.

Developer details

ItemManager.AddTemplateActions removes every existing CharacterItemAction, creates each template action in ID order, initializes matching module groups and module types, then passes the serialized fields to ReferenceResolverWindow.ResolveFields. Because the field copy includes the serialized action and module data, IDs and module settings come from the template even though the newly created components begin with builder defaults.

Reference Resolver keeps shared ScriptableObject, Sprite, Material, AudioClip, and persistent prefab references. For hierarchy objects, it attempts Humanoid-bone, Animator-hierarchy, and relative-path mapping before reporting a conflict. A custom helper object is not cloned merely because a module references it.

Released UCC Version 3.2.0 recognizes the exact built-in Shootable, Melee, Magic, Throwable, Shield, and Usable action classes in Item Manager. Any other CharacterItemAction type falls through to the Usable builder path, so custom action subclasses require their own copy or construction workflow.