AI Agent Guide

Universal Player Combat ships a guide for the AI coding agent you already use, such as Claude Code, Codex or Cursor: hand it over with the editor open, and it builds a player from your mesh and animations.

• Adding the UPC Hit Stop node, followed by Inertialization, to an Animation Blueprint you already had (without it, hits land with no frozen pose).
• Reach animations for drawing and putting away an item on a custom skeleton; until you have them, the item has no Stowable fragment and disappears when put away.

How the agent reaches the editor

What it asks you

1. The mesh: your Skeletal Mesh.
2. The animations: a folder or a list. It sorts them by name into light attacks in combo order, a heavy attack, a dodge, hit reactions, idle and locomotion, and asks when the order of the light combo is unclear.
3. An Animation Blueprint for that skeleton with a DefaultSlot Slot node. With none, it makes one from the plugin's locomotion template.
4. A weapon mesh, if the player holds one. Without one, the player fights with its hands.
5. The folder and name: /Game/Player/ unless you say otherwise.

What it changes outside your folder

• Blade sockets on your weapon mesh.
• The open level's GameMode Override, set to the character's game mode (the report names the level).
• With your OK, on first use: one line naming the guide in your project's CLAUDE.md and AGENTS.md, and for Claude Code a copy of the upc-agent skill in .claude/skills.
• With your OK, to reach the editor: the .uproject plugin entries and config lines for the Python bridge, or for Epic's Unreal MCP those entries plus the MCP client entry (.mcp.json for Claude Code), each followed by an editor restart.

What to ask it

What ships with the plugin

Universal Player Combat: guide for AI agents

For the customer (an agent reading this file skips this block): an AI agent may not find this file on its own. Fab installs the plugin under the engine's Engine/Plugins/Marketplace/ folder. Tell the agent "Read Resources/AGENTS.md in the UniversalPlayerCombat plugin folder before you start". The same text is at https://rigbak.com/docs/universal-player-combat/agents. On first use, the agent offers to point the project at this file, so later sessions find it on their own.

One-time setup in a project

1. Find the plugin folder, the one holding UniversalPlayerCombat.uplugin: Plugins/UniversalPlayerCombat in the project folder, or, when Fab installed the plugin into the engine, a folder under Engine/Plugins/Marketplace/ in the engine folder ("The Python bridge" below, step 1, finds the engine folder).
2. Point the project at this guide. Add this line to CLAUDE.md and to AGENTS.md in the project folder, making a file that is missing, with the plugin folder written out (relative to the project folder when the plugin is inside it): For Universal Player Combat, read <plugin folder>/Resources/AGENTS.md before building anything with it. Claude Code reads CLAUDE.md; Codex and Cursor read AGENTS.md.
3. Claude Code only: the /upc-agent command. Copy the folder <plugin folder>/Resources/AgentSkills/upc-agent into the project's .claude/skills/ folder. Typing /upc-agent in a later session then starts it on this guide.

Connecting to the editor

The Python bridge (UE 5.6, 5.7 and 5.8)

1. Read the project's .uproject. EngineAssociation is the engine version. For a version such as 5.7, the engine folder is the InstallLocation of the UE_5.7 entry in the launcher's LauncherInstalled.dat (JSON text despite its extension, so search it as text when a file reader refuses it): C:/ProgramData/Epic/UnrealEngineLauncher/LauncherInstalled.dat on Windows, usually naming C:/Program Files/Epic Games/UE_5.7, and ~/Library/Application Support/Epic/UnrealEngineLauncher/LauncherInstalled.dat on a Mac. A source-built engine, and every engine on Linux, which has no launcher, is an identifier in EngineAssociation that UnrealEngine/Install.ini lists under [Installations] with its folder, in ~/.config/Epic/ on Linux and ~/Library/Application Support/Epic/ on a Mac; on Windows the registry key HKEY_CURRENT_USER\Software\Epic Games\Unreal Engine\Builds lists it. When none of these names the folder, ask the customer.
2. Check the connection:

   "<engine folder>/Engine/Binaries/ThirdParty/Python3/Win64/python.exe" "<plugin>/Resources/AgentBridge/run_in_editor.py" --project "<path to the .uproject>" -c "import unreal; print(unreal.SystemLibrary.get_engine_version())"
   

   It prints the engine version when it is connected. On a Mac the engine's Python is Engine/Binaries/ThirdParty/Python3/Mac/bin/python3, on Linux Engine/Binaries/ThirdParty/Python3/Linux/bin/python3. In PowerShell, put & and a space before the quoted python.exe path.
3. Exit code 2 means no editor answered. If the editor is closed, ask the customer to open the project. If it is open, the project needs a one-time setup. The bridge runs on Epic's Python Editor Script Plugin, which the engine marks Beta and UPC itself does not need, so make these two edits only with the customer's OK, then ask them to restart the editor:
   • In the .uproject's Plugins list: { "Name": "PythonScriptPlugin", "Enabled": true }.
   • In Config/DefaultEngine.ini:

     [/Script/PythonScriptPlugin.PythonScriptPluginSettings]
     bRemoteExecution=True

• Names a run defines stay defined in the editor until it restarts. Run the setup block in "Driving the editor with Python" once per editor session, and again after a restart or a NameError.
• The editor does nothing else while a run is going. Never wait or sleep inside the Python; start Play in one run and inspect it in the next.

Epic's Unreal MCP (UE 5.8)

• In the .uproject's Plugins list: { "Name": "ModelContextProtocol", "Enabled": true } and { "Name": "AllToolsets", "Enabled": true }.
• In Config/DefaultEditorPerProjectUserSettings.ini, so the server starts with the editor:

  [/Script/ModelContextProtocolEngine.ModelContextProtocolSettings]
  bAutoStartServer=True

• The client entry, for Claude Code .mcp.json in the project root: { "mcpServers": { "unreal-mcp": { "type": "http", "url": "http://127.0.0.1:8000/mcp" } } }. Cursor reads the same shape from .cursor/mcp.json; Codex reads [mcp_servers.unreal-mcp] with url = "http://127.0.0.1:8000/mcp" from .codex/config.toml.

The plugin's agent tools

Before you start: ask the customer

reg = unreal.AssetRegistryHelpers.get_asset_registry()
players = [str(a.package_name) for a in reg.get_assets_by_path("/Game", recursive=True)
           if (a.get_tag_value("NativeParentClass") or "").endswith(".UPCCharacterBase'")]
print(players)

1. The mesh. The Skeletal Mesh asset path. Read its Skeleton from the mesh.
2. The animations. A folder or a list. Sort them by name into light attacks (in combo order), heavy attack, dodge, hit reactions, idle and locomotion. Ask when the order of the light combo is unclear.
3. An Animation Blueprint for that skeleton, with a Slot node named DefaultSlot in its AnimGraph. If the customer has none, make one from the plugin's template ("No Animation Blueprint" below).
4. A weapon mesh, if the player holds one. Without one, the player fights with its hands.
5. The folder and name. Default: /Game/Player/, with <Name> a short PascalCase name such as Knight.

Rules

• Create everything in the customer's folder. Do not edit or save anything under /UniversalPlayerCombat/; duplicate a plugin asset into the customer's folder when you need to change it.
• Level steps work in the level open in the editor. If that level is the plugin's own (its path starts with /UniversalPlayerCombat/), ask the customer which of their levels to use, or make one in their folder.
• Name assets <Prefix>_<Name>_<Purpose>: BP_Knight, GM_Knight, ABP_Knight, AM_Knight_Light1, AG_Knight_Unarmed, Item_Knight_Unarmed, Item_Knight_Sword, IMC_Knight_Unarmed, Damage_Knight_Light.
• Save each asset as soon as you finish it.
• Check each step as described before you move on.
• Use the exact property names in this file. set_editor_property accepts the C++ name (HeldMesh, bIsMainWeapon) as well as the Python name. Several editor labels differ from the property: the Visuals fragment's Mesh is HeldMesh, a transition's Fires On is its trigger, When No Window Is Authored is ChainWithoutWindow, Main Weapon is bIsMainWeapon.
• In Python, a C++ type drops its U, A, F or E prefix: UUPCItemDefinition is unreal.UPCItemDefinition, FUPCTraceSocket is unreal.UPCTraceSocket. Enum values are upper snake case: EUPCTraceShape::CapsuleTwoPoint is unreal.UPCTraceShape.CAPSULE_TWO_POINT. The engine's animation functions are unreal.AnimationLibrary.
• An input tag on an item mapping and on a graph transition must match exactly. A parent tag does not count.
• Make montages only from animations on the character's own skeleton, the one its mesh names. An animation of another skeleton plays with that skeleton's proportions, or not at all, and nothing warns. When one does not match, ask the customer for the mesh's own animation or a retargeted copy.
• Give unreal.new_object the asset that will hold the object as its outer, never a class default object (unreal.get_default_object(...), defaults(...)), not even to look at a class's properties: a later object of that class with the same name takes it as its template, and the asset holding that object fails to save.

Driving the editor with Python

import unreal
import upc_agent_tools as upc
EAL = unreal.EditorAssetLibrary
TOOLS = unreal.AssetToolsHelpers.get_asset_tools()
DEMO = "/UniversalPlayerCombat/Demo"
 
def load(path):
    obj = EAL.load_asset(path)
    if obj is None:
        raise RuntimeError(f"No asset at {path}")
    return obj
 
def new_data_asset(cls, folder, name):
    factory = unreal.DataAssetFactory()
    factory.set_editor_property("DataAssetClass", cls)
    return TOOLS.create_asset(name, folder, cls, factory)
 
def duplicate(source_path, folder, name):
    return EAL.duplicate_asset(source_path, f"{folder}/{name}")
 
def defaults(bp):
    return unreal.get_default_object(bp.generated_class())
 
def tag(name):
    t = unreal.GameplayTag()
    t.import_text(name)
    return t
 
def tags(*names):
    return unreal.GameplayTagLibrary.make_gameplay_tag_container_from_array([tag(n) for n in names])
 
def length(anim):
    return unreal.AnimationLibrary.get_sequence_length(anim)
 
def save(*assets):
    for a in assets:
        if not EAL.save_loaded_asset(a, False):
            raise RuntimeError(f"{a.get_path_name()} did not save; log_warnings('EditorErrors') says why")
 
def log_warnings(prefix="LogUPC"):
    name = unreal.Paths.get_base_filename(unreal.Paths.get_project_file_path())
    path = unreal.Paths.project_log_dir() + name + ".log"
    with open(path, encoding="utf-8", errors="ignore") as f:
        return [l.strip() for l in f if prefix in l and ("Warning" in l or "Error" in l)]

Driving the editor without Python (Epic Unreal MCP, UE 5.8)

• An asset is its object path: the package path, a dot, and the asset name again, as in /Game/Player/AM_Knight_Light1.AM_Knight_Light1. The package path alone is refused.
• A class is /Script/<Module>.<Name>, the C++ name without its first letter. The classes this guide uses are in these modules: UPCCore (damage configs, trace sockets, the melee trace, state tag and anim effect windows, the gameplay event notify), UPCMotion (the approach window), UPCActions (action graphs, the action window, transitions, input mappings, ability sets), UPCEquipment (item definitions and their fragments, hold places, the inventory, the equipment manager, the equip commit notify), UPCTargeting (targetable, combat styles, targeting configs), UPCFoundation (telegraph marker windows, the movement component) and UPCGame (the character base). For example /Script/UPCActions.UPCActionWindowNotifyState and /Script/UPCEquipment.UPCItemDefinition.
• An instanced object (an item fragment, a payload) is made by giving its class path as a plain string: {"Fragments": ["/Script/UPCEquipment.UPCItemFragment_Visuals", "/Script/UPCEquipment.UPCItemFragment_Equippable"]}. Properties written beside the class path are dropped. Read the owner back with ObjectTools.get_properties, which gives each new object's path (.../Item_Knight_Sword.Item_Knight_Sword:UPCItemFragment_Visuals_0), and set its own properties on that path.
• An array changes one way per ObjectTools.set_properties call: elements added or removed while every other element stays exactly as get_properties returned it, or elements changed at the same length. Keep an existing instanced element as {"refPath": "<its path>"}. A call refused as ambiguous does both at once; split it in two.
• Log lines come from LogsToolset.GetLogEntries, which requires pattern, a regular expression, and reads only its own category unless category is empty: {"category": "", "pattern": "LogUPC[A-Za-z]*: (Warning|Error)"}.

Recipe 1: a playable character from the customer's mesh

F = "/Game/Player"                 # the customer's folder
N = "Knight"                       # the player's name
mesh = load("/Game/.../SKM_Knight")
abp = load("/Game/.../ABP_Knight") # the customer's Animation Blueprint, or the one "No Animation Blueprint" makes
probe = load("/Game/.../Attack_01")  # any animation on this skeleton, for bone checks

Step 1. Check the skeleton

for bone in ("hand_r", "hand_l"):
    print(bone, unreal.AnimationLibrary.does_bone_name_exist(probe, bone))

Step 2. Make the character Blueprint

bp = duplicate(f"{DEMO}/Characters/Player/BP_UPC_Character", F, f"BP_{N}")
abilities = duplicate(f"{DEMO}/Abilities/AbilitySet_UPC_Default", F, f"AbilitySet_{N}")
rows = [r for r in abilities.get_editor_property("GrantedGameplayAbilities")
        if r.get_editor_property("Ability").get_name() not in ("GA_UPC_ParryRecoil_C", "GA_UPC_PlayerStun_C")]
abilities.set_editor_property("GrantedGameplayAbilities", rows)
save(abilities)
 
d = defaults(bp)
d.set_editor_property("StartingAbilitySet", abilities)
body = d.get_editor_property("Mesh")
body.set_editor_property("SkeletalMeshAsset", mesh)
body.set_editor_property("AnimClass", abp.generated_class())
print(body.get_editor_property("ComponentTags"))       # must hold UPC.Montage and UPC.Attachment.Body
places = d.get_editor_property("EquipmentManagerComponent").get_editor_property("BodyPlaces")
for p in places:
    print(p.get_editor_property("Place"), p.get_editor_property("Socket"))
save(bp)

• GA_UPC_ParryRecoil and GA_UPC_PlayerStun play the demo mannequin's recoil and stun montages, which would make the customer's character perform the demo's motion. The copy keeps lock-on, sprint, interact, drop and the flinch on a poise break (GA_UPC_HitReact, which plays no animation). Without them the copy is never stunned and does not stagger back from a parried blow. To bring a recoil back on the customer's own animation, make a child Blueprint of GA_UPC_ParryRecoil, set its StunMontage, and add it to the copy. A stun is a child of GA_UPC_Stun added the same way; the duplicate's UPC.Vital.Stance row already sends UPC.Event.GuardBreak as its DepletedGameplayEvent, which starts it when the stance runs out. The demo's own player stun also lists UPC.Style.Soulslike in its ActivationRequiredTags, so only the Soulslike style stuns the demo player; leave that list empty for a stun under every style.
• UPC.Montage on the mesh is where montages play; UPC.Attachment.Body is where items attach. Without the attachment tag, items do not show. The duplicate keeps both.
• BodyPlaces maps each place to a socket: UPC.Place.Main to hand_r, UPC.Place.Off to hand_l, and three back places to the mannequin's stow_back_r, stow_back_l and back_center_heavy sockets. It also carries the demo's worn gear places: UPC.Place.Head on head, UPC.Place.Ring.Left on ring_01_l, UPC.Place.Ring.Right on ring_01_r, UPC.Place.Shoulders on back_center_heavy, and UPC.Place.Chest, .Hands, .Feet and .Neck with no socket. Change a row's Socket if the customer's skeleton names those bones otherwise, and delete the worn rows a game does not use. The back places matter only for items that hang on the body, the worn places only for worn gear (AgentGuide/ItemsEquipment.md, Worn gear).
• The duplicate keeps the demo mannequin's mesh placement, which fits a character built like the UE5 mannequin (origin at the feet, facing +Y). If the character floats, sinks or faces sideways, adjust the Mesh component's RelativeLocation and RelativeRotation.

Step 3. Make the game mode and use it

factory = unreal.BlueprintFactory()
factory.set_editor_property("ParentClass", load(f"{DEMO}/Game/BP_UPC_GameMode").generated_class())
gm = TOOLS.create_asset(f"GM_{N}", F, unreal.Blueprint, factory)
defaults(gm).set_editor_property("DefaultPawnClass", bp.generated_class())
save(gm)
 
world = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem).get_editor_world()
world.get_world_settings().set_editor_property("DefaultGameMode", gm.generated_class())
unreal.get_editor_subsystem(unreal.LevelEditorSubsystem).save_current_level()

Recipe 2: a combo

seqs = {"Light1": load("/Game/.../Attack_01"),
        "Light2": load("/Game/.../Attack_02"),
        "Light3": load("/Game/.../Attack_03"),
        "Heavy": load("/Game/.../Attack_Heavy")}

Step 1. Make a montage per attack

skeleton = mesh.get_editor_property("Skeleton")
other = [key for key, seq in seqs.items() if seq.get_editor_property("Skeleton") != skeleton]
if other:
    raise RuntimeError(f"{other} are animations of another skeleton than {mesh.get_name()}'s")
am = {key: upc.create_montage_from_animation(seq, F, f"AM_{N}_{key}") for key, seq in seqs.items()}

Step 2. Make the damage configs

def poise(amount):
    row = unreal.UPCVitalDamage()
    row.set_editor_property("VitalTag", tag("UPC.Vital.Poise"))
    row.set_editor_property("Amount", amount)
    return row
 
dmg_light = new_data_asset(unreal.UPCDamageConfig, F, f"Damage_{N}_Light")
dmg_light.set_editor_property("Damage", 10.0)
dmg_light.set_editor_property("AdditionalVitalDamage", [poise(20.0)])
dmg_heavy = new_data_asset(unreal.UPCDamageConfig, F, f"Damage_{N}_Heavy")
dmg_heavy.set_editor_property("Damage", 25.0)
dmg_heavy.set_editor_property("AdditionalVitalDamage", [poise(60.0)])
save(dmg_light, dmg_heavy)

Step 3. Mark the montages

• UPC Melee Trace Window (UUPCMeleeTraceNotifyState) over the frames that connect. Nothing takes damage without it. Without frame data from the customer, start it at 30% of the montage (40% for the heavy attack) and make it 25% long.
• UPC Action Window (UUPCActionWindowNotifyState) where the next press may start the next attack. It has no settings. Put it on every attack that leads into another, from about 55% to 90%. A press made earlier waits for the window.

for key in ("Light1", "Light2", "Light3", "Heavy"):
    m, L = am[key], length(am[key])
    start = 0.40 if key == "Heavy" else 0.30
    w = upc.add_notify_state_to_montage(m, unreal.UPCMeleeTraceNotifyState, L * start, L * 0.25)
    w.set_editor_property("SocketIDs", [])          # [] sweeps every socket the item registered
    w.set_editor_property("DamageConfig", dmg_heavy if key == "Heavy" else dmg_light)
    if key in ("Light1", "Light2"):
        upc.add_notify_state_to_montage(m, unreal.UPCActionWindowNotifyState, L * 0.55, L * 0.35)
    save(m)

Step 4. Build the action graph

graph = new_data_asset(unreal.UPCActionGraphAsset, F, f"AG_{N}_Unarmed")
for key in ("Light1", "Light2", "Light3", "Heavy"):
    upc.add_montage_node(graph, key, am[key], 1.0)
upc.add_transition(graph, "ROOT", "Light1", "UPC.Input.LightAttack")
upc.add_transition(graph, "Light1", "Light2", "UPC.Input.LightAttack")
upc.add_transition(graph, "Light2", "Light3", "UPC.Input.LightAttack")
upc.add_transition(graph, "ROOT", "Heavy", "UPC.Input.HeavyAttack")
print(upc.compile_action_graph(graph))    # empty means no problems
print(upc.describe_action_graph(graph))
save(graph)

Step 5. Make the unarmed item's keys

imc = duplicate(f"{DEMO}/Weapons/Unarmed/IMC_UPC_Unarmed", F, f"IMC_{N}_Unarmed")

Step 6. Make the unarmed item

item = new_data_asset(unreal.UPCItemDefinition, F, f"Item_{N}_Unarmed")
eq = unreal.new_object(unreal.UPCItemFragment_Equippable, outer=item)
eq.set_editor_property("ActionGraph", graph)
eq.set_editor_property("InputMappingContext", imc)
 
def mapping(action_name, tag_name):
    m = unreal.UPCInputMapping()
    m.set_editor_property("InputAction", load(f"{DEMO}/Inputs/{action_name}"))
    m.set_editor_property("InputTag", tag(tag_name))
    return m
 
eq.set_editor_property("InputMappings", [
    mapping("IA_UPC_LightAttack", "UPC.Input.LightAttack"),
    mapping("IA_UPC_HeavyAttack", "UPC.Input.HeavyAttack"),
    mapping("IA_UPC_Dash", "UPC.Input.Dash"),
])
 
def hand_socket(socket_id, bone):
    s = unreal.UPCTraceSocket()
    s.set_editor_property("ID", socket_id)
    s.set_editor_property("Shape", unreal.UPCTraceShape.SPHERE)
    s.set_editor_property("SocketOrBoneName", bone)
    s.set_editor_property("Radius", 12.0)
    return s                     # SourceComponentTag left empty: the socket follows the body mesh
 
eq.set_editor_property("TraceSockets", [hand_socket("HandR", "hand_r"), hand_socket("HandL", "hand_l")])
eq.set_editor_property("AttackStopDistance", 25.0)
item.set_editor_property("Fragments", [eq])
save(item)

• AttackStopDistance is how close in front of a target this item's attacks stop, in centimeters between the two bodies. The duplicated player's combat style stops attacks 50 cm short, which suits a blade; at that distance a punch stops out of reach, so fists take about 25. One move with a shorter reach than the rest, such as a shield bash beside a sword, sets its own StopDistance on its Play Montage node (AgentGuide/TargetingStylesSteering.md).
• A new Equippable fragment already holds the main hand in HoldPlaces (UPC.Place.Main).

Step 7. Give it to the character

d = defaults(bp)
d.get_editor_property("EquipmentManagerComponent").set_editor_property("DefaultItem", item)
d.get_editor_property("MeleeTraceComponent").set_editor_property("DefaultDamageConfig", dmg_light)
save(bp)

Step 8. Play and check

les = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
les.editor_request_begin_play()

game = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem).get_game_world()
unreal.SystemLibrary.execute_console_command(game, "UPC.Debug.Actions 1")
pawn = unreal.GameplayStatics.get_player_pawn(game, 0)
graph_comp = pawn.get_component_by_class(unreal.UPCActionGraphComponent)
print(graph_comp.process_action_input(tag("UPC.Input.LightAttack"), unreal.UPCTransitionTrigger.ON_STARTED))
print(graph_comp.get_action_state())
unreal.AutomationLibrary.take_high_res_screenshot(1280, 720, f"{N}_combo.png")
les.editor_request_end_play()
print(log_warnings())

Recipe 3: a dodge

am_dodge = upc.create_montage_from_animation(load("/Game/.../Roll_Back"), F, f"AM_{N}_Dodge")
L = length(am_dodge)
w = upc.add_notify_state_to_montage(am_dodge, unreal.UPCStateTagNotifyState, L * 0.05, L * 0.50)
w.set_editor_property("Tags", tags("UPC.State.Intangible"))
save(am_dodge)
 
interrupt = unreal.UPCTransitionTiming.INTERRUPT
press = unreal.UPCTransitionTrigger.ON_STARTED
upc.add_montage_node(graph, "Dodge", am_dodge, 1.0)
upc.add_transition(graph, "ROOT", "Dodge", "UPC.Input.Dash")
for key in ("Light1", "Light2", "Light3", "Heavy"):
    upc.add_transition(graph, key, "Dodge", "UPC.Input.Dash", press, interrupt, 10)
print(upc.compile_action_graph(graph))
save(graph)

• The dodge uses UPC.Input.Dash, which the unarmed item already maps to IA_UPC_Dash.
• INTERRUPT lets the dodge cut a swing. A running move still keeps its first 0.1 seconds (Cancel Window Start on the node) before an interrupt fires.
• A UPC melee trace skips a target holding UPC.State.Intangible (the trace's PassThroughTags default), so no other setting is needed.
• Multiplayer detail: for a dodge that travels far and fast, also put UPC.State.Dashing in the same State Tag Window and set GraceTag = UPC.State.Dashing on the character's CharacterMovement (a UUPCCharacterMovementComponent), so the server accepts the dash's travel instead of pulling the player back.

Recipe 4: a weapon with its own moves

Step 1. Sockets on the weapon mesh

sword_mesh = load("/Game/.../SM_Sword")
for name in ("TraceStart", "TraceEnd"):
    print(name, sword_mesh.find_socket(name) is not None)
 
print(upc.add_blade_sockets(sword_mesh))

Step 2. Montages, windows and graph

Step 3. The weapon's keys

imc_sword = duplicate(f"{DEMO}/Weapons/Sword/IMC_UPC_Sword", F, f"IMC_{N}_Sword")
save(imc_sword)

Step 4. The weapon item

sword = new_data_asset(unreal.UPCItemDefinition, F, f"Item_{N}_Sword")
vis = unreal.new_object(unreal.UPCItemFragment_Visuals, outer=sword)
vis.set_editor_property("HeldMesh", sword_mesh)          # editor label: Mesh
eq = unreal.new_object(unreal.UPCItemFragment_Equippable, outer=sword)
eq.set_editor_property("ActionGraph", sword_graph)
eq.set_editor_property("InputMappingContext", imc_sword)
eq.set_editor_property("InputMappings", [
    mapping("IA_UPC_LightAttack", "UPC.Input.LightAttack"),
    mapping("IA_UPC_HeavyAttack", "UPC.Input.HeavyAttack"),
    mapping("IA_UPC_Dash", "UPC.Input.Dash"),
])
blade = unreal.UPCTraceSocket()
blade.set_editor_property("ID", "Blade")
blade.set_editor_property("SourceComponentTag", "UPC.ItemMesh")
blade.set_editor_property("Shape", unreal.UPCTraceShape.CAPSULE_TWO_POINT)
blade.set_editor_property("SocketOrBoneName", "TraceStart")
blade.set_editor_property("EndSocketOrBoneName", "TraceEnd")
blade.set_editor_property("Radius", 8.0)
eq.set_editor_property("TraceSockets", [blade])
sword.set_editor_property("Fragments", [vis, eq])
save(sword)

• An item with a Visuals HeldMesh and no ItemActorClass shows that mesh in the hand on a component tagged UPC.ItemMesh, which is why the blade socket's SourceComponentTag is UPC.ItemMesh. An empty tag would trace from the body mesh instead.
• bIsMainWeapon (editor label Main Weapon) is on by default: the sword's graph takes over while it is drawn.
• The item has no Stowable fragment, so it disappears when put away rather than hanging on the body. Stowing needs reach animations and back sockets on the customer's skeleton; see the Equipment page.

Step 5. Give it to the character

inv = defaults(bp).get_editor_property("InventoryComponent")
items = list(inv.get_editor_property("StartingItems"))
if sword not in items:
    items.append(sword)
inv.set_editor_property("StartingItems", items)
save(bp)

defaults(bp).get_editor_property("EquipmentManagerComponent").set_editor_property("DefaultItem", None)
save(bp)

offset = unreal.Transform(unreal.Vector(0, 0, 0), unreal.Rotator(roll=0, pitch=0, yaw=90), unreal.Vector(1, 1, 1))
row = unreal.UPCHoldPlaceSpec()
row.import_text(f'(Place=(TagName="UPC.Place.Main"),Offset={offset.export_text()})')
eq.set_editor_property("HoldPlaces", [row])     # eq: the sword's Equippable fragment from Step 4
save(sword)

Recipe 5: lock-on

1. What can be locked. Any actor with a UPC Targetable component (UUPCTargetableComponent) that is not on the player's team. Every character built on the UPC character base has one. For another kind of enemy, add the component to its Blueprint; AimAtSocket names where the lock aims.
2. How locked movement feels. The combat style decides. The duplicate uses the Over Shoulder style. For the Soulslike style's strafing around a locked target:

   d = defaults(bp)
   d.get_editor_property("CombatComponent").set_editor_property("Style", load(f"{DEMO}/Combat/Styles/CombatStyle_UPC_Soulslike"))
   save(bp)

3. Range. The style's targeting config sets the scan radius (ScanRadius, 2000 cm) and whether a lock breaks with distance (LockBreakDistance, 0 turns it off). To change them, duplicate TargetingConfig_UPC_Soulslike and point the style's Targeting fragment at the copy, which means duplicating the style as well.

No Animation Blueprint

anims = "/Game/.../"
abp = upc.create_locomotion_anim_blueprint(mesh.get_editor_property("Skeleton"), F, f"ABP_{N}",
                                           load(anims + "Idle"), load(anims + "Walk_Fwd"), load(anims + "Run_Fwd"))

More tasks: the reference files

Reference

Assets you create

Shipped assets you reuse

Montage notifies

Gameplay tags you set

Common mistakes

Learn more

Reference files

Action graphs: every card, edited from Python (AgentGuide/ActionGraphs.md)

How a move is edited

s = upc.get_node_settings(graph, "Heavy")
s.cancellation.cancel_window_start = 0.3        # nothing may cut the heavy for 0.3 s
upc.set_node_settings(graph, "Heavy", s)
print(upc.compile_action_graph(graph))
save(graph)

A move's settings (unreal.UPCActionNode)

Payloads: what a move does

Recipe: a held guard with a parry window

am_guard = upc.create_montage_from_animation(load("/Game/.../Guard"), F, f"AM_{N}_Guard", enable_root_motion=False)
L = length(am_guard)
upc.set_montage_sections(am_guard, [("Raise", 0.0, "Hold"), ("Hold", L * 0.5, "Hold")])   # the second half loops while held
w = upc.add_notify_state_to_montage(am_guard, unreal.UPCStateTagNotifyState, 0.0, min(0.25, L * 0.5))
w.set_editor_property("Tags", tags("UPC.State.Parrying"))
save(am_guard)
 
upc.add_montage_node(graph, "Guard", am_guard, 1.0)
s = upc.get_node_settings(graph, "Guard")
s.state.applied_tags = tags("UPC.State.Blocking")
s.cancellation.cancel_window_start = 0.0        # a quick tap lets go at once
upc.set_node_settings(graph, "Guard", s)
 
upc.add_transition(graph, "ROOT", "Guard", "UPC.Input.Guard")
upc.add_transition(graph, "Guard", "ROOT", "UPC.Input.Guard", unreal.UPCTransitionTrigger.ON_COMPLETED, unreal.UPCTransitionTiming.INTERRUPT)
print(upc.compile_action_graph(graph))
save(graph)

• The item's mappings need a row for IA_UPC_Guard on UPC.Input.Guard (AGENTS.md, Recipe 2, Step 6). Both demo mapping contexts map it already.
• Pick the loop point from the animation: the frame where the guard is fully up. Tell the customer the times you picked.
• The looping guard opens no action window, so every way out of it is an INTERRUPT transition: the release above, and an attack out of the guard. A release that waits for the window never lands.
• A guard whose pose comes from the item's animation layer reading UPC.State.Blocking, as the demo's do, needs no montage: make the move with upc.add_node(graph, "Guard", unreal.UPCHoldActionPayload) instead, with the same tags and transitions.

Transitions

Transition settings

t = upc.get_transition_settings(graph, "ROOT", "BackStep", "UPC.Input.LightAttack")
cond = unreal.new_object(unreal.UPCTransitionCondition_Direction)
cond.set_editor_property("RequiredDirection", unreal.UPCInputDirection.BACK)
t.set_editor_property("Conditions", [cond])
upc.set_transition_settings(graph, "ROOT", "BackStep", "UPC.Input.LightAttack", t)

Sub graphs

upc.add_sub_graph(sword_graph, "ROOT", shield_graph, entry_required_tags=["UPC.Equipment.Shielded"])
print(upc.compile_action_graph(sword_graph))

for move in ("Light1", "Light2", "Light3"):
    upc.attach_sub_graph(sword_graph, move, shield_graph)
print(upc.compile_action_graph(sword_graph))

Removing and renaming

• upc.remove_transition(graph, from_node, to_node, input_tag, fires_on=None).
• upc.remove_node(graph, name) takes the move, every transition into and out of it and its row in every alias. ROOT stays.
• Rename by writing another NodeName through set_node_settings.

Graph and character settings

• On the graph asset: DefaultInputBufferMode (unreal.UPCInputBufferMode: IGNORE, ACCEPT_FIRST, ACCEPT_LAST, the default) decides what a press made before the action window does; LateInputGrace (seconds, default 0.25, 0 off): how long after a move runs to its end a press or release still follows that move's own transitions, so a combo carries on when the next press comes a moment late; a canceled move, or one that leaves through an AUTO transition to another move, grants none; HeldInputRestartWindow (seconds).
• On the character's UPC Action Graph component (the C++ base creates it): GlobalBlockTags (default UPC.State.ActionsBlocked) drops every press while the character holds one; ActionSpeed scales how fast every move plays (1 is authored speed).

Mistakes

Animation, HUD, settings and debugging (AgentGuide/AnimationHUDDebug.md)

Montage windows

Several meshes and animation layers

• Component tags on the character's skeletal meshes say what each is for: UPC.Montage (follows the action's montage), UPC.AnimLayer (takes the item's animation layer), UPC.Attachment.<Slot> (items attach to it; the duplicated player's body has UPC.Attachment.Body). Matching is by prefix. Add the tags to an extra mesh's ComponentTags.
• Walking differently with a weapon: the Equippable fragment's AnimLayerClass, a child of the demo's ABP_UPC_ItemAnimLayersBase for the customer's skeleton with its own walk and jog sets. Its Upper Body Default sequence also holds the arms through a dodge while UPC.State.Dashing is on, so a weapon playing the bare hands' dodge montages keeps its grip. Building the layer's AnimGraph is a step for the customer.
• Tag-driven bools: an Animation Blueprint whose parent is UUPCAnimInstanceBase has GameplayTagPropertyMap on its class defaults, setting a bool while a tag is held.
• Hit stop in the customer's own Animation Blueprint: a UPC Hit Stop node after the DefaultSlot slot and an Inertialization node after it. That is a step for the customer; the plugin's locomotion template already has both (AGENTS.md, "No Animation Blueprint"), and without them the log warns once and hits land without the freeze.

Footsteps and effects

• Footsteps: duplicate the demo's AnimEffectBank_UPC_Default and set it as the component's Bank. The console command UPC.AnimEffects.PlantFootsteps <content path> save writes UPC.AnimEffect.Footstep.Left and .Right notifies where each foot lands, for every animation in a folder.
• Footsteps per surface: give the bank a SurfaceSet (UUPCImpactSurfaceSet: MaterialSuffixes maps a physical material asset to a name such as Stone, SurfaceSuffixes a surface type) and a row for UPC.AnimEffect.Footstep.Stone, which then answers every footstep on that material unless a deeper row such as Footstep.Left exists. A row's tag must exist: upc.add_gameplay_tag(tag, comment). The component looks at the ground under the socket for an effect a bank it uses has a surface row for. upc.validate_asset(bank) warns about a surface no row ends in and notes a row that plays nothing, which silences its tag (how a layered bank mutes one).
• A weapon Blueprint's own swing effects (a blade glow, a whoosh of its own, sparks): the Equippable fragment's ItemActorClass, a child of UPC Equippable Item, already implements UPC Anim Effect Handler, answering false. Overriding its functions Handle Anim Effect, Handle Anim Effect Begin and Handle Anim Effect End (under Interfaces in the Blueprint editor), checking the request's Effect Tags, returning true when it acted and false for the rest, is a Blueprint graph step for the customer; the demo BP_UPC_Sword lights its blade on UPC.AnimEffect.Weapon.Glow windows that way. The request's Mesh and Socket Name are the character's, so a blade effect goes on the weapon's own mesh. Windows can overlap: a heavy attack chained into another can open the next window before the last one closes, when the next montage blends in, so the graph counts open windows and switches the effect off when the count returns to zero, as the demo sword does. The character's own handlers do not pass requests on to the weapon; the equipment manager already does.
• A ribbon behind the blade needs no graph: the Swing Trail fragment (AgentGuide/ItemsEquipment.md) and a window carrying UPC.AnimEffect.Weapon.Trail over each swing. upc.validate_asset(item) warns when no montage the item's Action Graph plays carries such a window.
• Item sounds are item events, not anim effects: an item's draw and put-away sounds are its Stowable fragment's DrawSound and PutAwaySound, and its drop and landing sounds come from its World Item fragment.
• In the animation editor, playing or scrubbing a clip plays the effects its notifies ask for from a preview bank: UUPCEditorSettings (Project Settings, Plugins, Universal Player Combat Editor, Animation Preview) PreviewBank, or PreviewBanksBySkeleton for one skeleton. While the clip, an animation or a montage, carries a UPC Anim Effect, the viewport's bottom left corner names the bank; a bank the project lacks plays nothing and shows no name.
• Nothing plays: UPC.Debug.AnimEffects 1 in Play writes each character's last requests above it with what answered (the bank, its row and surface, the Swing Trail, a Blueprint by class name), in red when nothing did. Then check, in order: the notify sits on the mesh that plays the montage; the character has a handler (the component has a Bank); a row's tag sits above the requested tag; a surface row's tag exists; the effect plays on a client or listen server, never a dedicated server; the notify's TriggerWeightThreshold and NotifyTriggerChance.

HUD and prompts

• The demo HUD WBP_UPC_HUD shows vitals (WBP_UPC_CoreVitals), the crosshair, cooldowns and the belt. A style's Tags fragment holds UPC.UI.Show.Stamina, UPC.UI.Show.Belt and the like, which the HUD reads to show each part. Changing a widget's layout is a step for the customer.
• Button prompts: UUPCInputDisplaySettings (Project Settings, Plugins, Universal Player Combat Input Display) lists GlyphSets (UUPCInputGlyphSet: DeviceFamily, HardwareDeviceIdentifiers naming the pads a sheet serves, Glyphs rows Key, Icon, ShortLabel, LongLabel), top to bottom, the first sheet serving the device and covering the key winning: the PlayStation sheet (DualSense, DualSenseEdge, DualShock4), the generic gamepad sheet, then keyboard.

Project settings

Debugging

Camera and attack warnings (AgentGuide/CameraTelegraphs.md)

The camera rig

Camera shots

Warning markers over swings

1. The attacker's montage carries a UPC Telegraph Window (UUPCTelegraphMarkerNotifyState) over the wind-up: TelegraphType, bFindAttackAutomatically (finds the trace window it describes), DamageConfig, Tags, OriginSpace, OriginItemTag, Broadcast (its Shape). Add it with upc.add_notify_state_to_montage.
2. The player sees markers through a UPC Telegraph Viewer (the duplicated player has one) with a StyleSet: a Telegraph Style Set (UUPCTelegraphStyleSet: Styles rows unreal.UPCTelegraphStyle RequiredTags, BlockedTags, Priority, PresenterClass, FallbackSocket, Duration; ViewRules). Duplicate the demo's TelegraphStyle_UPC_Default and change rows; a new marker look is a presenter Blueprint (duplicate a BP_UPC_TelegraphPresenter_*).
3. A marker over a character rather than a swing: a UPC Telegraph Subject component (UUPCTelegraphSubjectComponent) and its Show Marker call, a Blueprint step.

Mistakes

Damage, hit effects, blocks, parries and vitals (AgentGuide/DamageDefense.md)

Damage configs

Recipe: a shield that blocks and a timed guard that parries

rules = new_data_asset(unreal.UPCDefenseRuleSet, F, f"DefenseRuleSet_{N}_Shield")
parry = unreal.new_object(unreal.UPCDefenseRule_Guard, outer=rules)
parry.set_editor_property("RequiredTags", tags("UPC.State.Parrying"))
parry.set_editor_property("DamageMultiplier", 0.0)
parry.set_editor_property("ResultTag", tag("UPC.DamageResult.Parried"))
parry.set_editor_property("CostPerDamage", 0.0)
block = unreal.new_object(unreal.UPCDefenseRule_Guard, outer=rules)
block.set_editor_property("RequiredTags", tags("UPC.State.Blocking"))
block.set_editor_property("ArcHalfAngleDegrees", 70.0)
block.set_editor_property("DamageMultiplier", 0.2)
block.set_editor_property("ResultTag", tag("UPC.DamageResult.Blocked"))
rules.set_editor_property("Responses", [parry, block])
save(rules)
 
guard = unreal.new_object(unreal.UPCItemFragment_Guard, outer=shield)       # shield: the item from AgentGuide/ItemsEquipment.md
guard.set_editor_property("DefenseSet", rules)
shield.set_editor_property("Fragments", list(shield.get_editor_property("Fragments")) + [guard])
save(shield)

• The tags come from the guard move: UPC.State.Blocking while the guard node runs and UPC.State.Parrying over the first frames of its montage (AgentGuide/ActionGraphs.md, "A held guard with a parry window"). Without them the rules never answer and hits land whole.
• Put the guard move in the graph of the weapon held with the shield: the shield itself drives no moves.
• A guard costs stamina when CostVitalTag names a vital (CostPerDamage per point of damage, FlatCost per hit); empty costs nothing.
• ArcHalfAngleDegrees is half the arc in front that blocks; a hit from behind lands whole.

Defense responses

Vitals

Hit reactions

Mistakes

Stamina, costs, cooldowns, gates and hooks (AgentGuide/GatesCostsHooks.md)

Recipe: stamina, attack costs, a dodge cooldown and sprint drain

d = defaults(bp)
vitals = d.get_editor_property("VitalsComponent")
rows = list(vitals.get_editor_property("Vitals"))
names = [str(unreal.GameplayTagLibrary.get_tag_name(r.get_editor_property("VitalTag"))) for r in rows]
if "UPC.Vital.Stamina" in names:                  # the duplicated demo player has one
    row = rows[names.index("UPC.Vital.Stamina")]
else:
    row = unreal.UPCVitalDefinition()
    row.set_editor_property("VitalTag", tag("UPC.Vital.Stamina"))
    rows.append(row)
row.set_editor_property("MaxValue", 100.0)
row.set_editor_property("RegenRatePerSecond", 25.0)
row.set_editor_property("RegenDelaySeconds", 1.0)
vitals.set_editor_property("Vitals", rows)
save(bp)
 
def add_cost(graph, node, amount):
    s = upc.get_node_settings(graph, node)
    cost = unreal.new_object(unreal.UPCActionCost_Vital)
    cost.set_editor_property("VitalTag", tag("UPC.Vital.Stamina"))
    cost.set_editor_property("Amount", float(amount))
    s.set_editor_property("Costs", list(s.get_editor_property("Costs")) + [cost])
    upc.set_node_settings(graph, node, s)
 
for node in ("Light1", "Light2", "Light3"):
    add_cost(graph, node, 10)
add_cost(graph, "Dodge", 25)
 
s = upc.get_node_settings(graph, "Dodge")
gate = unreal.new_object(unreal.UPCActionGate_Cooldown)
gate.set_editor_property("CooldownTag", tag("UPC.Cooldown.Ability.Dodge"))
gate.set_editor_property("Seconds", 1.0)
gate.set_editor_property("Charges", 1)
s.set_editor_property("Gates", list(s.get_editor_property("Gates")) + [gate])
upc.set_node_settings(graph, "Dodge", s)
print(upc.compile_action_graph(graph))
save(graph)

• A cost is checked when the press arrives and spent when the move starts. A press the player cannot pay for does not start the move; it takes the move's Action Failed transition when one is wired.
• Do the same in every graph that has these moves: a drawn weapon's graph replaces the unarmed one.
• The cooldown tag names the timer. Gates sharing a tag share the timer, so they must agree on Seconds and Charges (the compile warns when they differ). For a second cooldown, add its own tag first: upc.add_gameplay_tag("UPC.Cooldown.Ability.Heavy", "Heavy attack cooldown").

Gates, costs and hooks

Mistakes

Input, abilities and sprint (AgentGuide/InputAbilities.md)

How a press reaches a move

• Item mappings (while an item is drawn): the Equippable fragment's InputMappingContext, InputMappingPriority and InputMappings rows (unreal.UPCInputMapping: InputAction, InputTag, RequiredStateTags, DisplayName), as AGENTS.md, Recipe 2, Steps 5 and 6, builds.
• Character mappings (always): the character's InputMappingComponent (UUPCInputMappingComponent): InputMappings, InputChords, ChordWindowSeconds, bAutoBind.
• Keys: IMC_UPC_Default on the controller maps movement, look, slots 1 to 4, dash, lock-on, interact, drop and sprint. Item contexts map attack and guard keys.

Recipe: a kick on F

upc.add_gameplay_tag("UPC.Input.Kick", "Kick")
ia = unreal.AssetToolsHelpers.get_asset_tools().create_asset(f"IA_{N}_Kick", F, unreal.InputAction, unreal.InputAction_Factory())
ia.set_editor_property("ValueType", unreal.InputActionValueType.BOOLEAN)
save(ia)
key = unreal.Key()
key.import_text("F")
imc.map_key(ia, key)                         # imc: the item's mapping context copy
save(imc)
m = unreal.UPCInputMapping()
m.set_editor_property("InputAction", ia)
m.set_editor_property("InputTag", tag("UPC.Input.Kick"))
eq.set_editor_property("InputMappings", list(eq.get_editor_property("InputMappings")) + [m])   # eq: the item's Equippable fragment
save(item)
upc.add_transition(graph, "ROOT", "Kick", "UPC.Input.Kick")

Chords

Abilities on keys

row = unreal.UPCAbilitySet_GameplayAbility()
row.import_text(f'(Ability="{heal_bp.generated_class().get_path_name()}",AbilityLevel=1,InputTag=(TagName="UPC.Input.Special"),InputAction="{ia_heal.get_path_name()}",bInterruptsActionGraph=True)')
abilities.set_editor_property("GrantedGameplayAbilities", list(abilities.get_editor_property("GrantedGameplayAbilities")) + [row])
save(abilities)

Sprint

Pausing combat input

Mistakes

Inventory, belt, pickups, drops and interaction (AgentGuide/InventoryInteraction.md)

Inventory and belt

• Starting items: StartingItems on the character's InventoryComponent (AGENTS.md, Recipe 4, Step 5).
• The belt is the UPC Quick Bar component on the player controller (BP_UPC_PlayerController; duplicate it to change it, and set the copy as the game mode's PlayerControllerClass). Fields: Slots (unreal.UPCQuickBarSlot rows: Filter, an item kind the item's SlotTags must hold, its children included), bAutoPopulateFromInventory (off by default; on, a new item also takes the first free slot that admits it, as on the demo controller; what a combine makes is no new item), bAutoDrawOnInit (with Auto Populate on, an item landing on a slot also comes to hand when its places are free; it does nothing while Auto Populate is off), bRestoreWhenPlaceFrees, bWeaponKeepsItsPlace, DefaultMaxCopiesPerDefinition (1 on the demo controller, so its belt holds one of each item; the demo sword's Belt Limit fragment of 2 lets it hold two swords), DriverReplacementOnDrop, BlockedTags (tags that switch the belt off while the character carries one; UPC.State.BeltBlocked by default). The controller's IMC_UPC_Default maps keys 1 to 4 and the D-pad's up, right, down and left to IA_UPC_SelectSlot_1 to _4.
• Ask the customer which belt layout the game wants. Any item on any slot, as a survival game's hotbar: leave every slot's Filter empty, and a worn item drawn from the belt is put on. Slots by item kind, as the demo's souls-like diamond: slot 1 (top) UPC.Slot.Weapon, slot 2 (right) UPC.Slot.Consumable.Potion, slot 3 (bottom) UPC.Slot.OffHand, slot 4 (left) UPC.Slot.Consumable, with a Belt Limit fragment (MaxBeltCount 1) on the potion so its stacks take the right slot alone and the left slot holds other consumables; worn gear and a second weapon then stay in the inventory. Ask too whether any combat style has no belt: put UPC.State.BeltBlocked in that style's Gameplay Tags fragment (unreal.UPCStyleFragment_Tags, field Tags), as the demo Freeflow style does, and while it is active a belt press does nothing, nothing new goes on the belt and its slots keep their items. The demo HUD shows its belt only while the character carries UPC.UI.Show.Belt, which a style with a belt adds the same way.
• Item kinds are one UPC.Slot hierarchy in each item's SlotTags, read by the belt's filters, the inventory's rules and its sort order: UPC.Slot.Weapon (.Sword, .TwoHanded), UPC.Slot.OffHand (.Shield), UPC.Slot.Consumable (.Potion), UPC.Slot.Apparel, UPC.Slot.Ingredient, UPC.Slot.Ammo (.Arrow), UPC.Slot.KeyItem, UPC.Slot.Upgrade. Add the project's own kinds under these, such as a spear kind under UPC.Slot.Weapon, so a filter on the parent takes them. An item with no SlotTags fits unfiltered slots only. A Belt Limit fragment caps copies on the belt.

Containers

• Containers rows (unreal.UPCContainerSpec): a Container tag and a UPC Container Definition (unreal.UPCContainerDefinition: DisplayName, Icon, Layout unreal.UPCContainerLayout.LIST, SLOTS or GRID, SlotCount, GridSize (unreal.IntPoint), bAllowRotation, CapacityTag, Rules, bCarried, bTakesNewItems, AccessTag, bOpensBags). Adds try the rows in order, each followed by the bags open in it, and take the first container whose rules let the item in and that has room; a bTakesNewItems container off is filled by moves only. A List has no size and takes anything its rules allow, so give a container meant for one kind of item an Item Filter rule.
• CarryRules, judged over every carried container together. The rules: Weight Limit (Limit, CapacityTag, bRefuseOverLimit, Thresholds of Fraction and Tag), Category Limit (Limits rows of Category, MaxUnits, CapacityTag, matched against the item's SlotTags) Item Filter (AllowedTags, BlockedTags) and Belt Only (no settings: lets in only what the belt holds, for a style with no inventory; the belt needs bAutoPopulateFromInventory on. It turns down any bag, an item with a Container fragment, since what a bag holds would be carried off the belt. In the Carry Rules it limits everything carried; on a container it limits that container alone, as the demo Simple config's Belt container beside a Worn container whose Item Filter takes apparel).
• BeltSpace and EquippedSpace (unreal.UPCHeldItemSpace: KEEPS_ITS_PLACE, FREES_ITS_PLACE): whether an item on the belt, or drawn and off the belt, keeps its place in its container. Under FREES_ITS_PLACE, RequestMove of the whole held stack to a place in a carried container has the belt and the hand let go of it and puts it there, and CanPlace answers for that move. A screen that drops an item out of the hand onto a place sends RequestMove first and the belt's clear or RequestUnequipItem after it: a timed put-away running when the move arrives refuses the move. SortOrder: the Slot Tags RequestSort lays items out by. bEquipAtOnce, bPutAwayAtOnce and bCombineAtOnce (Timing): on, an equip, a put-away or a combine asked for from the inventory lands at once with no animation and no wait, which a screen that pauses the game needs; off, the request plays the item's reach, or waits DrawTiming or StowTiming (unreal.UPCItemActionTiming: Seconds, StartSound, CommitSound, bCancelOnMove) for an item with none, or the recipe's time for a combine. The server reads these three, so no request takes a flag for them. bSwapWhenFull is explained with pickups, in the paragraph after the code below. bShowCarriedItemsOnBody (off by default): on, every stowable item carried outside a bag hangs on the body while out of hand; off, only the belt's items do and an item only in the inventory shows nowhere on the character. BeltSlots (one tag per slot, an empty tag taking any item): the belt this config gives, standing in for the belt's own Slots while the config is used, as the party RPG's four slots taking any item; left empty, the belt keeps its own.
• An item with a Capacity Bonus fragment raises a capacity tag while owned; a container's or a limit rule's CapacityTag names it.
• Another config at runtime, such as a game that lets the player pick an inventory style: call the inventory's SetConfig on the server, never set Config itself outside the defaults. A container both configs list, such as a stash, keeps its items; every other item outside a bag is placed again in the new layout as an add would, each staying on the belt and in hand; one that fits nowhere stays in a carried container, past its end when that is full, with a warning. To start the new config empty, call RemoveAllItems first, which empties the stash too; to keep the stash, remove only the items IsItemCarriedAndInReach answers true for, as the demo wardrobe's BP_UPC_InventoryStylePad does before it adds the style's starter kit.

spec = unreal.UPCContainerSpec()
spec.import_text('(Container=(TagName="UPC.Inventory.Container.Backpack"),Definition="/Game/Inventory/Container_Backpack.Container_Backpack")')
config = load("/Game/Inventory/InventoryConfig_Knight")      # the project's copy of a demo config
config.set_editor_property("Containers", list(config.get_editor_property("Containers")) + [spec])
save(config)

Recipe: a survival grid

• Containers, in this order: Case (UPC.Inventory.Container.Case: Grid, GridSize 6 by 4, bAllowRotation on, an Item Filter rule with BlockedTags UPC.Slot.KeyItem and UPC.Slot.Upgrade, CapacityTag UPC.Inventory.Capacity.CaseRows), Key Items (UPC.Inventory.Container.KeyItems: List, an Item Filter rule with AllowedTags UPC.Slot.KeyItem and UPC.Slot.Upgrade, bOpensBags on, so keys and pouches take no room in the case and a pouch opens there) and Stash (UPC.Inventory.Container.Stash: Slots, SlotCount 30, bCarried off, bTakesNewItems off, AccessTag UPC.State.AtStash; the same container asset the three demo style configs list, so a stash survives a switch of config).
• Each item larger than one cell gets a Grid Footprint fragment (unreal.UPCItemFragment_GridFootprint, Size columns by rows: the demo sword 1 by 3, the shield 2 by 2). The hip pouch (/UniversalPlayerCombat/Demo/Items/Bags/Item_UPC_HipPouch) is a bag whose Container fragment opens Container_UPC_HipPouch, a Grid 6 by 1 with the case's Item Filter; the case is listed first, so adds fill it before the pouch's cells, and what lies in those cells drops, travels and comes back with the pouch. The demo survival grid screen draws each open pouch's cells under the case (WBP_UPC_ExtraCells). For space that stays with the character, such as a case upgrade, give an item a Capacity Bonus row for UPC.Inventory.Capacity.CaseRows instead: it adds a row, and the player cannot drop it while that row holds an item.
• CarryRules: the demo's Blueprint rule BP_UPC_InventoryRule_UniqueKeyItems (one of each key item). CombineSets: the demo's CombineSet_UPC_Demo (Combines, below). bPutAwayAtOnce on, so a screen's put-away leaves the hand at once while Equip keeps its draw animation. bShowCarriedItemsOnBody on, so every weapon in the case hangs on the body.
• The stash is opened at a demo storage box (Storage boxes, below). A whole stack on the belt never goes into storage the character does not carry until the belt lets go of it; the demo screens' Store clears the belt slot first.

Recipe: a party RPG inventory

• Containers: Backpack (UPC.Inventory.Container.Backpack: List, bOpensBags on, so a pouch opens once picked up) and Stash (UPC.Inventory.Container.Stash: Slots, SlotCount 30, bCarried off, bTakesNewItems off, AccessTag UPC.State.AtStash).
• CarryRules: a Weight Limit with Limit 60, bRefuseOverLimit off and Thresholds UPC.State.Encumbered at 0.7 and UPC.State.HeavilyEncumbered at 1. Every item gets a Weight fragment. The slow is the character's UPC Speed Modifier (SpeedScaleByTag: the demo character's 0.85, and 0 for UPC.State.HeavilyEncumbered and UPC.State.Overburdened, which hold it still); the demo character's UPC Sprint names UPC.State.Encumbered and UPC.State.Overburdened in its BlockedTags, so an encumbered character cannot sprint.
• CombineSets: CombineSet_UPC_Demo. bEquipAtOnce, bPutAwayAtOnce and bCombineAtOnce on, so the screen equips, puts away and combines at once. BeltSpace and EquippedSpace FREES_ITS_PLACE, so an item on the belt or in hand, worn gear included, leaves the backpack while held and its weight still counts. BeltSlots: four empty tags, a row taking any item.
• The Stash is the same container as the survival grid's, opened at the same storage box (Storage boxes, below). The party RPG screen's paper doll is WBP_UPC_PaperDoll (Inventory screens, below); a doll of the project's own reads the equipment manager's GetInstanceInPlace for each place it shows, skips the unarmed fallback (IsDefaultItem), and redraws on OnDrawnStateChanged. Loot chests are BP_UPC_LootChest (Loot chests, below).

Recipe: an open world list

• Containers: Satchel (UPC.Inventory.Container.Satchel: List) and the demo's Stash (Container_UPC_Stash, as the survival grid lists it), which the list screen shows in a panel of its own on the right of its frame while the character stands at a storage box.
• CarryRules: a Weight Limit with Limit 60, bRefuseOverLimit off and a threshold UPC.State.Overburdened at 1, and the demo's Blueprint rule BP_UPC_InventoryRule_Valuables (UPC.State.CarryingValuables while an item worth 100 gold or more is carried).
• SortOrder: UPC.Slot.Weapon, UPC.Slot.OffHand, UPC.Slot.Apparel, UPC.Slot.Consumable, UPC.Slot.Ingredient; items of no listed kind sort last. The demo's list screen shows the satchel in that order (GetItemsInSortOrder), with a category column filtering by the same kinds.
• bHasBelt off: the player has no belt while this config is used. The belt has no slots, so the 1 to 4 keys do nothing and nothing goes on it, and the HUD and the list screen show no belt, no On Belt category and no Add to belt prompt. Leave it on for a list with the belt as favorites: the screen then sends RequestAssignSlot, and its On Belt category lists the belt's items.
• CombineSets: CombineSet_UPC_Demo. bEquipAtOnce, bPutAwayAtOnce and bCombineAtOnce on, since the list screen pauses a game with no other players and a paused world runs no timers.

Recipe: hands only

• Containers: one container, Slots with SlotCount 2, bCarried on, no rules. BeltSpace and EquippedSpace stay KEEPS_ITS_PLACE (the defaults), so two held items fill it.
• bSwapWhenFull on, so a third pickup reads Swap and puts down the item in hand that makes room, the weapon driving combat first.
• BeltSlots: two empty tags, a belt of two slots taking any item. On the controller's belt, bAutoPopulateFromInventory and bAutoDrawOnInit on: a picked-up item lands on the first free slot and comes to hand while its Hold Places are free. For two of one item, the belt's DefaultMaxCopiesPerDefinition must allow two (0 is no limit; the demo controller's is 1), or the item needs a Belt Limit fragment of 2.
• No HUD shows the belt: leave UPC.UI.Show.Belt out of the style's Gameplay Tags fragment. Leave the belt's keys out of the game's mapping context so no key puts an item away.

Recipe: a keychain

• A container listed first is tried first by each add, and an Item Filter rule on it lets in only the UPC.Slot.KeyItem kind, so keys land there and nothing else does. The pack, listed second, takes the rest.
• An item with no World Item fragment cannot be dropped or lie on the ground: the drop ability refuses it and the demo screens show no Drop for it.
• An item with no Weight fragment weighs nothing, so the weight limit does not count a key, even in a pack already full.

F = "/Game/Inventory"                                    # the customer's folder
upc.add_gameplay_tag("UPC.Inventory.Container.Keychain", "The player's keychain")
 
def make_item(name, kind, stack=1, weight=None):
    item = new_data_asset(unreal.UPCItemDefinition, F, f"Item_{name}")
    item.set_editor_property("DisplayName", name)
    item.set_editor_property("SlotTags", tags(kind))
    item.set_editor_property("MaxStackSize", stack)
    if weight is not None:
        w = unreal.new_object(unreal.UPCItemFragment_Weight, outer=item)
        w.set_editor_property("Weight", weight)
        item.set_editor_property("Fragments", [w])
    save(item)
    return item
 
rusty = make_item("RustyKey", "UPC.Slot.KeyItem")        # no Weight, no World Item fragment
gold = make_item("GoldKey", "UPC.Slot.KeyItem")
flint = make_item("Flint", "UPC.Slot.Ingredient", stack=10, weight=1.0)
 
keychain = new_data_asset(unreal.UPCContainerDefinition, F, "Container_Keychain")     # a List by default
only_keys = unreal.new_object(unreal.UPCInventoryRule_ItemFilter, outer=keychain)
only_keys.set_editor_property("AllowedTags", tags("UPC.Slot.KeyItem"))
keychain.set_editor_property("Rules", [only_keys])
save(keychain)
pack = new_data_asset(unreal.UPCContainerDefinition, F, "Container_Pack")
save(pack)
 
config = new_data_asset(unreal.UPCInventoryConfig, F, "InventoryConfig_Hero")
rows = []
for container_tag, definition in (("UPC.Inventory.Container.Keychain", keychain), ("UPC.Inventory.Container.Backpack", pack)):
    row = unreal.UPCContainerSpec()
    row.import_text(f'(Container=(TagName="{container_tag}"),Definition="{definition.get_path_name()}")')
    rows.append(row)
config.set_editor_property("Containers", rows)             # the keychain first
limit = unreal.new_object(unreal.UPCInventoryRule_WeightLimit, outer=config)
limit.set_editor_property("Limit", 30.0)
config.set_editor_property("CarryRules", [limit])
save(config)
 
bp = load("/Game/Player/BP_Hero")                          # the customer's player
defaults(bp).get_editor_property("InventoryComponent").set_editor_property("Config", config)
save(bp)

holds = keychain                                           # Container_Keychain above: the Item Filter on keys
chain = make_item("Keychain", "UPC.Slot.Upgrade")
bag = unreal.new_object(unreal.UPCItemFragment_Container, outer=chain)
bag.set_editor_property("Definition", holds)               # ContainerTag keeps its default, UPC.Inventory.Container.Bag
chain.set_editor_property("Fragments", [bag])
save(chain)
 
pack = new_data_asset(unreal.UPCContainerDefinition, F, "Container_PackWithBags")
pack.set_editor_property("bOpensBags", True)
no_keys = unreal.new_object(unreal.UPCInventoryRule_ItemFilter, outer=pack)
no_keys.set_editor_property("BlockedTags", tags("UPC.Slot.KeyItem"))
pack.set_editor_property("Rules", [no_keys])
save(pack)
# The config lists the pack alone; the character starts with the keychain.
defaults(bp).get_editor_property("InventoryComponent").set_editor_property("StartingItems", [chain])

More pieces from Python

• A container shaped as slots or a grid. layout = unreal.UPCContainerLayout.SLOTS with SlotCount, or GRID with GridSize as unreal.IntPoint(6, 4) and bAllowRotation; either grows with a CapacityTag. An item bigger than one grid cell carries a Grid Footprint fragment (Size, unreal.IntPoint(1, 3)). A container off the character, such as a bank, sets bCarried off (its items leave the weight limit, the belt and Get Item Count), and bTakesNewItems off keeps adds out of it; AccessTag locks it to a character holding that tag.
• A cap per item kind. A Category Limit rule, on a container's Rules or the config's CarryRules, with Limits rows written as text: row = unreal.UPCCategoryLimit(); row.import_text('(Category=(TagName="UPC.Slot.Ammo.Arrow"),MaxUnits=20)'), then rule.set_editor_property("Limits", [row]).
• A weight limit that slows instead of refusing. bRefuseOverLimit off and Thresholds rows, each '(Fraction=0.7,Tag=(TagName="UPC.State.Encumbered"))' through unreal.UPCWeightThreshold().import_text(...); the tag then sits on the character, and the character's UPC Speed Modifier or a transition's BlockedTags gives it an effect.
• An item that grows a capacity. A Capacity Bonus fragment whose Bonuses row names the capacity tag and an Amount, written as text (unreal.UPCCapacityBonus().import_text('(CapacityTag=(TagName="UPC.Inventory.Capacity.CaseRows"),Amount=1)')); a container's, a Weight Limit's or a Category Limit's CapacityTag names the same tag. The player cannot drop, store or put back such an item while items sit in the slots or rows it gives (CanItemLeave answers UPC.Inventory.Refused.CapacityInUse); for extra space whose items go with it, make the item a bag.
• The config's other settings. SortOrder (a list of tags: [tag("UPC.Slot.Weapon"), tag("UPC.Slot.Consumable")]), BeltSpace and EquippedSpace (unreal.UPCHeldItemSpace.FREES_ITS_PLACE), bSwapWhenFull, and the three at-once switches, all plain set_editor_property writes.
• Which screen it opens. A config of the project's own needs a row in the screens component's InventoryScreenClasses, or it opens the open world list (Inventory screens, below).

Building on it in Blueprint

• A rule (parent unreal.UPCInventoryRule): override GetUnitsAccepted to turn items away (BP_UPC_InventoryRule_UniqueKeyItems reads the inventory's GetItemCount) or GetStatusTags to tag the character (BP_UPC_InventoryRule_Valuables). The context's Departing lists what leaves the rule's scope in the same change, a row per stack (a swap's other item, what a combine takes from both of its stacks), and ArrivingWith what comes in beside the item; count the first as gone and the second as already in, as the unique key rule counts Departing. List it on a container's Rules or the config's CarryRules. A rule keeps no state of its own.
• A combine (parent unreal.UPCInventoryCombine): for what a Combine Set's recipe row cannot say; the demo's Load Holder and Coat Weapon (Combines, below).
• An item fragment (parent unreal.UPCItemFragment): data an item carries, such as BP_UPC_ItemFragment_GoldValue (an integer Value). Add an instance to an item's Fragments like any fragment; a graph reads it with the item instance's FindFragmentByClass and a cast. The C++ sort reads Slot Tags only, so a Blueprint fragment orders nothing by itself.

Inventory screens

• As it is. Keep BP_UPC_PlayerController, or the project's duplicate of it, as the game mode's PlayerControllerClass, or add BPC_UPC_InventoryScreens to the project's own player controller (Components panel, Add; a Blueprint step), which brings the screens, the I and Back keys and the chest's Open option with it; a player ability set duplicated from AbilitySet_UPC_Default already grants the use and drop abilities (Using and dropping from a screen, below). The component's InventoryScreenClasses maps each inventory config to its screen, and FallbackInventoryScreen serves the rest, so a config duplicated from a demo one needs a row of its own, or it opens the open world list.
• A copy. Duplicate the screen into the project's folder, point the screens component's row at the copy, and change the copy in the Widget Blueprint editor (a Blueprint step). Data the customer changes in the editor's Class Defaults or Details panel: the list panel's CategoryRows (WBP_UPC_ListPanel, which both sides of the list screen share; each a Label, the item kinds it shows in Kinds, OtherKinds for a row taking what no other row names, or BeltOnly for a row of the belt's items), the paper doll's Places (WBP_UPC_PaperDoll: a place tag, a label, a row and a column each, following BP_UPC_Character's places, held once in the doll's class defaults, so a body with other BodyPlaces needs them edited there) and the message line's RefusalWords (WBP_UPC_InventoryMessage: the words shown for each UPC.Inventory.Refused and UPC.Equipment.Cancelled reason; a reason with no row shows the last part of its tag). A copy keeps using the blocks in Common beside the screens, so keep the demo in the project while it does.
• A screen of the project's own. Start from a copy all the same: the blocks in Common hold every action once. WBP_UPC_ItemTile draws one item or one empty place; WBP_UPC_ContainerList, WBP_UPC_ContainerGrid and WBP_UPC_ContainerSlots draw one container each; BP_UPC_ItemMove is the carried item, for a mouse drag and a click or pad pick-up alike; BFL_UPC_InventoryScreens holds each item action as a check and a send, and the carry flow every screen calls (Pick Up, Put Down, Put Back, Send To Belt); BPI_UPC_InventoryScreen is what the screens component and the tiles call on a screen, Show Inventory among them; the panels are WBP_UPC_BeltPanel, WBP_UPC_StoragePanel, WBP_UPC_ChestPanel, WBP_UPC_BagPanel and WBP_UPC_PaperDoll. Keep the screens' contract: every action asks the check its request runs on the server (Containers, above), sends the request only when the check said yes, and redraws from the components' events once the change arrives, about a round trip later, with nothing predicted. A button that moves an item with no place picked, such as Take or Store, asks the inventory where it lands: FindTransferDestination between the player's inventory and a chest, FindMoveDestination into one container, FindAddDestination where an add would put it; each answers the place one request moves the most units into, with the server's own answer there and, on a refusal, its reason (Full, or Held when the belt or the hand holds the item and more of it would land once they let go), and the button sends RequestTransfer or RequestMove with that place. Pick Up plays the item's grab sound and Put Down and Put Back its place sound, from the equipment manager's GetInventoryMoveSound (the item's own InventoryGrabSound and InventoryPlaceSound, else its Stowable fragment's DrawSound and PutAwaySound, and none for a move into or out of the hand that the item's look sounds itself). UPCInventoryStatics.GetItemFootprint answers an item's grid cells for a drag picture, the belt's GetSlotOfItem the slot an item sits in, and the inventory's IsHeldBy whether the belt or a hand holds it.

theme = duplicate(f"{DEMO}/UI/Theme/UITheme_UPC_Default", F, f"UITheme_{N}")
theme.set_editor_property("Accent", unreal.LinearColor(0.80, 0.25, 0.05, 1.0))
save(theme)

comp = load("/Game/Player/BPC_InventoryScreens")
d = defaults(comp)
screens = d.get_editor_property("InventoryScreenClasses")
screens[load("/Game/Inventory/InventoryConfig_Survival")] = load(f"{DEMO}/UI/Widgets/Inventory/WBP_UPC_InventoryScreen_SurvivalGrid").generated_class()
d.set_editor_property("InventoryScreenClasses", screens)
save(comp)

opt = unreal.UPCInteractionOption()
opt.import_text('(OptionId="OpenInventory",ActivationInputTag=(TagName="UPC.Input.Interact"),Prompt=(Verb=NSLOCTEXT("", "", "Open"),Name=NSLOCTEXT("", "", "Chest")),PayloadSpec=/Script/UPCInteraction.UPCDelayInteractionPayloadSpec(DelaySeconds=0.0))')

Storage boxes

actors = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
box = actors.spawn_actor_from_class(EAL.load_blueprint_class(f"{DEMO}/Interactables/StorageBox/BP_UPC_StorageBox"), unreal.Vector(400, 0, 0))
box.set_editor_property("AccessTag", tag("UPC.State.AtStash"))
unreal.get_editor_subsystem(unreal.LevelEditorSubsystem).save_current_level()

Using and dropping from a screen

Combines

herb = load("/Game/Items/Item_Herb")
mixed = load("/Game/Items/Item_MixedHerb")
combine_set = new_data_asset(unreal.UPCCombineSet, "/Game/Inventory", "CombineSet_Knight")
made = unreal.UPCCombineResult()
made.set_editor_property("item", mixed)
recipe = unreal.UPCCombineRecipe()
recipe.set_editor_property("item_a", herb)
recipe.set_editor_property("item_b", herb)
recipe.set_editor_property("results", [made])
recipe.set_editor_property("seconds", 1.0)
combine_set.set_editor_property("recipes", list(combine_set.get_editor_property("recipes")) + [recipe])
save(combine_set)
config = load("/Game/Inventory/InventoryConfig_Knight")     # the project's copy of a demo config
config.set_editor_property("combine_sets", list(config.get_editor_property("combine_sets")) + [combine_set])
save(config)

• Matches(Item, Target): whether it handles Item dropped onto Target.
• GetUnits(Query, OutReason): how many units to make, from 0 to Query.Count (Query, a UPCInventoryCombineQuery: Inventory, Item, Target, Count). Asked when the drop is judged, also by a screen previewing it, and again before each unit with the units left; it changes nothing. 0 turns the drop down; set OutReason to a tag under UPC.Inventory.Refused, such as UPC.Inventory.Refused.Full.
• ApplyUnit(Context) (Context, a UPCInventoryCombineContext with the same four fields): makes one unit on the server, such as one more stack of a loaded stat tag on Target (AddStatTagStack) and one unit of Item consumed (the inventory's ConsumeItemInstance).
• UnitTiming (unreal.UPCItemActionTiming): half a second per unit by default, stopped by moving; 0 makes every unit at once.

combine_set = load("/Game/Inventory/CombineSet_Knight")
combine = unreal.new_object(EAL.load_blueprint_class("/Game/Inventory/BP_MagazineCombine"), outer=combine_set)
combine_set.set_editor_property("combines", list(combine_set.get_editor_property("combines")) + [combine])
save(combine_set)

Bags

• The bag bar is a config row whose definition has bOpensBags on and bTakesNewItems off, listed after the backpack, so adds fill the backpack and then the bags in bag bar order (row tag UPC.Inventory.Container.BagBar).
• A bag is an item with MaxStackSize 1 and a Container fragment (unreal.UPCItemFragment_Container): Definition, the UPC Container Definition of what it holds (its own size, rules, bCarried, bTakesNewItems, AccessTag, bOpensBags off), and ContainerTag (UPC.Inventory.Container.Bag by default; never a tag the config's own rows use).
• A bag's container is named by a UPC Container Id (unreal.UPCContainerId: Tag and ProvidingItem, the bag); a tag alone names one of the config's rows. GetContainers lists each open bag's id right after the bag bar, and GetContainerOpenedBy answers it for one bag, so a bag bar slot opens its bag's window with it.

pouch = new_data_asset(unreal.UPCItemDefinition, F, f"Item_{N}_Pouch")
bag = unreal.new_object(unreal.UPCItemFragment_Container, outer=pouch)
bag.set_editor_property("Definition", load("/Game/Inventory/Container_Pouch"))
pouch.set_editor_property("MaxStackSize", 1)
pouch.set_editor_property("Fragments", [bag])
save(pouch)

Saving the inventory

• Save: the inventory's ExportSnapshot into that variable, then Save Game to Slot, while the player's controller still possesses the character.
• Load: Load Game from Slot, then the inventory's ImportSnapshot with the variable, from the player controller's On Possess after its parent call, or later. The character's Event Possessed is too early: the belt is not bound yet, so the belt slots stay empty and a warning says so. The import replaces everything the inventory held, starting items included, also on the first possession at map start, which comes before Begin Play, and puts back each stack's place, stat data, belt slot and what was in hand or worn, in the same places; anything the belt or the hand held from outside the inventory is put away.

Pickups

actors = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
pickup = actors.spawn_actor_from_class(unreal.UPCWorldItem, unreal.Vector(300, 0, 50))
pickup.set_editor_property("ItemDefinition", load(f"{F}/Item_{N}_Sword"))
unreal.get_editor_subsystem(unreal.LevelEditorSubsystem).save_current_level()

Drops

Item holders

Loot chests

chest = duplicate(f"{DEMO}/Interactables/LootChest/BP_UPC_LootChest", F, "BP_ProjectChest")
sds = unreal.get_engine_subsystem(unreal.SubobjectDataSubsystem)
for handle in sds.k2_gather_subobject_data_for_blueprint(chest):
    obj = unreal.SubobjectDataBlueprintFunctionLibrary.get_object_for_blueprint(unreal.SubobjectDataBlueprintFunctionLibrary.get_data(handle), chest)
    if isinstance(obj, unreal.UPCWorldInventoryComponent):
        obj.set_editor_property("Config", load(f"{DEMO}/Items/Inventory/InventoryConfig_UPC_LootChest"))
        obj.set_editor_property("StartingItems", [potion, potion, rusty])      # one unit per entry; repeats join into one stack
        obj.set_editor_property("AccessRadius", 250.0)                         # cm; an AccessTag locks it to a key holder
unreal.BlueprintEditorLibrary.compile_blueprint(chest)
save(chest)

Interaction

opt = unreal.UPCInteractionOption()
opt.import_text('(OptionId="Pull",ActivationInputTag=(TagName="UPC.Input.Interact"),Prompt=(Verb=NSLOCTEXT("", "", "Pull"),Name=NSLOCTEXT("", "", "Lever")),PayloadSpec=/Script/UPCInteraction.UPCMontageInteractionPayloadSpec(Montage="/Game/Player/AM_Knight_PullLever.AM_Knight_PullLever",PlayRate=1.0))')

Mistakes

Items and equipment: fragments, hands, shields and stowing (AgentGuide/ItemsEquipment.md)

The item and its fragments

Hands and places

row = unreal.UPCHoldPlaceSpec()
row.import_text('(Place=(TagName="UPC.Place.Off"))')
eq.set_editor_property("HoldPlaces", [row])

Recipe: a shield in the left hand

shield_mesh = load("/Game/.../SM_Shield")
shield = new_data_asset(unreal.UPCItemDefinition, F, f"Item_{N}_Shield")
vis = unreal.new_object(unreal.UPCItemFragment_Visuals, outer=shield)
vis.set_editor_property("HeldMesh", shield_mesh)
eq = unreal.new_object(unreal.UPCItemFragment_Equippable, outer=shield)
eq.set_editor_property("bIsMainWeapon", False)
eq.set_editor_property("EquipmentTags", tags("UPC.Equipment.Shielded"))
row = unreal.UPCHoldPlaceSpec()
row.import_text('(Place=(TagName="UPC.Place.Off"))')
eq.set_editor_property("HoldPlaces", [row])
shield.set_editor_property("Fragments", [vis, eq])
save(shield)
 
inv = defaults(bp).get_editor_property("InventoryComponent")
items = list(inv.get_editor_property("StartingItems"))
items.append(shield)
inv.set_editor_property("StartingItems", items)
save(bp)

• The belt takes each starting item into its own slot and draws every one that fits beside what is held, so the sword (main hand) and the shield (off hand) are both drawn at the start. The slot keys 1 to 4 draw and put away each one.
• To draw an item the inventory holds from code at once, putting nothing away, as a loadout handed out in a level does: the equipment manager's EquipItemIfFree (server only), which draws it only while it is equippable, not drawn, carried and in reach and every place it needs is free.
• To give a character gear from Blueprint, on the server: the inventory's Add Item Definition, then Equip Item If Free on the equipment manager with the item it returns. A null answer means a place is taken, such as by another cape; Request Equip Item puts that one away first. Remove Item Instance takes the gear off as it leaves the inventory. For a game with no inventory, belt or weapons that only dresses a character, skip the inventory: Equip Item on the equipment manager (server) takes the item definition with no inventory item, puts away whatever holds the places it needs (places are gameplay tags, as many as the body's Body Places names) and returns the drawn instance, null when the body has no place for it; Unequip Item with that instance, or the one Get Instance In Place answers, takes it off. A player's equip request, RequestEquipItem, also takes an item in the Stash or a chest, moving it into the carried containers first.
• The shield's block and parry are its Guard fragment (AgentGuide/DamageDefense.md); the guard move goes in the sword's graph (AgentGuide/ActionGraphs.md).
• UPC.Equipment.Shielded sits on the character while the shield is drawn, so a transition or sub graph can require it.
• If the shield sits crooked, judge a correction from a capture and write it as the row's Offset, as AGENTS.md, Recipe 4, Step 5, does for the sword.

Stowing on the body

Worn gear: helmets, capes, armor and rings

eqm = defaults(bp).get_editor_property("EquipmentManagerComponent")
rows = list(eqm.get_editor_property("BodyPlaces"))
for place, socket in (("UPC.Place.Head", "head"), ("UPC.Place.Shoulders", "None"), ("UPC.Place.Ring.Left", "ring_01_l"), ("UPC.Place.Ring.Right", "ring_01_r")):
    row = unreal.UPCBodyPlace()
    row.import_text(f'(Place=(TagName="{place}"),Socket="{socket}")')
    found = [i for i, r in enumerate(rows) if str(unreal.GameplayTagLibrary.get_tag_name(r.get_editor_property("Place"))) == place]
    if found:
        rows[found[0]] = row
    else:
        rows.append(row)
eqm.set_editor_property("BodyPlaces", rows)
save(bp)
 
def worn(item, places):
    eq = unreal.new_object(unreal.UPCItemFragment_Equippable, outer=item)
    eq.set_editor_property("bIsMainWeapon", False)
    held = []
    for place in places:
        row = unreal.UPCHoldPlaceSpec()
        row.import_text(f'(Place=(TagName="{place}"))')
        held.append(row)
    eq.set_editor_property("HoldPlaces", held)
    return eq
 
helmet = new_data_asset(unreal.UPCItemDefinition, F, f"Item_{N}_Helmet")
vis = unreal.new_object(unreal.UPCItemFragment_Visuals, outer=helmet)
vis.set_editor_property("HeldMesh", load("/Game/.../SM_Helmet"))
helmet.set_editor_property("Fragments", [worn(helmet, ["UPC.Place.Head"]), vis])
save(helmet)
 
cape = new_data_asset(unreal.UPCItemDefinition, F, f"Item_{N}_Cape")
look = unreal.new_object(unreal.UPCItemFragment_WornMesh, outer=cape)
look.set_editor_property("Meshes", [load("/Game/.../SK_Cape")])
cape.set_editor_property("Fragments", [worn(cape, ["UPC.Place.Shoulders"]), look])
save(cape)
 
ring = new_data_asset(unreal.UPCItemDefinition, F, f"Item_{N}_Ring")
ring_eq = worn(ring, ["UPC.Place.Ring.Left", "UPC.Place.Ring.Right"])
ring_eq.set_editor_property("EquipmentTags", tags("UPC.State.Swift"))
ring_vis = unreal.new_object(unreal.UPCItemFragment_Visuals, outer=ring)
ring_vis.set_editor_property("HeldMesh", load("/Game/.../SM_Ring"))
ring.set_editor_property("Fragments", [ring_eq, ring_vis])
save(ring)

• Add each place tag to the project's tags first; the plugin declares the demo's places.
• A ring that sits crooked gets an Offset on each of its two rows, written into the row text as for the shield.

Mistakes

Paired Actions: finishers, counters and grabs (AgentGuide/PairedActions.md)

The asset

pa = new_data_asset(unreal.UPCPairedActionAsset, F, f"Paired_{N}_Execute")
atk = unreal.UPCPairedActionParticipant(role_id="Attacker")
atk.set_editor_property("Montage", am_exec_attacker)
atk.set_editor_property("bRequired", True)
vic = unreal.UPCPairedActionParticipant(role_id="Victim")
vic.set_editor_property("Montage", am_exec_victim)
vic.set_editor_property("bRequired", True)
cut = unreal.new_object(unreal.UPCPairedActionEvent_Damage, outer=pa)
cut.set_editor_property("DamageConfig", dmg_heavy)
cut.set_editor_property("LeaveHealthAtLeast", 1.0)     # an earlier blow leaves the victim alive for the killing blow
cut.set_editor_property("TimeSeconds", 0.6)
cut.set_editor_property("TargetRoleId", "Victim")
hit = unreal.new_object(unreal.UPCPairedActionEvent_Damage, outer=pa)
hit.set_editor_property("DamageConfig", dmg_heavy)
hit.set_editor_property("bKill", True)                 # takes all the health left, whatever defends the victim
hit.set_editor_property("TimeSeconds", 1.2)
hit.set_editor_property("TargetRoleId", "Victim")
atk.set_editor_property("Events", [cut, hit])
pa.set_editor_property("Participants", [atk, vic])
pa.set_editor_property("AnchorRoleId", "Victim")        # the victim stands still and the attacker lines up on it
pa.call_method("DeriveOffsetsFromMontages")
save(pa)
print(upc.validate_asset(pa))

Starting it

• From a combo: a move whose payload is UUPCPlayPairedActionPayload (Play Paired Action: Source PAIRED_ACTION with PairedAction, OwnerRoleId, TargetRoleId, PrimaryPicker; or PAIRED_ACTION_SETS with PairedActionSets), reached by a transition with a Paired Action Available condition (UUPCPairedActionCondition, Actions) or a Target State condition requiring a stun tag (AgentGuide/ActionGraphs.md). For a move the stick aims, such as a vault, make the PrimaryPicker a Proximity Scan (unreal.UPCPairedTargetPicker_Scan: Radius, MaxAngleDegrees, bArcFollowsMovementInput on), and give the node an ON_FAILED transition to the move that plays when nobody stands in that direction, such as a roll.
• A set of options: a Paired Action Set (UUPCPairedActionSet: GatherRadius, GatherArcDegrees, Options rows unreal.UPCPairedActionOption Action, OwnerRoleId, TargetRoleId, PrimaryPicker, RequiredTargetTags, TargetTeams, Priority), which one button searches. The demo sword's PairedActionSet_UPC_SwordExecute executes only the demo's Soulslike boss in its finisher stun: its one row requires UPC.Enemy.SoulslikeBoss, which BP_UPC_Boss_Soulslike carries in its CombatComponent CharacterTags, and UPC.State.Finishable, which that stun holds. For one action with its own montages per enemy type, put a type tag of the project's own (Enemy.Type.Heavy) in the enemy Blueprint's CombatComponent CharacterTags, add one row per type with a higher Priority, that tag in RequiredTargetTags and the type's own paired action as Action, and keep one catch-all row last with no RequiredTargetTags, which every other enemy gets.
• From the level: a UPC Paired Action Spot or UPC Paired Action Interactable component on an actor.

Mistakes

Editor Python: what can be set, and how (AgentGuide/Python.md)

Setting properties

• obj.set_editor_property("Name", value) takes the C++ name (bIsMainWeapon) or the Python name (is_main_weapon). It refuses a property the editor shows read-only, and it refuses a class-defaults-only property on anything that is not a template (an asset, a class default object, or an object inside an asset).
• Arrays come back as copies. Edit the list, then write the whole list back:

  rows = list(item.get_editor_property("Fragments"))
  rows.append(frag)
  item.set_editor_property("Fragments", rows)

• A struct you make in Python is not a template, so its class-defaults-only fields refuse set_editor_property. Several of this plugin's row structs are like that, among them unreal.UPCHoldPlaceSpec (Hold Places rows), unreal.UPCStowPlaceSpec (Stow Places rows), unreal.UPCContainerSpec (an inventory config's Containers rows), unreal.UPCCapacityBonus (a Capacity Bonus fragment's Bonuses), unreal.UPCWeightThreshold (a Weight Limit's Thresholds), unreal.UPCCategoryLimit (a Category Limit's Limits) and the ability set rows unreal.UPCAbilitySet_GameplayAbility and unreal.UPCAbilitySet_GameplayEffect; an interaction option's PayloadSpec refuses a field write too. A Combine Set's rows (unreal.UPCCombineRecipe, unreal.UPCCombineResult) take field writes. Write any row that refuses as text:

  row = unreal.UPCAbilitySet_GameplayAbility()
  row.import_text('(Ability="/Game/Player/GA_Knight_Heal.GA_Knight_Heal_C",InputTag=(TagName="UPC.Input.Special"))')

  Read a shipped row with row.export_text() to see the text form of each field.
• A struct read from an object is a copy: edit it, then write it back to the object with set_editor_property. Inside that copy, nested fields edit in place: s.state.applied_tags = tags("UPC.State.Blocking").
• A call that answers yes or no and also fills a value (unreal.UPCInventoryStatics.can_combine, the inventory's get_item_placement and can_item_leave) hands back the filled values and not the yes or no: one value comes back alone, several as a tuple, and None stands for no. answer = unreal.UPCInventoryStatics.can_combine(inv, item, target) is None when the two do not combine, else (results, reason). A call that returns a number and fills a value gives both: units, reason = inv.get_units_that_fit(item, 1, False).

Instanced objects

• Make one with unreal.new_object(cls, outer=<the asset that holds it>), set its properties, put it in the owner's list, then save the asset. The lists in this plugin: an item's Fragments, an inventory container's Rules, an inventory config's CarryRules and a Combine Set's Combines. Write the whole list back with set_editor_property: a list read from the asset is a copy, so adding to it without writing it back changes nothing and raises nothing.
• An object made without outer= belongs to no asset: its properties refuse a write ("cannot be edited on instances").
• Exception: for upc.set_node_settings and upc.set_transition_settings, make it with unreal.new_object(cls) and no outer; the call copies it into the graph.
• Never give a class default object as the outer (unreal.get_default_object(...)), not even to look at a class. The next object of that class with the same name takes it as its template, and the asset holding it fails to save.

Components on a Blueprint

• A component the C++ base creates (every component AUPCCharacterBase makes: EquipmentManagerComponent, InventoryComponent, ActionGraphComponent, MeleeTraceComponent, InputMappingComponent, AnimManagerComponent, VitalsComponent, DefenseComponent, TargetingComponent, TargetableComponent, TeamComponent, ApproachComponent, CombatComponent, InteractorComponent, AnimEffectComponent, AbilitySystemComponent, and the character's own CapsuleComponent, CharacterMovement and Mesh) is read from the class defaults: defaults(bp).get_editor_property("VitalsComponent"). Edit it there and save the Blueprint.
• A component the Blueprint adds (sprint, camera rig, speed modifier, stow visuals on the demo player) lives in its construction script. Read its template:

  sds = unreal.get_engine_subsystem(unreal.SubobjectDataSubsystem)
  handles = sds.k2_gather_subobject_data_for_blueprint(bp)
  for h in handles:
      data = unreal.SubobjectDataBlueprintFunctionLibrary.get_data(h)
      obj = unreal.SubobjectDataBlueprintFunctionLibrary.get_object_for_blueprint(data, bp)
      if isinstance(obj, unreal.UPCSprintComponent):
          sprint = obj

  Edit sprint, then unreal.BlueprintEditorLibrary.compile_blueprint(bp) and save(bp).
• Adding a component to a Blueprint:

  params = unreal.AddNewSubobjectParams(parent_handle=handles[0], new_class=unreal.UPCSpeedModifierComponent, blueprint_context=bp)
  new_handle, fail = sds.add_new_subobject(params)

  Then read it as above, set it, compile and save.

Montage sections

upc.set_montage_sections(montage, [("Light1", 0.0), ("Light2", 0.9), ("Light3", 1.8)])