ue5-world-interaction ยท diff
git:20260302.11fee6c to git:20260303.c186337
90 added, 8 removed. Audit A to A.
---
name: ue5-world-interaction
description: UE5.6/UE5.7 world interaction systems for pickups, spawners, overlap/trace checks, and visual feedback. Use when requests involve interactive world actors, spawn logic, pickup behavior, interaction radius checks, success/failure feedback, and actor lifecycle control.
---
# 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.
+ # UE5.7 API Anchors
+ - 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
- - Build actor components (root, collision, visual mesh/effect) and defaults.
- - Implement interaction eligibility checks (distance, authority, target validity).
- - Apply gameplay effect on success and failure with explicit result object.
- - Add visual/audio feedback and optional UI toast hooks.
- - Finalize lifecycle policy: destroy, disable, or keep actor after interaction.
+ ## 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
- - If pickup fails due to capacity/conditions, keep actor state stable and report reason.
- - If overlap triggers multiple times, guard with active/in-progress state.
- - If spawned actors leak, track and clean managed instances on respawn.
+ - 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.7 Compatibility Notes
+ - Overlap, trace, and actor lifecycle APIs listed above are stable across UE5.6 and UE5.7.
+ - Prefer explicit collision profile/channel configuration in both versions.
# Escalation
- Escalate when design requires persistent world state synchronization across sessions.
- Escalate when system must integrate with GAS ability targeting rules.