unrealxu/unrealengine5-skills/ue5-world-interaction

Quick Start

• Define interaction model: overlap-driven, trace-driven, or explicit use key.
• Define actor set: pickup actor, optional spawner, optional visual mapping data asset.
• Output runtime state transitions from spawn to interaction resolution.

API Anchors (UE5.6-UE5.8)

• Detection anchors:
• USphereComponent, UBoxComponent
• UPrimitiveComponent::OnComponentBeginOverlap
• UPrimitiveComponent::OnComponentEndOverlap
• FHitResult
• Trace anchors:
• UWorld::LineTraceSingleByChannel(...)
• UWorld::SweepSingleByChannel(...)
• UKismetSystemLibrary::SphereTraceSingle(...)
• Lifecycle anchors:
• AActor::SetActorHiddenInGame(...)
• AActor::SetActorEnableCollision(...)
• AActor::Destroy(...)
• AActor::SetActorTickEnabled(...)
• Networking anchors:
• server authority validation for interaction success
• replicated result state for client feedback

Interaction Stage Contract

• Every interaction feature must define:
• Detection source (overlap/trace/use-key)
• Eligibility checks (distance, tags, inventory/capacity, authority)
• Success and failure result payloads
• Feedback path (VFX/SFX/UI)
• Post-interaction lifecycle policy (destroy/disable/cooldown/respawn)
• If any item is missing, interaction behavior is underspecified.

Workflow

1) Actor and Component Setup

• Build root + collision + visual components with explicit collision channels.
• Define default states (active, cooldown, consumed) and replication needs.
• Keep collision shape and bounds aligned with intended interaction distance.

2) Detection Path

• Overlap model: bind begin/end overlap delegates on collision component.
• Trace model: run line/sphere traces on input request and validate hit actor/component.
• Keep detection deterministic by explicit channels/profiles.

3) Eligibility and Authority

• Validate target state, range, actor validity, and gameplay conditions.
• In multiplayer, validate success on server before mutating shared state.
• Return structured failure reason on rejection.

4) Resolve Interaction

• On success: apply effect (grant item, trigger state change, start cooldown).
• On failure: keep state stable and emit reason-specific feedback.
• Prevent re-entrant execution during in-progress resolution.

5) Feedback Path

• Emit VFX/SFX/UI feedback for both success and failure paths.
• Separate cosmetic-only effects from authoritative gameplay mutations.
• Keep feedback idempotent for repeated client updates.

6) Lifecycle and Cleanup

• Choose lifecycle explicitly: destroy, hide+disable collision, or reuse via respawn timer.
• If spawner exists, track spawned instances and cleanup on reset/despawn.
• Disable tick for dormant interaction actors when not needed.

Constraints

• Keep interaction validation server-authoritative in multiplayer.
• Ensure collision channels and trace responses are explicit.
• Keep spawner randomization deterministic when reproducibility is needed.
• Avoid hidden side effects in Tick without clear need.
• Do not destroy actors before broadcasting required success/failure feedback.
• Keep overlap and trace paths functionally equivalent when both are enabled.

Failure Handling

• Symptom: overlap never triggers.
• Locate: collision enabled state, overlap flags, collision channel responses.
• Fix: enable overlap generation, set proper channel responses, verify component bounds.
• Symptom: trace path misses obvious targets.
• Locate: trace channel/profile and ignore actor list.
• Fix: align trace channel/profile and reduce self/owner ignore misuse.
• Symptom: interaction triggers multiple times.
• Locate: missing in-progress guard and duplicated delegate bindings.
• Fix: add state guard and ensure single bind per component.
• Symptom: client sees success but server rejects.
• Locate: authority checks and RPC validation path.
• Fix: move final validation to server and replicate authoritative result.
• Symptom: consumed pickup remains interactable.
• Locate: lifecycle state and collision disable logic.
• Fix: disable collision/interaction immediately after confirmed success.
• Symptom: spawned interactables leak over time.
• Locate: spawner bookkeeping and reset cleanup path.
• Fix: track spawned instances and destroy/disable stale instances on respawn cycle.
• Symptom: frame spikes near dense interaction areas.
• Locate: per-frame trace/overlap workload and unnecessary ticking.
• Fix: reduce polling frequency, gate traces by input/distance, disable idle tick.

Interaction Authority Ops

• Use server-validated interaction resolution for shared gameplay effects.
• Use client-side prediction only for cosmetic feedback when acceptable.
• Replicate result state, not raw input spam.
• Keep cooldown/timer ownership on authority side for deterministic multiplayer behavior.

UE5.6-UE5.8 Compatibility Notes

• Overlap, trace, and actor lifecycle APIs listed above are stable across UE5.6-UE5.8.
• Prefer explicit collision profile/channel configuration across all supported versions.

Escalation

• Escalate when design requires persistent world state synchronization across sessions.
• Escalate when system must integrate with GAS ability targeting rules.