13 — Technical Design

1Nền tảng & package

1.1 Thông số khóa

1.2 Hiện trạng project → việc phải sửa

1.3 Package

2Render pipeline & Pixel Perfect

2.1 Quyết định: URP 2D Renderer

Project đang ở Built-in. Chọn URP + Renderer2D vì: (1) 00 §1 đã khóa; (2) Built-in bị đóng băng trong vòng đời Unity 6 — Light 2D, Sprite-Lit, Render Graph, SRP Batcher chỉ có ở URP; (3) Light 2D cho ánh lửa/đèn hồn trên nền tối (00 D1) mà không vẽ tay biến thể sáng; (4) PixelPerfectCamera URP có Upscale Render Texture: thế giới vẽ vào RT 270×H rồi phóng lên → fill-rate ~1/16 so với 1080×1920, đèn 2D và VFX cộng rẻ cả trên máy Low.

2.2 PixelViewport — tỉ lệ nguyên ưu tiên, thế giới rộng 270–384 px

Chạy lúc khởi động và khi đổi độ phân giải (Screen.width/height). Quy tắc thống nhất với 02 §2 và 11 §3:

k = min(⌊W/270⌋, ⌊H/480⌋)
if k >= 3 and W/k <= 384:                // chế độ NGUYÊN (đa số điện thoại, iPad)
    rtW = ⌊W/k⌋ ; rtH = ⌊H/k⌋ ; filter = Point
else:                                    // chế độ LẺ (màn < 810 px ngang, hoặc quá rộng)
    kf  = min(W/270, H/480)
    rtW = min(384, round(W/kf)) ; rtH = round(H/kf) ; filter = RetroAA (sharp-bilinear)
if W/(scale) > 384: pillarbox phần vượt 384 px thế giới (FrameCam vẽ khung Địa Tầng)
ppc.assetsPPU = 16 ; ppc.refResolution = (rtW, rtH)
ppc.gridSnapping = UpscaleRenderTexture ; ppc.cropFrame = None

Ví dụ: 1080×1920 → k 4 → 270×480 · 1080×2400 → 270×600 · 1440×3200 → k 5 → 288×640 · iPad 1536×2048 → k 4 → 384×512 · 720×1280 → lẻ 2.667 → 270×480.

• Chiều cao dư (rtH − 480) mở rộng vùng trần/khung dưới (01 §2), sàn luôn ở 66% vùng chiến đấu.
• Zoom 2× (Tuyệt Sát, Tuyệt Kỹ — 01 §2): đặt refResolution = (rtW/2, rtH/2) và tâm camera tại điểm va trong cùng tick khung va; trả về sau slow-mo. Không bao giờ zoom lẻ.
• Rung camera: offset tính bằng px nguyên (01 §14.2), cộng sau khi snap → không rung nửa pixel.
• Safe area chỉ áp cho HUD; thế giới vẽ tràn màn hình.

2.3 Camera & UI

Không stack overlay camera lên WorldCam (Upscale RT của PPC không hỗ trợ stack ổn định). Nếu prefab UIManager template đang dùng Screen Space – Camera, task setup đổi sang Overlay.

2.4 Sorting layer

Background (parallax xa) → Stage (tilemap sàn/tường/cầu thang) → Props → Decals (vết máu/tro, trần theo tier) → Actors → FX (cộng) → WorldUI → Overlay (letterbox, nháy toàn màn). Trong Actors: order = 1000 − laneOffsetY×10 + actorId%10; actor đang ở khung va hoặc khung chạm phòng thủ được +200 trong 6 tick để pha đọc được (P1).

2.5 Ánh sáng 2D & color space

• Blend style 0 Multiply (bóng tối Địa Tầng), 1 Additive (lửa, đèn hồn, phép). Không normal map, không shadow caster.
• Mỗi phòng: 1 Global Light (cường độ từ ArtStrata.csv), đèn hồn gắn anh hùng (luôn bật), 2–4 đuốc tĩnh, đèn VFX lấy từ pool, trần theo tier (tech_tiers). Light texture scale 0.5 (Low 0.25, đèn động tắt — chỉ Global + sprite glow cộng).
• Giữ Gamma: palette pixelfx và UI pixel kit đã chỉnh trong không gian sRGB; blend cộng ở Gamma khớp ảnh xem trước của pixelfx gallery (cái thấy khi duyệt act = cái thấy trong game).

2.6 Material & batching

• Thế giới dùng Sprite-Lit-Default; VFX Sprite-Unlit cộng; World UI unlit.
• Hiệu ứng trạng thái đổi sharedMaterial giữa vài material dùng chung (Mat_Lit, Mat_LitFlash trắng 1 khung, Mat_OutlineGold Dòng Chảy, Mat_OutlineWhite Vỡ Thế) + tint bằng vertex color — không MaterialPropertyBlock (giữ SRP Batcher/dynamic batching).
• Atlas: 1 atlas/anh hùng, 1/Địa Tầng (địch), 1 Thủ Vệ+Boss, VFX chung + VFX Địa Tầng (§16.3). Import theo PixelArtImportRules.cs (point, không nén, không mipmap, PPU 16 thế giới / 25 UI).

3Assembly & ranh giới

3.1 Sơ đồ phụ thuộc

                   ┌──────────────────────────── 2.BUS (Features/) ── meta, UI, kinh tế, adapter Ports, TigerForge
                   │            │ refs ▼                      ▲ không bao giờ ngược lại
4.CORE (Core/) ◄───┘   3.GAMEPLAY (Gameplay/) ── driver, Pixel, Feel, View, Ports (interface)
   ▲ hạ tầng template          │ refs ▼
   │                   3.GAMEPLAY.Sim (Gameplay/Sim/) ── noEngineReferences: true — mô phỏng thuần C#
   │                           ▲
5.PLUGINS, packages    3.GAMEPLAY.Editor (importer, validator, codegen) · 3.GAMEPLAY.Tests.EditMode/PlayMode

Tách Sim khỏi engine là cách ép tất định bằng compiler: Mathf, Random, Time, Debug không tồn tại trong Sim; headless autosim và EditMode test chạy Sim mà không cần scene.

3.2 Ports

Sim không gọi ra ngoài: nó ghi vào hàng đợi đầu ra (sự kiện trình diễn, cue âm thanh, telemetry) và dừng ở trạng thái chờ khi cần quyết định (AwaitingEchoPick, AwaitingLanding, AwaitingRevive). RunDriver (3.GAMEPLAY) đọc hàng đợi mỗi frame và gọi các port; 2.BUS hiện thực port.

Luật: (1) DTO qua port (RunSetup, RunResult, EchoOfferView) là struct/class bất biến của Sim, không chứa UnityEngine.Object; (2) IRunResultSink.Commit gọi đúng một lần, idempotent theo runId (app chết giữa commit → khôi phục snapshot phase = Ended và commit lại, sink bỏ qua runId đã nhận); (3) port không được ném exception vào driver — lỗi log BugLogger, run tiếp tục.

4Cây thư mục

4.1 Assets/_Project/Gameplay/

Gameplay/
├── 3.GAMEPLAY.asmdef
├── Sim/                     3.GAMEPLAY.Sim.asmdef (noEngineReferences)
│   ├── Core/      SimWorld, SimTick, Rng (Xorshift128Plus, SplitMix64, RngStreams), Hash64, RingBuffer, SimOutput, SimChecksum
│   ├── Data/      Generated/ (model + parser sinh từ header CSV), GameplayDb, SymbolTable, CombatTuning, DbValidator
│   ├── Run/       RunStateMachine, RunSetup, RunResult, RunSnapshot (+Writer/Reader/Migrations), RunRewardCalc, RevivePolicy
│   ├── Floor/     FloorDirector, WaveDirector, SpawnQueue, SpawnPoints, LandingRunner (LD00–LD08), VendorStock
│   ├── Actors/    ActorTable (struct-of-arrays), HeroState, EnemyState, ProjectileTable, SummonTable, StatSheet, ActorMotor
│   ├── Brains/    HeroBrain, TargetSelector, EnemyBrain + Behaviors/, BossBrain + PatternRunner, CombatDirector, AreaAvoid
│   ├── Combat/    DefenseResolver, ClashDetector, HitPipeline, HitboxQuery2D, DamageService, PostureService,
│   │              PoiseService, ReactionSelector, StatusService, EnemyDefense
│   ├── Combo/     MoveRunner, RouteRunner, ComboDirector, CondCompiler, ComboTree, SkillService, ExecutionService,
│   │              StyleService, OverdriveService, HeroGaugeService, ComboCounter
│   ├── Echoes/    EchoDatabase, EchoDslParser, CompiledEffect, Ops/ (§8.3), EffectExecutor, BuildState, RuleSet,
│   │              HeroRules/, TriggerTable, RunEventBus, HealCap, OfferGenerator, AutoPick
│   └── Telemetry/ RunStats (defense_stats, route_usage, execution), RunHash
├── Ports/         8 interface §3.2
├── Driver/        RunController (MonoBehaviour BattleScene), RunDriver, SimToViewBridge, RunAssetLoader
├── Pixel/         PixelClipPlayer, BodyClipLibrary, CombatClock, PixelViewport, ShakeService, TintService,
│                  AfterimagePool, DamageNumberPool, SpriteFont, VfxPlayer, LightRig, ActorView, ProjectileView
├── Feel/          FeelDirector, FeelSettings          View/  ArenaView, DescentView, TelegraphView, WorldUiView, DebugOverlay
├── Data/          Config/ (CSV §12), Clips/<HERO>/, Vfx/, Strata/<Sxx>/
├── Scenes/        BattleScene, CombatSandbox, PixelLab
├── Editor/        3.GAMEPLAY.Editor: BodyClipImporter, ActSyncValidator, GameplayCsvCodegen, EchoValidator,
│                  DeterminismGolden, DefenseCaseRunner, LinkXmlGenerator
└── Tests/         EditMode/, PlayMode/, Golden/

4.2 Feature mới trong Assets/_Project/Features/

Nhóm mới Meta/, Run/ (+ Run/_Session/: RunSetupService, RunResultService, RunSessionAdapter, FirebaseRunAnalytics) và feature mới trong Monetization/ — danh sách đúng bằng enum §13.3. Scaffold /new-feature, UI /new-ui + mockup. Dùng lại template: Shop, GloryPass (= Lantern Pass), PiggyBank, Vip30Day (= Thẻ Tháng), StarterPack, FirstPurchase, RemoveAds, DailyLogin, SevenDayLogin, Quest, LuckySpin, MailBox (Hộp thư G5/G9), FeatureUnlock, Tutorials, Settings, RewardPopup, Account.

5Mô phỏng tất định

5.1 Mô hình

SimWorld là đối tượng C# thuần chứa toàn bộ trạng thái trận (actor dạng struct-of-arrays, bảng đạn, RNG, build Hồi Âm, meter). Một tick = SimWorld.Step(). Không đối tượng Unity nào đọc/ghi trạng thái sim ngoài SimToViewBridge (chỉ đọc, sau tick). Nhiều SimWorld chạy song song được (autosim đa luồng) vì Sim không có static mutable.

5.2 CombatClock (Pixel/) — thời gian thực → tick

const float DT = 1f / 60f;
void Tick(float realDelta) {                       // gọi từ RunController.Update (UpdateManager)
    if (paused || awaitingInput) return;
    realDelta = min(realDelta, 0.10f);             // về từ background: không bù dồn
    float rate = speed * slowMo.Scale(realTime);   // speed 1/1.5/2/3; slow-mo đo theo GIÂY THỰC
    acc += realDelta * rate;
    int n = 0;
    while (acc >= DT && n < maxSteps) { world.Step(); acc -= DT; n++; }   // maxSteps = RC 8
    if (n == maxSteps) acc = 0;                    // máy quá yếu: sim chậm lại, không bao giờ nhảy cóc
    bridge.Present(acc / DT);                      // nội suy vị trí hiển thị rồi snap px nguyên
}

• Hit-stop là cục bộ trong sim (freezeTicks của từng actor, 01 §14.1) → tất định, độc lập tốc độ.
• Slow-mo toàn cục chỉ đổi nhịp bước (bao nhiêu tick mỗi giây thực), không đổi logic → không ảnh hưởng kết quả (INV-13/14). Ở x2/x3, rate = speed × scale (slow-mo tương đối với tốc độ hiện tại), thời lượng thực giữ nguyên.
• Headless: không có CombatClock; driver gọi Step() liên tục.

5.3 Đơn vị & lượng tử tick

Thời gian trong Sim là số nguyên tick. Mọi khoảng thời gian dữ liệu (giây) đổi sang tick lúc nạp (round half-up). Bảng dưới kiểm tra các hằng số chính rơi đúng lưới tick:

Tiến trình clip tấn công dùng fixed-point: progressMilli += aspdMilli mỗi tick (aspdMilli = round(AtkSpeed × 1000), tính lại khi chỉ số đổi); hit kích hoạt khi progressMilli ≥ hitTick × 1000. Không có float trong timing đòn → hit-frame không bao giờ trôi (INV-05). Đòn ngắn hơn 0.08 s sau AtkSpeed → hit dư âm (01 §6.6).

5.4 Thứ tự cập nhật trong một tick

tick++ → WaveDirector (spawn, actorId tăng dần) → CombatDirector (token mỗi 30 tick, giãn hit-frame lính ≥ 15 tick) → Brains (anh hùng trước, rồi địch theo actorId) → MoveRunner (bỏ qua actor freezeTicks > 0; phát AttackCommit/HitFrame/CancelWindow/ClipEnd) → DefenseResolver theo (hitTick, actorId, hitIndex) → ClashDetector → HitPipeline theo (actorId, hitIndex): hitbox → phòng thủ/sát thương → Thế/Poise/phản ứng → trạng thái → trigger Hồi Âm (độ sâu ≤ 2, thứ tự id thẻ) → đạn (theo projectileId) → chuyển động kinematic → trạng thái mỗi 30 tick, hồi HP/Khí Thủ/Thế → meter (Combo, Phong Độ, Bộc Phá AUTO, Cổng) → chết & dọn, hết wave → ghi SimOutput; debug SimChecksum mỗi 60 tick.

5.5 RNG — xorshift128+ theo luồng con

StreamSeed(runSeed, stream, floor, sub) = SplitMix64( runSeed ^ Fnv1a64(stream)
                                         ^ (ulong)floor * 0x9E3779B97F4A7C15 ^ (ulong)(uint)sub * 0xD1B54A32D192ED03 )
Xorshift128Plus(seed): s0 = SplitMix64(seed); s1 = SplitMix64(s0); (s0|s1 == 0 → hằng khác 0)
Next(): x = s0; y = s1; s0 = y; x ^= x << 23; s1 = x ^ y ^ (x >> 17) ^ (y >> 26); return s1 + y
NextUnit(): (Next() >> 11) * 2^-53 (double)   ·   NextInt(n): (int)(((Next() >> 32) * (ulong)n) >> 32)

Mỗi luồng có khóa con riêng nên lựa chọn ở tầng N không làm đổi spawn tầng N+1; luồng chiến đấu khóa theo (floor, wave) nên khôi phục đầu wave tái tạo đúng các roll. runSeed 64-bit = Hash64(installId, runIndex, TimeManager.UtcNowMs) tạo ở RunPrep, lưu snapshot; Thử Thách Ngày dùng daily_seed.

5.6 Luật float & tất định

1. Vị trí/vận tốc float px, dt hằng 1f/60f, biểu thức viết theo một thứ tự cố định. Chỉ + − × ÷, MathF.Sqrt (IEEE làm tròn chuẩn), Min/Max/Abs/Floor, Math.Round(x, MidpointRounding.AwayFromZero) tường minh.
2. Cấm lúc chạy trong Sim: Sin/Cos/Pow/Exp/Log (bảng tính sẵn lúc nạp; tăng trưởng tầng đọc từ FloorScaling.csv do Python tính), DateTime, Guid, System.Random, string.GetHashCode (dùng FNV-1a 64), duyệt Dictionary/HashSet (chỉ tra cứu; duyệt bằng mảng có thứ tự), LINQ, async, đa luồng bên trong một world.
3. HP/sát thương double (Vực Không Đáy vượt 1e15 — hiển thị 1.23aa).
4. Góc cung hitbox: so sánh tích vô hướng với cos² tính một lần lúc nạp; không atan2.
5. Phạm vi bảo đảm: bit-exact với cùng build + cùng kiến trúc CPU (INV-14: replay, khôi phục wave, hồi quy). Giữa ARM64 (máy) và x64 (Editor/autosim), trình biên dịch C++ của IL2CPP có thể gộp FMA → autosim là thống kê, không replay chéo máy; kiểm tra chéo bằng phân phối (§5.7). Không thêm cờ tối ưu float cho IL2CPP.

5.7 Hash & hồi quy 1,000 seed

• SimChecksum mỗi 60 tick: FNV-1a 64 trên (tick, với mỗi actor theo id: (int)(x·16), (int)(y·16), bit HP, Thế, state, clip, progressMilli; số lần rút của mỗi luồng RNG) → gộp thành RunHash.
• Golden: Tests/Golden/determinism.json = RunHash của seed 1…1,000 × {H01, H02} × B1–B10, meta profile cố định, Auto-Pick "Cân Bằng". Khóa theo ContentHash (hash mọi CSV Gameplay) + SimVersion. Đổi nội dung có chủ đích → chạy menu Deepstair/Golden/Rebuild, commit file golden cùng thay đổi (code-reviewer kiểm).
• Song sinh: cùng seed chạy 2 lần trong một process → cùng hash (bắt static). Song song: 8 world trên 8 luồng = kết quả tuần tự.
• Tương đương khôi phục: chạy tới đầu wave X, ghi snapshot, nạp vào world mới, chạy tiếp → RunHash từ điểm đó trùng run không gián đoạn.
• Chéo máy: 50 seed × B1–B5 trên 1 máy Android Mid (PlayMode trên thiết bị) so với Editor: báo tỉ lệ lệch hash (thông tin) + KS-test phân phối tầng chết p > 0.05 (bắt buộc).

6DefenseResolver

6.1 Trình tự (01 §5)

Địch E (MoveRunner)      CombatDirector      DefenseResolver                    Anh hùng H                 Trình diễn
 │ bắt đầu lấy đà t0 ───────────────────────────────────────────────────────────────────────────────────► glyph/nháy đỏ (01 §11.3)
 │                        (đã giãn ≥15 tick
 │                         với hit lính khác)
 │ AttackCommit{E,hit,kind,hitTick} @ hitTick−9 ─►│
 │ E → Committed (khóa hitTick: bỏ qua hit-stop,   │ ReadyState(H) theo bảng 01 §5.2
 │      Chill, slow cho tới hitTick)               │ H có hit trong [hitTick−3, hitTick+3]? → Clash pending, không roll
 │                                                 │ hệ số loại đòn × trạng thái → trần → r = defense.NextUnit()
 │                                                 │ kết quả O + clip phòng thủ c (contact = k tick)
 │                                                 │──── BeginDefending(c, start = hitTick − k) ──►│ Defending (khóa đòn mới,
 │                                                 │                                              │ clip miễn hit-stop)
 │ HitFrame @ hitTick ───────────────────────────► │ Apply(O) CÙNG tick: Gạt → Thế ×mult + Mất Thăng Bằng; Chặn → ST×(1−BlockRed), Khí Thủ;
 │                                                 │ Né → 0 + i-frame; Trúng → ST đầy đủ, Poise, Combo đứt ─────────► tia lửa/đóng băng/chữ/SFX @ hitTick (INV-05)
 │                                                 │ roll Phản Đòn (Gạt: luôn; Chặn/Né: rate, ICD) ─► QueueCounter(hitTick+1)
 │                                                 │ RunEventBus: on_deflect/on_perfect_deflect/on_block/on_evade/on_clash …

6.2 Căn khung chạm

• Clip phòng thủ (DEFLECT, BLOCK, EVADE_*) mang contact (tick). Chuẩn dữ liệu: contact = 9 cho Gạt/Chặn → bắt đầu đúng tick cam kết. k > 9: clip bắt đầu ở tick cam kết, nhảy cóc k − 9 tick đầu. k < 9: anh hùng giữ guard key 9 − k tick rồi mới chạy clip.
• Trong Defending, đồng hồ clip phòng thủ không bị hit-stop (hit-stop của đòn khác đè vào anh hùng bị hoãn tới sau hitTick). Debug assert defense_contact_error_ticks = 0; log tối đa ±1 tick ở bản phát hành.
• Đạn: cam kết khi thời gian tới va (khoảng cách / tốc độ, tính bằng tick) ≤ 9; từ đó đạn bị khóa tới hitTick (bám mục tiêu ≤ 2 px).
• Đòn area: không roll; AreaAvoid quyết định lúc bắt đầu báo hiệu (≥ 0.8 s → luôn rời vùng nếu tự do; 0.6–0.8 s → roll 70% trên luồng defense).

6.3 Hủy & va chạm

6.4 Cấu trúc dữ liệu (0 GC)

AttackCommit, DefensePlan { enemyId, hitIndex, hitTick, outcome, clipId, startTick, counterRolled } là struct trong mảng vòng cố định 32 phần tử; ReadyState tính từ HeroState (bit cờ Attacking/HitWindow/Airborne/Armor/Stunned/Grabbed/IFrame). Hệ số loại đòn đọc từ CombatConfig.csv (attack_*_mods), trần từ cap_*.

7Combo runtime

8Echo runtime

8.1 Nạp

HeroEchoes.csv + EchoesShared.csv → EchoDatabase.Load() (một lần khi vào BattleScene, ~420 thẻ, mục tiêu < 15 ms Mid): mỗi effect qua EchoDslParser (Lexer → AST → Compiler) thành CompiledEffect = mảng OpInstr { OpCode op; short argStart; byte argCount; } + mảng OpArg { ArgKind kind; float v1, v2, v3; int sym; } (giá trị theo cấp Lv1/2/3). Ký hiệu (RPGStatType, id lộ trình/đòn, sự kiện, rule, nguyên tố) được intern thành int qua SymbolTable. Ký hiệu không giải được → thẻ bị vô hiệu + BugLogger (bản dev: lỗi đỏ), EditMode test bắt trước khi build. Lexer chấp nhận − (U+2212) như -, hậu tố % và s.

8.2 Áp dụng

• Thẻ áp từ tầng kế (06 §5): ở Descent, BuildState.Rebuild() dựng lại toàn bộ từ danh sách (echoId, lv, pickOrder) theo thứ tự nhặt — không "gỡ" từng phần → không lệch khi lên cấp/thay thế. Chi phí ~0.2 ms, mảng cấp phát trước.
• Chỉ số: StatSheet giữ 4 lớp (BaseAdd, BasePercent, TotalAdd, TotalPercent) cho 52 RPGStatType, tính lại khi bẩn: Final = ((Base + ΣBaseAdd)·(1+ΣBasePercent) + ΣTotalAdd)·(1+ΣTotalPercent) → kẹp CAPS. Meta (lớp 1–2) đến trong RunSetup, Hồi Âm (lớp 3–4) từ BuildState.

8.3 Handler theo op (06 §8.2) — bảng tĩnh, không reflection

OpCode → handler là mảng tĩnh khởi tạo trong code (switch), hiệu ứng con (burst, wave, proj, status, heal, shield, buff, meter, cdr, ember, slowmo, clone, posture, exec_ready) chạy trong EffectExecutor.Execute(in OpInstr, ref EffectContext) bằng switch — không delegate cấp phát, không reflection mỗi hit.

8.4 Trigger & RunEventBus

• Sự kiện là struct CombatEvent { EventKind kind; int source, target; float value; int tag; } đẩy vào mảng frame; TriggerTable lập chỉ mục theo EventKind → danh sách (echoIndex, opIndex) đã sắp theo id thẻ (tất định).
• Độ sâu kích hoạt ≤ 2 (06 §8.6), cờ "đang xử lý" theo thẻ (K7), ICD lưu bằng tick, chance roll trên luồng combat.
• HealCap: cửa sổ trượt 60 tick, tổng hồi từ trigger ≤ 2% Max HP/s; ICD mặc định burst/wave 12 tick/mục tiêu, slowmo 240, clone 60, heal 18.

8.5 Quy tắc riêng anh hùng

rule(<CODE>_<NAME>) → class sealed hiện thực IHeroRule (hook: OnCommit, OnHit, OnDefense, OnGauge, ModifyScore…) đăng ký thủ công trong HeroRuleRegistry (một dòng/rule). Anh hùng mới = dữ liệu + rule class + một dòng đăng ký (03 §9).

8.6 IL2CPP

Sim không dùng reflection. link.xml (sinh bởi LinkXmlGenerator) chỉ giữ: kiểu save 2.BUS/4.CORE (Newtonsoft TypeNameHandling.All của DataPlayerBase), model CsvReaders của 2.BUS, Newtonsoft.Json converters. Build IL2CPP thử ở mỗi milestone + test smoke trên máy.

9Trình diễn pixel

9.1 Import act (M1 pixelfx → Unity)

• node tools/body-sheet.mjs <HERO> [--costume SK…] → <HERO>_body.png + .json: frames[{rect, pivot, startTick, tags[hit_i | contact | guardKey | airReady]}], clips{<MoveId>{frames[], durTicks, hits[tick], contact, root[(dx,dy)/khung], weaponTip[]}}.
• node tools/move-export.mjs <HERO> → moves_<HERO>.json (act.hits[].t, stop, shake, điểm neo VFX).
• Exporter lấy mẫu act theo lưới 12 fps và chèn khung khóa đúng tick của mỗi hit và contact → mỗi hit-frame bắt đầu đúng một ranh giới khung.
• BodyClipImporter → BodyClipLibrary (SO/anh hùng). ActSyncValidator (lỗi = dừng): tick hit act ≠ tick hit HeroHits.csv; dur lệch > 1 tick; khung đầu/cuối của đòn trong lộ trình mặt đất khác hash guard key (INV-16); clip Gạt/Chặn contact ≠ 9.

9.2 PixelClipPlayer

Mỗi frame: lấy (clipId, progressMilli) của actor từ bridge → con trỏ khung tăng dần (startTick·1000 ≤ progress) → chỉ gán SpriteRenderer.sprite khi đổi index. AtkSpeed tự đúng vì progress là thời gian clip. Vị trí: nội suy giữa 2 tick rồi làm tròn px nguyên + lệch làn 0–6 px (01 §2).

9.3 Feel & pool (cấp phát trước, trần theo tier)

Sim không biết hình ảnh: hit-stop hiển thị đúng vì progress clip của actor đứng yên trong sim.

10Sự kiện

• Trong trận: chỉ RunEventBus (struct, không boxing) + SimOutput. TigerForge không xuất hiện trong 3.GAMEPLAY.
• Ranh giới: RunSessionAdapter (2.BUS) dịch đầu ra của driver thành EventManager.EmitEvent(nameof(EventId.X), data). EventId thêm (giữ quy ước template: chỉ dùng qua nameof):

11Lưu dữ liệu

11.1 Module (PlayerDataManager.<Module>)

Mảnh anh hùng là tiền tệ (ví PlayerResource, MoneyTypes 700–711/720–722) để RewardManager/CSV thưởng (res_type = 1) cấp được trực tiếp; PlayerHeroes không lặp số mảnh.

11.2 File & mã hóa

• Template hiện lưu mỗi module vào PlayerPrefs (JSON, không mã hóa) → thay bằng SaveHub (4.CORE): module vẫn kế thừa DataPlayerBaseGeneric<T> (giữ API Load/Save/SetupDefaultData), nhưng Save() chỉ đánh dấu bẩn; SaveHub ghi một file persistentDataPath/save/profile.dsv chứa mọi module → giao dịch nhiều module (Triệu Hồi: KC + mảnh + pity) nguyên tử.
• Định dạng: header {magic "DSV1", schemaVersion, installId, seq, savedUtc (TimeManager), payloadLen} + payload = AES-256-CBC(gzip(JSON {module: json})) + HMAC-SHA256(header ‖ ciphertext). Khóa = PBKDF2(bí mật ứng dụng obfuscate qua com.blackface.security, installId). Mục tiêu: chống sửa tay & phát hiện hỏng, không phải chống hacker quyết tâm (game offline).

11.3 Ghi nguyên tử, backup, phục hồi

• Ghi: serialize JSON trên main thread → gzip + AES + HMAC + IO trên thread pool (UniTask.RunOnThreadPool) → profile.dsv.tmp + Flush(true) → File.Replace(tmp, profile.dsv, profile.bak1). profile.bak2 cập nhật tối đa mỗi 30 phút và khi mở app (hai mốc thời gian khác nhau → backup không cùng hỏng).
• Đọc: profile.dsv → bak1 → bak2 → SetupDefaultData(); mỗi bước kiểm HMAC + parse. Dùng backup → toast "Đã khôi phục dữ liệu từ bản sao lưu" + save_recovered + BugLogger kèm file hỏng.
• Nhịp: giao dịch có giá trị (IAP grant, Triệu Hồi, Rương, tiêu KC) → SaveHub.FlushNow() trước khi hiện kết quả; còn lại debounce save_debounce_s (ProgressThread timer); OnApplicationPause(true)/quit → flush đồng bộ. Không bao giờ trong Update (rule data-persistence).

11.4 Migration

schemaVersion toàn cục + v mỗi module; ISaveMigration { int From; void Apply(JObject root); } chạy tuần tự, ghi profile.v<n>.bak một lần trước khi áp. v0 → v1 (máy dev đã chạy template): nhập các key PlayerPrefs cũ vào file mới, bỏ số dư Energy (3), đặt PlayerBattle.depthRecord = 0, xóa key PlayerPrefs cũ sau khi ghi thành công. Mỗi migration có EditMode test với JSON mẫu. Quyết định này đóng nhóm "save-migration" mà /planning-system bắt buộc hỏi.

11.5 Run snapshot

• File riêng run.dsr (cùng phong bì mã hóa), nhị phân có version (RunSnapshotWriter vào byte[] pool, 4–8 KB) — ghi được giữa trận mà không giật.
• Schema nghiệp vụ theo 05 §16; phần kỹ thuật bắt buộc: snapVersion, simVersion, contentHash, runId, runSeed, RunSetup đầy đủ (kể cả RunTuning chụp từ RC), floor, wave, phase, HeroState (vị trí, HP, Khí Thủ, Bộc Phá, Cổng, Phong Độ, Combo, hồi chiêu, ICD, chuỗi Gạt, trạng thái), Hồi Âm (id, lv, pickOrder), Loại bỏ, pity, Đổi thẻ đã dùng/còn, pendingOffer + rerollIndex, lộ trình chờ ra mắt + lịch sử 3 lộ trình, hồi sinh đã dùng (miễn phí/trả phí), trạng thái Chiếu Nghỉ/Thương Nhân, bộ tích lũy Kết Quả, RunStats telemetry, cờ detail lấy mẫu.
• Điểm ghi: (1) pendingOffer vừa sinh — trước khi hiện (INV-11); (2) sau khi chọn → Descent; (3) checkpoint wave: tick đầu tiên của wave khi không còn địch sống (wave chồng → lùi về đầu tầng); (4) Downed; (5) mua ở Chiếu Nghỉ; (6) phase = Ended trước IRunResultSink.Commit.
• Khôi phục sau cập nhật app: snapVersion còn hỗ trợ → nạp; contentHash khác → vẫn nạp (không bảo đảm replay), thẻ bị xóa xử lý theo 06 K5.

12CSV config

Luồng: GDD/Tools/data/*.py → GDD/Config/*.csv (nguồn thiết kế) → py -I GDD/Tools/sync_unity_config.py (task setup viết) chép theo bảng dưới, đổi phần thưởng dạng chữ thành dòng Resource 6 cột (res_type, res_id, res_number, bonus, stage_bonus, custom_value — skill csv-config) cho feature template → importer:

• 2.BUS: pipeline CsvReaders sẵn có (CSV → SO collection → DataManagerAutoGenerate).
• 3.GAMEPLAY.Sim: GameplayCsvCodegen sinh model + parser C# từ header (không reflection, AOT-safe) vào Sim/Data/Generated/; CSV nhúng dạng TextAsset trong group Addressables core_boot, Sim parse lúc vào BattleScene. Header CSV đổi → codegen + test schema báo lỗi.

Bảng ánh xạ (tự quét mọi module data lúc build; dòng (REVIEW) = CSV chưa có luật, phải thêm luật trong tech.py trước khi hiện thực):

13Enum: MoneyTypes, ResourceTypes, Features — kiểm tra trùng

Đã đối chiếu Assets/_Project/Core/GameSystem/EnumBase.cs + quét toàn bộ 30 CSV template (res_type = 1 chỉ dùng id 1, 2, 3, 17). validate() của tech.py khóa các kiểm tra dưới đây.

13.1 MoneyTypes

Phát hiện & cách xử lý:

1. 5/12/13/14/16 nằm trong dải 4–16 mà comment enum ghi "Đã gỡ (không tái dùng số)", trong khi cùng comment lại gọi 4–16 là "dải trống cho game". Không code/CSV/save nào dùng các số này → Deepstair nhận lại có chủ đích (00 §14 đã khóa); sửa comment enum thành "4–16: Deepstair dùng 5, 12, 13, 14, 16"; migration v0→v1 xóa mọi key ví 4–16 lạ trong save máy dev.
2. 17 đã là LuckySpinCoin = "Xu Vòng Quay" của 00 → dùng lại, không thêm member.
3. Energy = 3 đang được 13 CSV template thưởng (DailyAds, DefaultResource 60, LuckySpin, Quest, SevenDayLogin, GemRefillPack, FirstPurchase, Vip30Day, AccountReward, GloryPass, ResourceExchange, DailyShop, MiniShopConversion) + GeneralConfig.csv cột năng lượng. Deepstair không có năng lượng: giữ member (code template tham chiếu), thay toàn bộ các CSV đó bằng bản sinh từ 08–10, ẩn Energy khỏi HomeResourceView; sync_unity_config.py từ chối dòng res_id 3.
4. 207 sát dải gỡ 200–206 nhưng trống; 700–722 không chạm dải gỡ 600–609 → hợp lệ.
5. Bundle id lệch: ProjectSettings + mọi pack_id IAP template dùng com.defaultcompany.deepstair.* → đổi thành com.blackface.deepstair.* (SKU theo IapCatalog.csv của 09).
6. Than Hồng (Embers) không là MoneyTypes — chỉ sống trong snapshot run (INV-03).

13.2 ResourceTypes (thưởng không phải tiền)

Số 3 (Hero) đã gỡ → dùng 11. Thưởng "tặng Aldric" (00 §7.1 bước 11) = res_type 11, res_id 2.

13.3 Features (tên member = tên prefab, nạp bằng Resources.Load(name))

Không trùng số đang dùng/đã gỡ (3, 18, 20, 22, 31, 47, 56, 57, 75, 78, 91, 98, 100, 114, 123, 124, 127, 177). Codex và StarterPack là tên cũ với số mới (207, 253) — hợp lệ vì enum serialize theo số. Lantern Pass dùng lại GloryPass/GloryPassPremium (129/130), chỉ đổi chuỗi hiển thị. UiScreens.csv (12) phải đối chiếu đúng danh sách này.

14Analytics (Firebase qua TrackingManager)

FirebaseRunAnalytics hiện thực IRunAnalytics; tên event/param sinh thành hằng AnalyticsEvents.g.cs từ TechAnalyticsEvents.csv (validator: ≤ 40 ký tự, ≤ 25 param, không tên dành riêng của Firebase — ví dụ ad_reward bị cấm nên giữ ads_reward của template). Dictionary tham số chỉ tạo ở ranh giới (cuối tầng/run), không mỗi hit. Lấy mẫu chi tiết: detail = Hash64(runId) mod 10⁴ < analytics_detail_sample × 10⁴, quyết định ở run_start, lưu snapshot.

User properties:

Đồng thuận: Google UMP (EU/UK) → Firebase consent mode v2 → ATT (iOS) → khởi tạo quảng cáo cá nhân hóa. run_id = 16 hex ngẫu nhiên, không chứa định danh thiết bị.

15Remote Config

Khóa gameplay/LiveOps do 10 §Remote Config sở hữu; dưới là khóa kỹ thuật. Fetch lúc boot (timeout 3 s → giá trị cache → remote_config_defaults.xml sinh từ TechRemoteConfig.csv). Khóa cột "Chụp" được đọc một lần vào RunTuning khi bắt đầu run và lưu snapshot — RC đổi giữa run không bao giờ tác động trận đang chạy (tất định). Mọi khóa của 10 ảnh hưởng sim phải khai báo cùng cờ này.

combat_overrides_json: chỉ nhận key có trong CombatConfig.csv, kẹp ±50% giá trị gốc, log hash vào run_start.seed_hash để phân tích.

16Hiệu năng

16.1 CPU (đo bằng ProfilerMarker, máy tham chiếu §16.2)

GPU (Mid): ≤ 8 ms/frame. Thế giới vẽ ở 270×H nên overdraw VFX cộng + đèn ≤ 3× diện tích RT là rẻ; chi phí GPU chính là uGUI ở độ phân giải gốc → overdraw UI ≤ 2.5×, tách canvas tĩnh/động, không Layout lồng trong HUD. Draw call (Mid): thế giới ≤ 40, UI ≤ 30, tổng ≤ 80, SetPass ≤ 25.

16.2 Tier thiết bị

Tự phát hiện lần đầu (RAM, SoC whitelist, model iPhone) → đo FPS trung bình trong perf_downgrade_window_s giây Combat; dưới perf_downgrade_fps hai lần liên tiếp → hạ 1 tier (lưu, không tự nâng). Người chơi đổi được trong Cài đặt. Đổi tier có hiệu lực từ run sau (giới hạn địch là tham số sim).

Adaptive Performance (module có sẵn): cảnh báo nhiệt → hiển thị 30 FPS + tắt dư ảnh; sim không đổi.

16.3 Bộ nhớ

Sprite thế giới để RGBA32 không nén (luật import pixel, ASTC làm vỡ pixel ở 1×) → atlas là chi phí chính. Một atlas/anh hùng; Trang Phục là body sheet riêng thay atlas gốc khi mặc.

Trần ô khung: anh hùng/địch ≤ 96×80 px, Thủ Vệ ≤ 128×96, Boss ≤ 160×128 (ô vượt → act bị validator chặn). Anh hùng cần > 2048×1024 → tách 2 atlas 2048×1024: bộ gốc (luôn nạp) + đòn Hồi Âm (nạp bất đồng bộ trong Descent khi nhặt thẻ đầu tiên cần nó) — đa số run chỉ giữ 8–12 MB/anh hùng; bảng trên là trường hợp xấu nhất.

16.4 0 GC trong Combat

Cấm trong đường nóng (Sim + Pixel + Feel + HUD cập nhật): new class, closure/lambda bắt biến, LINQ, string format/concat (HUD số dùng TMP_Text.SetCharArray hoặc glyph), boxing (enum làm key Dictionary → mảng theo index), foreach trên interface, GetComponent (cache ở Awake), Instantiate (pool đủ trần tier lúc vào tầng). Kiểm bằng PlayMode test Recorder("GC.Alloc") 600 frame CombatSandbox = 0 B và performance-reviewer trên mọi diff chạm đường nóng.

16.5 Thời gian nạp

Vào BattleScene ≤ 2.5 s (Mid): nạp group anh hùng + Địa Tầng song song (Addressables), EchoDatabase + GameplayDb ≤ 60 ms, pool dựng trước. Chuyển tầng không nạp gì (cùng Địa Tầng); sang Địa Tầng mới: tải trước group kế tiếp từ tầng x8.

16.6 Addressables & phân phối

Android: addressables.android ánh xạ group → asset pack PAD (install-time/fast-follow). Chưa tải xong group cần dùng → chặn ở cầu thang với tiến độ (R14). iOS: mọi group nằm trong IPA (không ODR). Không remote catalog ở v1.0 (offline-first); dành cho v1.1+.

17Headless autosim

Unity -batchmode -nographics -projectPath . -executeMethod Deepstair.Run.Editor.AutoSimCli.Run
      -hero H01 -seeds 1-1000 -profile f2p:d7 -policy autopick:BALANCED -dread 0 -startFloor 1 -maxFloor 100
      -speed max -threads 8 -perFloor -out Builds/autosim/H01_f2p_d7 -quit

Đầu ra: runs.csv (seed, hero, profile, policy, floor_max, cause, enemy gây gục, time_game_s, kills, attacks, deflects, perfect, blocks, evades, hits, clashes, counters, executions, kết quả từng Boss/Thủ Vệ + thời gian, echoes, build_cluster, unique_routes, top_route_share, gold, soul_ash, exp, mastery_xp), floors.csv, routes.csv (số lần chạy, DPS factor thực — kiểm 03 §10 ±10%). Hiệu năng: ≥ 150× thời gian thực mỗi luồng trên PC dev (1,000 run B1–B100 ≈ 25 phút với 8 luồng). Hiệu chỉnh: balance_sim.py --calibrate Builds/autosim/*.csv (08) khớp hệ số sức mạnh anh hùng; cổng M2: sai số tầng chết trung vị ≤ 3 tầng. Autosim không cần scene, art, audio.

18Kiểm thử

18.1 Tự động

CI (máy Mac runner sẵn có + Windows dev): mỗi push lên nhánh làm việc chạy EditMode + autosim smoke; hằng đêm Determinism1000 + autosim 1,000 seed → so với lần trước.

Vector kiểm phòng thủ (trích TechDefenseCases.csv, đầy đủ trong CSV):

18.2 Thủ công & thiết bị

Ma trận: Android Low (Helio G85, 3–4 GB), Android Mid (Helio G99), Android High (Pixel 7), iPhone 11, iPad 9 (3:4, pillarbox). QA agent /auto-test-device theo charter từng feature; bug tự lên BugHub.

19Cheat (skill feature-cheat, chỉ khi GameSystems.isCheat)

Cộng mọi MoneyTypes · đặt kỷ lục/first-kill · mở mọi anh hùng, Thông Thạo 20, mọi nhóm Hồi Âm · thêm/nâng Hồi Âm theo id trong run · ép kết quả phòng thủ N đòn kế (Gạt/Hoàn Hảo/Chặn/Né/Trúng/Va Kiếm) · bất tử · hạ toàn bộ địch · nhảy tầng · spawn địch/Thủ Vệ/Boss theo id · overlay hitbox + timeline phòng thủ (commit/contact/hit) · sim x10 · chạy N autosim trên máy · dump snapshot · reset FTUE · đặt tier · làm hỏng save (test phục hồi) · dịch giờ TimeManager. Bản release: chỉ máy được duyệt qua BugHub (TesterAccess).

20Build & phát hành

• Android: AAB + PAD, IL2CPP ARM64, minSdk 26/target 36, hỗ trợ trang 16 KB (Unity 6), ký qua AndroidSigningFromEnv; iOS: Xcode từ Mac runner.
• Phiên bản: VersionIncrementor (Core/Build) — bundleVersion 1.0.N, versionCode tăng mỗi build; SimVersion (hằng trong Sim) tăng khi đổi logic sim (khóa golden + snapshot).
• Pipeline: skill /build (Android/Release → Android/AutoBuild → runner build + deploy). Symbol IL2CPP lên Crashlytics; BugLogger gắn commit sha.
• Track: internal → closed (tester) → soft launch (VN, PH, CA) → production staged 10% → 50% → 100%. Cập nhật nội dung = cập nhật app ở v1.0.
• Store: phân loại tuổi khai "In-game purchases (includes random items)"; trang công khai tỉ lệ Triệu Hồi/Rương; chính sách quyền riêng tư.

21Rủi ro kỹ thuật

Rủi ro dự án tổng hợp ở 14 §8 (R4, R9, R11, R14); riêng kỹ thuật:

22HANDOFF — giả định module khác phải tôn trọng

• 02 Pixel pipeline: export đúng §9.1 (khung khóa vào tick hit/contact, startTick từng khung, root motion theo khung, cờ guard key); contact = 9 tick cho Gạt/Chặn; trần ô khung §16.3; VFX recolor lúc export; PPU 16.
• 03/Heroes: mọi hit t là bội 1/60 s sau khi đổi tick (validator báo lệch > 1 ms); mỗi rule <CODE>_* đặc tả đủ để viết IHeroRule; ≤ 64 lộ trình/anh hùng.
• 04 Địch/Boss: mọi đòn khai AttackKind + lấy đà tối thiểu; đạn tốc độ hằng (cam kết tất định); pattern Boss là dữ liệu, chỉ rule có tên mới cần code; khai bán kính + chiều cao thân.
• 05 Run: snapshot chứa đủ trường §11.5; checkpoint wave = tick không còn địch sống; mọi ngẫu nhiên qua luồng §5.5 (thêm luồng → thêm vào constants.RNG_STREAMS + tech.py).
• 06 Hồi Âm: effect theo ngữ pháp 06 §8.1, chỉ dùng op/sự kiện/rule đã liệt kê; số có đơn vị %/s; ICD ≥ 1 tick.
• 07–10 Meta/Kinh tế/Kiếm tiền/LiveOps: dùng đúng id §13; mảnh trong ví; kết quả gacha ghi save trước animation; khóa RC ảnh hưởng sim khai cờ "Chụp"; event analytics thêm vào tech.py (validator Firebase); không điểm IAP trong run (INV-08).
• 11 UI: canvas Overlay 1080×1920; World UI vẽ trong RT pixel; quyết định trong run đi qua IRunPrompt; nút tương tác trong run ở 45% dưới (INV-07).
• 12 Art/Audio: SFX/nhạc theo id int (AudioSfx.csv/AudioMusic.csv), VFX theo ArtVfxMap.csv, đèn theo ArtStrata.csv và trần tier.