Sơ đồ thiết kế chi tiết Oggy Adventure

Thư mục này là bộ sơ đồ thiết kế chi tiết (design diagrams) của game: dữ liệu trông như thế nào, mỗi module có những "lớp" (object) và hàm gì, các luồng quan trọng chạy theo thứ tự nào, các máy trạng thái bên trong, cách code được nạp và đưa lên mạng, và vì sao chúng tôi thiết kế như vậy.

Bức tranh tổng quan đọc trước: docs/learn/ARCHITECTURE-DIAGRAMS.md có 5 sơ đồ lớn: phụ thuộc giữa các module, máy trạng thái các scene, luồng event (ai phát ai nghe), vòng đời một frame, cây thư mục. Bộ sơ đồ ở đây không vẽ lại các sơ đồ đó mà đi sâu vào từng phần.

Hợp đồng chính thức (API, payload, thứ tự load) vẫn là docs/ARCHITECTURE.md và docs/STORY.md. Sơ đồ khác code thì code đúng, sơ đồ cần sửa.

Mục lục #

Gợi ý thứ tự đọc cho người mới: 06 (hiểu vì sao) → 05 (bức tranh triển khai) → 01 (dữ liệu) → 02 (module) → 03 và 04 (hành vi). Khi đọc một bài trong docs/learn/, mở sơ đồ tương ứng bên cạnh.

Xem sơ đồ ở đâu #

• GitHub tự vẽ mọi khối ```mermaid. VS Code cần extension xem trước Mermaid (vd "Markdown Preview Mermaid Support").
• Ngoại tuyến: dưới mỗi sơ đồ có link (xem SVG) trỏ tới bản đã vẽ sẵn trong svg/. Các file này được vẽ bằng Kroki từ đúng khối Mermaid phía trên (font chữ trong SVG đã đổi sang "Segoe UI", system-ui, ... như OG.FONT để hiện đủ dấu tiếng Việt).
• Muốn sửa thử một sơ đồ: dán khối Mermaid vào https://mermaid.live.

Cách đọc ký hiệu Mermaid (cho người mới) #

Mỗi mục dưới đây có một sơ đồ tí hon dùng chính tên trong game, kèm bảng ký hiệu.

Class diagram (sơ đồ lớp) #

Game không dùng class của JavaScript, nhưng mỗi namespace OG.X là một object có dữ liệu + hàm, nên vẫn vẽ được như một "lớp". Ô có ba phần: tên, thuộc tính, phương thức.

classDiagram
  class Scene {
    <<interface>>
    +enter(params, fromName)
    +update(dt)
    +draw(ctx)
  }
  class Scenes["OG.Scenes"] {
    -registry : Object
    -stack : StackEntry[]
    +go(name, params)
    +push(name, params)
    +pop()
  }
  class LevelScene["scene 'level'"]
  Scenes o-- Scene : giữ nhiều
  LevelScene ..|> Scene : cài đặt

(xem SVG)

Sequence diagram (sơ đồ tuần tự) #

Đọc từ trên xuống theo thời gian. Mỗi cột là một bên tham gia (module, scene, trình duyệt).

sequenceDiagram
  participant P as OG.Player
  participant Ev as OG.Events
  participant Au as OG.Audio
  P->>Ev: emit('player:jump', {charId, x, y})
  Ev->>Au: listener(payload)
  Au-->>Ev: (không trả gì)
  Note over Ev,Au: Player không biết Audio tồn tại

(xem SVG)

State diagram (sơ đồ trạng thái) #

Mỗi ô là một trạng thái, mũi tên là chuyển trạng thái kèm điều kiện. [*] là điểm bắt đầu / kết thúc.

stateDiagram-v2
  direction LR
  [*] --> play : enter()
  play --> clear : đủ pizza + chạm EXIT
  clear --> done : sau CLEAR_DELAY giây
  done --> [*]

(xem SVG)

ER diagram (sơ đồ thực thể – quan hệ) #

Dùng cho dữ liệu. Mỗi khối là một loại bản ghi, bên trong là field (kiểu, tên, ghi chú). Đường nối có ký hiệu số lượng ở hai đầu.

erDiagram
  JourneyDef ||--|{ AreaDef : "areas"
  AreaDef ||--|{ LevelDef : "levels"
  JourneyDef {
    string id PK "home, vietnam..."
    string title
  }

(xem SVG)

Đường liền = quan hệ "chứa trong" (dữ liệu lồng nhau trong cùng object). Đường đứt (..) = tham chiếu bằng id chuỗi (không lồng, phải tra cứu).

Flowchart (lưu đồ) #

Dùng cho thành phần, thứ tự nạp, triển khai. subgraph là một nhóm (khung).

flowchart LR
  subgraph dev["Máy bạn"]
    code["index.html + src/"]
  end
  code -->|git push| ci["GitHub Actions"] --> pages["GitHub Pages"]

(xem SVG)

Quy ước chung của bộ sơ đồ #

• Tên trong sơ đồ (namespace, hàm, scene, event, field, state) lấy nguyên văn từ code và được kiểm tra bằng grep. Hàm nội bộ (không gắn vào OG) có dấu - hoặc ghi "(nội bộ)".
• Link tới code dạng src/game/level.js kèm tên hàm (không ghi số dòng vì code còn thay đổi).
• Đơn vị: giây (thời gian game), px (toạ độ logic 960×540), giống docs/learn/CODE_STYLE.md.
• Sơ đồ lớn được tách nhỏ (≤ ~25 nút). Chi tiết không vẽ được thì nằm trong phần giải thích ngay dưới sơ đồ.

Tự kiểm tra sau khi sửa #

Công cụ render-svg.js (Node, không cần thư viện) gửi từng khối Mermaid tới Kroki, lưu SVG vào svg/, và kiểm tra mọi link tương đối + anchor #... trong các file .md ở đây. Tên file SVG lấy từ link (svg/<tên>.svg) ngay dưới mỗi khối.

node docs/design/render-svg.js            # vẽ lại toàn bộ SVG (cần mạng) + kiểm tra link
node docs/design/render-svg.js --links    # chỉ kiểm tra link, không cần mạng
node docs/design/render-svg.js 04         # chỉ vẽ lại file có tên chứa "04"

git grep -nE "Scenes\.(register|go|push)\('" -- src   # đối chiếu tên scene
git grep -nE "setState\('[a-zA-Z]+'" -- src/bosses     # đối chiếu trạng thái trùm
git grep -nE "Save\.ns\('[a-z]+'\)" -- src             # đối chiếu các ngăn ext.* của SaveData