配置

所有内容都在 config.lua 中进行配置。本页将逐一介绍每个选项。

通用

config.lua

Config.Framework = 'qbox'    -- qbox / qbcore / esx / standalone
Config.Command   = 'animpos' -- 聊天指令名称
Config.Cooldown  = 15        -- 使用冷却时间（秒）

Framework — 选择核心资源以及适用的元数据限制。
Command — 打开工具的聊天指令（同时也用作按键映射名称）。
Cooldown — 两次使用之间的最小秒数。

按键绑定

允许玩家使用按键打开工具，可在 GTA V 设置中重新绑定。

config.lua

Config.Keybind = {
    Enabled = true,
    Default = 'F6',  -- 默认按键（留空则无；玩家可自行重新绑定）
}

ℹ

只有当 Enabled = true 且 Default 不为空时，按键映射才会注册。玩家随时可以在“设置” → “按键绑定” → “FiveM”中重新绑定。

权限（可选）

限制谁可以使用该工具。默认关闭。

config.lua

Config.Permission = {
    Enabled = false,
    Type    = 'ace',                     -- 'ace' / 'job'
    Ace     = 'animpos.use',             -- 当 Type == 'ace' 时使用
    Jobs    = { 'police', 'ambulance' }, -- 当 Type == 'job' 时使用
}

ace — 通过 ox_lib 回调在服务端通过 IsPlayerAceAllowed 进行检查（最安全）。使用 add_ace ... animpos.use allow 授予权限。
job — 玩家的框架职业名称必须在 Jobs 列表中（QBox / QB-Core / ESX）。

限制

阻止玩家在特定状态下使用。原生检查适用于所有框架；元数据检查仅适用于 QBox 和 QB-Core。

config.lua

Config.Restrictions = {
    -- 基于框架（仅限 qbox / qbcore）
    CheckDead        = true,   -- 死亡时阻止
    CheckLastStand   = true,   -- 垂死挣扎时阻止
    CheckHandcuffed  = true,   -- 被戴手铐时阻止

    -- 基于原生（适用于所有框架，包括 standalone）
    CheckInVehicle   = true,   -- 在载具内时阻止
    CheckFalling     = true,   -- 坠落 / 跳伞时阻止
    CheckSwimming    = false,  -- 游泳时阻止

    -- 从玩家数据中读取的元数据字段名称
    MetaKeys = {
        Dead       = 'isdead',
        LastStand  = 'inlaststand',
        Handcuffed = 'ishandcuffed',
    },
}

⚠

MetaKeys 对应你所使用的框架玩家数据上的元数据字段名称。如果你的核心（或自定义包）使用不同的键来存储这些数据，请在此处进行更改，以便死亡 / 垂死挣扎 / 手铐检查能够读取到正确的值。

通知

选择每条消息所使用的后端。

config.lua

Config.Notify = 'ox_lib'  -- 'ox_lib' / 'qbcore' / 'esx' / 'custom'

-- 仅在 Config.Notify == 'custom' 时使用。
-- ntype 取值之一：'success' / 'error' / 'primary' / 'inform'
Config.CustomNotify = function(message, ntype)
    -- exports['my-notify']:SendAlert(message, ntype)
end

ox_lib — lib.notify（默认）。
qbcore — QBCore:Notify 事件。
esx — esx:showNotification 事件。
custom — 你在 Config.CustomNotify 中的自定义处理程序。

ℹ

无效的 Config.Notify 值会在服务端控制台记录警告，并安全地回退到 ox_lib。

UI

config.lua

Config.UI = {
    Position = 'right',       -- left / right / center
    OffsetX  = 30,            -- 距边缘的距离 (px)
    OffsetY  = 0,             -- 垂直偏移量 (px)
    AccentColor = '#f4cb98',  -- 按键高亮 / 发光的强调色
    ShowHeader = true,        -- 显示标题/副标题栏
    ShowTip    = true,        -- 显示底部提示行
    ShowAnimations = true,    -- 按键按下动画
    AnimationType = {
        Movement = 'pulse',   -- pulse / glow
        Action   = 'glow',    -- pulse / glow
    }
}

移动

config.lua

Config.Movement = {
    Speed         = 0.01,  -- 移动速度
    RotationSpeed = 0.5,   -- 旋转速度
    MaxDistance   = 5.0,   -- 距起始位置的最大距离 (m)
    MaxHeight     = 3.5,   -- 距起始位置的最大高度 (m)
    MinHeight     = -3.5,  -- 距起始位置的最低高度 (m)
    PrecisionMultiplier = 0.25, -- 按住精准键时的速度倍率
}

性能

config.lua

Config.Performance = {
    NetworkUpdateDelay = 50,   -- 网络同步延迟 (ms)
    LoopWait           = 0,    -- 主循环等待时间 (ms)
    AnimationDuration  = 300,  -- UI 动画持续时间 (ms)
    SyncCooldown       = 50,   -- 服务端防刷同步冷却时间 (ms)
}

AnimationDuration 作为面板的过渡长度传递给 UI。与同步相关的数值用于限制位置更新发送和接受的频率。

音效

用于打开 / 确认 / 取消 / 重置的可选 GTA V 前端音效。

config.lua

Config.Sounds = {
    Enabled = true,
    Open    = { name = 'SELECT',        set = 'HUD_FRONTEND_DEFAULT_SOUNDSET' },
    Confirm = { name = 'SELECT',        set = 'HUD_FRONTEND_DEFAULT_SOUNDSET' },
    Cancel  = { name = 'CANCEL',        set = 'HUD_FRONTEND_DEFAULT_SOUNDSET' },
    Reset   = { name = 'RESET_PROMPTS', set = 'HUD_FRONTEND_DEFAULT_SOUNDSET' },
}

将 Enabled = false 设置为静音所有音效。

CanUse 钩子

每次玩家尝试打开工具时运行的自定义检查。返回 true 表示允许，或返回 false（可选择附带消息字符串）以阻止。

config.lua

Config.CanUse = function()
    -- 示例：受伤时阻止
    -- local ped = PlayerPedId()
    -- if HasEntityBeenDamagedByAnyPed(ped) then
    --     return false, '你不能在受伤时这样做！'
    -- end
    return true
end

控制键

控制键的扫描码也可以在 Config.Controls 下完全配置（前进、后退、上、下、左、右、旋转、确认、取消 + 两个备用键、重置和精准）。默认布局请参阅使用与控制页面。

PreviousUsage & Controls Next Integrations