Sơ đồ kiến trúc Oggy Adventure

flowchart TB
  main["<b>core/main.js</b> (12, nạp CUỐI)<br/>boot(): DOM → Save → Input → Progress<br/>→ init() module tính năng → Journeys.init<br/>→ Scenes.go('boot') → Loop.start"]

  subgraph FEATURE["Module tính năng — init() theo OG.FEATURE_INIT_ORDER"]
    direction LR
    story["<b>story/</b> (10)<br/>OG.Story · OG.Learn<br/>OG.Guide · OG.Photos"]
    ui["<b>ui/</b> (8)<br/>OG.Menus · OG.Shop"]
    world["<b>world/</b> (7)<br/>OG.World · OG.Quests"]
    social["<b>social/</b> (9)<br/>OG.Social"]
    bosses["<b>bosses/</b> (6)<br/>OG.Bosses"]
    audio["<b>audio/</b> (4)<br/>OG.Audio"]
  end

  journeys["<b>journeys/&lt;id&gt;/</b> (11)<br/>dữ liệu hành trình<br/>đăng ký lúc LOAD"]
  game["<b>game/</b> (5)<br/>OG.Game · OG.Level · OG.Player<br/>OG.Enemies · OG.Collectibles · OG.Particles<br/>OG.Progress · OG.Difficulty · OG.BossScene"]
  gfx["<b>gfx/</b> (3)<br/>OG.Sprites · OG.Decor"]
  data["<b>data/</b> (2)<br/>OG.Data"]
  core["<b>core/</b> (1)<br/>OG.Events · OG.EV · OG.Save · OG.Input<br/>OG.Camera · OG.Physics · OG.DOM · OG.Scenes<br/>OG.Loop · OG.Scenery · OG.Journeys"]
  ns["<b>core/namespace.js</b> (nạp ĐẦU TIÊN)<br/>OG · OG.Config · OG.Palette · OG.util · OG.FONT"]

  main --> core
  main -. "init()" .-> FEATURE
  main -. "init()" .-> game

  FEATURE --> game
  FEATURE --> gfx
  FEATURE --> data
  FEATURE --> core
  game --> gfx
  game --> data
  game --> core
  game -. "OG.util.call: Bosses, Menus, Shop,<br/>Quests, Social, Story" .-> FEATURE
  gfx --> data
  gfx --> core
  gfx -. "đọc lúc CHẠY: Level.state,<br/>Game.run, Particles.spawn" .-> game
  journeys -->|"Journeys.register, Scenery.register*"| core
  journeys -->|"Decor.define"| gfx
  journeys -->|"Enemies.registerType"| game
  data -->|"Journeys.getLevel (lúc chạy)"| core
  core --> ns

flowchart LR
  ns["namespace.js<br/>OG.Config · OG.util"]
  events["events.js<br/>OG.Events · OG.EV"]
  save["save.js<br/>OG.Save"]
  input["input.js<br/>OG.Input"]
  camera["camera.js<br/>OG.Camera"]
  physics["physics.js<br/>OG.Physics"]
  dom["dom.js<br/>OG.DOM"]
  scenes["scenes.js<br/>OG.Scenes"]
  loop["loop.js<br/>OG.Loop"]
  scenery["scenery-registry.js<br/>OG.Scenery"]
  journeysC["journeys.js<br/>OG.Journeys"]
  mainC["main.js"]

  events --> ns
  physics --> ns
  save --> events
  dom --> events
  scenes --> events
  scenes -->|"Input.reset khi đổi scene"| input
  input --> events
  input -->|"đọc settings"| save
  input -->|"Scenes.current() (chạm để nhảy)"| scenes
  loop --> camera
  loop --> scenes
  loop -->|"endFrame"| input
  journeysC --> scenery
  mainC --> dom & save & input & scenes & loop
  mainC -->|"autoPause: push('pause')"| scenes
  mainC -. "util.call('Journeys','init')" .-> journeysC

stateDiagram-v2
  direction LR
  [*] --> boot : main.js go('boot')
  boot --> menu : frame đầu tiên
  menu --> charselect
  menu --> shop
  menu --> settings
  menu --> leaderboard
  menu --> notebookHub : 📒 Sổ tay
  menu --> modeSelect : 📖 PHIÊU LƯU HỌC TẬP (xem sơ đồ b)
  charselect --> shop
  menu --> worldmap : ▶ CHƠI CỔ ĐIỂN (Game.newRun)
  worldmap --> level : Game.startLevel
  worldmap --> menu : Esc
  level --> boss : Game.finishStage (màn có trùm)
  level --> worldmap : Game.completeLevel (màn không trùm)
  boss --> worldmap : Game.completeLevel
  boss --> victory : màn final (lair)
  level --> gameover : game over (hết mạng)
  boss --> gameover : game over
  gameover --> worldmap : THỬ LẠI
  gameover --> menu
  victory --> leaderboard : Social.mountResult
  gameover --> leaderboard : Social.mountResult
  leaderboard --> menu : params.back

stateDiagram-v2
  direction LR
  menu --> modeSelect : 📖 PHIÊU LƯU HỌC TẬP
  modeSelect --> journeySelect : chọn Bé chơi / Thử thách
  journeySelect --> comic : Story.startJourney (truyện mở đầu, lần đầu)
  journeySelect --> journeyMap : đã xem truyện
  journeyMap --> journeySelect : Esc
  journeyMap --> notebook : 📒 Sổ tay
  notebookHub --> notebook
  journeyMap --> comic : truyện đầu khu, đầu màn (lần đầu)
  comic --> journeyMap : next = journeyMap
  journeyMap --> level : Story.playLevel, Game.startLevel
  comic --> level : next = level
  level --> comic : truyện trước trùm (lần đầu)
  comic --> boss : next = boss
  level --> boss : Game.finishStage
  level --> comic : Story.afterLevel (truyện kết màn, kết khu)
  boss --> comic : Story.afterLevel
  level --> journeyMap : Story.afterLevel (không còn truyện)
  boss --> journeyMap : Story.afterLevel (không còn truyện)
  comic --> journeyEnd : Story.finishJourney (màn cuối)
  level --> gameover : hết mạng (chỉ chế độ Thử thách)
  boss --> gameover : hết mạng (Thử thách)
  gameover --> journeyMap : THỬ LẠI (Game.retryRun)
  journeyEnd --> notebook
  journeyEnd --> journeyMap
  journeyEnd --> leaderboard : nút Bảng xếp hạng
  leaderboard --> journeyEnd : back
  journeyEnd --> menu

flowchart LR
  level(["level"]) -. "push: Esc/P/⏸/mất focus" .-> pause(["pause<br/>drawBelow: true"])
  boss(["boss"]) -. "push" .-> pause
  pause -. "push {overlay:true}" .-> settings(["settings"])
  settings -. "pop" .-> pause
  pause -. "pop → resume()<br/>'game:resume'" .-> level

  level -. "push: nhặt trang sách mới<br/>Learn.openCard" .-> card(["card"])
  level -. "push: chạm cổng câu đố<br/>Learn.openQuiz" .-> quiz(["quiz"])
  level -. "push {overlay:true}<br/>comicTriggers" .-> comic(["comic"])
  notebook(["notebook"]) -. "push: mở thẻ đã có" .-> card
  card -. "pop" .-> level
  quiz -. "pop (+ onPass)" .-> level
  comic -. "pop (+ onDone)" .-> level

stateDiagram-v2
  direction LR
  [*] --> play : enter()
  play --> clear : đủ pizza + qua mọi cổng + chạm EXIT ('level#58;clear', 'door#58;enter')
  clear --> done : sau CLEAR_DELAY giây ăn mừng
  done --> [*] : Game.finishStage(levelId)

flowchart LR
  player["game/player.js"] --> jump(["player:jump"]) & land(["player:land"]) & hurt(["player:hurt"]) & action(["player:action"])
  shopE["ui/shop.js (nhảy đôi)"] --> jump
  game["game/game.js"] --> die(["player:die"]) & lives(["lives:change"])
  diffE["game/difficulty.js (hồi mạng)"] --> lives

  jump --> audio["audio/audio.js"]
  jump --> sprites["gfx/sprites.js"]
  land --> audio
  land --> sprites
  hurt --> audio
  hurt --> sprites
  hurt --> quests["world/quests.js"]
  hurt --> shopL["ui/shop.js"]
  action --> audio
  action --> bossesL["bosses/bosses.js"]
  die --> audio
  lives --> audio

flowchart LR
  level["game/level.js"] --> lstart(["level:start"]) & collect(["item:collect"]) & stomp(["enemy:stomp"]) & locked(["level:exitLocked"]) & door(["door:enter"]) & lclear(["level:clear"])
  game["game/game.js"] --> lcomplete(["level:complete"])

  lstart --> audio["audio/audio.js"]
  lstart --> quests["world/quests.js"]
  lstart --> shop["ui/shop.js"]
  collect --> audio
  collect --> sprites["gfx/sprites.js"]
  collect --> quests
  stomp --> audio
  stomp --> sprites
  stomp --> quests
  locked --> audio
  door --> audio
  lcomplete --> audio
  lcomplete --> quests
  lcomplete --> diff["game/difficulty.js"]
  lcomplete --> social["social/social.js"]

flowchart LR
  bscene["game/boss-scene.js"] --> bstart(["boss:start"]) & bhit(["boss:hit"]) & bdef(["boss:defeated"]) & bstomp(["enemy:stomp"])
  kit["bosses/bosses.js<br/>(kit dùng chung)"] --> bphase(["boss:phase"])
  kit -->|"source:'reflect'"| bhit
  trio["bosses/trio.js"] --> bphase
  deedee["bosses/deedee.js"] --> bheal(["boss:heal"]) & bstolen(["boss:foodStolen"])

  bstart --> audio["audio/audio.js"] & hud["ui/hud.js"]
  bhit --> audio & sprites["gfx/sprites.js"]
  bphase --> audio & hud
  bdef --> audio & sprites & quests["world/quests.js"]
  bstomp --> audio & sprites & quests

flowchart LR
  scenes["core/scenes.js"] --> sc(["scene:change"])
  game["game/game.js"] --> gstart(["game:start"]) & gover(["game:over"]) & gvic(["game:victory"])
  pauseE["ui/menus.js · game/default-scenes.js<br/>(scene pause)"] --> gpause(["game:pause"])
  resumeE["game/level.js · game/boss-scene.js<br/>(resume)"] --> gresume(["game:resume"])
  save["core/save.js"] --> coins(["coins:change"]) & settings(["settings:change"]) & reset(["save:reset"])
  input["core/input.js"] --> first(["input:firstGesture"])
  quests["world/quests.js"] --> qdone(["quest:complete"])
  dom["core/dom.js + 7 file UI khác"] --> uiclick(["ui:click"])

  sc --> audio["audio/audio.js"] & defsc["game/default-scenes.js"] & guide["story/guide.js"] & learn["story/learn.js"]
  gstart --> audio & social["social/social.js"] & shop["ui/shop.js"]
  gover --> audio & social & diff["game/difficulty.js"]
  gvic --> audio & social
  gpause --> audio
  gresume --> audio
  coins --> gameL["game/game.js<br/>(refreshHud)"] & menus["ui/menus.js"] & quests
  settings --> audio & mainL["core/main.js<br/>(nút cảm ứng)"]
  reset --> audio & diff & social & shop & jmap["world/journey-map.js"] & quests
  first --> audio
  qdone --> audio & menus
  uiclick --> audio

flowchart LR
  story["story/story.js"] --> jsel(["journey:select"]) & jdone(["journey:complete"]) & aenter(["area:enter"]) & adone(["area:complete"])
  learn["story/learn.js"] --> page(["page:collect"]) & cunlock(["card:unlock"]) & copen(["card:open"]) & qopen(["quiz:open"]) & qans(["quiz:answer"]) & qpass(["quiz:pass"]) & gate(["gate:open"]) & nb(["notebook:open"])
  sscenes["story/scenes.js"] --> cstart(["comic:start"]) & cend(["comic:end"])
  guide["story/guide.js"] --> talk(["guide:talk"])
  diff["game/difficulty.js"] --> cp(["checkpoint:reach"]) & resp(["player:respawn"]) & dchg(["difficulty:change"]) & assist(["assist:on"])

  jdone & page & cunlock & qans & qpass & gate & talk & cp & resp --> audio["audio/audio.js"]

sequenceDiagram
  autonumber
  participant B as Trình duyệt
  participant In as OG.Input
  participant L as OG.Loop
  participant Cam as OG.Camera
  participant Sc as OG.Scenes
  participant Lv as scene 'level'
  participant P as OG.Player
  participant Ph as OG.Physics
  participant Ev as OG.Events
  participant Au as OG.Audio
  participant Sp as OG.Sprites

  B->>In: keydown Space (giữa 2 frame)
  In->>In: setKey('jump', true) → keys.jump = true, pressed('jump') = true
  B->>L: requestAnimationFrame → frame(t)
  L->>B: requestAnimationFrame(frame) (xin frame sau NGAY ĐẦU hàm)
  L->>L: dt = min(MAX_DT, (t − lastTimestamp) / 1000)
  L->>L: tick(dt): OG.time += dt
  L->>Cam: update(dt) (giảm dần rung màn hình)
  L->>Sc: update(dt)
  Sc->>Lv: update(dt) (CHỈ scene trên cùng)
  Lv->>In: pressed('pause')? → không
  Lv->>Lv: Game.tickTime(dt) (cộng thời gian chơi)
  Lv->>P: update(p, dt, st)
  P->>In: keys.left/right, pressed('jump')
  P->>Ev: emit('player:jump', {charId, x, y})
  Ev->>Au: listener → sfx('jump')
  Ev->>Sp: listener → hiệu ứng bụi
  P->>Ph: moveBody(p, dt, platforms) (trọng lực, va chạm AABB)
  Ph-->>P: {landed, prevBottom}
  P-->>Lv: res (prevBottom dùng để xét giẫm)
  Lv->>Lv: handleFall → hook.update → vật phẩm → kẻ địch → checkExit
  Lv->>Cam: follow(player, worldW)
  L->>L: ctx.save() · ctx.clearRect(0, 0, 960, 540)
  L->>Sc: draw(ctx)
  Sc->>Lv: draw(ctx) (từ scene thấp nhất còn nhìn thấy lên đỉnh)
  Lv->>Sp: drawBackground(ctx, theme, Camera.x, t) (toạ độ MÀN HÌNH, parallax)
  Lv->>Cam: apply(ctx) (translate −Camera.x → toạ độ THẾ GIỚI)
  Lv->>Sp: bục, decor, vật phẩm, kẻ địch, cửa EXIT, hook, hạt, người chơi
  Lv->>Lv: ctx.restore() → lớp phủ + hook màn hình + Menus.drawHud
  L->>L: ctx.restore()
  L->>In: endFrame() (xoá cờ "vừa bấm" — PHẢI sau update)

flowchart LR
  root["oggy-adventure/"]
  root --> idx["index.html<br/>khung DOM + thứ tự &lt;script&gt;"]
  root --> src["src/<br/>toàn bộ mã game (IIFE)"]
  root --> assets["assets/photos/<br/>ảnh thẻ kiến thức + credits.js"]
  root --> tests["tests/<br/>smoke test Node"]
  root --> docs["docs/<br/>hợp đồng, giáo trình"]
  root --> tools["tools/photos/<br/>script Python soạn ảnh"]
  root --> gh[".github/workflows/<br/>CI + deploy Pages"]
  root --> cfg["jsconfig.json<br/>kiểm tra kiểu JSDoc"]

  src --> core["core/ — engine: namespace, events,<br/>save, input, camera, physics, dom,<br/>scenes, loop, scenery-registry,<br/>journeys, main"]
  src --> data["data/ — nhân vật, skin, 4 màn cổ điển"]
  src --> gfx["gfx/ — vẽ procedural: sprites,<br/>skins, scenery, decor*"]
  src --> audio["audio/ — Web Audio: sfx + nhạc"]
  src --> game["game/ — gameplay: player, enemies,<br/>level, boss-scene, game, difficulty..."]
  src --> bosses["bosses/ — kit trùm + 4 trùm"]
  src --> world["world/ — bản đồ, nhiệm vụ, màn phụ"]
  src --> ui["ui/ — menu, HUD, cửa hàng"]
  src --> social["social/ — chia sẻ, bảng xếp hạng"]
  src --> story["story/ — truyện, thẻ, câu đố, dẫn đường"]
  src --> journeys["journeys/ — 4 hành trình<br/>home · vietnam · world · science"]
  src --> types["types.d.ts — kiểu dùng chung"]

  docs --> learn["learn/ — giáo trình (bạn đang ở đây)"]