菜单与 HUD 绘制 API

插件菜单

samp.ui.menu.register(page)

需要 ui.menu。注册页面，或替换相同 ID 的页面，无返回值。结构错误或控件 校验失败时通常会跳过对应内容；类型错误和无效数字参数仍可能抛出 Lua 错误。

samp.ui.menu.register({
    id = "main",
    title = "示例",
    controls = {
        { type = "switch", id = "enabled", title = "启用", value = true },
        {
            type = "dropdown",
            id = "theme",
            title = "主题",
            value = "dark",
            options = {
                { value = "dark", label = "深色" },
                { value = "light", label = "浅色" }
            }
        }
    }
})

页面字段	类型	约束
id	string	必填、非空，最长 64 字节。
title	string	必填、非空，最长 128 字节。
controls	array	最多 32 个控件，同一页面中的 ID 必须唯一。

每个插件最多注册 8 个页面。每个控件都必须提供非空 type、最长 64 字节的 id 和最长 128 字节的 title。所有控件都支持以下公共可选字段：

字段	类型	默认值	说明
description	string	""	辅助说明，最长 512 字节。
enabled	boolean	true	禁用后仍显示，但不产生交互事件。
visible	boolean	true	隐藏后不占布局，也不产生交互事件。
read_only	boolean	false	只读后仍显示，但不产生交互事件。
error	string	""	控件下方的错误提示，最长 512 字节。

完整控件列表

下面是 API 1.1 的完整控件集合。Lua 入参使用 snake_case 字段名；宿主在 收到控件变化时还会再次校验值。

控件类型	附加字段和规则
section	无。显示带标题的分组标题，不产生事件。
text	text: string，可为空，最长 512 字节。只读展示，不产生事件。
button	无。点击产生 valueType="action"、value="click"。
switch	必填 value: boolean，变化回传布尔值。
slider	min=0、max=1、step=0.1、value=min；均为有限数，绝对值不超过 1,000,000，且 max > min、step > 0；初始值会被钳制，变化按 step 归一化，回传 number。
choice	value: string 和 1–32 个唯一 { value, label }；value 最长 512 字节、label 最长 128 字节，当前 value 必须存在，回传选中的字符串。
text_input	value=""、placeholder=""、max_length=512；max_length 是按 UTF-8 字节计算的 1..512 整数，value 不能超长；用户点击“应用”后才回传字符串。
number_input	min=0、max=100、step=1、value=min；数值有限且绝对值不超过 1,000,000，max > min、step > 0，初始值必须在区间内；点击应用后回传归一化 number。
dropdown	value: string 和 1–32 个唯一 options；当前 value 必须存在，选择后回传该字符串。
multi_choice	values: string[]（可为空）和 1–32 个唯一 options；每个已选值必须存在且不重复；点击会切换选中状态，并回传被切换的 option value 字符串。
color_picker	value: string，格式为 #RRGGBB 或 #RRGGBBAA；点击应用后回传通过校验的颜色字符串。
confirm_button	confirmation: string，最长 512 字节；点击先弹出确认，确认后回传 action/click。
divider	无。显示分隔线，不产生事件。
group	expanded: boolean，默认 true；点击回传 action/toggle，控制当前 group 到下一个 group 之间的控件显示与隐藏。
list	options 为 0–32 个唯一 { value, label }；可选 empty_text，最长 512 字节；点击条目回传其 value 字符串，空列表显示 empty_text。
progress	value 为 0..1，可选 indeterminate: boolean（默认 false）；仅展示，不产生事件。

所有选项的 value 最长 512 字节、label 最长 128 字节；choice、 dropdown、multi_choice 和 list 都拒绝重复 option value。替换页面时， 校验失败的控件不会暴露给菜单。

ui.control_changed

控件变化事件包含 pluginId、pageId、controlId、valueType 和类型化的 value：

控件	valueType	value
switch	boolean	true 或 false
slider、number_input	number	宿主按范围和 step 归一化后的有限数值
choice、dropdown、multi_choice、color_picker、text_input、list	string	选中、切换、提交或点击条目的值
button、confirm_button	action	确认后的 "click"
group	action	"toggle"

section、text、divider 和 progress 不产生控件变化事件。菜单变化在 受限的菜单回调阶段派发，通用事件信封见事件回调参数。

HUD 调用阶段

所有 samp.draw 函数均需要 ui.draw，并且只能在 draw.hud 回调中同步调用。 每个插件每帧最多排队 512 条绘制命令。除 world_to_screen 外均无返回值。

颜色使用 0xAARRGGBB ARGB 整数。normalized=true 时坐标范围是 0..1， 否则使用屏幕坐标。普通坐标必须有限且绝对值不超过 100,000。

samp.draw.text(options)

字段	默认值	约束
x、y	0	坐标。
text	—	必填字符串，最长 1,024 字节。
size	16	有限，>0 且 <=512。
color	0xFFFFFFFF	ARGB。
normalized	false	布尔值。

samp.draw.line(options)

字段为 x1=0、y1=0、x2=0、y2=0、color=0xFFFFFFFF、 thickness=1（>0..100）和 normalized=false。

samp.draw.rect(options)

与 line 相同，另有 filled=false。即使填充，thickness 也必须有效。

samp.draw.circle(options)

字段为 x=0、y=0、radius=1、color=0xFFFFFFFF、filled=false、 thickness=1（>0..100）和 normalized=false。radius 必须为正且不超过 100,000；归一化模式下不得超过 1。

samp.draw.progress_bar(options)

字段为 x1=0、y1=0、x2=0、y2=0、value=0、 color=0xFFFFFFFF、background_color=0x66000000 和 normalized=false。要求 x2 > x1、y2 > y1，value 范围为 0..1。

samp.draw.image(options)

字段	默认值	约束
x1、y1、x2、y2	0	x2 > x1、y2 > y1。
resource	—	必填的包内安全相对路径，最长 256 字节。
alpha	1	有限 0..1。
normalized	false	布尔值。

支持 PNG、WebP、JPEG、JPG。源文件最大 16 MiB，解码尺寸最大 1024×1024。 每个插件最多缓存 16 张图和 16 MiB 解码数据；整个运行环境上限 64 MiB； 每帧最多开始加载一张未缓存图片。

samp.draw.world_to_screen(position)

接收 Vector3。游戏不可用或点无法投影到镜头前方时返回 nil，否则返回：

{ x = number, y = number, depth = number, width = number, height = number }