01 · Mô hình dữ liệu

erDiagram
  JourneyDef ||--|{ AreaDef : "areas"
  JourneyDef ||--o{ CardDef : "cards"
  JourneyDef ||--o{ QuizDef : "quizzes"
  JourneyDef ||--o{ Comic : "comics[comicId]"
  JourneyDef ||--|| Guide : "guide"
  AreaDef ||--|{ LevelDef : "levels"
  AreaDef ||--o| AreaBoss : "boss"
  QuizDef ||--|{ Choice : "choices 2-3"
  Comic ||--|{ PanelDef : "panels"
  PanelDef ||--o{ PanelChar : "chars"
  PanelDef ||--o{ Bubble : "bubbles"
  CardDef }o..|| AreaDef : "areaId"
  QuizDef }o..|| AreaDef : "areaId"
  QuizDef }o..o| CardDef : "cardId"
  JourneyDef }o..o| Comic : "intro, ending"
  AreaDef }o..o| Comic : "intro, outro"
  AreaBoss }o..o| Comic : "intro"
  JourneyDef {
    string id PK "a-z0-9_, tiền tố mọi id riêng"
    number order "thứ tự trên màn chọn"
    string title
    string emoji
    string description
    object palette "primary, secondary, accent, bg, ink"
    string intro FK "comicId"
    mixed ending "comicId hoặc {comic, title, text}"
    bool invalid "validateAll gắn khi có lỗi"
  }
  Guide {
    string charId FK "olivia, bob, owl, robot"
    string name
  }
  AreaDef {
    string id PK "duy nhất trong hành trình"
    string name
    string emoji
    string sceneryTheme FK "ThemeDef id"
    string music "trackId Audio"
    string intro FK
    string outro FK
  }
  AreaBoss {
    string bossId FK "OG.Bosses id"
    object arena "width, platforms, spawn, theme"
    string intro FK "truyện trước trận"
  }
  CardDef {
    string id PK
    string areaId FK
    string title
    string fact "1-2 câu, tối đa 160 ký tự"
    fn drawIcon "ưu tiên: vẽ canvas"
    mixed icon "IconSpec dự phòng"
  }
  QuizDef {
    string id PK
    string areaId FK
    string question
    number answer "chỉ số đáp án đúng"
    string hint "hiện khi sai"
    string explain "hiện khi đúng"
    string cardId FK "mở khoá thẻ khi đúng"
  }
  Choice {
    string text
    mixed icon "IconSpec hoặc drawIcon"
  }
  PanelDef {
    mixed bg "theme id, color:#hex, {theme, camX}, hàm vẽ"
    string caption "lời dẫn"
  }
  PanelChar {
    string id FK "charId"
    string anim "idle, talk, wave..."
    number x "0..1 tỉ lệ khung"
    number y
    number face "1 hoặc -1"
    number scale
  }
  Bubble {
    string who "charId trong panel hoặc narrator"
    string text "tối đa 90 ký tự"
  }

erDiagram
  LevelDef ||--o{ Page : "pages"
  LevelDef ||--o{ QuizGateDef : "quizGate / quizGates"
  LevelDef ||--o{ GuideSpotDef : "guideSpots"
  LevelDef ||--o{ CheckpointX : "checkpoints"
  LevelDef ||--o{ ComicTrigger : "comicTriggers"
  LevelDef ||--o{ EnemySpawn : "enemies"
  LevelDef ||--o{ QuestDef : "quests"
  LevelDef }o..o| ClassicLevel : "from"
  Page }o..|| CardDef : "card"
  QuizGateDef }o..|| QuizDef : "quiz"
  GuideSpotDef }o..o| CardDef : "card"
  GuideSpotDef }o..o| CharacterDef : "charId"
  ComicTrigger }o..|| Comic : "comic"
  EnemySpawn }o..|| EnemyTypeDef : "type"
  LevelDef {
    string id PK "jid-area-n, duy nhất toàn game"
    string name
    string theme FK "mặc định area.sceneryTheme"
    string music
    number width "px"
    object spawn "x, y"
    number goal "số pizza cần, nhỏ hơn hoặc bằng số pizza"
    array platforms "[x,y,w,h], phần tử 0 là sàn y=480"
    array pizzas "[x,y] tâm"
    array coins "[x,y] tâm"
    object exit "x"
    string boss FK "mặc định: trùm của khu nếu là màn cuối"
    string intro FK
    string outro FK
  }
  Page {
    string card FK
    number x "tâm, px thế giới"
    number y
  }
  QuizGateDef {
    string quiz FK
    mixed x "số = tường giữa màn, bỏ trống hoặc exit = ở cửa"
    string id "mặc định gate0, gate1"
  }
  GuideSpotDef {
    number x "chân NPC"
    number y "mặc định 480"
    string text
    string[] lines "hoặc nhiều câu"
    string charId FK "mặc định người dẫn đường"
    string name
    string card FK "mở khoá thẻ sau khi nói"
  }
  CheckpointX {
    number x "thiếu thì Difficulty tự đặt mỗi 600 px"
  }
  ComicTrigger {
    number x "đi qua x thì chiếu"
    string comic FK
    bool once
  }
  EnemySpawn {
    string type FK "roach, joey, jid-ten..."
    number x
    number range
    number speed
    number dir "1 hoặc -1"
  }
  QuestDef {
    string id
    string type "collect_all, no_damage..."
    number target
    string text
    number reward "xu"
  }
  ClassicLevel {
    string id PK "kitchen, garden, roof, lair..."
  }

flowchart LR
  subgraph SRC["1 · Dữ liệu gốc (lúc LOAD)"]
    jdef["JourneyDef<br/>journey.js + content.js<br/>register() nhiều lần"]
  end
  subgraph CMP["2 · Bản biên dịch (sau boot)"]
    lvl["LevelDef đã compile<br/>+ journey, areaId, areaIndex,<br/>indexInArea, journeyIndex,<br/>isLastOfArea, bossArena, bossIntro,<br/>quizGates chuẩn hoá, final=false"]
  end
  subgraph RUN["3 · Trạng thái chạy (mỗi lần vào màn)"]
    st["OG.Level.state (LevelState)<br/>platforms, items, enemies,<br/>player, phase, t"]
    learn["st.learn<br/>pages: LearnPage[] (got, had, bob)<br/>gates: LearnGate[] (open, openT)"]
    cps["st.checkpoints: Checkpoint[]<br/>(reached, raiseT)<br/>st.checkpoint (điểm hồi sinh)"]
    gs["st.guideSpots: GuideSpot[]<br/>(idx, near, talked)"]
  end
  jdef -->|"OG.Journeys.init():<br/>validateAll → compileAll"| lvl
  lvl -->|"OG.Journeys.getLevel(id)<br/>(OG.Data.getLevel tự tra sang)"| st
  st --> learn & cps & gs
  st -.->|"KHÔNG ghi ngược"| lvl

erDiagram
  AreaBoss }o..|| BossDef : "bossId"
  LevelDef }o..o| BossDef : "boss"
  BossDef ||--o| BossArenaDef : "arena"
  BossDef ||--|| BossSpec : "create dùng SPEC"
  BossSpec ||--|{ PhasePattern : "patterns[phase]"
  BossSpec ||--o{ PhaseLine : "phaseLines[phase]"
  BossDef {
    string id PK "deedee, marky, joey, trio, jid-ten"
    string name
    number maxHp
    fn create "create(arena) trả BossInstance"
  }
  BossArenaDef {
    number width "px, mặc định 960"
    array platforms "[x,y,w,h]"
    object spawn "x, y người chơi"
    string theme
  }
  BossSpec {
    string id
    string charId "bộ vẽ OG.Sprites"
    number maxHp
    number scale
    number[] phaseAt "vd [3,1]: hp nhỏ hơn hoặc bằng 3 sang pha 2"
  }
  PhasePattern {
    number phase "1, 2, 3"
    string[] actions "vd walk, roll, walk, roll"
  }
  PhaseLine {
    number phase
    string text "toast khi đổi pha"
  }

erDiagram
  AreaDef }o..|| ThemeDef : "sceneryTheme"
  ThemeDef }o..o| BuiltinTheme : "base"
  ThemeDef ||--o| Sky : "sky"
  ThemeDef ||--o{ SceneryLayer : "layers xa đến gần"
  ThemeDef ||--o| PlatformStyle : "platformStyle"
  PlatformStyle ||--o{ PlatformPaint : "floor, ledge"
  ThemeDef ||--o{ DecorPlacement : "decor"
  ThemeDef ||--o| Ambient : "ambient"
  ThemeDef ||--o| DrawCustom : "drawCustom"
  SceneryLayer }o..o| LayerFn : "kind"
  DecorPlacement }o..|| DecorFn : "kind"
  ThemeDef {
    string id PK "vd vietnam-halong"
    string name
    string base FK "chủ đề v1 dự phòng"
  }
  BuiltinTheme {
    string id PK "kitchen, garden, roof, lair, boss"
  }
  Sky {
    string top "màu"
    string bottom
    object sun "x, y, r, color"
    bool stars
    mixed clouds "false hoặc {color, count}"
  }
  SceneryLayer {
    string kind FK "mountains, waves, decorRow, custom..."
    number parallax "0 đứng yên .. 1 theo camera"
    number y "px màn hình"
    number height
    string color
    number spacing
    fn draw "chỉ với kind custom"
  }
  PlatformPaint {
    string fill
    string top
    number topH
    number radius
  }
  DecorPlacement {
    string kind FK
    number every "lặp mỗi N px"
    number start
    number[] at "hoặc vị trí cố định"
    number y "mặc định 480 chân"
    bool front "vẽ đè lên người chơi"
  }
  Ambient {
    string kind "snow, leaves, bubbles, sparkle"
    string color
  }
  DrawCustom {
    fn background
    fn platform "trả true nếu đã vẽ"
    fn decor
  }
  LayerFn {
    string kind PK "registerLayer"
  }
  DecorFn {
    string kind PK "registerDecor hoặc Decor.define"
  }

erDiagram
  CardDef ||..o| PhotoEntry : "journeyId + cardId"
  PhotoEntry ||--o| PhotoRecord : "cache jid/cardId"
  PhotoEntry }o--|| CreditsFile : "register(jid, map)"
  CreditsFile {
    string path PK "assets/photos/jid/credits.js"
    string journeyId
  }
  PhotoEntry {
    string journeyId FK
    string cardId FK
    string file "mặc định cardId.webp"
    string src "assets/photos/jid/file"
    number w "px thật của file"
    number h
    string author "bắt buộc"
    string license "phải qua licenseOk"
    string licenseUrl
    string source "Wikimedia Commons, Unsplash, Pexels, NASA"
    string sourceUrl "bắt buộc"
    string title
    string note "Đã thu nhỏ, chuyển sang WebP"
    object focus "x, y 0..1 điểm giữ khi cắt"
  }
  PhotoRecord {
    object img "HTMLImageElement"
    string state "loading, ready, error"
  }

erDiagram
  CharacterDef ||--o{ SkinDef : "charId"
  SkinDef ||--o| SkinGfx : "OG.Sprites.skinGfx[skinId]"
  CharacterDef ||--o| Unlock : "unlock"
  CharacterDef ||--o| Perk : "Shop PERKS[charId]"
  ShopItem }o..o| SkinDef : "kind skin"
  ShopItem }o..o| CharacterDef : "kind char, id char:charId"
  ShopItem }o..o| Consumable : "kind consumable"
  Consumable ||--|| Modifiers : "tác dụng khi vào màn"
  Perk ||--|| Modifiers : "mods"
  CharacterDef {
    string id PK "oggy, jack, olivia, joey, bob..."
    string name
    string role "player, enemy, boss, npc"
    number w "px hitbox"
    number h
    number speed "px/giây, chỉ player"
    number jump "px/giây"
    object colors "body, head, ear, feet, muzzle, accent"
  }
  Unlock {
    string type "free, coins, level"
    number cost
    string levelId
  }
  SkinDef {
    string id PK "vd oggy_gold"
    string charId FK
    string name
    number price "xu, 0 = có sẵn"
    object colors "chỉ ghi khoá muốn đổi"
  }
  SkinGfx {
    string hat "chef, crown, beret"
    string cape
    string mask
    bool apron
  }
  Consumable {
    string id PK "shield, boots, magnet, heart"
    number price
    number max "số tối đa được giữ"
  }
  ShopItem {
    string id PK
    string kind "consumable, skin, char"
    number price
    bool owned
    number count
    bool loadout "mang theo vào màn"
  }
  Modifiers {
    number extraLives
    number speedMul
    number jumpMul
    number magnet "px"
    number shield
    number doubleJump
  }
  Perk {
    string label
    string desc
  }

erDiagram
  LevelDef ||--o{ QuestDef : "quests"
  QuestDef ||--|| Quest : "getForLevel dựng"
  GlobalQuestDef ||--|| Quest : "getDaily, getAchievements dựng"
  QuestStore ||--o{ QuestRecord : "levels[qid]"
  QuestStore ||--o{ QuestRecord : "global[qid]"
  QuestStore ||--|| Daily : "daily"
  Daily ||--o{ QuestRecord : "prog[qid]"
  Quest }o..o| QuestRecord : "id"
  GlobalQuestDef {
    string id PK "ach_..., daily_..."
    string type "stomp_n, pizza_n, stars_n..."
    mixed target "số hoặc all"
    number reward
    number limit "chỉ time_under, giây"
  }
  Quest {
    string id
    string levelId "null nếu toàn cục"
    string category "level, daily, achievement"
    number progress
    number target
    bool done
    bool claimed
    bool failed
  }
  QuestStore {
    bool seeded "đã lấy số liệu từ stats"
  }
  Daily {
    string date "YYYY-MM-DD giờ máy"
    string[] ids "3 nhiệm vụ của ngày"
  }
  QuestRecord {
    number progress
    bool done
    bool claimed
  }

classDiagram
  direction LR
  class SaveData {
    +v : number = 1
    +coins : number
    +bestScore : number
    +playerName : string
    +selectedChar : string
    +unlockedChars : string[]
    +ownedSkins : string[]
    +equippedSkins : charId→skinId
    +inventory : itemId→count
  }
  class SaveSettings {
    +masterVolume : 0..1
    +musicVolume : 0..1
    +sfxVolume : 0..1
    +muted : bool
    +touchControls : auto|on|off
    +tapJump : auto|on|off
    +difficulty : kid|challenge
  }
  class Progress["progress"] {
    +unlocked : levelId[]
    +levels : levelId→LevelRecord
  }
  class LevelRecord {
    +completed : bool
    +bestScore : number
    +stars : 1..3
    +bestTime : giây
    +plays : number
  }
  class Stats["stats"] {
    +plays, deaths, stomps
    +pizzas, coins
    +bossesDefeated, victories
  }
  class Ext["ext (OG.Save.ns)"] {
    +quests : QuestStore
    +story : seen, last
    +learn : cards, quizzes
    +difficulty : fails
    +social : leaderboard, onlineUrl
    +shop : loadout
  }
  class LearnStore["ext.learn"] {
    +cards : jid→cardId→timestamp ms
    +quizzes : jid→quizId→QuizRecord
  }
  class QuizRecord {
    +tries : number
    +passed : bool
  }
  class StoryStore["ext.story"] {
    +seen : 'jid:comicId'→true
    +last : jid
  }
  class SocialStore["ext.social"] {
    +leaderboard : LeaderboardEntry[] tối đa 10
    +onlineUrl : string
  }
  SaveData *-- SaveSettings : settings
  SaveData *-- Progress : progress
  Progress *-- LevelRecord : levels
  SaveData *-- Stats : stats
  SaveData *-- Ext : ext
  Ext *-- LearnStore
  LearnStore *-- QuizRecord
  Ext *-- StoryStore
  Ext *-- SocialStore

flowchart LR
  mvp[("Bản MVP<br/>localStorage 'oggyBest'<br/>= một con số kỷ lục")]
  v1[("v1<br/>'oggyAdventure.save.v1'<br/>SaveData v: 1")]
  v2[("v2 (hành trình)<br/>cùng khoá, cùng v: 1<br/>+ settings.tapJump, settings.difficulty<br/>+ ext.story, ext.learn, ext.difficulty")]
  mvp -->|"load(): đọc 'oggyBest',<br/>giữ số lớn hơn vào bestScore"| v1
  v1 -->|"load(): merge(defaults(), saved)<br/>field mới tự nhận mặc định"| v2
  v2 -.->|"commit(): vẫn ghi lại 'oggyBest'<br/>để bản cũ đọc được"| mvp