overlord_event_system/behaviors/quests/

loop_tasks.rs

//! Native ports for the `additional_quests` category — quest
//! `additional_quests_behavior`s (run via `run_event` in
//! `logic::quests::{handle_claim_quest, handle_hidden_quest_completed}`,
//! returning `Vec<OverlordEvent>`).
//!
//! These scripts fire when a quest is claimed (or a hidden quest completes) and
//! issue follow-up quests. The shipped bodies fall into a small set of patterns:
//!
//! 1. **loop-task cycle** — `loop_tasks::on_finish_regular_loop_task` +
//!    `loop_tasks::advance_loop` (the regular loop-task quest chain).
//! 2. **loop-task cycle + first-loop flag** — pattern 1 plus a
//!    `SetCustomValue("loop_tasks.first_loop_skill_crystals_received", 1)`.
//! 3. **loop-task prepare** — `prepare_loop` (RNG) + `advance_loop`, optionally
//!    preceded by `on_finish_regular_loop_task`.
//! 4. **milestone marker** — `SetCustomValue("loop_tasks.last_milestone.<k>", n)`
//!    then `advance_loop`.
//! 5. **set custom value** — a single `SetCustomValue(key, n)` (mimic-item codes,
//!    events, so they are not ported.
//! 6. **redirect loop task** — a single
//!    `UpdateActiveLoopTaskId(<fixed quest uuid>)`.
//!
//! ## RNG
//! Only the `prepare_loop` pattern (#3) consumes RNG (slot-draw `randint`s). The
//! native draw order matches exactly. All other patterns ignore the snapshot
//! (harmless).
//!
//! ## Scope (per the `run_event` call site in `quests.rs`)
//! `Random`, `CharacterState`, `State` — plus `config`/`lookups` the loop_tasks
//! logic needs.

use configs::game_config::GameConfig;
use essences::character_state::CharacterState;
use event_system::script::random::GameRng;
use uuid::Uuid;

use crate::behaviors::{BehaviorKind, BehaviorMeta, BehaviorRegistry};
use crate::event::OverlordEvent;
use crate::mechanics::content_lookups::ContentLookups;
use crate::mechanics::loop_tasks;

/// Inputs available to an `additional_quests` native fn — the quest
/// `additional_quests_behavior` scope plus config/lookups the loop_tasks logic
/// needs.
pub struct AdditionalQuestsCtx<'a> {
    /// `CharacterState` const.
    pub character_state: &'a CharacterState,
    /// RNG snapshot (clone at the same state) so `prepare_loop` draws identically
    pub rng: &'a GameRng,
    pub config: &'a GameConfig,
    pub lookups: &'a ContentLookups,
}

/// Signature of an `additional_quests` native fn.
pub type AdditionalQuestsFn = fn(&AdditionalQuestsCtx) -> anyhow::Result<Vec<OverlordEvent>>;

fn set_custom_value(key: &str, value: i64) -> OverlordEvent {
    OverlordEvent::SetCustomValue {
        key: key.to_string(),
        value,
    }
}

// ---------------------------------------------------------------------------
// Shared parametrized bodies
// ---------------------------------------------------------------------------

/// `on_finish_regular_loop_task` (no-op) + `advance_loop`.
fn finish_and_advance(ctx: &AdditionalQuestsCtx) -> anyhow::Result<Vec<OverlordEvent>> {
    let mut events = Vec::new();
    loop_tasks::on_finish_regular_loop_task(&mut events, ctx.character_state);
    loop_tasks::advance_loop(&mut events, ctx.config, ctx.lookups, ctx.character_state);
    Ok(events)
}

/// `SetCustomValue(key, value)` then `advance_loop` (the milestone markers).
fn set_value_then_advance(
    ctx: &AdditionalQuestsCtx,
    key: &str,
    value: i64,
) -> anyhow::Result<Vec<OverlordEvent>> {
    let mut events = vec![set_custom_value(key, value)];
    loop_tasks::advance_loop(&mut events, ctx.config, ctx.lookups, ctx.character_state);
    Ok(events)
}

/// A single `SetCustomValue(key, value)` (no advance).
fn set_value_only(
    _ctx: &AdditionalQuestsCtx,
    key: &str,
    value: i64,
) -> anyhow::Result<Vec<OverlordEvent>> {
    Ok(vec![set_custom_value(key, value)])
}

// ---------------------------------------------------------------------------
// Distinct ports
// ---------------------------------------------------------------------------

/// Pattern 1: on_finish_regular_loop_task + advance_loop. Shared by the regular
/// loop-task quests (019a4b43 / 019b561c / 019b561e / 019b561f / 019b5621 /
/// 019bc1e6 / 019bc29c-572e / 019bc29c-b647 / 019d768d).
pub fn loop_finish_advance(ctx: &AdditionalQuestsCtx) -> anyhow::Result<Vec<OverlordEvent>> {
    finish_and_advance(ctx)
}

/// Pattern 2 (019a6ef3): finish + advance, then mark the first-loop crystals flag.
pub fn loop_finish_advance_first_crystals(
    ctx: &AdditionalQuestsCtx,
) -> anyhow::Result<Vec<OverlordEvent>> {
    let mut events = finish_and_advance(ctx)?;
    events.push(set_custom_value(
        "loop_tasks.first_loop_skill_crystals_received",
        1,
    ));
    Ok(events)
}

/// Pattern 3a (019bdb53): on_finish_regular_loop_task + prepare_loop (RNG) +
/// advance_loop.
pub fn loop_finish_prepare_advance(
    ctx: &AdditionalQuestsCtx,
) -> anyhow::Result<Vec<OverlordEvent>> {
    let mut events = Vec::new();
    loop_tasks::on_finish_regular_loop_task(&mut events, ctx.character_state);
    loop_tasks::prepare_loop(&mut events, ctx.config, ctx.character_state, ctx.rng);
    loop_tasks::advance_loop(&mut events, ctx.config, ctx.lookups, ctx.character_state);
    Ok(events)
}

/// Pattern 3b (019cd269): prepare_loop (RNG) + advance_loop (no finish call).
pub fn loop_prepare_advance(ctx: &AdditionalQuestsCtx) -> anyhow::Result<Vec<OverlordEvent>> {
    let mut events = Vec::new();
    loop_tasks::prepare_loop(&mut events, ctx.config, ctx.character_state, ctx.rng);
    loop_tasks::advance_loop(&mut events, ctx.config, ctx.lookups, ctx.character_state);
    Ok(events)
}

// --- Pattern 4: level milestone markers (SetCustomValue + advance) ---

/// Pattern 4: `SetCustomValue("loop_tasks.last_milestone.level", N)` + advance.
pub fn milestone_level<const N: i64>(
    ctx: &AdditionalQuestsCtx,
) -> anyhow::Result<Vec<OverlordEvent>> {
    set_value_then_advance(ctx, "loop_tasks.last_milestone.level", N)
}

/// Pattern 4: `SetCustomValue("loop_tasks.last_milestone.stage", N)` + advance.
pub fn milestone_stage<const N: i64>(
    ctx: &AdditionalQuestsCtx,
) -> anyhow::Result<Vec<OverlordEvent>> {
    set_value_then_advance(ctx, "loop_tasks.last_milestone.stage", N)
}

// --- Pattern 5: single SetCustomValue (mimic item codes) ---

/// Pattern 5: `SetCustomValue("next_mimic_item_code", CODE)`.
pub fn mimic_next_item<const CODE: i64>(
    ctx: &AdditionalQuestsCtx,
) -> anyhow::Result<Vec<OverlordEvent>> {
    set_value_only(ctx, "next_mimic_item_code", CODE)
}

// --- Pattern 6: redirect to a fixed loop task quest id ---

// Redirect-target loop-task quest ids, exported for deploy-time content
// validation (see `super::validate`).
pub const REDIRECT_KILL_3_ENEMIES: u128 = 0x019cd267_a50f_7d1b_81a5_83147141fb8c;
pub const REDIRECT_OPEN_CHEST_6: u128 = 0x019cd268_6b9e_7b89_826c_96b0e1cb4c55;
pub const REDIRECT_SELL_5_GEAR: u128 = 0x019cd268_a523_7e35_bb43_3cff76868568;
pub const REDIRECT_REACH_LEVEL_3: u128 = 0x019cd269_8571_7361_936b_08a48ca9cffe;

/// Pattern 6: `UpdateActiveLoopTaskId(QUEST)`.
pub fn redirect_to<const QUEST: u128>(
    _ctx: &AdditionalQuestsCtx,
) -> anyhow::Result<Vec<OverlordEvent>> {
    Ok(vec![OverlordEvent::UpdateActiveLoopTaskId {
        quest_id: Uuid::from_u128(QUEST),
    }])
}

// ---------------------------------------------------------------------------
// Test-fixture loop-task chain ports
// ---------------------------------------------------------------------------
//
// `tests_game_config.rs` defines a 3-quest loop-task cycle
// `additional_quests_behavior` pushed two events on claim:
//   `SetCustomValue("loop_task", N)` and
//   `UpdateActiveLoopTaskId(<next quest id>)`.
// value was never written (tests index `custom_values["loop_task"]`) and the
// active loop task never advanced. Faithful ports, one per quest slot.

fn set_loop_task_and_redirect(value: i64, next_quest_id: &str) -> Vec<OverlordEvent> {
    let quest_id = Uuid::parse_str(next_quest_id).expect("valid quest uuid literal");
    vec![
        set_custom_value("loop_task", value),
        OverlordEvent::UpdateActiveLoopTaskId { quest_id },
    ]
}

/// Test loop-task 305300e2 on claim: `loop_task = 1`, advance to 29540ca2.
pub fn test_loop_task_1(_ctx: &AdditionalQuestsCtx) -> anyhow::Result<Vec<OverlordEvent>> {
    Ok(set_loop_task_and_redirect(
        1,
        "29540ca2-21f3-4f0e-a478-240adafed4e3",
    ))
}

/// Test loop-task 29540ca2 on claim: `loop_task = 2`, advance to 9d3d2428.
pub fn test_loop_task_2(_ctx: &AdditionalQuestsCtx) -> anyhow::Result<Vec<OverlordEvent>> {
    Ok(set_loop_task_and_redirect(
        2,
        "9d3d2428-af3c-409f-a580-593de0fd06cf",
    ))
}

/// Test loop-task 9d3d2428 on claim: `loop_task = 0`, advance back to 305300e2.
pub fn test_loop_task_0(_ctx: &AdditionalQuestsCtx) -> anyhow::Result<Vec<OverlordEvent>> {
    Ok(set_loop_task_and_redirect(
        0,
        "305300e2-f432-4cbf-ad46-85386a9a9410",
    ))
}

/// Test loop-task seeder (hidden starting quest c3ae0d0c, completes after the
///   `SetCustomValue("loop_task", 0)` +
///   `give_quests([305300e2, 29540ca2, 9d3d2428])` +
///   `UpdateActiveLoopTaskId(305300e2)`.
/// This is what first unlocks the 3-quest loop-task cycle; the migration
/// stubbed it to `None`, so loop tasks were never given.
pub fn test_loop_task_seed(_ctx: &AdditionalQuestsCtx) -> anyhow::Result<Vec<OverlordEvent>> {
    Ok(vec![
        set_custom_value("loop_task", 0),
        OverlordEvent::NewQuests {
            quest_ids: vec![
                Uuid::parse_str("305300e2-f432-4cbf-ad46-85386a9a9410").unwrap(),
                Uuid::parse_str("29540ca2-21f3-4f0e-a478-240adafed4e3").unwrap(),
                Uuid::parse_str("9d3d2428-af3c-409f-a580-593de0fd06cf").unwrap(),
            ],
        },
        OverlordEvent::UpdateActiveLoopTaskId {
            quest_id: Uuid::parse_str("305300e2-f432-4cbf-ad46-85386a9a9410").unwrap(),
        },
    ])
}

/// Register this category's native fns.
pub fn register(registry: &mut BehaviorRegistry) {
    let mut reg = |name: &str, title: &str, desc: &str, f: AdditionalQuestsFn| {
        registry.register_additional_quests(
            BehaviorMeta {
                name: name.to_string(),
                category: BehaviorKind::AdditionalQuests,
                title: title.to_string(),
                description: desc.to_string(),
            },
            f,
        );
    };

    reg(
        "loop_finish_advance",
        "Доп. квесты: завершить и продвинуть loop",
        "on_finish_regular_loop_task (no-op) + advance_loop; общий для регулярных loop-квестов.",
        loop_finish_advance,
    );
    reg(
        "loop_finish_advance_first_crystals",
        "Доп. квесты: завершить/продвинуть + флаг первых кристаллов (019a6ef3)",
        "finish + advance, затем SetCustomValue(loop_tasks.first_loop_skill_crystals_received, 1).",
        loop_finish_advance_first_crystals,
    );
    reg(
        "loop_finish_prepare_advance",
        "Доп. квесты: завершить + prepare(RNG) + продвинуть (019bdb53)",
        "on_finish_regular_loop_task + prepare_loop (RNG) + advance_loop.",
        loop_finish_prepare_advance,
    );
    reg(
        "loop_prepare_advance",
        "Доп. квесты: prepare(RNG) + продвинуть (019cd269)",
        "prepare_loop (RNG) + advance_loop.",
        loop_prepare_advance,
    );

    // Milestone markers.
    let milestones: &[(&str, &str, AdditionalQuestsFn)] = &[
        ("aq_milestone_level_1", "level=1", milestone_level::<1>),
        ("aq_milestone_level_2", "level=2", milestone_level::<2>),
        ("aq_milestone_level_3", "level=3", milestone_level::<3>),
        ("aq_milestone_level_4", "level=4", milestone_level::<4>),
        ("aq_milestone_level_5", "level=5", milestone_level::<5>),
        ("aq_milestone_level_6", "level=6", milestone_level::<6>),
        ("aq_milestone_level_7", "level=7", milestone_level::<7>),
        ("aq_milestone_level_8", "level=8", milestone_level::<8>),
        ("aq_milestone_level_9", "level=9", milestone_level::<9>),
        ("aq_milestone_level_10", "level=10", milestone_level::<10>),
        ("aq_milestone_level_11", "level=11", milestone_level::<11>),
        ("aq_milestone_level_12", "level=12", milestone_level::<12>),
        ("aq_milestone_level_13", "level=13", milestone_level::<13>),
        ("aq_milestone_level_14", "level=14", milestone_level::<14>),
        ("aq_milestone_level_15", "level=15", milestone_level::<15>),
        ("aq_milestone_level_16", "level=16", milestone_level::<16>),
        ("aq_milestone_level_17", "level=17", milestone_level::<17>),
        ("aq_milestone_level_18", "level=18", milestone_level::<18>),
        ("aq_milestone_stage_1", "stage=1", milestone_stage::<1>),
        ("aq_milestone_stage_2", "stage=2", milestone_stage::<2>),
        ("aq_milestone_stage_3", "stage=3", milestone_stage::<3>),
        ("aq_milestone_stage_4", "stage=4", milestone_stage::<4>),
        ("aq_milestone_stage_5", "stage=5", milestone_stage::<5>),
        ("aq_milestone_stage_6", "stage=6", milestone_stage::<6>),
        ("aq_milestone_stage_7", "stage=7", milestone_stage::<7>),
        ("aq_milestone_stage_8", "stage=8", milestone_stage::<8>),
        ("aq_milestone_stage_9", "stage=9", milestone_stage::<9>),
        ("aq_milestone_stage_10", "stage=10", milestone_stage::<10>),
        ("aq_milestone_stage_11", "stage=11", milestone_stage::<11>),
        ("aq_milestone_stage_12", "stage=12", milestone_stage::<12>),
        ("aq_milestone_stage_13", "stage=13", milestone_stage::<13>),
        ("aq_milestone_stage_14", "stage=14", milestone_stage::<14>),
        ("aq_milestone_stage_15", "stage=15", milestone_stage::<15>),
        ("aq_milestone_stage_16", "stage=16", milestone_stage::<16>),
        ("aq_milestone_stage_17", "stage=17", milestone_stage::<17>),
        ("aq_milestone_stage_18", "stage=18", milestone_stage::<18>),
        ("aq_milestone_stage_19", "stage=19", milestone_stage::<19>),
    ];
    for (name, label, f) in milestones {
        reg(
            name,
            &format!("Доп. квесты: веха {label} + advance"),
            "SetCustomValue(loop_tasks.last_milestone.<k>, n) + advance_loop.",
            *f,
        );
    }

    // Mimic item-code setters.
    let mimic_codes: &[(&str, AdditionalQuestsFn)] = &[
        ("aq_mimic_next_item_0", mimic_next_item::<0>),
        ("aq_mimic_next_item_1002", mimic_next_item::<1002>),
        ("aq_mimic_next_item_1011", mimic_next_item::<1011>),
        ("aq_mimic_next_item_2010", mimic_next_item::<2010>),
        ("aq_mimic_next_item_3002", mimic_next_item::<3002>),
        ("aq_mimic_next_item_4001", mimic_next_item::<4001>),
    ];
    for (name, f) in mimic_codes {
        let code = name.rsplit('_').next().unwrap();
        reg(
            name,
            &format!("Доп. квесты: next_mimic_item_code={code}"),
            "SetCustomValue(next_mimic_item_code, <код>).",
            *f,
        );
    }

    // Loop-task redirects.
    let redirects: &[(&str, &str, AdditionalQuestsFn)] = &[
        (
            "aq_redirect_to_kill_3_enemies",
            "019cd267",
            redirect_to::<REDIRECT_KILL_3_ENEMIES>,
        ),
        (
            "aq_redirect_to_open_chest_6",
            "019cd268-6b9e",
            redirect_to::<REDIRECT_OPEN_CHEST_6>,
        ),
        (
            "aq_redirect_to_sell_5_gear",
            "019cd268-a523",
            redirect_to::<REDIRECT_SELL_5_GEAR>,
        ),
        (
            "aq_redirect_to_reach_level_3",
            "019cd269",
            redirect_to::<REDIRECT_REACH_LEVEL_3>,
        ),
    ];
    for (name, target, f) in redirects {
        reg(
            name,
            &format!("Доп. квесты: переключить loop task → {target}"),
            "UpdateActiveLoopTaskId(<целевой loop-task квест>).",
            *f,
        );
    }

    // Test-fixture loop-task chain (tests_game_config.rs).
    reg(
        "test_loop_task_1",
        "Тест: loop_task=1 → 29540ca2",
        "SetCustomValue(loop_task, 1) + UpdateActiveLoopTaskId(29540ca2).",
        test_loop_task_1,
    );
    reg(
        "test_loop_task_2",
        "Тест: loop_task=2 → 9d3d2428",
        "SetCustomValue(loop_task, 2) + UpdateActiveLoopTaskId(9d3d2428).",
        test_loop_task_2,
    );
    reg(
        "test_loop_task_0",
        "Тест: loop_task=0 → 305300e2",
        "SetCustomValue(loop_task, 0) + UpdateActiveLoopTaskId(305300e2).",
        test_loop_task_0,
    );
    reg(
        "test_loop_task_seed",
        "Тест: выдать loop-task цикл (305300e2/29540ca2/9d3d2428)",
        "SetCustomValue(loop_task, 0) + NewQuests([3 loop tasks]) + UpdateActiveLoopTaskId(305300e2).",
        test_loop_task_seed,
    );

    register_default_loop_tasks(registry);
}

/// Inputs for the default-loop-task selector
/// (`game_settings.default_loop_task_behavior`).
pub struct DefaultLoopTaskCtx;

/// Signature of a default-loop-task fn (returns the loop-task quest id).
pub type DefaultLoopTaskFn = fn(&DefaultLoopTaskCtx) -> anyhow::Result<Uuid>;

/// The shipped default loop task: a constant quest id.
pub fn default_loop_task_const(_ctx: &DefaultLoopTaskCtx) -> anyhow::Result<Uuid> {
    Ok(Uuid::from_u128(0x019cd267_a50f_7d1b_81a5_83147141fb8c))
}

/// Test default loop task: the fixture's first loop-task quest.
pub fn test_default_loop_task(_ctx: &DefaultLoopTaskCtx) -> anyhow::Result<Uuid> {
    Ok(Uuid::from_u128(0x305300e2_f432_4cbf_ad46_85386a9a9410))
}

/// Register the default-loop-task selectors (the loop-task quest behaviors
/// above are registered in [`register`]).
fn register_default_loop_tasks(registry: &mut BehaviorRegistry) {
    registry.register_default_loop_task(
        BehaviorMeta {
            name: "default_loop_task_const".to_string(),
            category: BehaviorKind::DefaultLoopTask,
            title: "Дефолтное loop-задание (константный uuid)".to_string(),
            description: "Возвращает константный uuid loop-задания.".to_string(),
        },
        default_loop_task_const,
    );
    registry.register_default_loop_task(
        BehaviorMeta {
            name: "test_default_loop_task".to_string(),
            category: BehaviorKind::DefaultLoopTask,
            title: "Тест: дефолтное loop-задание (305300e2)".to_string(),
            description: "Возвращает 305300e2 (фикстурный путь восстановления loop-task)."
                .to_string(),
        },
        test_default_loop_task,
    );
}