Native Hooking | 原生鈎子

1. 功能概述

MachoHookNative 提供了一組 API，可在遊戲全局掛鉤（hook）「原生函式」（native functions）。

• 限制：無法掛鉤 CitizenFX（FiveM）特定的 native，但所有普通的遊戲 native 都支持。

• 隔離機制：位於 Macho 的隔離環境（isolated environment）不會觸發這些 hook；只有遊戲資源（resources）直接呼叫時，這些 hook 才會生效。

2. API 語法與使用方式

MachoHookNative([integer] hash, [function] callback) -> void

• hash：64 位元的原生函式哈希值（非 JOAAT 哈希）。

• callback：當該 native 被呼叫時執行的函式，必須：

  1. 接收相同的參數。

  2. 回傳一個布林值（boolean）＋原本 native 的回傳值。

  • 若布林傳回 false：跳過原函式的執行（即攔截它）。

  • 若傳回 true：繼續執行下一個 Lua hook（若無更多 hook），再執行原 native，除非其他 hook 返回 false。

3. 範例說明

以下範例掛鉤了 GetPlayerName native 函式：

MachoHookNative(0x6D0DE6A7B5DA71F8, function (player_id)
    -- 這段在隔離環境中執行，不會被偵測。
    print(GetCurrentResourceName() .. " 試圖獲取我們的真實名稱: " .. GetPlayerName(player_id))

    -- 回傳 false，代表不呼叫原始函式，並傳回「macho-man」字串作為結果。
    return false, "macho-man"
end)

接著測試結果如下：

MachoInjectResource("any", [[
    print(GetPlayerName(PlayerId()))
]])

這段測試會顯示玩家名稱為 "macho-man"，證明 hook 已成功攔截並替換了原本的返回值。

---

總結整理表格

項目	說明
功能	掛鉤任意遊戲原生函式（non-CitizenFX native）
API	MachoHookNative(hash, callback)
參數	hash：64-bit 原生函式哈希； callback：Lua 函式，參數一致，回傳 boolean + return values
回傳值機制	false → 攔截不呼叫原函式； true → 繼續 hook 或呼叫原函式
範例結果	成功將 GetPlayerName 的回傳值改為 "macho-man"