📚 Học lập trình game với Oggy

Giáo trình này dùng chính mã nguồn của Oggy Adventure (game đi cảnh 2D chạy trên trình duyệt) để dạy khái niệm làm game và design pattern (mẫu thiết kế). Bạn sẽ đọc code thật của một game hoàn chỉnh, chạy thí nghiệm nhỏ, rồi tự viết thêm tính năng.

Dành cho ai: sinh viên đại học đã biết JavaScript cơ bản: biến, hàm, mảng, object, vòng lặp, callback, DOM (document.getElementById, addEventListener). Giáo trình không dạy lại cú pháp JS. Nó dạy những thứ sách JS thường bỏ qua: vì sao game cần game loop (vòng lặp game), làm sao nhân vật nhảy đúng như nhau trên màn 60 Hz và 144 Hz, vì sao một module âm thanh có thể "nghe" người chơi nhảy mà không ai gọi nó...

Vì sao học bằng game này:

• Không build step, không thư viện ngoài. Mở index.html là chạy. Mọi dòng code đều do dự án tự viết, không có "hộp đen".
• Đủ lớn để giống dự án thật (khoảng 70 file JS, 38 màn, 4 trùm, nhạc tổng hợp, lưu trữ, bảng xếp hạng, test tự động), nhưng chia module rõ ràng nên đọc từng phần được.
• Code đã được chú thích để dạy học: mỗi file có khối đầu file ghi vai trò, khái niệm, bài học liên quan; trong code có các nhãn 💡 Khái niệm:, ⚠️ Bẫy:, 🧪 Thử: (xem mục 6).

Mục lục #

1. Lộ trình 14 bài
2. Chuẩn bị: chạy game và mở DevTools
3. Dùng VS Code: gợi ý kiểu với JSDoc và @ts-check
4. Quy tắc làm bài tập
5. Mỗi bài học gồm những gì
6. Cách đọc code có chú thích
7. Bảng thuật ngữ nhanh
8. Sự cố thường gặp
9. Tài liệu liên quan

1. Lộ trình 14 bài #

Thời lượng là ước tính cho một sinh viên trung bình, đã gồm đọc bài, đọc code, làm thí nghiệm 🧪 và bài tập. Tổng cộng khoảng 36 giờ, tức chừng 6–8 tuần nếu học 5 giờ mỗi tuần.

Đi theo thứ tự nào? #

Bài 00–02 là bắt buộc và nên học đúng thứ tự. Từ bài 03 trở đi, bạn có thể đi theo mũi tên "cần học trước":

flowchart LR
  b00["00 Bắt đầu"] --> b01["01 Module"] --> b02["02 Game loop"]
  b02 --> b03["03 Input"] --> b04["04 Vật lý"]
  b02 --> b04
  b02 --> b05["05 State machine"]
  b01 --> b06["06 Event bus"]
  b02 --> b07["07 Canvas"]
  b04 --> b08["08 Camera"]
  b07 --> b08
  b04 --> b09["09 AI & trùm"]
  b05 --> b09
  b06 --> b10["10 Web Audio"]
  b01 --> b11["11 Lưu trữ"]
  b04 --> b12["12 Data-driven"]
  b05 --> b12
  b06 --> b12
  b02 --> b13["13 Kiểm thử & CI"]
  b06 --> b13

Gợi ý ba hướng học nếu không đủ thời gian làm hết:

• Gameplay (khoảng 15 giờ): 00 → 01 → 02 → 03 → 04 → 05 → 09.
• Đồ hoạ và âm thanh (khoảng 15 giờ): 00 → 01 → 02 → 06 → 07 → 08 → 10.
• Kiến trúc phần mềm (khoảng 16 giờ): 00 → 01 → 02 → 05 → 06 → 11 → 12 → 13.

2. Chuẩn bị: chạy game và mở DevTools #

2.1 Cần cài gì #

Dự án không có package.json và không cần npm install. Node chỉ dùng để chạy test.

2.2 Chạy game #

git clone <địa chỉ repo của lớp> oggy-adventure
cd oggy-adventure

Cách 1: mở trực tiếp. Nhấp đúp index.html. Game chạy qua file:// vì không dùng ES modules (bài 01 giải thích lý do).

Cách 2: server tĩnh (khuyên dùng khi học). Một số trình duyệt chặn localStorage với file://, nên tiến độ không được lưu. Chạy một trong hai lệnh rồi mở http://localhost:8080:

python -m http.server 8080
# hoặc (cần mạng lần đầu để tải gói serve)
npx serve -l 8080 .

Dừng server bằng Ctrl + C trong cửa sổ terminal đã mở nó.

Chạy smoke test (kiểm thử tự động chơi hết game, mất khoảng 20–60 giây tuỳ máy):

node tests/smoke.js            # ổn thì in "XANH — không có lỗi runtime." và thoát mã 0; có lỗi thì thoát mã 1
node tests/smoke.js --verbose  # in từng bước và số lần phát mỗi event
node --check src/core/loop.js  # chỉ kiểm tra cú pháp một file
node tests/check-doc-links.js  # kiểm tra mọi link tương đối trong docs/learn/ (in "SẠCH" nếu không có link gãy)

2.3 Mở DevTools #

DevTools (công cụ cho nhà phát triển có sẵn trong trình duyệt) là "phòng thí nghiệm" chính của giáo trình.

Các tab bạn sẽ dùng:

Lệnh Console hay dùng (gõ khi game đang chạy):

OG.Scenes.stackNames()                 // scene stack hiện tại, vd ["level", "pause"]
OG.Loop.fps                            // FPS ước lượng
OG.Config.GRAVITY = 600                // trọng lực thấp: nhảy như trên Mặt Trăng (bài 04)
OG.Config.DEBUG = true                 // OG.Events in mọi event ra Console (bài 06)
var off = OG.Events.on('*', function (name, payload) { console.log(name, payload); });
off();                                 // huỷ đăng ký listener ở dòng trên
OG.Sprites.setCacheEnabled(false)      // tắt cache khung hình rồi xem OG.Loop.fps (bài 07)
OG.Save.data                           // toàn bộ dữ liệu lưu (bài 11)
OG.Journeys.validate('home')           // kiểm tra dữ liệu hành trình (bài 12)

⚠️ Thay đổi gõ trong Console chỉ sống tới khi tải lại trang (F5). Muốn thay đổi lâu dài thì sửa file trong src/.

⚠️ Gõ Console khi đang chơi: game tự tạm dừng và xoá phím. Bấm chuột vào DevTools để gõ lệnh thì cửa sổ game mất focus (phát event blur; có thể xảy ra cả khi DevTools gắn liền cửa sổ). Lúc đó hai việc xảy ra:

1. src/core/main.js (hàm autoPause) push scene pause nếu đang ở level/boss → stack thành ["level", "pause"].
2. src/core/input.js gọi OG.Input.reset() → mọi phím đang giữ bị nhả. Bấm "Tiếp tục" thì OG.Scenes.pop() lại gọi OG.Input.reset() thêm lần nữa.

Hậu quả: lệnh như OG.Input.setKey('right', true) gõ thẳng vào Console sẽ không làm Oggy tự chạy (phím bị xoá khi bạn bấm "Tiếp tục"), và thí nghiệm "giữ phím rồi làm gì đó" không làm được. Đây là hành vi cố ý của game (bài 03 mục 4, bài 05), không phải lỗi của bạn. Cách làm thí nghiệm:

• Hẹn giờ: bọc lệnh trong setTimeout(..., 3000), nhấn Enter, rồi trong vòng 3 giây bấm "Tiếp tục" trên màn hình game (bấm vào game để trang có lại focus). Lệnh chạy khi bạn đã quay lại chơi:

  jsSao chép

  setTimeout(function () { OG.Input.setKey('right', true); }, 3000);   // dừng: OG.Input.setKey('right', false)

• Tách DevTools ra cửa sổ riêng (menu ⋮ của DevTools → Dock side → Undock) cũng vẫn làm game mất focus, nên vẫn cần hẹn giờ.

• Lệnh chỉ đọc trạng thái (OG.Scenes.stackNames(), OG.Loop.fps, OG.Sprites.cacheStats()) hay đổi cấu hình (OG.Config.GRAVITY = 600) thì không bị ảnh hưởng: gõ xong bấm "Tiếp tục" là được.

3. Dùng VS Code: gợi ý kiểu với JSDoc và @ts-check #

Mở cả thư mục dự án trong VS Code (File → Open Folder...), không mở từng file lẻ, để VS Code đọc được jsconfig.json.

JSDoc là comment dạng /** ... */ mô tả kiểu tham số và giá trị trả về. VS Code dùng nó để gợi ý code và báo lỗi kiểu, dù code vẫn là JavaScript thuần (không cần TypeScript, không cần build).

• jsconfig.json: đặt checkJs: false, nghĩa là chỉ file có dòng đầu // @ts-check mới bị kiểm tra kiểu. Đây là cách bật kiểm tra từng file một (opt-in) để dự án lớn chuyển dần sang có kiểu mà không bị ngập lỗi.
• src/types.d.ts: các kiểu dùng chung (AABB, Scene, LevelDef, BossInstance, ThemeDef...). Trong file JS, bạn viết /** @type {Player} */ var p = st.player; để VS Code biết p có những field nào.

Thao tác nên tập ngay ở bài 00:

Kiểm tra kiểu cho cả dự án bằng dòng lệnh (không in gì và mã thoát 0 nghĩa là sạch):

npx -y -p [email protected] tsc -p jsconfig.json --noEmit

Lệnh này tải TypeScript tạm thời để kiểm tra, không thêm thư viện nào vào dự án và không sinh file nào.

Extension VS Code tuỳ chọn (không bắt buộc, dự án không phụ thuộc vào chúng):

• Một extension xem trước Mermaid cho Markdown, để thấy sơ đồ trong ARCHITECTURE-DIAGRAMS.md ngay trong VS Code.
• Một extension "live server" để chạy server tĩnh thay cho python -m http.server.

4. Quy tắc làm bài tập #

4.1 Mỗi bài tập một nhánh Git riêng #

Không làm bài tập thẳng trên nhánh chính (master). Mỗi bài tập là một nhánh (branch) riêng để dễ nộp, dễ chấm và dễ bỏ đi làm lại.

# 1. Bắt đầu từ nhánh chính sạch sẽ, mới nhất
git switch master
git pull
git status                       # phải báo "nothing to commit, working tree clean"

# 2. Tạo nhánh cho bài tập. Quy ước tên: bt/<số bài>-<tên ngắn>-<mã sinh viên>
git switch -c bt/04-nhay-cao-21520001

# 3. Làm bài, kiểm tra thường xuyên
node --check src/game/player.js  # mỗi file vừa sửa
node tests/smoke.js              # trước mỗi commit: phải XANH

# 4. Commit nhỏ, thông điệp nói rõ làm gì
git add src/game/player.js
git commit -m "bt04: thêm nhảy cao khi giữ phím lâu hơn"

# 5. Nộp: đẩy nhánh lên và tạo Pull Request (hoặc theo cách giảng viên yêu cầu)
git push -u origin bt/04-nhay-cao-21520001

Muốn làm lại từ đầu thì quay về master và tạo nhánh mới. Không cần xoá code đã viết.

4.2 Luật chung khi sửa code #

1. Smoke test phải XANH trước khi nộp. Test đỏ thì đọc dòng báo lỗi đầu tiên, sửa xong mới nộp.
2. Giữ ràng buộc của dự án: không thêm build step, không thêm thư viện ngoài, không dùng import/export, game vẫn phải chạy khi mở index.html qua file://.
3. Không đổi API công khai trừ khi đề bài yêu cầu: tên hàm OG.X.fn, tên scene, chuỗi tên event trong OG.EV, định dạng dữ liệu lưu và dữ liệu màn. Có nhiều nơi phụ thuộc vào chúng (xem ARCHITECTURE-DIAGRAMS.md).
4. File mới phải có thẻ <script> trong index.html đúng vị trí theo thứ tự phụ thuộc (bài 00, 01), và có khối đầu file theo CODE_STYLE.md mục 2.
5. Comment theo CODE_STYLE.md: tiếng Việt có dấu, giải thích tại sao chứ không lặp lại cái gì, ghi đơn vị (giây, px, px/giây). Font chữ dùng OG.font(...) / OG.FONT; không gõ tên "font cấm" ghi ở CODE_STYLE.md mục 0 (smoke test quét cả comment và sẽ báo đỏ).
6. Thí nghiệm 🧪 là để thử rồi hoàn lại. Sau khi thử, chạy git restore <file> (hoặc git diff để xem mình đã đổi gì) để nhánh bài tập chỉ chứa phần bài làm.
7. Ghi lại điều đã học: trong mô tả Pull Request, viết 3–5 câu: đã đổi gì, vì sao chọn cách đó, đã kiểm tra thế nào.

5. Mỗi bài học gồm những gì #

Mỗi file bài NN-*.md có cùng một khung:

Lời giải của bài tập nằm trong solutions/, cùng tên file với bài học (vd solutions/03-input.md). Hãy tự làm trước, chỉ mở lời giải để so sánh sau khi smoke test của bạn đã XANH.

6. Cách đọc code có chú thích #

6.1 Khối đầu file #

Mọi file trong src/ mở đầu bằng một khối giới thiệu (định dạng đầy đủ ở CODE_STYLE.md mục 2):

/* ============================================================================
 * OG.Loop — VÒNG LẶP GAME (game loop)
 * ----------------------------------------------------------------------------
 * Vai trò:      module này làm gì trong game, ai gọi nó, khi nào
 * Khái niệm:    các khái niệm / pattern file này minh hoạ
 * Bài học:      bài học liên quan trong docs/learn/
 * Phụ thuộc:    module khác mà file này dùng (đọc lúc LOAD hay lúc CHẠY)
 * Event:        phát: ... · nghe: ...
 * API công khai: các hàm gắn vào OG.*
 * Đọc tiếp:     file nên đọc tiếp theo
 * ========================================================================== */

Đọc dòng Vai trò và Đọc tiếp trước. Chỉ cần vậy là đủ để đi hết dự án theo một mạch.

Hai file mẫu đã áp dụng chuẩn đầy đủ, nên đọc đầu tiên: src/core/loop.js và src/core/events.js.

6.2 Ba nhãn trong code #

Tìm mọi nhãn trong dự án:

git grep -n "🧪 Thử" -- src         # mọi thí nghiệm
git grep -n "⚠️ Bẫy" -- src/core    # mọi bẫy trong engine

6.3 Thứ tự đọc dự án gợi ý #

1. index.html: xem danh sách <script> (đó là bản đồ của cả dự án).
2. src/core/namespace.js → src/core/events.js → src/core/loop.js → src/core/scenes.js → src/core/main.js.
3. src/game/level.js → src/game/player.js → src/core/physics.js: một frame gameplay diễn ra thế nào.
4. Sau đó đọc theo bài học bạn đang học.

Sơ đồ module, scene, event và vòng đời frame: ARCHITECTURE-DIAGRAMS.md. Muốn đào sâu hơn (mô hình dữ liệu, class diagram, sequence diagram từng luồng, state machine của boss/quiz/audio, sơ đồ triển khai và 10 quyết định thiết kế): docs/design/.

7. Bảng thuật ngữ nhanh #

8. Sự cố thường gặp #

9. Tài liệu liên quan #

• ARCHITECTURE-DIAGRAMS.md: sơ đồ Mermaid về module, scene, event, vòng đời frame, cây thư mục.
• docs/design/: 60 sơ đồ thiết kế chi tiết — mô hình dữ liệu, class diagram, sequence diagram, state machine, component & deployment, và các bản ghi quyết định thiết kế (ADR).
• CODE_STYLE.md: quy ước comment, JSDoc, refactor; bắt buộc đọc trước khi nộp bài tập đầu tiên.
• docs/ARCHITECTURE.md: hợp đồng API v1 (thứ tự load, toạ độ, scene, event, API từng module).
• docs/STORY.md: hợp đồng v2 (dữ liệu hành trình, độ khó, truyện, thẻ, câu đố).
• src/types.d.ts: kiểu dữ liệu dùng chung cho JSDoc.
• src/<thư mục>/INTEGRATION.md (vd src/gfx/INTEGRATION.md): ghi chú tích hợp của từng thư mục. Dự án được viết song song bởi nhiều nhóm, mỗi nhóm giữ một thư mục; file này ghi việc nhóm đó cần nhóm Tích hợp làm ở ngoài thư mục (thêm thẻ <script>, gắn hook, payload event mới). Khi bài tập bảo "ghi vào INTEGRATION.md của module", hãy viết theo cùng kiểu.
• README.md ở thư mục gốc: giới thiệu game, cách chơi, deploy.