TaskSystem.h

Go to the documentation of this file.

/**
 * @file TaskSystem.h
 * @brief ECS system that iterates TaskRunnerComponent entities and drives
 *        ATS Visual Script graph execution each frame.
 * @author Olympe Engine
 * @date 2026-02-22 (refactored Phase 4 - 2026-03-08)
 *
 * @details
 * TaskSystem inherits from ECS_System and is registered in the World alongside
 * all other runtime systems.  Each frame, Process() iterates the set of
 * entities that own a TaskRunnerComponent, retrieves the bound
 * TaskGraphTemplate via AssetManager, and delegates to ExecuteVSFrame() to
 * advance Visual Script graph execution.
 *
 * ### Execution paths (Phase 4)
 * - VS graphs (graphType == "VisualScript"): dispatched via ExecuteVSFrame()
 *   which calls VSGraphExecutor::ExecuteFrame().  This is the PRIMARY path.
 * - Legacy BT-style graphs: ExecuteNode() is retained for direct invocation
 *   by unit tests; Process() no longer calls it (VS is the only path in the
 *   main loop).
 *
 * ### AtomicTask lifecycle (Phase 2.C / Phase 4)
 * ExecuteNode() implements the following lifecycle for AtomicTask nodes:
 *  1. On first entry to a node, create the IAtomicTask instance via
 *     AtomicTaskRegistry::Create() and store it in runner.activeTask.
 *  2. Each tick, call runner.activeTask->ExecuteWithContext(ctx, params).
 *  3. Running => keep activeTask; accumulate StateTimer; return.
 *  4. Success/Failure => reset activeTask; set LastStatus; reset StateTimer;
 *     advance CurrentNodeID via TransitionToNextNode().
 *     NODE_INDEX_NONE signals that the graph is complete.
 *  5. If runner.CurrentNodeID is set to NODE_INDEX_NONE while a task is
 *     Running, the next call to ExecuteNode() calls activeTask->Abort() before
 *     releasing the instance.
 *
 * C++14 compliant - no C++17/20 features.
 */
 
#pragma once
 
#include "../ECS_Systems.h"
#include "../ECS/Components/TaskRunnerComponent.h"
#include "TaskGraphTemplate.h"
#include "../Core/AssetManager.h"
#include "LocalBlackboard.h"
#include "VSGraphExecutor.h"
 
namespace Olympe {
 
/**
 * @brief Signature of the editor publish callback.
 *
 * Called by TaskSystem each frame while an AtomicTask node is Running.
 * The editor registers a function of this type via
 * TaskSystem::SetEditorPublishCallback() to receive live runtime info
 * without creating a compile-time dependency on editor code.
 *
 * @param entity     ID of the entity currently executing the task.
 * @param nodeIndex  Current node ID being executed.
 * @param bb         Non-owning pointer to the LocalBlackboard for this tick.
 *                   Only valid for the duration of the callback invocation.
 */
using TaskEditorPublishFn = void(*)(EntityID entity, int nodeIndex, const LocalBlackboard* bb);
 
/**
 * @class TaskSystem
 * @brief ECS system responsible for advancing task graph execution each frame.
 *
 * @details
 * Usage:
 * @code
 *   TaskSystem* taskSystem = world.RegisterSystem<TaskSystem>();
 *   // TaskSystem sets its own requiredSignature in the constructor.
 * @endcode
 *
 * Inheritance: TaskSystem : ECS_System
 */
class TaskSystem : public ECS_System
{
public:
 
    // -----------------------------------------------------------------------
    // Lifecycle
    // -----------------------------------------------------------------------
 
    /**
     * @brief Constructs the system and configures the required component signature.
     *
     * @note Signature configuration is left as a TODO until the component
     *       registration API is fully wired up in Phase 1.5.
     */
    TaskSystem();
 
    // -----------------------------------------------------------------------
    // Editor runtime wiring
    // -----------------------------------------------------------------------
 
    /**
     * @brief Register a callback that receives live task-runner state each
     *        frame while a task is executing.
     *
     * Pass nullptr to unregister.  The callback is invoked from
     * ExecuteAtomicTask() after ticking the task when the task is Running.
     * It is safe to call this from any thread before the first Process().
     *
     * @param fn  Function matching TaskEditorPublishFn, or nullptr.
     */
    static void SetEditorPublishCallback(TaskEditorPublishFn fn);
 
    // -----------------------------------------------------------------------
    // ECS_System interface
    // -----------------------------------------------------------------------
 
    /**
     * @brief Processes all entities registered with this system for one frame.
     *
     * For each entity in m_entities:
     *  1. Retrieves the TaskRunnerComponent (TODO Phase 1.5: from World).
     *  2. Looks up the bound TaskGraphTemplate via AssetManager::Get().
     *  3. Skips the entity if no valid template is found.
     *  4. Calls ExecuteNode() to advance task graph execution.
     */
    virtual void Process() override;
 
    // -----------------------------------------------------------------------
    // Core execution (public to allow direct invocation in unit tests)
    // -----------------------------------------------------------------------
 
    /**
     * @brief Advances execution of one node in the task graph for the given entity.
     *
     * @details
     * Implements the AtomicTask lifecycle described in the class documentation.
     * runner.CurrentNodeID is treated as a NodeID (looked up via
     * TaskGraphTemplate::GetNode()).  NODE_INDEX_NONE (-1) means there is no
     * active node; any lingering activeTask is Abort()ed and released.
     *
     * @param entity  The entity being processed.
     * @param runner  Reference to the entity's TaskRunnerComponent.
     * @param tmpl    Non-null pointer to the resolved TaskGraphTemplate.
     * @param dt      Delta-time in seconds for the current frame.
     */
    void ExecuteNode(EntityID entity,
                     TaskRunnerComponent& runner,
                     const TaskGraphTemplate* tmpl,
                     float dt);
 
    /**
     * @brief Dispatches VS-graph execution to VSGraphExecutor.
     * Called from Process() when tmpl->GraphType == "VisualScript".
     *
     * @param entity  The entity being processed.
     * @param runner  Reference to the entity's TaskRunnerComponent.
     * @param tmpl    Non-null pointer to the resolved TaskGraphTemplate.
     * @param dt      Delta-time in seconds for the current frame.
     */
    void ExecuteVSFrame(EntityID entity,
                        TaskRunnerComponent& runner,
                        const TaskGraphTemplate* tmpl,
                        float dt);
 
    /**
     * @brief Aborts the active atomic task on a runner, if any.
     *
     * @details
     * Calls Abort() on runner.activeTask (if non-null), resets the unique_ptr,
     * and sets runner.LastStatus to TaskRunnerComponent::TaskStatus::Aborted.
     * Safe to call when runner.activeTask is nullptr (no-op).
     *
     * @param runner  Reference to the entity's TaskRunnerComponent.
     */
    void AbortActiveTask(TaskRunnerComponent& runner);
 
private:
 
    // -----------------------------------------------------------------------
    // Private helpers
    // -----------------------------------------------------------------------
 
    /**
     * @brief Executes one tick of an AtomicTask node.
     *
     * Creates runner.activeTask on first call for this node, ticks it, and
     * handles Running / completion transitions.
     *
     * @param entity  The entity being processed.
     * @param runner  Reference to the entity's TaskRunnerComponent.
     * @param node    The current AtomicTask node definition.
     * @param tmpl    Non-null pointer to the resolved TaskGraphTemplate (used
     *                to resolve LocalVariable bindings).
     * @param dt      Delta-time in seconds for the current frame.
     */
    void ExecuteAtomicTask(EntityID entity,
                           TaskRunnerComponent& runner,
                           const TaskNodeDefinition& node,
                           const TaskGraphTemplate* tmpl,
                           float dt);
 
    /**
     * @brief Advances runner.CurrentNodeID after a node completes.
     *
     * Sets runner.CurrentNodeID to node.NextOnSuccess if @p success is
     * true, or node.NextOnFailure otherwise.  NODE_INDEX_NONE signals that
     * the graph has finished.  Also resets runner.StateTimer to 0.
     *
     * @param runner   The runner component to update.
     * @param node     The node that just completed.
     * @param success  true if the node succeeded, false if it failed.
     */
    void TransitionToNextNode(TaskRunnerComponent& runner,
                              const TaskNodeDefinition& node,
                              bool success);
 
    /// Callback registered by the editor to receive live runtime info.
    static TaskEditorPublishFn s_EditorPublishFn;
};
 
} // namespace Olympe