---
doc_id: "DOC-ADR-001"
title: "ADR 0001: Đoạn Tuyệt Với Lua — Ứng Dụng WebAssembly Trong Game Scripting"
category: "adr"
diataxis_type: "explanation"
status: "canonical"
version: "2026.1"
owner_role: "server_systems_architect"
last_updated: "2026-09-29"
tags: ["adr", "wasm", "lua", "game-scripting", "sandboxing"]
related_code:
  - "server/engine/scripting_engine.py"
related_docs:
  - "docs/architecture/GAME_ENGINE_ARCHITECTURE.md"
summary: "Quyết định thay thế Lua VM bằng WebAssembly (Wasm) để đạt hiệu năng native AOT, bộ nhớ sandbox cô lập tuyệt đối."
---

# BẠCH THƯ KỸ THUẬT: ĐOẠN TUYỆT VỚI LUA SCRIPT — CÔNG NGHỆ GAME SCRIPTING NĂM 2026

> **Dự án**: `FreeExile` — Dark Martial Astral ARPG (Cổ Võ Hắc Ám 2.5D)  
> **Chủ đề**: Phân tích sự lạc hậu của Lua (thời kỳ VLTK 1) và định hình kiến trúc Scripting thế hệ mới: **WebAssembly (Wasm) Sandbox & Data-Driven Protobuf Engine**.

---

## 1. TẠI SAO LUA SCRIPT ĐÃ TRỞ NÊN LẠC HẬU VÀ BỊ ĐÀO THẢI Ở DỰ ÁN LỚN NĂM 2026?

Lua (ra đời từ năm 1993) từng là "ông vua kịch bản" của kỷ nguyên game thập niên 2000 (*Võ Lâm Truyền Kỳ 1 - 2005*, *World of Warcraft - 2004*) nhờ sự gọn nhẹ và dễ nhúng vào C++. Tuy nhiên, trong kỷ nguyên 2026 với yêu cầu **1.000.000 CCU**, **bảo mật khắt khe trên di động** và **kiểm thử tự động**, Lua bộc lộ những điểm nghẽn chí tử:

### 1.1. Untyped Dynamic Typing: Thảm Họa Runtime Nil Crash
- Trong Lua, chỉ cần một lỗi chính tả nhỏ của Game Designer: `player.mana` gõ nhầm thành `player.manaa` sẽ trả về `nil`.
- Không có trình biên dịch bắt lỗi kiểu (Static Type Checking). Các lỗi này âm thầm lọt qua khâu test và phát nổ khi game đang phục vụ hàng trăm ngàn người chơi, làm sập cả Zone Server.

### 1.2. Garbage Collection (GC) Jitter & Memory Leaks
- Lua sử dụng cơ chế gom rác tự động (Incremental / Generational GC).
- Khi hàng vạn bùa chú, chiêu thức, nhiệm vụ sinh ra các bảng tạm (`tables`), GC của Lua phải quét qua đồ thị bộ nhớ. Điều này gây ra các **xung giật khung hình (frame latency spikes)** ngẫu nhiên từ $5ms - 15ms$, phá vỡ ngân sách nghiêm ngặt $33.33ms$ của vòng lặp mô phỏng $30\text{Hz}$.

### 1.3. Apple iOS Triệt Tiêu Sức Mạnh Của LuaJIT (Chính Sách W^X)
- Lua chỉ nhanh khi có **LuaJIT** (Just-In-Time Compiler).
- Tuy nhiên, trên hệ sinh thái Apple iOS (nền tảng Flagship của FreeExile), chính sách bảo mật **W^X (Write XOR Execute)** nghiêm cấm mọi ứng dụng cấp quyền ghi và thực thi bộ nhớ động. Do đó, LuaJIT trên iOS bị **ép buộc chạy ở chế độ thông dịch thuần (`-joff`)**, tốc độ tụt giảm từ $10$ đến $40$ lần, trở nên cực kỳ chậm chạp và hao pin.

### 1.4. Đơn Luồng Cố Hữu (Single-Threaded State)
- Mỗi trạng thái Lua (`lua_State`) là đơn luồng. Muốn chạy đa luồng trên CPU 64-core, server phải tạo hàng trăm `lua_State` riêng biệt và tuần tự hóa dữ liệu qua lại rất tốn kém tài nguyên.

---

## 2. TOÀN CẢNH CÁC CÔNG NGHỆ GAME SCRIPTING NĂM 2026

Năm 2026, ngành công nghiệp game AAA đã chuyển dịch sang 3 giải pháp tiên tiến vượt trội:

```mermaid
flowchart TD
    subgraph Traditional["Kỷ Nguyên Cũ (2005 - VLTK1)"]
        Lua["Lua 5.1 / LuaJIT\n(Dynamic, Untyped, GC Spikes, iOS JIT Blocked)"]
    end

    subgraph Modern2026["Kỷ Nguyên 2026 (FreeExile Standard)"]
        WASM["1. WebAssembly (WASM Sandbox)\n(Wasmtime / WAMR, Zero-Crash, Polyglot: Rust/TS)"]
        Luau["2. Luau (Roblox Open Source)\n(Gradual Typing, Fast Bytecode, Linting)"]
        CEL["3. Google CEL / Data-Driven\n(Deterministic Expression Engine, Non-Turing, Microsecond)"]
    end

    Lua -.->|"Đào Thải Do Lag & Nil Bug"| WASM
    Lua -.->|"Thay Thế"| CEL
```

| Tiêu Chí Kỹ Thuật | Lua 5.1 (Kỷ Nguyên VLTK 1) | Luau (Roblox 2026) | WebAssembly (WASM Sandbox 2026) |
| :--- | :--- | :--- | :--- |
| **Kiểm Tra Kiểu Dữ Liệu**| Không (Dynamically Typed) | Có (Strict Gradual Typing) | **Tuyệt Đối 100% (Rust / TypeScript AST)** |
| **Tốc Độ Thực Thi** | Chậm (Khi JIT bị iOS chặn) | Nhanh hơn Lua 2-3x | **Cực Hạn (Gần tương đương C++ Native)** |
| **Cô Lập Bộ Nhớ & An Toàn** | Lỗi script có thể làm sập Server | Tốt hơn | **Sandbox Tuyệt Đối (Memory Trap không thể crash Server)** |
| **Garbage Collector** | Quét rác toàn cục gây giật nhịp tick | GC tối ưu hóa hơn | **Linear Memory / Zero-GC do module tự quản lý** |
| **Ngôn Ngữ Viết Kịch Bản**| Chỉ dùng cú pháp Lua cũ kỹ | Cú pháp Lua mở rộng | **Đa Ngôn Ngữ: Rust, Zig, TypeScript (AssemblyScript)** |
| **Tương Thích Apple iOS** | Bị khóa JIT, chạy thông dịch chậm | Chạy thông dịch | **Hỗ trợ AOT (Ahead-Of-Time) biên dịch thẳng mã máy** |

---

## 3. GIẢI PHÁP ĐỘT PHÁ CỦA FREEEXILE 2026: WEBASSEMBLY (WASM) SANDBOX ENGINE

FreeExile chính thức **loại bỏ hoàn toàn Lua**, áp dụng mô hình **WebAssembly (WASM) Sandboxed Guest Engine** kết hợp **Data-Driven Protobuf**:

```mermaid
flowchart LR
    subgraph ScriptAuthoring["Tác Quyền Kịch Bản (Developer / Designer)"]
        TS["TypeScript (AssemblyScript)\nhoặc Rust"] --> Compiler["asc / rustc --target wasm32"]
        Compiler --> WasmBinary["Quest_Boss_01.wasm\n(File nhị phân tối ưu)"]
    end

    subgraph NativeCppServer["Server C++20 Zone Server Engine"]
        WasmRuntime["Wasm Micro-Runtime (WAMR / Wasmtime)"]
        WasmBinary --> WasmRuntime
        
        WasmRuntime --> IsolatedSandbox["Linear Memory Sandbox\n(Giới hạn RAM cứng 4MB/script)"]
        IsolatedSandbox --> CppFFI["Zero-Copy C++ Engine Bridge"]
        CppFFI --> ZoneServer["30Hz Simulation Hot Path"]
    end
```

### 3.1. Các Ưu Điểm Độc Tôn Của WebAssembly Trong FreeExile:

1. **Kiến Trúc Bất Tử (Zero-Crash Architecture)**:
   - Mỗi file kịch bản (Nhiệm vụ, Boss AI, Sự kiện thế giới) chạy trong một vùng nhớ tuyến tính riêng biệt (**Linear Memory Sandbox**).
   - Nếu Game Designer viết sai logic dẫn đến chia cho $0$ (`divide by zero`), tràn mảng (`buffer overflow`) hoặc vòng lặp vô tận: Runtime Wasm lập tức **bắt bẫy ngoại lệ (Trap)** và cách ly kịch bản đó một cách êm ái, **Zone Server C++ vẫn tiếp tục phục vụ $10.000$ người chơi mà không bị sập**!
2. **Hiệu Năng Gần Như Native (Near-Native Speed)**:
   - Wasm là định dạng mã máy ảo nhị phân (Binary Bytecode) được chuẩn hóa bởi W3C, được tối ưu hóa thanh ghi và opcode tương đồng với kiến trúc CPU hiện đại.
   - Nhanh gấp **15 đến 30 lần** so với Lua thông dịch không có JIT.
3. **Đa Ngôn Ngữ Linh Hoạt (Polyglot)**:
   - Các kỹ sư hệ thống có thể viết Boss AI phức tạp bằng **Rust** rồi xuất ra `.wasm`.
   - Các Game Designer có thể viết kịch bản nhiệm vụ bằng **TypeScript (AssemblyScript)** với đầy đủ auto-complete, static type checking trên IDE, không bao giờ lo gõ nhầm tên biến.
4. **Không Có Rác GC (Zero-GC Jitter)**:
   - Module Wasm tự quản lý vùng nhớ tuyến tính của mình thông qua Arena Allocator, trả lại bộ nhớ tức thì khi kết thúc nhiệm vụ mà không cần một trình dọn rác toàn cục nào can thiệp vào vòng lặp $30\text{Hz}$.

---

## 4. BẢNG SO SÁNH VÍ DỤ: KỊCH BẢN BOSS AI LUA (2005) vs. WASM TYPESCRIPT (2026)

### Kịch Bản Thời 2005 (VLTK 1 - Lua Dễ Lỗi):
```lua
-- ❌ CŨ KỸ: Lua không bắt lỗi cú pháp, dễ crash lúc nửa đêm
function OnBossAttack(player)
    if player.Hp < 500 then -- Gõ nhầm Hp thành hp -> NIL CRASH!
        CastSkill(player, 102)
    end
end
```

### Kịch Bản Chuẩn 2026 (FreeExile - AssemblyScript / Wasm):
```typescript
// ✅ CHUẨN 2026: TypeScript chặt chẽ 100%, tự động biên dịch sang .wasm
import { Player, SkillId, ServerAPI } from "freeexile-engine";

export function onBossEvaluate(bossId: i32, target: Player): void {
    // IDE báo đỏ ngay lập tức nếu gõ sai tên trường hoặc sai kiểu dữ liệu
    if (target.healthPoints < 500.0 && !target.isInEvasionIFrame) {
        ServerAPI.castElementalSkill(bossId, target.entityId, SkillId.LietDiemBocPha);
    }
}
```

---

## 5. KẾT LUẬN & ĐỊNH HƯỚNG

Quyết định **đoạn tuyệt với Lua** và áp dụng **WebAssembly (Wasm)** là bước ngoặt công nghệ tất yếu năm 2026. Giải pháp này kết hợp:
* **Tốc độ đỉnh cao** của C++20 Native Engine.
* **Sự an toàn và linh hoạt** của TypeScript/Rust qua WebAssembly Sandbox.
* **Tính ổn định tuyệt đối** cho máy chủ phục vụ 1.000.000 CCU mà không sợ bị sập bởi các kịch bản lỗi thời.