# 最佳实践：使用多线程加速逻辑

#if UNITY_WEBGL && !UNITY_EDITOR
        [DllImport("__Internal")]
        private static extern void TD_BattleWorkerAuthoritative_Init(// ... 省略中间参数 ...);

        [DllImport("__Internal")]
        private static extern void TD_BattleWorkerAuthoritative_Dispose(int requestId, int timeoutMs, int debugLogEnabled);

        // Plan27 SABTransport: C# 主动轮询 SAB 结果
        [DllImport("__Internal")]
        private static extern int TD_BattleWorkerAuthoritative_PollResult(byte[] buffer, int bufferSize);
#endif

mergeInto(LibraryManager.library, {
  // ...
  TD_BattleWorkerAuthoritative_Init__deps: ['$TD_BattleWorkerShadow_EnsureState', '$TD_BattleWorkerShadow_CreateWorker'],
  TD_BattleWorkerAuthoritative_Init: function (...) {
    // 这里的函数体就是 C# DllImport 调用时实际执行的 JS 代码
  },

// BattleWorkerShadowBridge.jslib (合并到 Unity 主线程 JS 中)

TD_BattleWorkerAuthoritative_Init: function(gameObjectNamePtr, ..., timeoutMs, debugLogEnabled) {

    // ══ Step 1: 获取/创建全局状态 ══
    var state = TD_BattleWorkerShadow_EnsureState();
    state.gameObjectName = UTF8ToString(gameObjectNamePtr);

    // ══ Step 2: 创建 Worker（含 SAB 通道） ══
    TD_BattleWorkerShadow_CreateWorker(state);

    // ══ Step 3: 从 Emscripten HEAP 拷贝 C# 传入的二进制配置 ══
    function copyBuffer(ptr, length) {
        return HEAPU8.slice(ptr, ptr + length).buffer;
    }
    // ... 其余所有配置 buffer

    // ══ Step 4: 检测 SAB 是否启用 ══
    state.sabEnabled = !!(state.Worker && state.Worker.sabEnabled);

    // ══ Step 5: 向 Worker 发送 init 消息 ══
    // SAB 模式：走 BATTLE_SAB_INIT，将两个 SAB 引用传递给 Worker
    if (state.sabEnabled) {
        Worker.postMessage({
            type: 'BATTLE_SAB_INIT',
            cmdBuffer: sabChannel.cmdSab,
            resultBuffer: sabChannel.resultSab,
            initPayload: {
                // 附带 init 配置（一次性 Transferable）
            }
        });
    } else {
        // 降级模式：纯 postMessage
        Worker.postMessage({ type: 'init', ... });
    }
}

    //.jslb

    TD_BattleWorkerShadow_CreateWorker(state);
         内部流程:
    //   ├─ adapter = GameGlobal.TD_BattleCoreWorkerAdapter.create()
    //   │   ├─ wx.createWorker('Workers/request/battlecore-Worker.js')  ← 微信 API 创建 Worker
    //   │   ├─ sabChannel = GameGlobal.TD_BattleCoreSabChannel.create() ← 创建 SAB 通道
    //   └─ state.Worker = adapter

// battlecore-Worker.js (独立线程)

Worker.onMessage(function(message) {

    // ══ 收到 BATTLE_SAB_INIT ══
    if (message.type === 'BATTLE_SAB_INIT') {
        // Step A: 接收 SAB 引用（此时两端共享同一块物理内存）
        cmdSab    = message.cmdBuffer;       // SharedArrayBuffer
        resultSab = message.resultBuffer;    // SharedArrayBuffer

        // Step B: 创建 Typed View（用于后续原子操作 + 二进制读写）
        cmdFlagArray = new Int32Array(cmdSab, 0, 1);
        cmdDataView  = new DataView(cmdSab);
        ringControl  = new Int32Array(resultSab, 0, 4);

        // Step C: 启动 1ms 轮询循环（持续监听 cmdSAB 中的命令）
        startCmdPolling();

        // Step D: 处理 initPayload — 加载 wasm 并初始化战斗
        var initMsg = message.initPayload;
        loadBattleRuntime().then(function(module) {
            handleInit(module, initMsg);
            // handleInit 内部:
            //   1. module.create()         → 分配 C 运行时实例
            //   2. 将配置写入 wasm HEAP    → module.malloc + memcpy
            //   3. module.loadScene(...)   → C 端解析场景配置
            //   4. 启动帧步进逻辑自驱循环      → setInterval(stepAuthoritativeFrame, 33ms)
            //   5. 将 init-result 写入 resultSAB Ring Buffer
        });
    }
});

# woker.js

function handleBattleCoreMessage(message) {
    if (!validateMessage(message)) {
        protocolError(message, 'Invalid battleCore protocol message');
        return;
    }

    loadBattleRuntime().then(function (module) {
        if (message.type === 'init') {   #加载Wasm模块
            handleInit(module, message);
            return;
        }
        if (message.type === 'dispose') {
            handleDispose(module, message);
        }
    }).catch(function (error) {
        protocolError(message, error && error.message ? error.message : String(error));
    });
}


worker.onMessage(handleBattleCoreMessage);

function loadBattleRuntime() {
    if (battleCoreRuntimePromise) {
        return battleCoreRuntimePromise;
    }
    battleCoreRuntimePromise = new Promise(function (resolve, reject) {
        var imports = createBattleRuntimeImports();
        var wasmPath = 'battlecore-wasm/battlecore-runtime.wasm';
        var errors = [];

        // 优先：微信 Worker 原生能力，直接传相对路径
        instantiateWithWXWebAssembly(wasmPath, imports).then(resolve, function (wxError) {
            errors.push('WXWebAssembly: ' + (wxError && wxError.message ? wxError.message : String(wxError)));

            // 兜底：标准 WebAssembly，需要先读取 wasm 二进制
            instantiateWithWebAssembly(wasmPath, imports).then(resolve, function (webError) {
                errors.push('WebAssembly: ' + (webError && webError.message ? webError.message : String(webError)));
                reject(new Error('Failed to instantiate battlecore-runtime.wasm. ' + errors.join(' | ')));
            });
        });
    });
    return battleCoreRuntimePromise;
}

#build-battle-runtime-Worker.ps1

$exportedFunctions = "[...,''_BattleRuntime_Step',...]"

# ...
  -s EXPORTED_FUNCTIONS=$exportedFunctions `
# ...

function scheduleAuthoritativeLoop(module) {
    if (!authoritativeLoopActive) {
        return;
    }
    authoritativeLoopTimer = setTimeout(function () {
        stepAuthoritativeFrame(module);
    }, authoritativeStepIntervalMs);
}

function stepAuthoritativeFrame(module) {
    // ...
    // 1 驱动 wasm 计算一帧
    stepResult = module.step(runtimeHandle, frameIndex, 1) | 0;

    // 2 获取帧结果大小
    frameResultSize = module.getFrameResultSize(runtimeHandle) >>> 0;

    // 3 分配内存
    frameResultPtr = module.malloc(frameResultSize) >>> 0;

    // 4 拷贝帧结果到分配的内存
    getResult = module.getFrameResult(runtimeHandle, frameResultPtr, frameResultSize) | 0;

    // 5 直接写入 SAB Ring Buffer 给主线程消费
    sabChannel.writeResultDirect(frameIndex, heapView, frameResultPtr, frameResultSize, ...);

    // 6 释放内存，推进帧号，调度下一帧
    module.free(frameResultPtr);
    authoritativeNextFrame = frameIndex + 1;
    scheduleAuthoritativeLoop(module);
}

// ── 第一层：DllImport 声明（C# → JS 桥） ──

[DllImport("__Internal")]
static extern int TD_BattleWorkerAuthoritative_PollResult(byte[] buffer, int bufferSize);
// 调用后，JS 侧会：
//   1. channel.pollResult()  → 从 SAB Ring Buffer 读一个 slot
//   2. 将结果序列化为 [header + payload] 写入 buffer
//   3. 返回写入的总字节数（0 = 无数据）

  $TD_BattleWorkerShadow_PollSabResult__deps: ['$TD_BattleWorkerShadow_EnsureState'],
  $TD_BattleWorkerShadow_PollSabResult: function (bufPtr, bufSize) {

    // ...
    var result = channel.pollResult();
    // ...

    // 构造 header 到 C# buffer
    var headerView = new DataView(HEAPU8.buffer, bufPtr | 0, HEADER_SIZE);
    // ... 填充result到headerView
    return totalLen;
  }

/**
 * 轮询读取结果通道 Ring Buffer（Worker→Main）
 * @returns {{ frameIndex: number, data: Uint8Array, resultType: number, requestId: number, success: boolean } | null}
 */
BattleCoreSabChannel.prototype.pollResult = function () {
    // ...
    // 深拷贝 payload（RingBuffer slot 数据）
    // this.resultSab : SAB
    var copy = resultSize > 0
        ? new Uint8Array(this.resultSab, slotOffset + this.slotHeaderSize, resultSize).slice()
        : new Uint8Array(0);

    // 推进 readIdx（释放 slot 给 Worker）
    Atomics.store(this.ringControl, 1, readIdx + 1);

    return {
        frameIndex: frameIndex,
        data: copy,
        resultType: resultType,
        requestId: requestId,
        success: success
    };
};

// ── 消费队列（流控） ──

Update(){
    //...
    DrainRuntimeInbox();
}
void DrainRuntimeInbox()
{
    // 先轮询 SAB，把 Worker 写入的结果全部读出来
    PollSabResult();

    // 再按流控策略从 inbox 取出消息，驱动游戏逻辑
    while (inbox.Count > 0)
    {
        var message = inbox.Dequeue();

        if (message.type == "frame-result")
        {
            scheduler.Receive(message);          // 入 Jitter Buffer
            // → 后续 CommitReadyResults() 按节拍取出
            // → EventConsumer 解析 payload 中的弹道/敌人数据
            // → ApplyWorkerMirror() 同步到 C# 游戏世界
        }
    }
}

C# Dispose() → JSlib TD_BattleWorkerAuthoritative_Dispose
  → [SAB模式] sabChannel.writeBinaryCommand(CMD_DISPOSE)
       → Worker 轮询 cmdSAB 读取 → handleDispose()
           → stopAuthoritativeLoop()       // 停止帧循环
           → sabChannel.dispose()          // 清理 Worker 端 SAB
           → module.destroy(runtimeHandle) // 调用 C/wasm 销毁
           → sendMessage('dispose-result') // 结果写入 resultSAB + postMessage
  → JSlib onMessage('dispose-result')
       → adapter.terminate()              // 终止 Worker 线程
       → state.Worker = null
  → C# 收到 dispose-result → _runtimeInitialized = false

//Workers\request\battlecore-sab-channel.js

/**
 * 轮询读取结果通道 Ring Buffer（Worker→Main）
 * @returns {{ frameIndex: number, data: Uint8Array, resultType: number, requestId: number, success: boolean } | null}
 */
BattleCoreSabChannel.prototype.pollResult = function () {
    if (!this.resultSab || !this.ringControl) {
        return null;
    }

    var writeIdx = Atomics.load(this.ringControl, 0);
    var readIdx  = Atomics.load(this.ringControl, 1);

    // 无新帧
    if (readIdx >= writeIdx) {
        return null;
    }

    // 字段bytes获取...

    // 校验
    var maxPayload = this.slotSize - this.slotHeaderSize;
    if (resultSize > maxPayload) {
        Atomics.store(this.ringControl, 1, readIdx + 1); // 跳过坏槽
        return null;
    }

    // 拷贝 payload...

    // 推进 readIdx（释放 slot 给 Worker）
    Atomics.store(this.ringControl, 1, readIdx + 1);

    return {...};
};

 #Workers\request\battlecore-sab-channel.js
/*
 * 写入帧结果到结果通道（Worker→Main）— Ring Buffer 版
 * @param {number} frameIndex - 帧索引
 * @param {Uint8Array|ArrayBuffer} data - frame-result 二进制数据
 * @param {number} [resultType] - 响应类型：0=frame, 1=init, 2=dispose, 3=error
 * @param {number} [requestId] - 请求ID（lifecycle 时传递）
 * @param {boolean} [success] - 是否成功
 * @returns {boolean} 写入成功返回 true
 */
WorkerSabChannel.prototype.writeResult = function (...) {
    if (!this.resultSab || !this.ringControl) {
        return false;
    }

    var writeIdx = Atomics.load(this.ringControl, 0); // writeIdx
    var readIdx  = Atomics.load(this.ringControl, 1); // readIdx

    // Ring 满判断：已写未读帧数 >= slotCount
    // ...

    var bytes;
    // 内存分配...

    var slotIndex = writeIdx % this.slotCount;
    var slotOffset = this.ringControlSize + slotIndex * this.slotSize;

    // 写入 Slot Header (20B, big-endian)
    // ...
    // 写入 payload
    // ...
    // 推进 writeIdx（release 语义，确保 payload 在 idx 更新前对主线程可见）
    Atomics.store(this.ringControl, 0, writeIdx + 1);
    return true;
};

#build-battle-runtime-Worker.ps1

$exportedFunctions = "[......]"

# ...

& $emcc @sources "-I$include" "-I$internalInclude" -O0 `
  -s MODULARIZE=1 `
  -s EXPORT_NAME=BattleCoreRuntimeModule `
  -s EXPORTED_FUNCTIONS=$exportedFunctions `
  -s EXPORTED_RUNTIME_METHODS="[]" `
  -s ALLOW_MEMORY_GROWTH=1 `
  -s ERROR_ON_UNDEFINED_SYMBOLS=1 `
  -o $output

minigame/
├── framework/
│   ├── battlecore-framework-adapter.js   ← 主线程：C# DllImport 桥
│   └── battlecore-sab-channel.js         ← 主线程：SAB Ring Buffer 读端
├── Workers/
│   └── request/
│       ├── battlecore-Worker.js          ← Worker 线程：帧循环 + 驱动 wasm
│       └── battlecore-sab-channel.js     ← Worker 线程：SAB Ring Buffer 写端
├── battlecore-wasm/
│   └── battlecore-runtime.wasm           ← Worker 加载：C/wasm 战斗计算核心
└── protocol/
    └── battlecore-protocol.js            ← 可选：消息协议定义