Controlled writes and effects

Write APIs require explicit permissions and a managed callback phase. They reject stale handles, invalid sessions, non-finite numbers, and values outside supported ranges.

Player and vehicle writes

With game.player.write or game.vehicle.write, a plugin can modify selected health, armor, position, velocity, skin, weapon, and ammunition values.

samp.events.on("player.spawned", function()
    local player = samp.player.local_player()
    if player == nil or not player:is_valid() then
        return
    end

    player:set_health(100)
    player:set_armor(100)
end)

Local changes to server-owned state may be overwritten by later synchronization. Do not use write APIs to assume server authority.

Effect leases

Effects represent reversible, host-managed overrides. Multiple plugins may request fields with priorities; releasing or unloading a lease restores the remaining merged state.

local flags

samp.events.on("player.spawned", function()
    flags = samp.effects.acquire(
        "player.physics_flags",
        {
            onSolidSurface = true,
            isStanding = true,
            priority = 50
        }
    )
end)

samp.events.on("session.ended", function()
    if flags ~= nil then
        flags:release()
        flags = nil
    end
end)

game.physics.override is high risk. Acquire only the fields required by the feature, release them promptly, and always test unload, player death, reconnect, and session shutdown.

Surface handles and collision filters are also generation-checked resources. A released or stale handle must not be reused.

API 1.1 also provides the high-risk camera.follow effect. It accepts a current streamed remote-player Handle, stores its session and stream generation, and is released automatically when the target or session becomes stale.