05 · Thành phần, thứ tự nạp và triển khai

flowchart TB
  subgraph L4["Tính năng (feature)"]
    direction LR
    ui["ui/<br/>OG.Menus · OG.Shop"]
    story["story/<br/>OG.Story · Learn · Guide · Photos"]
    world["world/<br/>OG.World · OG.Quests"]
    social["social/<br/>OG.Social"]
    bosses["bosses/<br/>OG.Bosses"]
    audio["audio/<br/>OG.Audio"]
  end
  subgraph L3["Gameplay"]
    game["game/<br/>OG.Game · Level · Player · Enemies<br/>Collectibles · Particles · Progress<br/>Difficulty · BossScene"]
  end
  subgraph L2["Đồ hoạ + dữ liệu"]
    direction LR
    gfx["gfx/<br/>OG.Sprites · OG.Decor"]
    data["data/<br/>OG.Data"]
  end
  subgraph L1["Lõi engine"]
    core["core/<br/>OG.util · Events · Save · Input · Camera<br/>Physics · DOM · Scenes · Loop<br/>Scenery · Journeys"]
  end
  journeys[["journeys/&lt;id&gt;/ (dữ liệu)<br/>theme · content · extras · journey"]]
  photos[["assets/photos/&lt;id&gt;/credits.js (dữ liệu)"]]
  bus(("OG.Events<br/>event bus"))

  L4 -->|"① gọi trực tiếp API công khai"| L3
  L4 -->|"①"| L2
  L4 -->|"①"| L1
  L3 -->|"①"| L2
  L3 -->|"①"| L1
  L2 -->|"①"| L1
  L3 -.->|"② OG.util.call (tuỳ chọn)"| L4
  L1 -.->|"② main.js: util.call(ns, 'init')<br/>theo FEATURE_INIT_ORDER"| L4
  L3 ==>|"③ emit"| bus
  L4 ==>|"③ emit / on"| bus
  bus ==>|"③ on"| audio
  journeys -->|"④ register lúc LOAD"| L1
  journeys -->|"④"| L2
  journeys -->|"④ registerType"| L3
  journeys -->|"④ Bosses.register"| bosses
  photos -->|"④ Photos.register"| story

flowchart TB
  subgraph G1["1 · Core"]
    ns["namespace.js<br/>tạo window.OG, OG.util"] --> ev["events.js"] --> sv["save.js · input.js · camera.js<br/>physics.js · dom.js · scenes.js · loop.js"]
    sv --> scr["scenery-registry.js"] --> jr["journeys.js"]
  end
  subgraph G2["2 · Data"]
    chars["characters.js"] --> lvls["levels.js"]
  end
  subgraph G3["3 · Gfx"]
    spr["sprites.js"] --> skins["skins.js<br/>registerSkin lúc load"] --> scen["scenery.js"] --> dec["decor.js<br/>registerDecor/Layer"] --> decp["decor-places.js · decor-home.js<br/>OG.Decor.define"]
  end
  subgraph G45["4–5 · Audio + Game"]
    aud["audio.js → music.js"]
    gm["particles · progress · difficulty · game · player<br/>enemies · collectibles · level · boss-scene<br/>→ default-scenes.js (scene mặc định)"]
  end
  subgraph G6["6 · Bosses"]
    bs["bosses.js (kit, factories)"] --> b3["joey.js · marky.js · deedee.js<br/>Bosses.register"] --> trio["trio.js<br/>dùng factories.*"]
  end
  subgraph G79["7–9 · World, UI, Social"]
    wl["extraLevels.js (registerLevel) → world.js → journey-map.js → quests.js"]
    uis["menus.js → hud.js → shop.js"]
    soc["social.js → leaderboard.js (cần OG.Social)"]
  end
  subgraph G10["10 · Story"]
    st["story.js → learn.js → photos.js"] --> cr["assets/photos/*/credits.js<br/>OG.Photos.register"] --> gd["guide.js → scenes.js<br/>Scenes.register lúc load"]
  end
  subgraph G11["11 · Journeys (×4)"]
    th["theme.js<br/>Scenery.registerTheme"] --> ct["content.js<br/>Journeys.register"] --> ex["extras.js<br/>Enemies.registerType..."] --> jj["journey.js<br/>Journeys.register (gộp)"]
  end
  main["12 · main.js — LUÔN CUỐI<br/>boot() khi DOM sẵn sàng"]
  G1 --> G2 --> G3 --> G45 --> G6 --> G79 --> G10 --> G11 --> main
  chars -.->|"OG.Data.registerSkin"| skins
  scr -.->|"OG.Scenery"| dec
  lvls -.->|"OG.Data.registerLevel"| wl

flowchart LR
  subgraph DEV["Máy người phát triển"]
    direction TB
    src["index.html, src/, assets/,<br/>docs/, CNAME, robots.txt,<br/>sitemap.xml, llms.txt, site.webmanifest"]
    run1["Mở thẳng index.html<br/>(file://)"]
    run2["python -m http.server 8080<br/>hoặc npx serve ."]
    smoke1["node tests/smoke.js"]
    src --> run1 & run2 & smoke1
  end
  subgraph GH["GitHub"]
    repo[("repo, nhánh master")]
    subgraph ACT["GitHub Actions: Deploy GitHub Pages"]
      build["job build<br/>smoke test → đóng gói _site"]
      deploy["job deploy<br/>actions/deploy-pages@v4"]
      build --> deploy
    end
    pages["GitHub Pages<br/>môi trường github-pages"]
  end
  dns["DNS tên miền<br/>oggy-adventure.tiennhm.io.vn<br/>(file CNAME)"]
  user["Trình duyệt người chơi<br/>HTTPS, localStorage riêng theo tên miền"]
  src -->|"git push master<br/>(hoặc chạy tay workflow_dispatch)"| repo
  repo --> build
  deploy --> pages
  pages --> dns --> user

flowchart TB
  trig(["push lên master<br/>hoặc workflow_dispatch"]) --> conc["concurrency: group pages,<br/>cancel-in-progress: true"]
  conc --> b1
  subgraph BUILD["job build (ubuntu-latest)"]
    b1["actions/checkout@v5"] --> b2["actions/setup-node@v5<br/>node-version 22"]
    b2 --> b3{"node tests/smoke.js<br/>XANH?"}
    b3 -->|"không"| stop(["dừng: KHÔNG deploy"])
    b3 -->|"có"| b4["Đóng gói site:<br/>mkdir _site<br/>cp -r index.html src docs assets CNAME .nojekyll<br/>robots.txt sitemap.xml llms.txt site.webmanifest _site/<br/>rm -f _site/assets/photos/*/_entries.json"]
    b4 --> b5["actions/configure-pages@v5"] --> b6["actions/upload-pages-artifact@v3<br/>path: _site"]
  end
  subgraph DEPLOY["job deploy (needs: build)"]
    d1["actions/deploy-pages@v4<br/>environment: github-pages"]
  end
  b6 --> d1
  d1 --> live(["site mới trên GitHub Pages"])

flowchart LR
  author["Người soạn nội dung"] -->|"search 'từ khoá'"| tool["tools/photos/fetch_commons.py<br/>(Python 3 + Pillow, chạy TAY)"]
  tool <-->|"API Commons: User-Agent,<br/>nghỉ ~1 giây, lùi lại khi 429"| commons[("Wikimedia Commons")]
  manual[("Unsplash / Pexels / NASA<br/>(lệnh url)")] --> tool
  content["src/journeys/&lt;id&gt;/content.js<br/>(danh sách cardId hợp lệ)"] -->|"card_ids"| tool
  tool -->|"get: tải, thu nhỏ cạnh dài ≤ 800 px,<br/>WebP quality 78, kiểm giấy phép"| webp[("assets/photos/&lt;id&gt;/&lt;cardId&gt;.webp")]
  tool -->|"get / url / remove"| entries[("_entries.json<br/>(tạm, .gitignore)")]
  entries -->|"write &lt;id&gt;"| credits["assets/photos/&lt;id&gt;/credits.js<br/>OG.Photos.register(...)<br/>JSON giữa BEGIN/END-ENTRIES"]
  credits --> game["Game: OG.Photos (nạp lười)"]
  credits --> creditsPage["docs/credits.html<br/>(trang ghi công)"]
  credits --> smoke["tests/smoke.js photoChecks<br/>giấy phép, cardId, thứ tự nạp"]