Character State C++ API

Review draft. This source page has not completed website editorial and release-specific verification.

Include CharacterStateComponent.h, CharacterStateTypes.h, and CharacterStatePersistence.h. Access the component on the participant Actor and call the typed query/mutation APIs. Use FCharacterStateValueSnapshot and FCharacterStateChangedEvent for value/event transport, and UCharacterStateSubsystem::CapturePersistenceSnapshot / RestorePersistenceSnapshot for persistence.

The native mutation status is ECharacterStateMutationStatus. Changed is committed state change, NoChange is an idempotent request, and Rejected leaves authoritative state unchanged.

Runtime component lifecycle registry

UCharacterStateSubsystem is scoped to one UGameInstance. GetRegisteredComponents() returns a deterministic snapshot of live registered components from that subsystem’s existing weak identity maps. The returned array is temporary and does not keep components alive. The component’s GetTargetIdentity() is valid when registration is reported, and subsystem identity lookup resolves to that same component.

Consumers should subscribe to OnComponentRegistered() and OnComponentUnregistered() before enumerating GetRegisteredComponents(). A component may be observed both by a notification and by the initial snapshot; make binding idempotent by component identity. Registration notification occurs after runtime initialization, identity assignment, registry insertion, and any dormant-state restoration. Unregistration notification occurs after registry removal while the component remains alive and its identity is still readable, allowing consumers to release delegate bindings.

These native lifecycle delegates are GameInstance-local and transport-neutral. They do not replace or alter OnStateChanged(), Blueprint state-change events, typed mutations, or persistence behavior. The lifecycle API is intended for game-thread consumers.

Local command execution

UCharacterStateSubsystem::ExecuteCommand is a Blueprint-callable local owner API. It generates a request ID, executes through Character State validation and mutation, and returns the owner acknowledgement without requiring SignalBus. Native C++ integrations that already have a request ID can call ExecuteCommandMessage with an FCharacterStateCommandMessage; the owner preserves that ID and source context through Changed and threshold notifications. Both entry points use the same owner execution path.

Command/result types are declared in CharacterStateCommandTypes.h; event contracts are declared in CharacterStateEventTypes.h. Native OnStateChanged() and OnThresholdCrossed() are always available. Optional SignalBus transport belongs to DirectorBridge.

Editor-only Runtime Edit seam

Character State Runtime Controls’ Advanced Debug Override uses the non-Blueprint WITH_EDITOR API UCharacterStateComponent::ApplyEditorDebugOverride with FCharacterStateEditorMutationRequest. This seam remains owned by Character State and reuses the normal mutation validator, commit path, and threshold crossing behavior. It bypasses only the authored Allow Runtime Changes policy gate. It is absent from shipping-facing builds and does not expose private runtime containers.