Run reference combat.

Session lifecycle

Create a UDeckToolkitSession and retain it on a live host object. Initialize accepts 1 to 1,000 card definitions, a seed and a hand limit from 1 to 100. It validates atomically, snapshots each distinct definition, gives each copy a unique instance ID and shuffles.

Blueprint flow

1. Use Construct Object from Class with DeckToolkitSession and store its return value in a variable.
2. Call Initialize with Cards, Seed and HandLimit. Check its return value and OutReason.
3. Bind OnChanged to a UI refresh event. Query GetHand, GetEnergy and combat states.
4. Call BeginTurn with DrawCount and TurnEnergy.
5. Use the selected hand entry's InstanceId with PlayCard. Show OutReason when it returns false.
6. Call EndTurn, then BeginTurn for the next turn only if the session is not finished.

Minimal C++ call sequence

Inside a live UObject host, retain the session in a UPROPERTY field. The following is an integration excerpt, not a complete actor class.

// Host header (after including DeckToolkitSession.h):
UPROPERTY()
TObjectPtr<UDeckToolkitSession> Session;

// Host method (include DeckToolkitExamples.h in your .cpp):
Session = NewObject<UDeckToolkitSession>(this);
TArray<UDeckToolkitCard*> Cards = UDeckToolkitExamples::CreateExampleCards(this);
FText Reason;
if (Session->Initialize(Cards, 42, 10, Reason))
{
    Session->BeginTurn(5, 3);
    const TArray<FDTCardInstance> Hand = Session->GetHand();
    if (!Hand.IsEmpty())
    {
        // Inspect the boolean and Reason; a card can cost more than available energy.
        const bool bPlayed = Session->PlayCard(Hand[0].InstanceId, Reason);
    }
}

Turn boundaries

BeginTurn requires an initialized, unfinished session with no active turn or pending card. It refreshes energy, clears player block and draws. DrawCount must be 0 to 1,000; TurnEnergy must be 0 to 1,000,000. EndTurn discards non-retained cards, optionally applies an enemy attack and ages vulnerable. The API does not automatically begin the next turn.

Queue and step

QueueCard validates the instance and energy, spends the cost and removes that copy from the hand into pending resolution. StepEffect advances one authored effect. The resolving copy cannot be drawn during its own Draw effect. When resolution completes it enters discard or exhaust. PlayCard performs the equivalent complete resolution synchronously.

Draws and piles

When draw is empty, discard is shuffled into draw. Exhausted and resolving copies are excluded. At the hand limit, undrawn cards stay in the draw pile. Retained cards occupy hand slots next turn. Both combatants begin at 60 Health and MaxHealth; the reference model exposes snapshots for reading, not general-purpose combatant configuration.

Read state and events

GetHand returns instance/definition pairs. GetDrawCount, GetDiscardCount and GetExhaustCount return pile sizes. GetPlayer/GetEnemy return FDTCombatState; IsResolving, IsTurnActive and IsFinished describe lifecycle. GetTrace returns recent FDTTraceEntry records. Treat returned values as snapshots and render from OnChanged, rather than polling every frame.