Relationship C++ API

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

Include RelationshipComponent.h, RelationshipProfile.h, and RelationshipSubsystem.h. The component owns directional runtime overrides. The subsystem owns lifecycle and persistence coordination. FRelationshipChangedEvent is emitted after a committed value change; it includes source subject, target subject, metric, old value, new value, and delta.

V1.1 Runtime Edit

URelationshipComponent returns FRelationshipMutationResult from the authoritative methods:

FRelationshipMutationResult SetRelationshipValue(const FGameplayTag& TargetSubjectId, const FGameplayTag& MetricId, int32 RequestedValue);
FRelationshipMutationResult AddRelationshipValue(const FGameplayTag& TargetSubjectId, const FGameplayTag& MetricId, int32 Delta);
FRelationshipMutationResult ResetRelationshipMetric(const FGameplayTag& TargetSubjectId, const FGameplayTag& MetricId);
FRelationshipMutationResult ResetRelationshipWithTarget(const FGameplayTag& TargetSubjectId);

Set, Add, and Reset Metric support conditional safe reverts from Runtime Controls; Reset Relationship With Target does not. Runtime Controls journals each result and calls these same APIs for normal Runtime Edit. The separate Runtime Inspector only observes the resulting state.

Editor tooling uses ApplyEditorDebugOverride under WITH_EDITOR. The seam preserves structural validation and the absolute 0..100 domain while bypassing only authored Floor/Ceiling policy. It is not a gameplay or shipping API.

RelationshipDirectorProbabilityBridge is retired. For optional Probability-backed checks, use DirectorBridge Relationship.Probability. Relationship core remains independent of Probability Director and DirectorBridge. See Integrations.

Runtime component lifecycle observation

URelationshipSubsystem::GetRegisteredComponents() returns live Relationship source components in deterministic source SubjectId order. The snapshot exposes the subsystem’s existing weak live registry; dormant sources and directed target identities are not registry entries.

Runtime consumers can observe OnRelationshipComponentRegistered and OnRelationshipComponentUnregistered. Bind both native delegates first, then enumerate the current snapshot and de-duplicate by component pointer. Notifications run synchronously on the game thread after the owner registry transition. Components register and unregister through their existing lifecycle, with subsystem teardown clearing live entries and reporting unregistration. This is transport-neutral and does not change directed source-to-target semantics.