README — GDD đầy đủ

• Tài liệu thiết kế toàn bộ game Bladewake 1.0: action roguelite hack & slash, pixel art góc nhìn 3/4 từ trên xuống (pixelfx), bầy 150–250 kẻ địch, PC Steam trước (premium), tay cầm trước + bàn phím/chuột đủ, Steam Deck.
• Mục tiêu: đội người + agent AI dựng được cả game không cần hỏi lại — mọi luật, số, id, asset, âm thanh, UI, kiểm thử đều có ở đây.
• Cấu trúc 3 lớp:
  • docs/*.md — luật viết tay (vì sao, công thức, quy trình, bảng tham chiếu).
  • data/**/*.json — nguồn sự thật duy nhất cho mọi số/id/nội dung; kiểm bằng tools/schema/*.schema.json (draft 2020-12, additionalProperties: false).
  • Bản render (không sửa tay): docs/generated/, data/_unity/, data/_merged.json, site/, Design/ArtSpecs/.
• GDD demo (GDD/*.md, GDD/Data/*.csv) là lịch sử — Full thắng khi lệch.

1. docs/00-Design-Bible.md + data/_bible.json (id, tên, số canon; prose ≠ JSON → bug, sửa cả hai cùng lượt, số/id theo JSON).
2. Doc nền: 01, 10–17, 20, 30–32, 51.
3. Dữ liệu nội dung data/**/*.json và các doc còn lại (18, 19, 21, 23, 40–43, 50, 60).
4. Phán đoán của người/agent — chỉ khi 3 tầng trên im lặng, và phải ghi dòng quyết định (§8).

Thuật ngữ khoá (tên Bible thắng): Khăn Tang / Độ Tang Tro Dày MRN01–Tro Sống MRN15 · Act Mutator Trăng Tro MUT01–Gương Tro MUT12 · Dạng Rèn (aspect) · Dư Âm (ULT_GAUGE) · phòng thủ = chạm ĐÁP + verb giữ riêng của hero · Then Chốt = Edge E37–E40 · trạng thái STS_<NAME> · trạm hub ST_<NAME> · đòn địch mang adaptive_source BASE|ASH.

Chi tiết field: doc 51 §4. Chỉ sửa JSON; tệp/thư mục bắt đầu bằng _ (trừ _bible.json) là render/nháp.

                 00 Design Bible + data/_bible.json  (canon)
                                  |
     +-------------+--------------+-------------+--------------+
     |             |              |             |              |
  01 Roadmap   51 Data Schema  20 Lore      30 Art Dir     50 Tech Arch
     |          (schema/*)       |             |              |
     |             |          21 Story      31 VFX        41 Controls
     |             |          23 Map/Hub    32 Audio       42 Access.
     |             |             |             |           43 Steam
     |      10 Combat Core ------+-------------+
     |        |        |
     |  11 Defense   12 Hero Framework -- mechanics.json
     |   Tells         |
     |        \        |
     |     13 Upgrades/Builds -- 17 Economy/Balance (balance_calc.py)
     |              |                 |
     |     14 Adaptive AI -----> 15 Horde Director/Encounters
     |              |                 |
     |              +----> 16 Run Structure/Map
     |                          |
     |                 18 Meta/Hub <-> 19 Difficulty/Modes
     |                          |
     +------------------> 40 UI/UX/HUD
                                |
                     60 QA/Telemetry/Playtest (kiểm mọi tầng)

 data/**/*.json --validate/audit--> build_gdd.py --> docs/generated, data/_unity, Design/ArtSpecs
                                    build_site.py --> site/

Đọc: đường đi xuống = doc dưới phụ thuộc doc trên. Mỗi doc ghi đủ phụ thuộc ở dòng Phụ thuộc đầu file.

Danh sách từ cấm nằm ngoài repo: truyền --banned-terms <file|thư mục> hoặc đặt env BW_BANNED_TERMS.

py -3 GDD/Full/tools/validate.py --file GDD/Full/data/heroes/H03.json --banned-terms <thư mục từ cấm>   # sau mỗi lần sửa 1 file
py -3 GDD/Full/tools/validate.py --all --banned-terms <thư mục từ cấm>                                  # trước merge: 0 ERROR
py -3 GDD/Full/tools/audit_gdd.py --banned-terms <thư mục từ cấm>                                       # cổng G01–G13; --only G03,G05 · --file <data> · --json <báo cáo>
py -3 GDD/Full/tools/balance_calc.py --selftest                                                           # ví dụ doc 17 + --check-data
py -3 GDD/Full/tools/build_gdd.py                                                                         # md, csv, art, merged (--only md,csv · --schema-check)
py -3 GDD/Full/tools/build_site.py                                                                        # web tĩnh → GDD/Full/site/
py -3 GDD/Full/tools/check_site.py --banned "<glob file từ cấm>"                                          # kiểm site trước phát hành

Python = py -3, UTF-8, chỉ stdlib + jsonschema. Không bao giờ để JSON hỏng trên đĩa; bản render luôn dựng lại từ JSON, không sửa tay.

1. Không sửa dữ liệu trước. Ghi mục quyết định có ngày ở Bible §12: DEC-YYYY-MM-DD-nn — mục bị thay · cũ → mới · lý do · người duyệt.
2. Sửa 00-Design-Bible.md + data/_bible.json cùng lượt; đổi INV cần quyết định riêng + chạy lại kiểm màu INV-01 + test 5 s.
3. Doc/dữ liệu con lệch canon: thêm dòng quyết định có ngày vào ghi chú của chính file đó, dạng 2026-11-07 - <cũ → mới, lý do> (doc: mục "Quyết định đã chốt"; JSON: field ghi chú *_vi gần nhất).
4. Thêm LOẠI thực thể, đổi số lượng, tạo id ngoài dải canon (Edge 41+, SE073+, RL061+…), thêm field (sửa tools/schema + doc 51 §4), thêm key mechanics.json (sửa doc 12 §9/§10) → đều cần DEC.
5. Chạy validate.py --all + audit_gdd.py đến exit 0, rồi build_gdd.py + build_site.py.
6. Không ghi tên game, studio, nhà phát hành, thương hiệu hay nhân vật có thật vào bất kỳ file nào trong repo.