Mass

27 tools. Back to the index.

add_mass_trait

Additive, idempotent.

Adds a trait (a concrete UMassEntityTraitBase subclass) to a UMassEntityConfigAsset and saves the config. Idempotent: if the config already holds a trait of exactly that class, itself or through its parent config chain, nothing is added or saved and the reply has added=false, already_existed=true and that trait's trait_path. trait_class takes a reflected name with or without its U prefix, or a /Script path; an unknown or non-trait class is an error, but an abstract one is not refused: the engine creates it behind an ensure and warns it is nulled out on save. Edit it with set_mass_trait_property; remove_mass_trait is the inverse; add_mass_trait_to_entity tags a live entity instead.

Parameter	Type	Required	Description
config_path	string	yes	Asset path to the UMassEntityConfig
trait_class	string	yes	Trait class name to add (e.g. UMassMovementTrait)

Returns: { config_path, trait_class, trait_path, trait_count, added, already_existed, saved }

add_mass_trait_to_entity

Additive.

Add an FMassTag (a tag, not a trait or fragment, despite the name) to a Mass entity of the editor world (not PIE) by archetype migration. Caveat: EVERY entity sharing that archetype gets the tag, not only this one. Returns old_archetype_id, new_archetype_id and changed; inverse: remove_mass_trait_from_entity.

Parameter	Type	Required	Description
entity_handle	string	yes	Entity handle as "Index:SerialNumber", two integers such as "12:3" (no braces); a no-longer-valid entity is an error
tag	string	yes	Reflected name of an FMassTag struct without the F prefix, as list_mass_trait_types returns it (e.g. "MassOffLODTag"); /Script paths do not resolve

Returns: { entity_handle, old_archetype_id, new_archetype_id, tag, changed }

count_mass_entities

Read-only.

Count the live Mass entities of the editor world (not a PIE world), read-only. Returns total, archetype_count and per_archetype [{archetype_id, count}]; list_mass_archetypes adds fragment counts, query_mass_entities counts by fragment or tag.

No parameters.

Returns: { total: int, archetype_count: int, per_archetype: [{ archetype_id, count }] }

create_mass_entity_config

Additive.

Create a UMassEntityConfigAsset (an empty list of Mass traits) at package_path/config_name and save it; an existing config there is loaded and re-saved instead (created:false). Returns config_path, trait_count and saved. Add traits with add_mass_trait, then link it with set_mass_spawner_entity_types.

Parameter	Type	Required	Description
config_name	string	yes	Name of the UMassEntityConfig asset
package_path	string	no	Target content package path where the asset is created (default /Game/MCP)

Returns: { config_path, config_name, trait_count, created, saved }

create_mass_spawner_actor

Additive.

Spawn an AMassSpawner actor into the editor world at location (zero rotation) and label it; the level is not saved. config_path is only echoed, not linked (config_linked:false): link configs with set_mass_spawner_entity_types. Use a unique label, since the spawner tools take the first match.

Parameter	Type	Required	Description
actor_label	string	yes	Editor label for the new spawner actor
config_path	string	no	Optional entity config asset path (echoed; not linked)
location	array	no	Optional spawn location [X, Y, Z] in world units (cm), default the origin; ignored unless it holds exactly 3 numbers

Returns: { actor_label, actor_name, config_path, config_linked, note }

despawn_mass_entities

Destructive.

Trigger entity despawning on a AMassSpawner (DoDespawning from the FTSTicker path, outside Mass processing); inverse of spawn_mass_entities. Reports the global Mass entity-count delta; no-op (was_empty) when this spawner spawned nothing.

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

Returns: { actor_label, entity_count_before, entity_count_after, despawned, was_empty, note }

destroy_all_mass_entities

Destructive.

Destroy every Mass entity in the editor world (not a PIE world), archetype by archetype, with no undo. Returns destroyed_count, before_count and after_count. For one entity use destroy_mass_entity; to despawn what one spawner made use despawn_mass_entities.

No parameters.

Returns: { destroyed_count: int, before_count: int, after_count: int }

destroy_mass_entity

Destructive.

Destroy a single Mass entity by its handle (Index:SerialNumber).

Parameter	Type	Required	Description
entity_handle	string	yes	"{Index}:{SerialNumber}" string returned by spawn/query.

Returns: { entity_handle, destroyed: bool, already_destroyed: bool }

fire_mass_signal

Destructive.

Broadcast a signal to a single entity or to all entities (when entity_handle omitted). The tool does NOT validate the signal name — UMassSignalSubsystem::SignalEntity silently no-ops on unknown names, which is the documented engine behavior.

Parameter	Type	Required	Description
signal	string	yes	Signal name (FName).
entity_handle	string	no	Optional. "{Index}:{SerialNumber}". If omitted, broadcasts to all live entities.

Returns: { signal, dispatched_count: int, broadcast: bool }

get_mass_config_parent

Read-only.

Read the parent config path of a UMassEntityConfigAsset (inverse of set_mass_config_parent).

Parameter	Type	Required	Description
config_path	string	yes	Asset path of the UMassEntityConfigAsset

Returns: { config_path, parent_config_path, has_parent, config_class }

get_mass_entity_info

Read-only.

Inspect one Mass entity of the editor world (not PIE) by handle, read-only: valid, built, archetype_id and the fragment types of its archetype. A destroyed or unknown handle returns valid:false rather than an error; a malformed handle is an error.

Parameter	Type	Required	Description
entity_handle	string	yes	Entity handle as "Index:SerialNumber", two integers such as "12:3" (no braces)

Returns: { entity_handle, valid, built, archetype_id, fragment_count, fragment_types: [string] }

get_mass_spawner_count

Read-only.

Read the current spawn count of an AMassSpawner (inverse of set_mass_spawner_count).

Parameter	Type	Required	Description
actor_label	string	yes	Actor label of the AMassSpawner

Returns: { actor_label, actor_name, count }

get_mass_spawner_entity_types

Read-only.

Read the EntityTypes array of an AMassSpawner (inverse of set_mass_spawner_entity_types).

Parameter	Type	Required	Description
actor_label	string	yes	Actor label of the AMassSpawner

Returns: { actor_label, actor_name, entity_type_count, entity_types:[{entity_config, proportion}] }

get_mass_spawner_info

Read-only.

Read an AMassSpawner actor of the editor world, found by actor label (first match), read-only. Returns actor_name, count and entity_types [{entity_config, proportion}] with entity_type_count; the entities it spawned are counted by count_mass_entities instead.

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

Returns: { actor_label, actor_name, count, entity_type_count, entity_types: [{ entity_config, proportion }] }

get_mass_trait_property

Read-only.

Read a property (name or dotted path) of a trait in a Mass config via reflection (ExportText).

Parameter	Type	Required	Description
config_path	string	yes	Asset path to the UMassEntityConfigAsset
trait_class	string	yes	Trait class name; the trait must be on the config
property_name	string	yes	Property name or dotted path

Returns: { config_path, trait_class, property_name, value, type }

list_mass_archetypes

Read-only.

List every Mass archetype of the editor world (not a PIE world) with its live-entity and fragment counts, read-only. Returns archetype_count, total_entities and archetypes [{archetype_id, entity_count, fragment_count}]; get_mass_entity_info names the fragments of one entity.

No parameters.

Returns: { archetype_count: int, total_entities: int, archetypes: [{ archetype_id: string, entity_count: int, fragment_count: int }] }

list_mass_signals

Read-only.

ALWAYS RETURNS AN EMPTY LIST -- do not use it to discover signal names. Honest engine gap: UMassSignalSubsystem::NamedSignals is protected with no public enumeration API, so the tool can only answer count:0 plus a note. Call fire_mass_signal directly with a name you already know; the engine silently no-ops on an unknown one.

No parameters.

Returns: { count: 0, signals: [], note: "..." }

list_mass_trait_types

Read-only.

Enumerate every UScriptStruct class derived from FMassTag (the zero-size tag markers — what BatchChangeTagsForEntities accepts). Filters out abstract and editor-only.

Parameter	Type	Required	Description
include_abstract	boolean	no	If true (default false), include abstract tags too.

Returns: { count, traits: [{ name, path }] }

list_mass_traits

Read-only.

List the traits a UMassEntityConfigAsset holds itself (not those inherited from its parent config), read-only, in config order. Returns config_path, trait_count and traits [{class, name}]; edit them with add_mass_trait, remove_mass_trait and set_mass_trait_property.

Parameter	Type	Required	Description
config_path	string	yes	Asset path to the UMassEntityConfig

Returns: { class, name, config_path, trait_count, traits }

query_mass_entities

Read-only.

Count entities matching a fragment/tag requirement. Requires "fragment" (UScriptStruct path or name) and optional "presence" ("All"|"Any"|"None" — default "All"). For tag-only queries use "tag" (UScriptStruct path).

Parameter	Type	Required	Description
fragment	string	no	Script struct path or name (e.g. "/Script/MassMovement.MassMovementFragment" or "FMassMovementFragment").
tag	string	no	Optional. Same format as fragment. Use to require an FMassTag marker.
presence	string	no	"All" (default), "Any", or "None".

Returns: { matching_count: int, fragment, tag, presence }

remove_mass_trait

Destructive.

Remove a trait from a Mass entity config (inverse of add_mass_trait)

Parameter	Type	Required	Description
config_path	string	yes	Asset path to the UMassEntityConfig
trait_index	number	no	Index of the trait to remove (mutually exclusive with trait_class)
trait_class	string	no	Trait class name to remove; removes the first trait whose class is a child of it (mutually exclusive with trait_index)

Returns: { config_path, removed, removed_trait_class, removed_index, trait_count, saved }

remove_mass_trait_from_entity

Destructive.

Remove an FMassTag from a Mass entity of the editor world (not PIE) by archetype migration; inverse of add_mass_trait_to_entity. Caveat: the tag is removed from EVERY entity sharing that archetype, not only this one. Returns old_archetype_id, new_archetype_id and changed (false when nothing moved).

Parameter	Type	Required	Description
entity_handle	string	yes	Entity handle as "Index:SerialNumber", two integers such as "12:3" (no braces); a no-longer-valid entity is an error
tag	string	yes	Reflected name of the FMassTag struct to remove, without the F prefix, as list_mass_trait_types returns it (e.g. "MassOffLODTag"); /Script paths do not resolve

Returns: { entity_handle, old_archetype_id, new_archetype_id, tag, changed }

set_mass_config_parent

Destructive, idempotent.

Set the parent (base) config of a UMassEntityConfigAsset for trait inheritance.

Parameter	Type	Required	Description
config_path	string	yes	Asset path to the child UMassEntityConfigAsset
parent_config_path	string	yes	Asset path to the parent UMassEntityConfigAsset

Returns: { config_path, parent_config_path, parent, set, saved }

set_mass_spawner_count

Destructive, idempotent.

Set the spawn count on an AMassSpawner (reflection over its protected Count property).

Parameter	Type	Required	Description
actor_label	string	yes	Editor label of the AMassSpawner
count	number	yes	New spawn count

Returns: { actor_label, count, set }

set_mass_spawner_entity_types

Destructive, idempotent.

Link Mass entity configs to a spawner's EntityTypes (written by reflection: the array is protected).

Parameter	Type	Required	Description
actor_label	string	yes	Editor label of the AMassSpawner
config_paths	array	yes	Array of UMassEntityConfigAsset asset paths to set as the spawner's entity types

Returns: { actor_label, entity_type_count, linked, set }

set_mass_trait_property

Destructive, idempotent.

Set a property (name or dotted path) on a trait in a Mass config via reflection (ImportText).

Parameter	Type	Required	Description
config_path	string	yes	Asset path to the UMassEntityConfigAsset
trait_class	string	yes	Trait class name; the trait must already be on the config (e.g. MassVelocityRandomizerTrait)
property_name	string	yes	Property name or dotted path (e.g. MaxSpeed, or Movement.HighResSpeed)
value	string	yes	String value parsed by FProperty::ImportText_Direct

Returns: { config_path, trait_class, property_name, value, set, saved }

spawn_mass_entities

Additive.

Trigger entity spawning on a AMassSpawner (DoSpawning from the FTSTicker path, outside Mass processing); reports the global Mass entity-count delta.

Parameter	Type	Required	Description
actor_label	string	yes	Editor label of the AMassSpawner actor
count	number	no	Informational only; accepted but does not bound the spawn (default 0)

Returns: { actor_label, entity_count_before, entity_count_after, spawned, note }