Chapters — Easy Chapter Generator

A Chapter is one bounded sequence

A Chapter is a scene component containing an ordered array of ChapterObjective records. It owns selection within that array, skips ineligible entries, runs start and completion lifecycle work, records its runtime state, and reports final completion to the Manager. Chapters are appropriate for a mission, tutorial segment, level phase, narrative beat, or other sequence with a clear beginning and end.

Use multiple Chapters when sequences need independent identities, default selection, explicit transitions, or separate completion records. Do not split a short sequence merely to create headings; each Chapter adds a startup and completion boundary.

Identity, lifecycle, and ending

Field	Meaning	Authoring rule
Title	Editor-facing label	May change without becoming an integration key
Identifier	Stable exact ID used by selection, handoff, links, and persistence	Keep unique and avoid changing after content ships
On Chapter Start	Invoked when a fresh start or hydrated resume becomes active	Do not assume it means Objective 01 is eligible
Ordered Objectives	The single linear sequence	Order is meaningful and duplicates are invalid
On Chapter Completion	Invoked after every entry is terminal and Chapter completion is persisted	Runs before Manager transition handling
Completion Action	None, Load Scene, Load Scene and Start Chapter, or Restore Checkpoint	Only relevant fields appear in the Editor

Chapter states and their causes

Not StartedActiveCompleted

Failed is an explicit terminal state for the current run, reached only through an accepted TryFailCurrentChapter request. Starting a Chapter resets its known persisted Chapter and Objective records before running from the requested or first position. Hydrated completion, by contrast, restores terminal state without replaying historical lifecycle events.

The serialized legacy CanFail value is retained for compatibility but does not gate V1 failure. Recovery is project policy: a failure notification can show UI, then the project may select a Chapter, reload a scene, or transition elsewhere.

Choose the completion action by intent

None

Use when completion events or project code own what happens next.

Load Scene

Use when the destination should run its normal startup priority without a forced Chapter.

Load Scene and Start Chapter

Write a one-use Chapter handoff before loading the target scene.

Restore Checkpoint

Write both Chapter and Objective IDs so the destination resumes from that ordered position while respecting earlier hydrated terminal entries.

See Scene Transitions and Handoff before combining persistence with scene loads.

Default designation and Chapter order

The Default Chapter belongs to the Manager, not to a title string or a separate Chapter mode. Exactly one discovered Chapter may be the fallback used after a scene has no valid one-use handoff and no enabled Editor testing override. Changing the default does not start it immediately and does not change any persisted state.

The Chapter List order is an authoring order for readability and deterministic selectors; it is not an automatic chain between Chapters. A completed Chapter advances to another Chapter only when its Completion Action writes an explicit destination or project code selects one. Within each Chapter, the Ordered Objectives array is the sequence that advances automatically.

Add, duplicate, move, and delete safely

Control	Effect	Review afterward
Add Chapter	Creates a Chapter GameObject under the Manager with a generated unique ID	Set a meaningful Title, add Objectives, and choose the default if required
Duplicate	Copies serialized Chapter configuration and its ordered rows while generating new identities	Relink copied scene components; do not retain duplicate bindings
Move Up / Move Down	Changes list and hierarchy order with Undo support	Confirm deliberate menu/authoring order; objective order inside each Chapter is unchanged
Delete	Removes the Chapter and its generated containers through Unity Undo	Choose a new default and repair handoffs, Objective Links, or code that used its ID

Title is presentation; Identifier is a contract

Rename Title freely. Change Identifier only as a migration: scene links, code, progress keys, checkpoint destinations, and cross-scene handoffs compare the exact stable value.

One Chapter can own many Ordered Objectives

A Chapter may contain a long list, but it still exposes only one current position. On Chapter Start runs once after the Chapter becomes Active and before the first eligible row finishes its own delayed start. Each row then owns its start and completion work. On Chapter Completion runs only after every non-null row is Completed or Skipped and the Chapter completion record has been written.

The Chapter does not require every row to have a scene component. A UI event, dialogue bridge, custom Objective, or external script may complete an active row. Conversely, a scene detector without an exact Objective Link cannot become part of the ordered sequence merely by living below the Chapter GameObject.

Fresh starts, step-back, and restored progress are different operations

Operation	What it does	What it does not do
`StartChapter()` / Manager selection	Resets this Chapter's known progress, marks it Active, invokes On Chapter Start, and begins at the requested or first row	Does not hydrate an old Active or Failed state
`TryStepBack(currentObjectiveId)`	Requires the exact active ID, closes the current position in step-back mode, resets the previous row's runtime detector state, and activates it	Is not an arbitrary history stack and cannot move before the first row
Hydrated resume	Restores Completed/Skipped rows and resumes from the first remaining row without replaying historical completion events	Does not restore Active or Failed and never infers Chapter completion from rows alone
`ClearProgress()`	Deletes the Manager's known progression keys and resets in-memory state	Does not erase another profile, another scope, or arbitrary game save data

Use Reset and Step Back for operation details and Progress State Persistence for terminal-state rules.

No-code example: a three-step tutorial Chapter

1
Select Add Chapter, set Title to Power Tutorial, keep its generated Identifier, and mark it as the Manager default.
2
Add three rows: Read the panel, Enable the generator, and Reach the exit. Use Move Up/Down until that order is correct.
3
Use On Chapter Start to reveal the tutorial HUD. Link a ButtonObjective, MultiActionObjective, and TriggerObjective to the three exact rows.
4
Use each row's completion actions to hide its marker and reveal the next one. Leave Chapter Completion Action at None and use On Chapter Completion to show a final panel.
5
Refresh Validation. Test a normal run, a repeated completion request, TryStepBack on the second row, and a fresh run after clearing the selected profile.

The compiled C# example below selects a Chapter by its exact Identifier and checks the returned result. For direct Objective completion, continue to Complete and Control Progression.

Validation and Chapter-specific problems

No objective starts

Confirm the Chapter contains at least one non-null row, the selected/default ID resolves, and the first remaining row's conditions are satisfied or intentionally skipped.

The wrong Chapter starts after a scene load

Inspect one-use handoff first, then the Editor testing override, then Default Chapter. Handoff has the highest priority.

Completion never arrives

Find the first nonterminal row. A null entry is skipped with a warning; an Active row still needs an accepted exact completion request.

A copied Chapter reports duplicate bindings

Duplicating data does not retarget copied detectors automatically. Link every detector to the intended new row or remove the extra component.

Persisted completion looks inconsistent

A completed Chapter record with a pending row is preserved but reported. The Manager resumes from the first pending row instead of inventing completion.

Select and start a Chapter

Where to place it: Use this component on a project-owned menu, level selector or integration controller.
When to call it: Call TryStartChapter with the exact stable Chapter ID after the Manager exists.
Behavior: Selection starts and resets the chosen Chapter according to the public contract. Do not use a title or partial ID.

using System;
using System.Collections;
using System.Collections.Generic;
using OverFuture.ChapterObjectiveSystem.Chapters;
using OverFuture.ChapterObjectiveSystem.Events;
using OverFuture.ChapterObjectiveSystem.Objectives;
using OverFuture.ChapterObjectiveSystem.Persistence;
using OverFuture.ChapterObjectiveSystem.Progression;
using UnityEngine;

public sealed class ChapterSelectionExample : MonoBehaviour
{
    public bool TryStartChapter(string chapterId)
    {
        ChapterManager manager = ChapterManager.Instance;
        return manager != null &&
               !string.IsNullOrWhiteSpace(chapterId) &&
               manager.TrySelectChapter(chapterId);
    }
}