Skip to content
Programming Bible

Melee Drive Foundation (Phase C) Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Ship a playable Melee Drive on Lyra 5.8 Plugify: cone pick on Attack, grounded Motion Warp, Anim Notify reach capsule/box → server GE, air slash without warp — enough to unblock Flow/Singularity and Counter later.

Architecture: Remake TFACore (tags/messages) + TFAMelee GFP on 5.8_terra_demo. Combat verbs are Gameplay Abilities; UTFAMeleeDriveCombatComponent is helpers only (target pick, hit trace, Counter window stubs). Kill credit publishes a Core message — do not hard-call Singularity. No second action runtime next to ASC.

Tech Stack: UE 5.8 · Lyra · GAS · Motion Warping · Game Feature Plugins · C++

Spec / implementer path: docs/tutorials/melee-drive-guns-singularity.md (§0–§4, §0.5 map) · FS-CMB-002 · FS-ARCH-010/013/014 · hit-reg + air-melee designs · docs/22-demo.md Phase C

Global Constraints

Section titled “Global Constraints”
  • Host root: E:\Dev\projects\5.8_terra_demo (not legacy demo5.8 fat trees — remake Plugify GFPs).
  • Do not fork LyraGame or dump melee into ADDON.
  • Sibling GFPs: no #include of TFAWeapons / TFASingularity; Core messages only.
  • bCanEverTick = false on Melee Drive component; never Tick-magnet FindBestCombatTarget.
  • Warp only on Attack press while grounded; airborne Strike legal with same slash, no root/warp.
  • Damage = Gameplay Effect on authority; presentation may predict.
  • Do not git commit unless the user explicitly asks.
  • This plan is Phase C only. Phase D (TFASingularity / Flow / Burst Storm) and Phase E (Counter + gun→Flow) are separate plans.
  • Interim Flow helper on MeleeDrive may exist for lab; production kill path must message TFA.Combat.KillConfirmed / Tag_TFA_Combat_KillConfirmed once TFASingularity exists (tag locked 2026-11-05).

File map

Section titled “File map”
Path (under host) Role
Plugins/GameFeatures/TFACore/ Boot Active GFP: gameplay tags + message structs
Plugins/GameFeatures/TFAMelee/ Plugify Melee Drive GFP
…/TFAMelee/Source/TFAMelee/Public/TFAMeleeDriveCombatComponent.h Target / hit / Counter-window API
…/TFAMelee/Source/TFAMelee/Private/TFAMeleeDriveCombatComponent.cpp Implementations
…/TFAMelee/Source/TFAMelee/Public/Abilities/TFAGameplayAbility_MeleeStrike.h Strike GA
…/TFAMelee/Source/TFAMelee/Private/Abilities/TFAGameplayAbility_MeleeStrike.cpp Activate: cone → warp → montage
…/TFAMelee/Source/TFAMelee/Public/Notifies/TFAAnimNotifyState_MeleeHit.h ANS → ExecuteMeleeHitTrace
…/TFAMelee/Source/TFAMelee/Public/Data/TFAMeleeFamilyDataAsset.h Reach / montage stubs (1H/2H/Wrist)
Experience Action Set / AbilitySet assets Grant Strike + inject MeleeDrive + MotionWarping components
Bible: docs/tutorials/melee-drive-guns-singularity.md Authority for shapes; mark Phase C exit when green
Bible: docs/22-demo.md Flip Melee Drive “cannot make” → foundation delivered when C gates pass

Task 1: Scaffold TFACore + TFAMelee GFPs

Section titled “Task 1: Scaffold TFACore + TFAMelee GFPs”

Files:

  • Create: E:\Dev\projects\5.8_terra_demo\Plugins\GameFeatures\TFACore\ (.uplugin, module, Build.cs, minimal Public tags header)
  • Create: E:\Dev\projects\5.8_terra_demo\Plugins\GameFeatures\TFAMelee\ (.uplugin, module, Build.cs depending on TFACore + GameplayAbilities + MotionWarping)
  • Modify: Demo Experience GameFeaturesToEnable (ADDON experience that loads Ladder/sandbox) to include TFACore (if not Boot Active) and TFAMelee

Interfaces:

  • Produces: module API macros TFACORE_API, TFAMELEE_API

  • Produces tag names (NativeGameplayTags or ini):

    • TFA.Combat.KillConfirmed
    • Ability.Melee.Strike
    • State.Melee.Striking
    • State.Melee.CounterWindow (stub for Phase E)
    • Data.Damage (SetByCaller)

  • Consumes: Lyra Game Features / CommonGame patterns already on host

  • Step 1: Confirm host plugins folder

Run (PowerShell):

Terminal window
Test-Path "E:\Dev\projects\5.8_terra_demo\Plugins\GameFeatures"
Get-ChildItem "E:\Dev\projects\5.8_terra_demo\Plugins\GameFeatures" | Select-Object Name

Expected: path exists; today only Lyra GFPs (ADDON, ShooterCore, …) — no TFA* yet.

  • Step 2: Create TFACore.uplugin + module stub

TFACore.uplugin essentials:

{
  "FileVersion": 3,
  "FriendlyName": "TFA Core",
  "Version": 1,
  "VersionName": "0.1.0",
  "EnabledByDefault": true,
  "Modules": [
    { "Name": "TFACore", "Type": "Runtime", "LoadingPhase": "Default" }
  ],
  "Plugins": [
    { "Name": "GameplayAbilities", "Enabled": true }
  ]
}

TFACore.Build.cs PublicDependency: Core, CoreUObject, Engine, GameplayTags, GameplayAbilities, ModularGameplay, GameFeatures.

  • Step 3: Create TFAMelee.uplugin + module stub

TFAMelee.Build.cs PublicDependency must include:

"Core", "CoreUObject", "Engine",
"GameplayAbilities", "GameplayTags", "GameplayTasks",
"MotionWarping",
"TFACore"
// LyraAbilitySystem / CommonGame as already required by sibling GFPs on this host
// Do NOT PublicDepend TFAWeapons or TFASingularity

EnabledByDefault: false — Experience enables it (Plugify).

  • Step 4: Generate project files + compile

Close editor if open; regenerate VS project; build LyraEditor (or host target).
Expected: both modules link; no circular includes.

  • Step 5: Experience enable

Add TFAMelee to the Demo/sandbox Experience GameFeaturesToEnable list (and ensure TFACore is Boot Active or listed). PIE once — GFP loads without crash.

Task 2: UTFAMeleeDriveCombatComponent (.h + .cpp)

Section titled “Task 2: UTFAMeleeDriveCombatComponent (.h + .cpp)”

Files:

  • Create: …/TFAMelee/Source/TFAMelee/Public/TFAMeleeDriveCombatComponent.h
  • Create: …/TFAMelee/Source/TFAMelee/Private/TFAMeleeDriveCombatComponent.cpp

Interfaces:

  • Produces (exact names from implementer path):

    • AActor* FindBestCombatTarget(float MaxDistance, float MaxAngle) const
    • void ExecuteMeleeHitTrace(FVector BoxHalfSize, FName SocketStart, FName SocketEnd, TSubclassOf<UGameplayEffect> DamageEffectClass, float BaseDamageMagnitude)
    • void OpenCounterWindow(AActor* AttackingEnemy) / CloseCounterWindow() / bool AttemptCounter()
    • void AddFlowKillCredit() / void ResetFlow(bool bApplyStagger) / int32 GetFlowTier() const (lab interim; Phase D moves meter ownership)
    • Delegates: OnCounterWindowOpened/Closed, OnFlowChanged

  • Consumes: owner ACharacter mesh sockets; ASC via UAbilitySystemBlueprintLibrary

  • API macro: TFAMELEE_API (not TFACOMBAT_API)

  • Step 1: Header with Tick off

UCLASS(ClassGroup=(TFA), meta=(BlueprintSpawnableComponent))
class TFAMELEE_API UTFAMeleeDriveCombatComponent : public UActorComponent
{
  GENERATED_BODY()
public:
  UTFAMeleeDriveCombatComponent();
  // … declarations matching Melee Drive §3 …
protected:
  UPROPERTY(BlueprintReadOnly, Category="TFA|MeleeDrive")
  int32 CurrentComboScore = 0;
  UPROPERTY(BlueprintReadOnly, Category="TFA|MeleeDrive")
  TObjectPtr<AActor> ActiveAttackingEnemy;
  UPROPERTY(BlueprintReadOnly, Category="TFA|MeleeDrive")
  bool bIsCounterWindowActive = false;
  UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="TFA|MeleeDrive|Guns")
  bool bSuppressCounterWhileAiming = true;
};

Ctor: PrimaryComponentTick.bCanEverTick = false;

  • Step 2: Implement FindBestCombatTarget

Copy scoring from Melee Drive §3: sphere overlap pawns → score Dot * (1 - DistNorm) inside MaxAngle; stick vector else forward. No Tick callers.

  • Step 3: Implement ExecuteMeleeHitTrace

BoxTraceMultiForObjects between sockets; dedupe actors; on each target ASC apply GE with SetByCaller Data.Damage. Prefer authority apply; client may run for FX only.

  • Step 4: Counter window + Flow helpers

AttemptCounter true only if window open + valid enemy; else ResetFlow(true).
GetFlowTier: >=30 → 3, >=15 → 2, else 1.
AddFlowKillCredit: ++ + broadcast; do not activate Singularity GA here in Phase C (log / TODO message only until Phase D).

  • Step 5: PIE smoke

Add component to hero via Game Feature Action or temporary BP. Call FindBestCombatTarget(600, 90) from a debug console/cheat — returns nearest-in-cone dummy, not a Tick update.

Task 3: Family DA + MeleeStrike ability + Motion Warp

Section titled “Task 3: Family DA + MeleeStrike ability + Motion Warp”

Files:

  • Create: …/Public/Data/TFAMeleeFamilyDataAsset.h (+ .cpp if needed)
  • Create: …/Public/Abilities/TFAGameplayAbility_MeleeStrike.h
  • Create: …/Private/Abilities/TFAGameplayAbility_MeleeStrike.cpp
  • Content: placeholder slash montage(s) + Motion Warping notify state named CombatTarget

Interfaces:

  • Consumes: UTFAMeleeDriveCombatComponent::FindBestCombatTarget, UMotionWarpingComponent

  • Produces: UTFAGameplayAbility_MeleeStrike with tags:

    • AbilityTags: Ability.Melee.Strike
    • ActivationOwnedTags: State.Melee.Striking

  • Family DA fields (minimum): StrikeRange, TargetAngleCone, TargetStrikingOffset, BoxHalfSize, SocketStart, SocketEnd, DamageEffectClass, GroundMontages[]

  • Step 1: Family DA stub

UCLASS(BlueprintType)
class TFAMELEE_API UTFAMeleeFamilyDataAsset : public UPrimaryDataAsset
{
  GENERATED_BODY()
public:
  UPROPERTY(EditAnywhere) float StrikeRange = 600.f;
  UPROPERTY(EditAnywhere) float TargetAngleCone = 90.f;
  UPROPERTY(EditAnywhere) float TargetStrikingOffset = 100.f;
  UPROPERTY(EditAnywhere) FVector BoxHalfSize = FVector(40.f, 40.f, 40.f);
  UPROPERTY(EditAnywhere) FName SocketStart = TEXT("hand_r");
  UPROPERTY(EditAnywhere) FName SocketEnd = TEXT("hand_r");
  UPROPERTY(EditAnywhere) TSubclassOf<UGameplayEffect> DamageEffectClass;
  UPROPERTY(EditAnywhere) TArray<TObjectPtr<UAnimMontage>> GroundSlashMontages;
};

Create one content DA asset for 1H stub (Wrist/2H can be empty copies).

  • Step 2: MeleeStrike ActivateAbility

Follow Melee Drive §4 / §0.5:

CommitAbility
ensure TPP / melee stance message (if camera director exists; else skip with log)
if grounded:
  Target = Melee Drive.FindBestCombatTarget(DA.StrikeRange, DA.TargetAngleCone)
  if Target: Warp.AddOrUpdateWarpTargetFromLocationAndRotation("CombatTarget", …)
else:
  // airborne: NO warp
PlayMontageAndWait(chosen GroundSlashMontage)

On montage end / cancel: clear warp target; EndAbility.

  • Step 3: Montage Motion Warping notify

Editor: notify state Motion Warping · Warp Target Name = CombatTarget · span lunge frames only · grounded clips only.

  • Step 4: PIE — cone + grounded warp

Place two dummies; stick toward one; Attack warps toward that dummy only. No Attack → no slide toward enemies.

  • Step 5: PIE — air

Jump + Attack: same slash plays; character does not Motion-Warp / root-pull to target.

Task 4: Anim Notify hit window + damage GE

Section titled “Task 4: Anim Notify hit window + damage GE”

Files:

  • Create: …/Public/Notifies/TFAAnimNotifyState_MeleeHit.h
  • Create: …/Private/Notifies/TFAAnimNotifyState_MeleeHit.cpp
  • Content: GE_TFA_MeleeDamage (SetByCaller Data.Damage)
  • Modify: slash montage — add ANS spanning hit frames

Interfaces:

  • Consumes: UTFAMeleeDriveCombatComponent::ExecuteMeleeHitTrace

  • Produces: server HP change on dummy via GE

  • Step 1: ANS NotifyTick / NotifyBegin

On authority (or predict FX + server validate later): call ExecuteMeleeHitTrace with family DA half-size / sockets / GE / magnitude.

  • Step 2: Whiff rule (Phase C floor)

If notify ends with zero confirmed hits this swing → Melee Drive.ResetFlow(true) (0.5s stagger GE optional stub).

  • Step 3: Kill message stub

When dummy dies from this GE path (listen vitality / destroy):

// Server only — Phase D subscriber will own Flow meter
UGameplayMessageSubsystem::Get(this).BroadcastMessage(
  Tag_TFA_Combat_KillConfirmed, /*payload with Instigator/Victim*/);
Melee Drive->AddFlowKillCredit(); // interim until Singularity GFP owns combo
  • Step 4: PIE — 2-client damage

Listen server + client: attacker sees lunge immediately; dummy HP changes after server auth. Wall between attacker and dummy → no damage.

Task 5: AbilitySet + Experience inject + IMC

Section titled “Task 5: AbilitySet + Experience inject + IMC”

Files:

  • Content: DAS_MeleeDriveCombat (Lyra AbilitySet) granting GA_TFA_MeleeStrike ← InputTag.Ability.Melee (or Attack)
  • Game Feature Action: add UTFAMeleeDriveCombatComponent + ensure UMotionWarpingComponent on hero
  • Modify: IMC / Lyra input — Attack triggers melee InputTag when melee stance or temporary always-on for Phase C lab

Interfaces:

  • Consumes: Tasks 2–4 classes

  • Produces: cold-boot PIE: Attack works without manually adding components in a level BP

  • Step 1: AbilitySet asset

Grant Strike only (Counter = Phase E).

  • Step 2: GFP Actions

On Experience activate: inject AbilitySet + components.

  • Step 3: Input

Wire Attack to Strike InputTag for sandbox Experience.

  • Step 4: Cold PIE gate

Fresh PIE, no manual setup: Attack → cone pick → warp (ground) → ANS damage.

Task 6: Phase C acceptance + Bible status flip

Section titled “Task 6: Phase C acceptance + Bible status flip”

Files:

  • Modify: docs/22-demo.md buildability audit — Melee Drive row when gates pass
  • Modify: docs/tutorials/melee-drive-guns-singularity.md status note for Phase C foundation
  • Optional: kanban seed card demo / Phase C

Interfaces:

  • Consumes: working Phase C build

  • Produces: documented green gate so Phase D plan can start

  • Step 1: Run Demo exit checks that apply to Phase C

From Melee Drive §9 (subset):

  1. Cone pick on Attack only (no Tick magnet).
  2. Air Attack: slash, no warp.
  3. Server GE damage; no TakeDamage player power path.
  4. Components live under TFAMelee (not LyraGame / not ADDON dump).
  • Step 2: Update docs/22-demo.md

Move Melee Drive from “Cannot make yet” to “foundation delivered / playable Melee Drive lab” with date + host path 5.8_terra_demo.

  • Step 3: Tutorial status line

Change park note: Melee Drive foundation shipped (date); resume Counter / gun matrix / Singularity bridge (Phases E / D). Keep file DEFERRED only for unfinished verbs if any remain.

  • Step 4: Explicit non-goals checklist (must still be false)

  • Singularity auto takedown / Burst Storm

  • Counter prompt UI

  • Gun kill → Flow message from ShooterCore

  • TBD-056 final damage-break rule

Spec coverage (self-review)

Section titled “Spec coverage (self-review)”
Spec item Task
Plugify TFAMelee / no LyraGame fork 1
Tag gates → GAS (§0.5) 3, 5
Melee Drive helpers, no Tick magnet 2
Grounded warp on Attack only 3
Air slash no warp 3
ANS capsule/box + GE auth 4
Kill message stub 4
Experience AbilitySet 5
Phase C gate / bible flip 6
Counter / guns / Singularity climax Out of plan → Phase E / D

Follow-on plans (do not fold in)

Section titled “Follow-on plans (do not fold in)”
  1. Phase D — TFASingularity: Asymmetric Flow · second meter · Overclocked · auto takedown · full Burst Storm art · subscribe KillConfirmed.
  2. Phase E — Counter GA + AI window + gun kill → Flow messages + ADS suppress.

Execution handoff

Section titled “Execution handoff”

Plan complete and saved to docs/superpowers/plans/2026-11-05-melee-drive-foundation.md.

Two execution options:

  1. Subagent-Driven (recommended) — fresh subagent per task, review between tasks
  2. Inline Execution — this session with executing-plans checkpoints

Which approach?