Skip to content

NPC and Job Data Model

Part of NPCs World Verbs Rewards and Living World
Conceptual model — not final database schema.

NPC

npc:
  id: merchant_mara
  name: Mara
  role: merchant
  home_location: first_island
  primary_verbs: [repair, write, sort, restore]
  relationship_stage: trusted_helper
  times_helped: 7
  last_helped_at: 2026-07-05

NPC job

npc_job:
  id: merchant_repair_box_labels
  npc_id: merchant_mara
  story_stage: first_meeting
  world_verb: repair
  target_object: crate_labels
  supported_activity_types: [missing_letter, spelling]
  min_rounds: 3
  max_rounds: 5
  required_for_progression: true
  unlocks: [boat_access]

Job instance

One time a child receives a job:

npc_job_instance:
  id: job_instance_123
  child_id: child_456
  npc_id: merchant_mara
  job_id: merchant_repair_box_labels
  activity_type: missing_letter
  session_id: session_789
  selected_words: [bread, fish, rope]
  status: completed
  started_at: timestamp
  completed_at: timestamp

World object state

world_object_state:
  child_id: child_456
  object_id: merchant_crate_labels
  location: first_island
  state: repaired
  progress: { current: 3, total: 3 }
  last_updated_by_session: session_789

NPC relationship

npc_relationship:
  child_id: child_456
  npc_id: merchant_mara
  relationship_stage: trusted_helper
  times_helped: 3
  trust_points: 30  # invisible to child
  unlocked_jobs: [repair_box_labels, wet_labels, delivery_manifest]

Inventory

inventory_item:
  id: lighthouse_old_photo
  name: Old Lighthouse Photo
  category: house_decoration
  source_npc: lighthouse_keeper
  rarity: uncommon
  drop_rate: 8  # internal
  placement_type: wall_photo
  can_duplicate: false

child_inventory:
  child_id: child_456
  item_id: lighthouse_old_photo
  placed_in_house: true
  house_slot: wall_frame_01

World state

world_state:
  current_chapter: old_lighthouse
  current_destination: first_island
  unlocked_destinations: [first_island]
  unlocked_travel_tools: [merchant_boat]
  map_reveals:
    old_lighthouse: visible
    whale_bay: hidden_by_fog
  story_flags:
    helped_merchant_first_time: true
    boat_available: true
    lighthouse_lit: false

After lighthouse: whale_bay: visible, lighthouse_lit: true.

Godot reads state and shows correct world version.

Example — merchant_mara

Full NPC definition with first_interaction, main_story_jobs, repeatable_jobs, deterministic_rewards, optional_drops — see design doc section 38.

Key repeatable jobs:

  • merchant_wet_labels — write · spelling / missing_letter
  • merchant_shipping_manifest — restore · multiple_words / reading
  • merchant_single_crate — sort · single_word · 1 round

Session save levels

Attempt level: session_id, word_id, activity_type, submitted_answer, is_correct, retries, skip, response_time, speech_confidence

Completion level: npc_id, job_id, world_verb, target_object, success/error/skip counts → then update mastery, relationship, world objects, flags, collectible eligibility