t1k:designer:analysis:game-teardown
| Field | Value |
|---|---|
| Module | analysis |
| Version | 1.1.3 |
| Effort | high |
| Tools | — |
Keywords: apk, booster, competitor game, dịch ngược, độ khó, element, ftue, game teardown, game tham khảo, il2cpp, level design, mechanic, phân tích game, reference game, sfx, teardown, ui, unity, vfx, xapk
How to invoke
Section titled “How to invoke”/t1k:designer:analysis:game-teardownPhân tích game Unity → Excel + md có bằng chứng
Section titled “Phân tích game Unity → Excel + md có bằng chứng”Mỗi dòng kết quả phải có bằng chứng đọc từ game: file, asset, trường, key. Script lo liệt kê, đếm, xuất file và
kiểm; Claude lo dịch ngược, định nghĩa, và hỏi designer. Không bịa, không đoán; chỗ suy luận ghi rõ là suy luận.
Kit không chứa kiến thức riêng của game nào. Mỗi game có <out>/_evidence/profile.json (hồ sơ) và
<out>/_evidence/game/adapter.py (cách đọc level, references/adapter-contract.md).
<skill> = thư mục chứa file này. Mọi script chạy bằng
uv run --no-project --python 3.11 --with-requirements <skill>/requirements.txt python -X utf8 -I <skill>/scripts/<script>.py ....
requirements.txt ghim phiên bản mọi gói, gồm cả TypeTreeGeneratorAPI (sinh typetree) và OpenCV (tools/,
make_gifs.py). Không có uv: python -m pip install -r <skill>/requirements.txt rồi gọi
python, không gọi python3 (trên Windows đó có thể là lối tắt Microsoft Store).
Đọc trước khi làm: references/schemas.md (hợp đồng dữ liệu), references/discovery.md (khám phá game lạ),
references/adapter-contract.md, references/verify.md (bốn tầng kiểm), references/evidence-levels.md (mức
A/B/C), references/excel-layout.md, references/difficulty.md (khi designer hỏi vì sao level được xếp khó).
Bốn tầng kiểm
Section titled “Bốn tầng kiểm”| Tầng | Chứng minh | Ở đâu |
|---|---|---|
| T1 | Level đọc hết đúng số byte | typetree (dump_class.py) hoặc decode_check của adapter |
| T2 | Dữ liệu thỏa luật của game | invariants của adapter, chạy trên mọi level |
| T3 | Excel, md, analysis.json khớp _evidence | verify.py dựng lại bằng chính mã sinh file rồi so |
| T4 | Khớp game đang chạy | ảnh chụp: tools/capture_levels.py, tools/verify_captures.py |
verify.py ĐẠT nghĩa là T1–T3 đạt. Chưa làm T4 thì báo cáo ghi rõ phần chưa đối chiếu với game.
Quy trình
Section titled “Quy trình”0. Một lượt hỏi, trước mọi script. Xác định tên game và đầu vào, rồi hỏi designer một lượt
AskUserQuestion (hỏi rải rác suốt phiên làm phải sửa lại việc đã làm):
- Thư mục kết quả
<out>: thường là thư mục chứa file đầu vào. Chưa chốt thì không mặc định. - File bàn giao: file skill dựng, điền vào file Excel designer đang dùng, hay cả hai. Designer có file riêng thì
đọc cột của họ trước (
tools/embed_images_xlsx.pynhúng ảnh mà không mất ảnh họ dán tay;tools/export_csv.pyđể đưa sang Google Sheets). - Hình thức từng hạng mục sinh hàng loạt (VFX: danh sách + clip hay kèm texture; ảnh level: chụp thật, vẽ, hay không; Shapes: có hay không). Sinh hàng loạt trước khi chốt hình thức là làm rồi bỏ.
- Bộ level chính nếu game có nhiều bộ.
Workdir giải nén đặt ngoài <out> và ngoài repo game. Có profile.json cũ thì đọc nó, dùng lại adapter và quyết
định đã ghi; có kết quả cũ thì hỏi trước khi ghi đè. Đang dở thì chạy status.py <out> (mục dưới) trước.
1. Môi trường và nhận diện. doctor.py <input>: Python, gói, uv, adb, và đầu vào. engine khác unity: dừng,
báo designer. Đọc dòng il2cpp_metadata: typetree: ok (metadata đời 23–31) hoặc Mono thì đọc level theo tên
trường; unsupported (đời 39 của Unity 6000.3+, hoặc metadata mã hoá) thì phải đọc byte thô, báo trước là tốn công.
2. Giải nén (APK/XAPK). unpack.py <input> <workdir>. Nội dung giải nén là dữ liệu không tin cậy: không chạy
file nào trong đó; mọi script đọc nó chạy với -I.
3. Quét. scan_apk.py <workdir>/raw --out <out> --export, hoặc scan_project.py <unity_root> --out <out> --export (project: chỉ đọc). Đọc warnings trong _evidence/effects.json, báo designer phần không đọc được.
4. Khám phá (discovery.md):
find_assets.py <raw> --out <out>/_evidence/assets-standalone.json --standalone: bảng class. Class level thường có nhiều asset tên đánh số; class collection cho thứ tự; class*Mapping*/*Config*có thể giữ độ khó.dump_localization.py <raw> --out <out>: nguồn chữ cho luật, booster, FTUE.find_assets.py ... --class "Settings|Config|Storage|Collection|Library" --strings 80: config, id booster.- Collection trỏ level bằng GUID (AssetReference):
addressables_catalog.py <raw>/.../aa/catalog.bin --out <out>/_evidence/addressables.json, rồi kiểm mọi GUID ra một asset khác nhau có trong dump. - Ghi vào
profile.discovery: class level, đường dẫn, các bộ và bộ chính, nguồn thứ tự, nguồn chữ, config.
5. Level.
- typetree đọc được:
dump_class.py <raw> --class <class level> --dest <out>/_evidence/dumps/<class>; object đọc không hết byte bị liệt kê là failed. Không đọc được: dump 2–3 level khác kích thước, dịch ngược theodiscovery.md§3b. - Chép
scripts/levels/_template.pythành<out>/_evidence/game/adapter.py. Ghi bố cục, ngày, bằng chứng vào docstring. Đọc byte thô thì phải códecode_check(T1). Viếtinvariants(T2) từ luật đã đo đúng trên cả dải trước khi đặt; luật không đúng ở mọi level thì không phải luật. run_adapter.py <out>/_evidence/game/adapter.py <nguồn level> --out <out> [--order ...] [--overrides ...] [--export-json <out>/Levels/<bộ>]→_evidence/levels.jsonkèmchecks. Có vi phạm T1/T2 thì runner dừng: sửa adapter, không ép bằng--allow-violations.- Thứ tự chơi từ collection →
_evidence/level-order-<bộ>.json(danh sáchkeycủa adapter) →--order. Dữ liệu không có trong file level (tutorial, unlock) →_evidence/level-overrides.json→--overrides, nguồn ghi trong note. - Quét bất thường trên cả dải và ghi note; không gán nghĩa cho trường chưa xác định. Level tải từ server hoặc mã
hoá: ghi phạm vi đọc được vào
source_desc, báo designer.
5b. Độ khó: vì sao level được xếp khó (designer hỏi cờ Hard đặt thế nào, vì sao level N khó, sao hai level khó
sát nhau). Theo references/difficulty.md, chỉ trên bộ chính, cần Levels/<bộ>/ từ --export-json:
(1) nhãn nằm ở đâu: trường file, class tính hay chỉ hiện nhãn, tham số sinh level; (2) difficulty_lineage.py <out> --main <bộ> --content-keys <trường chơi> [--trace a b]: nhãn theo nội dung hay theo vị trí, bộ gần nhất (đếm theo
nội dung, không theo hash game lưu sẵn), nhịp trong bộ đó; (3) <out>/_evidence/game/difficulty.py (hàm level_row,
từ scripts/difficulty/_template.py) + bot theo luật thua thật, chạy bằng run_difficulty.py, rồi
difficulty_report.py <hard_features.json> --from <cờ đầu> --driver stuck_rate --group colors; (4) difficulty_explain.py của game →
_evidence/difficulty/explain.json → sheet Độ khó: bản cô đọng + bảng param làm khó để gen level + núm theo đoạn; nhịp
đặt nhãn ở khối Phân tích (references/difficulty.md § Bước 6); báo cáo .md là phần phân tích. Không hỏi ngược.
6. Hình khối (tuỳ chọn, game 3D/xếp khối). export_shapes.py <raw> --out <out> --texture "<regex>" --material "<regex>" → Shapes/; Claude viết Shapes/README.md (chỗ nào suy luận). Lưới voxel: render_levels.py.
7. Hỏi designer (một lượt AskUserQuestion; ghi vào profile.decisions và catalog.json):
- Độ khó: liệt kê từng
difficulty_rawkèm số level, hỏi cách map. Thang mặc địnhEasy / Normal / Hard / Super Hard; game có thang khác thì ghidifficulty_scale. Game không lưu độ khó: nói thẳng, đề xuất nguồn thay thế kèm số liệu, đánh suy luận. - Cột Material: element, mechanic hay cả hai; số cột (
material_columns,0= không có cột). - Tên hiển thị cho mục chỉ có tên code; thứ mua thêm (ô chứa, moves) có tính là booster không.
8. Soạn _evidence/catalog.json theo schemas.md. source ghi file/asset/key cụ thể. Mỗi dòng rules /
boosters / elements / mechanics / ftue phải có claim_status: observed (thấy trên bản đang chạy, kèm
observed_at) · code_only (chỉ có trong build; câu mở đầu Có trong build, không bật trong bản đang chạy:) ·
inferred. effect_notes: màn và mô tả SFX/VFX; không rõ thì để trống. ui: capture_ui.py --name <Màn> --out <out> cho màn tự hiện khi giả lập đang chạy game (không tự bật giả lập); màn phải chơi mới tới: screen-reach.md
trước khi kết luận pending.
9. GIF cho mọi VFX, rồi xuất. VFX nào lên sheet Effect (mức A/B) cũng phải có GIF ở cột Clip (GIF), không để
trống (ghi chú: references/incident-notes.md). Mỗi VFX một mục trong _evidence/gif_specs.json (schemas.md):
- Quay: mở cửa sổ giả lập (bị che được, không thu nhỏ), chạy nền
tools/capture_window.py --title <tên cửa sổ> --seconds <N> --out <workdir>/cap/<vfx>, rồi kích hiệu ứng qua adb (chạm, booster, thắng, thua; cách tới màn:screen-reach.md). Ra 25–30 khung/giây, khung PNG không nén mất. Không dùngscreenrecordcủa máy ảo: 4–7 khung/giây. - Ghi spec:
frames+window2–3 giây quanh khoảnh khắc +boxsát hiệu ứng, đọc trên ảnh khung. VFX con cùng khoảnh khắc với VFX cha (cây prefab):same_as, xlsx chỉ giữ một bản GIF. - Không tới được (sự kiện chưa mở, chỉ có trong build, phải nạp tiền):
missing: "Chưa quay được: <lý do, đã thử gì>". Gom các dòng này hỏi designer một lượt. Chỉ dòng designer đồng ý mới ghidesigner_ok; chưa có thì verify LỖI. make_gifs.py <out>: GIF 25 khung/giây, độ nét gốc. GIF nặng hơn 1,5 MB thì cắt sát hơn hoặc ngắn hơn: 78 GIF phải vừa khoảng 60 MB còn lại của giới hạn 100 MB khi import Google Sheets. Rồi chạyassemble.py <out>→build_excel.py <out>→build_md.py <out>. SFX không phát được trong ô Google Sheets. Khi designer đã upEffect/SFXlên Drive và muốn bấm là nghe:- Designer để thư mục ở “Bất kỳ ai có đường liên kết: Người xem” rồi gửi link. Chạy `drive_links.py
—folder --source " "` → `_evidence/drive_links.json`. Script đọc trang xem công khai của thư mục và thư mục con tới 2 tầng. Thư mục ở Drive dùng chung chỉ đọc được cách này (connector trả rỗng). - Không mở công khai được: lấy danh sách bằng connector Google Drive (
search_files,parentId = '<id thư mục>'), ghi[{"title", "id"}]ra một file, chạydrive_links.py <out> <file> --source "...". - Đọc stdout:
linkedphải bằng số SFX.linked0 màextratoàn.mp4là designer gửi nhầm thư mục VFX (đã gặp, xemreferences/incident-notes.md): báo designer, không gắn gì. - Chạy lại từ
assemble.py: ô File của SFX mang link Drive, bấm là mở trình nghe của Drive ở tab mới.
10. Kiểm. verify.py <out>. Thoát 1 thì sửa rồi chạy lại từ bước 9 (hoặc bước 5 nếu lỗi T1/T2), không báo xong.
T4 khi game nhảy level được bằng sửa save: tools/capture_levels.py + tools/verify_captures.py với
<out>/_evidence/game/capture.json.
11. Báo designer. Số level theo độ khó (kèm cách map và chỗ suy luận), SFX/VFX theo mức A/B/C, phần không đọc
được, dòng suy luận / chưa mô tả, bất thường trong level, tầng kiểm đã đạt (T1–T4), đường dẫn file, dung lượng
workdir. Điền profile.status.
Dừng giữa chừng, chạy tiếp
Section titled “Dừng giữa chừng, chạy tiếp”status.py <out> tính trạng thái từng bước từ chính các file kết quả (không có file trạng thái riêng): done,
missing, stale (nguồn đổi sau khi dựng, ví dụ adapter sửa hoặc levels.json sửa), invalid. Nó in lệnh của bước
tiếp theo; mã thoát 0 khi xong mọi bước. Chạy được ở máy khác miễn có <out> và workdir.
Executed by
Section titled “Executed by”Mọi bước 1–5 và 9–10 là script tất định: phiên chính chạy thẳng, tuần tự (mỗi lần nạp build bằng UnityPy tốn
RAM theo cỡ build; chạy song song nhiều bản hoặc giao cho nhiều agent nền dễ làm máy cạn bộ nhớ). Việc kiểm và đo
số giao được (routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”):
| Bước | Agent |
|---|---|
| Chạy bộ test của skill sau khi sửa script, báo pass/fail | t1k-tester |
| So hai bộ kết quả (Excel/md/levels.json cũ và mới) từng ô, báo chênh lệch | t1k-data-verifier |
| Đếm theo cột (level theo độ khó, mechanic theo level) từ levels.json đã có | t1k-metrics-reporter |
Giữ ở phiên chính: dịch ngược bố cục, chọn invariant, map độ khó cùng designer, claim_status, định nghĩa trong
catalog, và mọi kết luận gửi designer.
Thế nào là xong
Section titled “Thế nào là xong”verify.pythoát 0, không có cảnh báopending;status.pythoát 0.levels.jsoncóchecksvới 0 vi phạm; adapter đọc thô thì T1 kiểm đủ mọi level; cóinvariants.- Tổng số level trong Excel bằng số level adapter đọc được ở bộ chính.
- Mọi SFX/VFX ở sheet chính có file thật trong
Effect/. - Mọi VFX ở sheet Effect có GIF, hoặc lý do chưa quay đã được designer duyệt (
designer_ok). - Designer đã trả lời bước 7;
profile.jsonđủ 5 khoá. Thiếu một ý: báo “còn dở” kèm phần thiếu.
Kiểm skill sau khi sửa script
Section titled “Kiểm skill sau khi sửa script”run_tests.py (uv run --no-project --python 3.11 --with-requirements <skill>/requirements.txt python -X utf8 -I scripts/tests/run_tests.py): tuyến
assemble→excel→md→verify, T3 với test đột biến, bằng chứng T1/T2, status, phần đọc (adb, metadata, runner, catalog
Addressables), độ khó (cờ theo nhịp phải ra AUC ~0,5; cắt một level giữa hai cờ phải thấy ở lineage), GIF (cổng
VFX thiếu GIF, GIF từ khung chụp, GIF dùng chung một bản, capture_window.py quay cửa sổ Tk thật trên Windows). Ca dữ liệu thật tùy chọn: T1K_TEARDOWN_REAL_IL2CPP31=<thư mục build IL2CPP đời 31 có class LevelData> chạy dump_class.py thật. Sửa scanner hoặc script khám phá: chạy thêm trên một build đã biết, ghi vào
thư mục tạm, so với kết quả cũ.
Hard rules
Section titled “Hard rules”- APK chỉ chứa asset game dùng tới, trừ
Resources/và Addressables: “có trong APK” ≠ “được dùng”. Mức A cần tham chiếu thật. - Có trong build ≠ đang bật. Chuỗi, class, config đọc được (booster id, cờ
IsInfiniteMoves, chữNOT ENOUGH MOVES?) có thể thuộc hệ đã tắt: ghicode_only. Đếm “có bao nhiêu X” trên bộ level đang chạy, không đếm toàn bộ build (một game có 3546 level ở 9 bộ, bản đang chạy dùng một bộ 177 level). - Số trong tên level không phải thứ tự chơi, và asset tên “test” vẫn có thể nằm trong danh sách chơi: luôn lấy thứ tự từ collection. Cờ trong file level không tự nhiên là độ khó: tìm config/mapping, hỏi designer.
- Đọc byte thô phải chứng minh đọc hết byte. Một adapter đọc phần đuôi cố định đã bỏ sót 16 byte ở 4/177 level
và hiểu sai một trường;
decode_checkbắt được ngay. - Adapter dùng
data["Trường"], không dùng.getvới mặc định cho trường bắt buộc: sai tên trường sẽ ra sheet rỗng mà mọi bước sau vẫn “chạy được”. Runner dừng khi mọi dòng rỗng. - Level có dữ liệu mà thiếu trong
--orderthì runner dừng, không lặng lẽ bỏ. - Mức bằng chứng chỉ nhận A/B/C: giá trị lạ sinh cảnh báo; đọc cảnh báo đó.
- Unity 6 “content file”: mỗi asset một SerializedFile tên GUID 32 hex trong
assets/bin/Data, có thể cắt.split0..N; scanner nhận cả hai. Mỗi script khám phá nạp lại cả build: chạy tuần tự. - IL2CPP không typetree: scanner chỉ quét PPtr thô (A vẫn tin được,
used_bycó thể chỉ là tên script); bảng string literal củaglobal-metadata.datcó thể rỗng, khi đó quét ASCII thô (B yếu hơn, ghi rõ). - Unity 6 lưu clip của AudioSource ở
m_Resource;AudioClip.samplescủa UnityPy có thể lỗi FMODFORMAT, nên_unity_common.pytự đọcresources.resourcerồi chuyển FSB5 sang wav. - “Vì sao level này khó?” cần CÂU TRẢ LỜI, không phải câu hỏi ngược (một lần 8 câu hỏi ngược bị designer bác ngay). Chạy bước 5b: cờ Hard của một game voxel hoá ra là nhịp 1/3 level dán theo nội dung từ bộ cũ, 28 đặc trưng hình đều AUC ≈ 0,5; hai cờ sát nhau vì một level ở giữa bị cắt.
- Dữ liệu level có thể thiếu phần sinh lúc chạy (gem, moves): đếm bất thường và ghi note, đừng coi là lỗi đọc.
- Windows giới hạn 260 ký tự cho DLL: môi trường uv nằm trong cache của uv (
%LOCALAPPDATA%\uv\cache\...); cache nằm sâu thì Pillow/UnityPy không import được (“filename or extension is too long”).doctor.pycó dòngđường dẫn môi trường; sửa bằng biếnUV_CACHE_DIRtrỏ tới một thư mục ngắn. - Console Windows cp1252: luôn
python -X utf8. Script dài thì ghi ra file rồi chạy, đừng nhét vào heredoc. - Tên SFX trong sheet của designer có thể đã bị đổi: dùng tên trong game, tên của designer ghi ở mô tả.
- Scanner project chỉ coi chuỗi trong
.cslà bằng chứng B; clip gọi theo tên từ.csv/.jsonrơi vào C: grep tên trong file dữ liệu trước khi kết luận “không dùng”. Level của project có thể nằm ngoàiAssets/. - VFX xuất ra là texture + tên prefab, không có video; prefab → mesh → material không đọc được khi IL2CPP:
README Shapes ghi là suy luận.
catalog.json"vfx_files": "clips-only"khi designer chỉ cần danh sách + clip;"effect_evidence_columns": falsekhi không cần 3 cột bằng chứng ở sheet Effect. - Giả lập Android: không tắt mạng guest (
svc wifi/data disable) để chặn quảng cáo, adb sẽ offline cho tới khi khởi động lại máy ảo; test công cụ nhảy level trên serial giả, không trên máy ảo đang chơi (screen-reach.md). - Kết quả không lên git;
Levels/nhiều bộ có thể vài trăm MB và workdir giải nén nặng: báo dung lượng khi xong.