Module loop_tasks

Native ports for the additional_quests category — quest additional_quests_behaviors (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 randints). 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.

Structs

AdditionalQuestsCtx

Inputs available to an additional_quests native fn — the quest additional_quests_behavior scope plus config/lookups the loop_tasks logic needs.

DefaultLoopTaskCtx

Inputs for the default-loop-task selector (game_settings.default_loop_task_behavior).

Constants

REDIRECT_KILL_3_ENEMIES

REDIRECT_OPEN_CHEST_6

REDIRECT_REACH_LEVEL_3

REDIRECT_SELL_5_GEAR

Functions

default_loop_task_const

The shipped default loop task: a constant quest id.

loop_finish_advance

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).

loop_finish_advance_first_crystals

Pattern 2 (019a6ef3): finish + advance, then mark the first-loop crystals flag.

loop_finish_prepare_advance

Pattern 3a (019bdb53): on_finish_regular_loop_task + prepare_loop (RNG) + advance_loop.

loop_prepare_advance

Pattern 3b (019cd269): prepare_loop (RNG) + advance_loop (no finish call).

milestone_level

Pattern 4: SetCustomValue("loop_tasks.last_milestone.level", N) + advance.

milestone_stage

Pattern 4: SetCustomValue("loop_tasks.last_milestone.stage", N) + advance.

mimic_next_item

Pattern 5: SetCustomValue("next_mimic_item_code", CODE).

redirect_to

Pattern 6: UpdateActiveLoopTaskId(QUEST).

register

Register this category’s native fns.

test_default_loop_task

Test default loop task: the fixture’s first loop-task quest.

test_loop_task_0

Test loop-task 9d3d2428 on claim: loop_task = 0, advance back to 305300e2.

test_loop_task_1

Test loop-task 305300e2 on claim: loop_task = 1, advance to 29540ca2.

test_loop_task_2

Test loop-task 29540ca2 on claim: loop_task = 2, advance to 9d3d2428.

test_loop_task_seed

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.

Type Aliases

AdditionalQuestsFn

Signature of an additional_quests native fn.

DefaultLoopTaskFn

Signature of a default-loop-task fn (returns the loop-task quest id).