SmartObjects

27 tools. Back to the index.

add_smart_object_definition_default_behavior

Additive.

Attach a definition-level default behavior (applied to slots without their own) to a USmartObjectDefinition; the private DefaultBehaviorDefinitions array is reached via FArrayProperty reflection.

Parameter	Type	Required	Description
definition_path	string	yes	Path to the USmartObjectDefinition asset
behavior_class	string	yes	Behavior class: short native name or /Script path; must derive from USmartObjectBehaviorDefinition

Returns: { definition_path: string, behavior_class: string, default_behavior_count: int, added: bool, saved: bool }

add_smart_object_slot

Additive, idempotent.

Append a named activity slot to a USmartObjectDefinition (idempotent on name).

Parameter	Type	Required	Description
definition_path	string	yes	Path to the USmartObjectDefinition asset
slot_name	string	yes	Unique name for the new slot
activity_tag	string	no	Optional FGameplayTag to attach to the slot; defaults to "Default"

Returns: { definition_path: string, slot_name: string, activity_tag: string, slot_count: int, added?: bool, already_existed?: bool, saved: bool }

add_smart_object_slot_behavior_definition

Additive.

Attach a behavior definition (class resolved by name) to a slot of a USmartObjectDefinition. The class must derive from USmartObjectBehaviorDefinition (e.g. GameplayBehaviorSmartObjectBehaviorDefinition). A behavior on every slot (or a default) makes the definition Validate()-valid.

Parameter	Type	Required	Description
definition_path	string	yes	Path to the USmartObjectDefinition asset
behavior_class	string	yes	Behavior class: short native name (e.g. "GameplayBehaviorSmartObjectBehaviorDefinition") or full /Script path
slot_index	number	no	Index of the slot to attach the behavior to

Returns: { definition_path: string, slot_index: int, behavior_class: string, behavior_count: int, saved: bool }

add_smart_object_slot_entrance_annotation

Additive.

Add an entrance (entry/exit point) annotation to a slot of a USmartObjectDefinition, including its navigation/trajectory fields.

Parameter	Type	Required	Description
definition_path	string	yes	Path to the USmartObjectDefinition asset
slot_index	number	no	Index of the slot to add the entrance to
offset	array	no	Optional [x, y, z] local-space offset of the entrance
rotation	array	no	Optional [pitch, yaw, roll] local-space rotation (degrees)
is_entry	boolean	no	Optional: entrance can be used to enter the slot (default true)
is_exit	boolean	no	Optional: entrance can be used to exit the slot (default true)
tags	array	no	Optional gameplay tag names identifying the entrance
trace_ground_location	boolean	no	Optional: adjust ground location with a line trace (default true).
check_transition_trajectory	boolean	no	Optional: check collisions on the transition from nav location to slot (default false).
selection_priority	string	no	Optional entrance selection priority: Lowest|Lower|Low|BelowNormal|Normal|AboveNormal|High|Higher|Highest (default Normal).
trajectory_start_height_offset	number	no	Optional height offset at the start of the transition check (default 80).
trajectory_slot_height_offset	number	no	Optional height offset at the slot for the transition check (default 40).
transition_check_radius	number	no	Optional radius of the transition trajectory check (default 10).

Returns: { definition_path: string, slot_index: int, entrance_count: int, data_count: int, saved: bool }

claim_smart_object

Destructive.

Claim a free slot on the Smart Object component of an actor in the editor world. Returns the canonical claim_handle (LexToString) for downstream release.

Parameter	Type	Required	Description
actor_label	string	yes	Editor label of the actor carrying the USmartObjectComponent
definition_path	string	no	Optional path to the definition; only used for reporting

Returns: { actor_label: string, definition_path: string, claim_handle: string, slot_id: string, is_claimed: bool, success: bool }

create_smart_object_definition

Additive.

Create (or load) a USmartObjectDefinition asset and seed it with N activity slots via the public DebugAddSlot API.

Parameter	Type	Required	Description
definition_name	string	yes	Name for the new Smart Object definition
package_path	string	no	Content folder; defaults to /Game/MCP
num_activity_slots	number	no	Number of slots to add; defaults to 1

Returns: { definition_path: string, definition_name: string, num_slots: int, created: bool, saved: bool }

find_smart_objects

Read-only.

Spatially query the SmartObject subsystem for slots within a box centered on a point (USmartObjectSubsystem::FindSmartObjects). HONEST GATE: the spatial index only populates once the subsystem runtime is initialized (BeginPlay/PIE); in the editor/headless world it is empty, so this returns success with an empty results list and a note rather than fabricating hits.

Parameter	Type	Required	Description
center	array	yes	[x, y, z] world-space center of the search box
radius	number	yes	Half-extent (uu) of the AABB search box around center
include_claimed	boolean	no	Optional: also return already-claimed slots (default false)
include_disabled	boolean	no	Optional: also return disabled slots (default false)

Returns: { center: [number, number, number], radius: number, results: [{ object_handle: string, slot_handle: string, actor_label: string }], count: int, note?: string }

get_smart_object_component_definition

Read-only.

Read the USmartObjectDefinition assigned to an actor's USmartObjectComponent and whether it is registered.

Parameter	Type	Required	Description
actor_label	string	yes	Editor label of the actor carrying the USmartObjectComponent

Returns: { actor_label: string, definition: string, has_definition: bool, registered: bool }

get_smart_object_definition_summary

Read-only.

Read back the object-level state of a USmartObjectDefinition: activity tags, tag policies, user-filter presence, slot count, world-space bounds, and a structural Validate() pass with any error messages.

Parameter	Type	Required	Description
definition_path	string	yes	Path to the USmartObjectDefinition asset

Returns: { definition_path: string, slot_count: int, activity_tags: [string], merging_policy: string, filtering_policy: string, user_filter_is_empty: bool, bounds: { min: [number, number, number], max: [number, number, number] }, is_valid: bool, validation_errors: [string], default_behavior_count: int }

get_smart_object_info

Read-only.

Get slot count, activity tag set, and the number of registered actors for a USmartObjectDefinition.

Parameter	Type	Required	Description
definition_path	string	yes	Path to the USmartObjectDefinition asset

Returns: { definition_path: string, slot_count: int, activity_tags: [string], registered_actor_count: int }

get_smart_object_slot_entrance_annotations

Read-only.

List a slot's entrance annotations with all their fields (round-trip reader for add_smart_object_slot_entrance_annotation, including the navigation/trajectory fields).

Parameter	Type	Required	Description
definition_path	string	yes	Path to the USmartObjectDefinition asset.
slot_index	number	no	Index of the slot to read.

Returns: { definition_path: string, slot_index: int, entrance_count: int, entrances: [ { offset: [float], rotation: [float], is_entry: bool, is_exit: bool, tags: [string], trace_ground_location: bool, check_transition_trajectory: bool, selection_priority: string, trajectory_start_height_offset: float, trajectory_slot_height_offset: float, transition_check_radius: float } ] }

get_smart_object_slots_detail

Read-only.

Read back per-slot detail (name, enabled, offset, rotation, activity tags, behavior/data counts) of a USmartObjectDefinition.

Parameter	Type	Required	Description
definition_path	string	yes	Path to the USmartObjectDefinition asset

Returns: { definition_path: string, slot_count: int, slots: [{ index: int, name: string, enabled: bool, offset: [number, number, number], rotation: [number, number, number], activity_tags: [string], user_filter_is_empty: bool, behavior_count: int, behavior_classes: [string], data_count: int }] }

register_smart_object_actor

Additive.

Spawn an empty actor in the editor world, attach a USmartObjectComponent pointing at the given definition, and register it with USmartObjectSubsystem. Note: the definition must already have a behavior definition (per-slot or default) or the subsystem silently rejects the handle (see handle_valid).

Parameter	Type	Required	Description
actor_label	string	yes	Editor label for the new actor
definition_path	string	yes	Path to the USmartObjectDefinition asset
location	array	no	Optional [x, y, z] world location; defaults to (0,0,0)

Returns: { actor_label: string, actor_name: string, definition_path: string, has_component: bool, registered: bool, handle_valid: bool }

release_smart_object

Destructive.

Release a Smart Object claim. The only headless-safe path is to pass actor_label so the subsystem can unregister the component (which releases any claim it holds). FSmartObjectUserHandle is private in UE 5.7, so a claim_handle-only path is not possible without a C++ extension.

Parameter	Type	Required	Description
actor_label	string	no	Optional editor label of the actor whose component to unregister (releases all its claims)
claim_handle	string	no	Optional canonical claim string; documented limitation: round-trip is not public in 5.7

Returns: { actor_label: string, released: bool } | (error: "release_smart_object: ...")

remove_smart_object_definition_default_behavior

Destructive, idempotent.

Remove a definition-level default behavior (by index) from a USmartObjectDefinition; the private DefaultBehaviorDefinitions array is reached via FArrayProperty reflection and resized through FScriptArrayHelper. Idempotent: a behavior_index past the end returns already_absent without error.

Parameter	Type	Required	Description
definition_path	string	yes	Path to the USmartObjectDefinition asset
behavior_index	number	no	Index into DefaultBehaviorDefinitions to remove

Returns: { definition_path: string, behavior_index: int, default_behavior_count: int, removed: bool, already_absent: bool, saved: bool }

remove_smart_object_slot

Destructive.

Remove the slot at slot_index from a USmartObjectDefinition asset, together with its behaviors, tags and annotations; later slots shift down one index, so re-read indices with get_smart_object_slots_detail. Saves the asset; a failed save returns an error with the removal kept in memory. An invalid slot_index is an error. Undoable (one editor transaction). To turn a slot off while keeping indices stable use set_smart_object_slot_enabled; add_smart_object_slot appends one.

Parameter	Type	Required	Description
definition_path	string	yes	Path to the USmartObjectDefinition asset
slot_index	number	no	Index of the slot to remove

Returns: { definition_path: string, slot_index: int, slot_count: int, removed: bool, saved: bool }

remove_smart_object_slot_behavior_definition

Destructive, idempotent.

Remove a behavior definition from a slot of a USmartObjectDefinition by its index in the slot's BehaviorDefinitions array. Idempotent: a behavior_index past the end returns already_absent without error.

Parameter	Type	Required	Description
definition_path	string	yes	Path to the USmartObjectDefinition asset.
slot_index	number	no	Index of the slot to edit.
behavior_index	number	no	Index into the slot's BehaviorDefinitions to remove.

Returns: { definition_path: string, slot_index: int, behavior_index: int, behavior_count: int, removed: bool, already_absent: bool, saved: bool }

remove_smart_object_slot_entrance_annotation

Destructive, idempotent.

Remove an entrance annotation (by its index among the slot's entrance annotations) from a slot of a USmartObjectDefinition. entrance_index counts only FSmartObjectSlotEntranceAnnotation entries in the slot's DefinitionData (mirror of add_smart_object_slot_entrance_annotation, inverted). Idempotent: an entrance_index past the number of entrances returns already_absent without error.

Parameter	Type	Required	Description
definition_path	string	yes	Path to the USmartObjectDefinition asset
slot_index	number	no	Index of the slot to edit
entrance_index	number	no	Index among the slot's entrance annotations to remove (0-based; entrances only, not all definition data)

Returns: { definition_path: string, slot_index: int, entrance_index: int, entrance_count: int, data_count: int, removed: bool, already_absent: bool, saved: bool }

set_component_definition

Destructive, idempotent.

Set (change) the USmartObjectDefinition on the USmartObjectComponent of an actor in the editor world.

Parameter	Type	Required	Description
actor_label	string	yes	Editor label of the actor carrying the USmartObjectComponent
definition_path	string	yes	Path to the USmartObjectDefinition asset to assign

Returns: { actor_label: string, definition_path: string, definition: string, registered: bool, set: bool }

set_smart_object_definition_activity_tags

Destructive, idempotent.

Set the object-level activity tags of a USmartObjectDefinition, and optionally the tag merging/filtering policies.

Parameter	Type	Required	Description
definition_path	string	yes	Path to the USmartObjectDefinition asset
activity_tags	array	no	Gameplay tag names for the definition's object-level activity tags
merging_policy	string	no	Optional activity-tag merging policy: "Combine" (default) or "Override"
filtering_policy	string	no	Optional user-tag filtering policy: "NoFilter", "Combine", or "Override"

Returns: { definition_path: string, activity_tags: [string], merging_policy: string, filtering_policy: string, saved: bool }

set_smart_object_definition_user_tag_filter

Destructive, idempotent.

Set the object-level user tag filter (a gameplay tag query) of a USmartObjectDefinition, built from a tag list and a match mode.

Parameter	Type	Required	Description
definition_path	string	yes	Path to the USmartObjectDefinition asset
user_tags	array	no	Gameplay tag names the filter query matches against
match	string	no	Match mode: "any" (default), "all", or "none"

Returns: { definition_path: string, user_tags: [string], match: string, filter_is_empty: bool, saved: bool }

set_smart_object_slot_activity_tags

Destructive, idempotent.

Replace a slot's activity tags (which activity it supports) on a USmartObjectDefinition, addressed by slot_index.

Parameter	Type	Required	Description
definition_path	string	yes	Path to the USmartObjectDefinition asset
slot_index	number	no	Index of the slot to edit (from get_smart_object_slots_detail)
activity_tags	array	no	Gameplay tag names to set as the slot's activity tags; tags not registered are skipped

Returns: { definition_path: string, slot_index: int, activity_tags: [string], saved: bool }

set_smart_object_slot_enabled

Destructive, idempotent.

Set the authored enabled flag (bEnabled) of the slot at slot_index in a USmartObjectDefinition asset, then save it: the initial state that smart objects built from this definition start with. enabled defaults to true when omitted. An invalid slot_index is an error, and a failed save returns an error with the change kept in memory. Undoable (one editor transaction). Use remove_smart_object_slot to delete the slot instead, and get_smart_object_slots_detail to read slots back.

Parameter	Type	Required	Description
definition_path	string	yes	Path to the USmartObjectDefinition asset
slot_index	number	no	Index of the slot to edit
enabled	boolean	no	Whether the slot is enabled

Returns: { definition_path: string, slot_index: int, enabled: bool, saved: bool }

set_smart_object_slot_runtime_tags

Destructive, idempotent.

Replace a slot's initial runtime tags (FGameplayTagContainer) on a USmartObjectDefinition, addressed by slot_index. Tags not registered in the project are skipped.

Parameter	Type	Required	Description
definition_path	string	yes	Path to the USmartObjectDefinition asset.
slot_index	number	no	Index of the slot to edit.
runtime_tags	array	no	Gameplay tag names to set as the slot's runtime tags.

Returns: { definition_path: string, slot_index: int, runtime_tags: [string], saved: bool }

set_smart_object_slot_transform

Destructive, idempotent.

Set the local offset and/or rotation (degrees) of the slot at slot_index in a USmartObjectDefinition asset, relative to the smart object's owner, then save it. Each of offset and rotation is written only when given with 3 numbers; otherwise it keeps its value. An invalid slot_index is an error, and a failed save returns an error with the change kept in memory. Undoable (one editor transaction). Read slots back with get_smart_object_slots_detail; set_smart_object_slot_enabled and set_smart_object_slot_activity_tags edit other slot fields.

Parameter	Type	Required	Description
definition_path	string	yes	Path to the USmartObjectDefinition asset
slot_index	number	no	Index of the slot to edit
offset	array	no	Optional [x, y, z] local offset
rotation	array	no	Optional [pitch, yaw, roll] local rotation (degrees)

Returns: { definition_path: string, slot_index: int, offset: [number, number, number], rotation: [number, number, number], saved: bool }

set_smart_object_slot_user_tag_filter

Destructive, idempotent.

Set a slot's user tag filter (a gameplay tag query controlling which users may use it), built from a tag list and a match mode.

Parameter	Type	Required	Description
definition_path	string	yes	Path to the USmartObjectDefinition asset
slot_index	number	no	Index of the slot to edit
user_tags	array	no	Gameplay tag names the filter query matches against
match	string	no	Match mode: "any" (default), "all", or "none"

Returns: { definition_path: string, slot_index: int, user_tags: [string], match: string, filter_is_empty: bool, saved: bool }

use_smart_object

Destructive, idempotent.

Claim a free slot on an actor's SmartObject component and immediately mark it occupied (USmartObjectSubsystem::MarkSlotAsOccupied), driving a behavior definition. Single-call claim+occupy keyed by actor_label (an FSmartObjectClaimHandle cannot be rebuilt from a string, so a two-step claim_handle path is impossible). HONEST GATE: the component handle only registers once the subsystem runtime is initialized (PIE/BeginPlay); headless it is invalid and this returns a clean error. Idempotent: an already-occupied slot returns already_occupied without re-occupying.

Parameter	Type	Required	Description
actor_label	string	yes	Editor label of the actor carrying the USmartObjectComponent
behavior_class	string	no	Optional behavior definition class (short native name or /Script path); defaults to USmartObjectBehaviorDefinition

Returns: { actor_label: string, slot_id: string, behavior_definition: string, is_occupied: bool, already_occupied: bool, success: bool }