Skip to content

t1k:designer:analysis:game-teardown

FieldValue
Moduleanalysis
Version1.1.3
Efforthigh
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

/t1k:designer:analysis:game-teardown

Phâ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ó).

TầngChứng minhỞ đâu
T1Level đọc hết đúng số bytetypetree (dump_class.py) hoặc decode_check của adapter
T2Dữ liệu thỏa luật của gameinvariants của adapter, chạy trên mọi level
T3Excel, md, analysis.json khớp _evidenceverify.py dựng lại bằng chính mã sinh file rồi so
T4Khớ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.

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.py nhú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 theo discovery.md §3b.
  • Chép scripts/levels/_template.py thà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ết invariants (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.json kèm checks. 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ách key củ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_raw kèm số level, hỏi cách map. Thang mặc định Easy / Normal / Hard / Super Hard; game có thang khác thì ghi difficulty_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ùng screenrecord của máy ảo: 4–7 khung/giây.
  • Ghi spec: frames + window 2–3 giây quanh khoảnh khắc + box sá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 ghi designer_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ạy assemble.py <out> → build_excel.py <out> → build_md.py <out>. SFX không phát được trong ô Google Sheets. Khi designer đã up Effect/SFX lê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ạy drive_links.py <out> <file> --source "...".
  • Đọc stdout: linked phải bằng số SFX. linked 0 mà extra toàn .mp4 là designer gửi nhầm thư mục VFX (đã gặp, xem references/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.

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.

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ướcAgent
Chạy bộ test của skill sau khi sửa script, báo pass/failt1k-tester
So hai bộ kết quả (Excel/md/levels.json cũ và mới) từng ô, báo chênh lệcht1k-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.

  • verify.py thoát 0, không có cảnh báo pending; status.py thoát 0.
  • levels.json có checks vớ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.

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ũ.

  • 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: ghi code_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_check bắt được ngay.
  • Adapter dùng data["Trường"], không dùng .get vớ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 --order thì 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_by có thể chỉ là tên script); bảng string literal của global-metadata.dat có 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.samples của UnityPy có thể lỗi FMOD FORMAT, nên _unity_common.py tự đọc resources.resource rồ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.py có dòng đường dẫn môi trường; sửa bằng biến UV_CACHE_DIR trỏ 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 .cs là bằng chứng B; clip gọi theo tên từ .csv/.json rơ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ài Assets/.
  • 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": false khi 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.