Activities¶
Responsibility¶
Activities represent work that spans moves or turns. player_activity stores scheduling,
progress, targets, values, resume state, and an optional polymorphic activity_actor; actor
implementations own behavior for start, turn, finish, cancellation, and serialization.
Entry points¶
Read src/player_activity.h, src/activity_actor.h, their implementations, and the focused
activity_actor_definitions.h. Legacy handlers remain in activity_handlers; scheduling and
backlog behavior use activity_tracker.
Data ownership¶
A Character owns current and queued activity state through its tracker. player_activity
owns a cloneable actor and stable item locations/targets, not the target items or map tiles
themselves.
Dependencies¶
Activities depend on characters, item locations, coordinates, activity type definitions, inventory validity, movement points, UI interruption, events, and save JSON.
Lifecycle¶
An activity is constructed and assigned, its actor starts once, do_turn advances it,
interruption may suspend/cancel it, compatible work can resume, and finish or cancellation
cleans up before the tracker advances.
Invariants¶
Actor type equals activity ID; clone preserves concrete behavior; targets remain checked before use; move totals and remaining work stay coherent; cancellation performs required cleanup; and resume compares only compatible actors.
Extension points¶
New long-running behavior should be an activity_actor with a registered deserializer. Keep UI
selection outside the actor and put durable execution inputs inside it; avoid adding another
legacy handler.
Serialization¶
player_activity serializes in savegame_json.cpp; each actor must serialize its custom data
and register the matching deserializer. Add defaults or migration for old actor payloads.
Tests¶
Use activity tracker/scheduling tests plus focused behavior tests. Cover start, one turn, completion, cancellation, suspension/resume, invalid targets, cloning, and save round trip.
Performance¶
Activities execute every turn and may validate inventory. Actors that can safely manage invalid-item cleanup should use the documented override to avoid expensive repeated scans.
CCB divergence¶
CCB retains a mixture of actor and legacy activity paths. An upstream actor port must match the current CCB ID mapping, save payload, interruption, and inventory rules.
Technical debt¶
Legacy handlers and actor-based activities coexist. Migrate one behavior at a time with save compatibility; do not renumber or silently reinterpret legacy IDs.