unreal.MetaHumanCrowdAppearanceProvider

class unreal.MetaHumanCrowdAppearanceProvider(outer: Object | None = None, name: Name | str = 'None')

Bases: Object

Base class for objects that decide which appearance is used for each spawned crowd entity.

Subclass this (in C++ or Blueprint) and assign your subclass to the AppearanceProviderClass property on the MetaHuman Crowd Visualization trait.

The same provider object handles every spawn/despawn for that class in that world, so it is safe to hold persistent state.

Typical usage:

  1. Override Initialize to inspect the pre-registered MHIs and assemble any extra MHIs you want

    to make available. Call Subsystem->RegisterInstance(MyAssembledInstance) for each new MHI.

  2. Override AcquireAppearance to pick an appearance for a new entity.

    Use Subsystem->TryGetAppearanceHandleForInstance(MHI) to look up the handle for any MHI you

    already know about (whether pre-registered or registered by this provider).

    The world location of the spawn is provided so you can vary appearance by location.

  3. Override OnEntityDespawned to update bookkeeping when an entity is destroyed. This fires on actual entity destruction, not on temporary LOD-driven invisibility.

  4. To grow the pool at runtime, create a new MHI and call RegisterInstance.

    To shrink the pool, call UnregisterInstance(Handle). The subsystem refcounts handles, so a handle that is still in use by entities will be physically released only when the last such entity is destroyed.

C++ Source:

  • Plugin: MetaHumanCrowd

  • Module: MetaHumanCrowd

  • File: MetaHumanCrowdAppearanceProvider.h

acquire_appearance(subsystem, spawn_location) → MetaHumanCrowdAppearanceHandle

Called for each new crowd entity to determine which appearance it should use.

Parameters:

  • subsystem (MetaHumanMassRepresentationSubsystem) – The owning representation subsystem, useful for registering more instances on demand.

  • spawn_location (Vector) – World-space location at which the entity is being spawned.

Returns:

A handle previously obtained from RegisterInstance. Returning an invalid handle falls back to the trait’s CharacterInstances pool if one is set, or leaves the entity with no appearance otherwise.

Return type:

MetaHumanCrowdAppearanceHandle

initialize(subsystem, pre_registered_instances) → None

Called once when this provider is first created for a world.

The PreRegisteredInstances array contains the MetaHuman Instances that were already registered with the subsystem before this provider was created – typically the contents of the trait’s CharacterInstances property. To obtain their handles call Subsystem->TryGetAppearanceHandleForInstance(MHI).

Use this opportunity to assemble any additional MHIs you want to add to the pool, and call Subsystem->RegisterInstance for each.

Parameters:
on_entity_despawned(subsystem, handle) → None

Called when an entity that was assigned an appearance by this provider is despawned.

Does not fire for temporary LOD-driven invisibility, only when the entity itself is destroyed.

Parameters:
shutdown(subsystem) → None

Called when this provider’s owning subsystem is being torn down.

Parameters:

subsystem (MetaHumanMassRepresentationSubsystem)