Vọng Nguyệt Thư Viện

Webgame thẻ bài cổ phong 2D — Hero Deckbuilder nơi chu kỳ mặt trăng thay đổi luật chơi mỗi lượt.

Vọng Nguyệt Thư Viện là dự án cá nhân, phi thương mại (không có nạp tiền thật). Người chơi lập đội 3 Hero cùng một deck 18 lá, đi qua các lượt chơi roguelike, thu thập Hero và trang bị qua gacha, rồi thử sức ở Đấu Trường PvP hoặc cùng đồng đội hạ boss trong chế độ Liên Thủ (co-op).

Thể loại	Hero Deckbuilder 2D + Roguelike + Gacha + PvP + Co-op realtime
Nền tảng	Trình duyệt (desktop)
Ngôn ngữ	TypeScript (strict) toàn bộ dự án
Trạng thái	Giai đoạn 6 hoàn tất — còn bước 5e.2 (triển khai Internet thật)

---

Mục lục

• Điểm nổi bật
• Tính năng hiện có
• Kiến trúc
• Cấu trúc thư mục
• Bắt đầu nhanh
• Các lệnh thường dùng
• Kiểm thử
• Dữ liệu game
• Tài nguyên hình ảnh
• Triển khai
• Tài liệu thiết kế
• Quy tắc phát triển
• Lộ trình

---

Điểm nổi bật

Game được xây trên ba trụ cột thiết kế (chi tiết ở docs/00-gdd.md):

1. Nguyệt Luân — thanh 8 pha trăng tự tiến mỗi vòng. Mỗi pha đổi luật: Trăng Non tăng damage sát thủ, Trăng Tròn nhân đôi hồi máu, Hạ Huyền tăng giáp… Một số lá bài có thể đẩy trăng tiến/lùi hoặc gọi Huyết Nguyệt.
2. Lore thành cơ chế — mỗi Hero thăng cấp trong trận khi đạt điều kiện gắn với tính cách của họ; các cặp Hero có quan hệ đặc biệt mở khóa lá Song Hành.
3. Chơi cùng nhau — PvP 1v1 trên nền trang bị chuẩn hóa (Đấu Trường Công Bằng) và co-op 2 người đánh boss Nguyệt Thực.

Vòng chiến đấu

• Đầu trận rút 6 lá, được Đổi Bài tối đa 2 lá.
• Mỗi vòng nhận Nguyệt Lực (3 ở vòng 1, +1 mỗi vòng, tối đa 8) cộng Nguyệt Lực Dự Trữ mang sang từ lượt trước (tối đa 3).
• Rút bù đủ 6 lá. Chồng bài không xáo lại — hết cả chồng lẫn tay là thua (Cạn Bài).
• Mỗi lá thuộc về một Hero; Hero ngã thì lá của họ thành Tàn Chiêu, nên phải cân nhắc bảo vệ ai.
• Kẻ địch dùng cùng đường cong Nguyệt Lực và báo trước chuỗi chiêu (tối đa 3) qua biểu tượng ý định.

Toàn bộ luật chính xác nằm trong docs/01-combat-rules.md.

---

Tính năng hiện có

Nhóm	Nội dung
Chiến đấu	Luật đầy đủ: Nguyệt Luân 8 pha, Huyết Nguyệt, trạng thái, Phản Đòn, cướp buff, thăng cấp (2 dạng), lá Song Hành, boss hành động theo pha, 21 từ khóa
Roguelike	Bản đồ 8 tầng sinh theo seed (trận thường, Tinh Anh, Nghỉ Chân, Kho Báu, Boss), Kỳ Vật và Lõi trong lượt chơi
Tiến trình	Tài khoản, hồ sơ lưu trên server, Tu Luyện mở khóa lá, xếp và lưu tối đa 30 deck, nhiệm vụ, thành tựu
Gacha & trang bị	3 banner (Hero, Binh Khí, Nguyệt Bảo), bảo hiểm (pity), Tinh Hồn 0–6, Tinh Luyện R1–R5, Cộng Minh 1–5, cửa hàng
PvP — Đấu Trường	Trận xếp hạng Elo với 5 bậc (Đồng Sinh → Trạng Nguyên), Vinh Dự và cửa hàng Vinh Dự, Phòng riêng, Đấu Tập với bot, hẹn giờ lượt, kết nối lại
Co-op — Liên Thủ	Lượt đồng thời, Hợp Kích (đòn phối hợp), Boss Nguyệt Thực 4 giai đoạn, phòng riêng, đồng đội máy, thưởng theo ngày

Nội dung hiện tại (trong packages/data/): 5 Hero, 68 lá bài, 7 kẻ địch, 9 trận, 10 Binh Khí, 8 Nguyệt Bảo, 10 Kỳ Vật, 16 Lõi, 3 Hợp Kích.

---

Kiến trúc

Dự án là một pnpm monorepo với nguyên tắc cốt lõi: luật chơi là code thuần, tất định, dùng chung cho client lẫn server.

                     ┌─────────────────────────────┐
                     │   packages/data             │
                     │   JSON nội dung + schema zod│
                     └──────────────┬──────────────┘
                                    │ GameData
                     ┌──────────────▼──────────────┐
                     │   packages/rules            │
                     │   Luật thuần, RNG có seed   │
                     │   applyAction(state, action)│
                     │     → { state, events }     │
                     └───────┬──────────────┬──────┘
                             │              │
          Action / Event     │              │   replayRun, applyPvpResult,
      ┌──────────────────────▼───┐      ┌───▼──────────────────────────┐
      │  apps/client             │ HTTP │  apps/server                 │
      │  Vite + Phaser 4         │◄────►│  Fastify 5 + WebSocket       │
      │  Hiển thị, input,        │  WS  │  Trọng tài hồ sơ, phiếu      │
      │  animation theo event    │      │  lượt chơi, phòng PvP/co-op  │
      └──────────────────────────┘      └──────────────┬───────────────┘
                                                       │ postgres.js
                                              ┌────────▼────────┐
                                              │ Postgres        │
                                              │ (Supabase)      │
                                              └─────────────────┘

Gói	Công nghệ	Vai trò
packages/rules	TypeScript thuần	Toàn bộ luật chiến đấu, roguelike, PvP, co-op và meta (hồ sơ, kinh tế, gacha, Elo). Không phụ thuộc DOM, mạng, file system; không dùng Math.random() hay Date.now()
packages/data	JSON + zod	Nội dung game và schema kiểm tra khi nạp; tính dataVersion (FNV-1a 64 bit) để client và server khớp phiên bản dữ liệu
apps/client	Vite 8, Phaser 4	Chỉ gửi Action, nhận CombatEvent[] rồi phát animation theo thứ tự. Mọi con số hiển thị lấy từ state
apps/server	Node 22, Fastify 5, @fastify/websocket, postgres	Tài khoản, hồ sơ, phiếu lượt chơi, gacha, hàng chờ xếp hạng, phòng trận realtime. Bundle bằng Vite SSR build

This is the beginning of the README. Read the rest at the original. Read the full README ↗