how_progression/docs/MISSION_DESIGN.md

Mission design contract

Read ARCHITECTURE.md, PROGRESSION.md, CREWS.md, CONTACTS.md and PHONE.md before creating or substantially changing a mission. This is the target contract for migration; current gaps are identified below.

Registration and phases

Each mission has a stable string ID, owning contact, eligibility stage, objective state machine, client/server entry points, crew tasks, reward policy, and explicit phase manifest. Keep durable IDs such as crowbar:1:return_vehicle; parse /prog crowbar 1.2 as integer mission 1 and integer phase 2, then resolve through a registry. Never store or compare 1.2 as a floating-point number. Numeric progression stage in existing SQL remains a separate concept.

Every advertised phase must reconstruct from a clean baseline, not assume a previous shortcut ran. A phase descriptor must say which entities, vehicles, props, NPCs, blips, markers, targets, routes, crew tasks, items and mission state exist; it must also remove things belonging to earlier/later phases. Phase setup must be repeatable. Completion shortcuts should go through the same server reward/progression path as gameplay, with explicit exceptions for development overrides. Do not promise deterministic phases until tested in game.

Current /prog phases exist only for Crowbar: 1.1–1.3, 2.1–2.2, 3.1–3.3, 4.1–4.4, 5.1–5.4. Plain X sets a stage. Mack and Tina support plain stages only. Current later phases often require an active mission, so the proposed contract is an improvement, not a description of existing behavior.

Participation and authority

• Support solo players and crews. Snapshot eligible crew members when accepting a mission. Store citizenid as durable identity; resolve current source only for live actions. A mid-mission joiner does not automatically receive progress or rewards.
• Server owns mission objective, completion validation, progression, currency, ownership and inventory rewards. Clients may present the world and report observations; validate any network ID, model, location, item and participant before reward.
• Send objective changes to all valid snapshotted participants and update bs_groupsystem tasks at the same transition. Define whether each objective is collective, owner-only or per-member. Scale counts/actors where the mission calls for it (Easy Rider uses one bike per participant up to five).
• Declare reward recipients explicitly. Existing behavior differs: Crowbar 1 pays the initiator cash, Crowbar 5 pays the carrier cash, Easy Rider pays every eligible participant cash. Do not silently normalize these.

World and lifecycle

• Track ownership of every spawned entity or target: server networked mission vehicle, client-local scenery, client-owned networked vehicle, prop, ped, blip, marker and target. Give each a deterministic spawn key and cleanup path. Prevent duplicate creation on sync/restart.
• Define start, objective transition, completion, abort, reset, player disconnect and resource-stop behavior. Keep preserved property/owned vehicles distinct from temporary mission assets; Crowbar 2 deliberately leaves the physical Premier after transfer.
• Route and GPS must match the current objective for each participant, and clear when the objective completes or is aborted. Draw active markers every frame. Make reconstruction replace stale routes and markers.
• World presence and service availability are separate: a ped or yard prop can exist before its mission/interaction is unlocked. Contact definitions express both.
• Use shared NPWD/contact services for SMS and established sender numbers. Keep existing dialogue, timing and text unless a separate gameplay change is approved.
• Prefer installed resources for mechanics already present: ox_inventory stash/items, qbx_vehicles ownership, qbx_vehicleshop purchase, ff_storerobbery register completion, randol_moneywash laundering, bs_groupsystem tasks. Do not implement duplicate economies or shops in mission code.

Current gaps to standardize deliberately

Global singleton mission instances, inconsistent reset/stop cleanup, source IDs retained in snapshots, mixed crew task status types, no universal abort path, and non-reconstructing /prog phases require separate decisions and in-game parity tests. The current mission state is not persisted in SQL. Avoid changing these semantics as an incidental consequence of splitting files.