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
Game được xây trên ba trụ cột thiết kế (chi tiết ở docs/00-gdd.md):
- 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.
- 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.
- 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 |
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
