效果与物理 API

效果是可撤销的租约，不是永久修改。创建、移动、取得和释放资源只能在托管回调 中进行。资源归创建插件所有，并绑定当前会话与玩家世代；插件卸载、错误清理、 断线、死亡或重生都会使其失效。

Effect 租约

samp.effects.acquire(name, options)

返回带有 release() 的 Effect Handle，重复释放是安全的。 options.priority 是可选的 -1000..1000 整数，默认 0。每个插件最多 拥有 64 个效果。

player.physics_flags

需要 game.physics.override：

local lease = samp.effects.acquire("player.physics_flags", {
    priority = 50,
    usesCollision = true,
    collidable = true,
    disableCollisionForce = false,
    applyGravity = true,
    onSolidSurface = true,
    isStanding = true,
    wasStanding = true
})

每个标志都可选，但至少提供一个，且提供的值必须为 boolean。各标志独立决策： 优先级更高的租约获胜；优先级相同时较早的租约获胜。省略某个标志表示该租约 不控制它。

player.collision_filter

需要 game.physics.override。API 1.0 只支持：

local lease = samp.effects.acquire("player.collision_filter", {
    priority = 0,
    mode = "only_surface",
    surface = surface
})

surface 必须是同一插件拥有且当前有效的 Local Surface Handle。该策略下， 本地玩家只与指定 surface 碰撞。

批量释放

samp.effects.group(handles)

接收 1–64 个当前有效、互不重复且由本插件拥有的 Effect Handle，返回 { release = function }。release() 会释放全部成员并可重复调用。 创建 group 不会复制或转移所有权，成员仍可先单独释放。

本地 Surface

samp.physics.create_surface(options)

需要 game.physics.override 且本地玩家可用：

local surface = samp.physics.create_surface({
    position = { x = 0, y = 0, z = 10 }
})

position 必填；x、y 必须是 -2500..2500 的有限数，z 必须是 -100000..100000 的有限数。每个插件最多拥有 16 个 surface。

返回的 Handle 提供：

方法	阶段	说明
surface:is_valid()	任意	返回 boolean，失效后仍可安全调用。
surface:set_position(vector)	托管	使用相同坐标限制，无返回值。
surface:release()	托管	可重复调用，无返回值。

不要持久化 surface 或 lease Handle；应在下一次 player.spawned 后重新创建。