Vehicle drive-by

Control handheld combat from a vehicle and read that action from client or server Lua. Passengers use window combat; drivers use the game's native car or motorcycle combat pose. Open77 replicates aim, weapons, shots and reload.

Available in Open77 Unstable 2.31.21-unstable+op77.118, protocol 1.43. Use the matching client, server and animation assets. Passenger support first shipped in .117 (protocol 1.42); car/motorcycle drivers and the additional state fields below require .118. Stable does not include this feature yet.

Supported passenger seats are front_right, back_left and back_right. The driver uses front_left, including on motorcycles. Draw a suitable handheld weapon using the normal game controls. Enabling drive-by permits that action; it does not equip a weapon, start shooting or force an animation. Driver-operated mounted weapons have their own vehicle weapon APIs.

Functions and permissions#

All functions belong to Open77.players. Use a network player ID, not a native entity handle. There are no drive-by global aliases.

Server reads require a positive connected player ID. On the client, omit the ID or pass integer 0 to read the local player. Pass no argument rather than nil. Remote client reads require a player known to that client.

enabled and active answer different questions. An enabled player can be on foot; an exiting player can already be disabled. Test a boolean read against nil to detect an error: a returned false is a valid answer.

Server example: an admin policy command#

Use server policy for gameplay rules such as a race, a safe zone or a restrained player. Decide the rule from server-owned state before changing it.

Create open77.lua:

resource "driveby_rules"
version "1.0.0"
auto_start true

server_script "server/main.lua"
permissions { "players.driveby", "players.life.read" }

Then server/main.lua:

RegisterCommand("driveby", function(source, args)
    local playerId = tonumber(args[1])
    local action = args[2]
    if not playerId or playerId <= 0 or playerId % 1 ~= 0
        or (action ~= "off" and action ~= "on" and action ~= "status") then
        print("Usage: driveby <playerId> <off|on|status>")
        return
    end

    if action ~= "status" then
        local ok, reason = Open77.players.setDriveByEnabled(playerId, action == "on")
        if not ok then
            print("Cannot change drive-by: " .. tostring(reason))
            return
        end
    end

    local state, reason = Open77.players.getDriveByState(playerId)
    if not state then
        print("Cannot read drive-by: " .. tostring(reason))
        return
    end
    print(("Player %d: allowed=%s, phase=%s, available=%s")
        :format(playerId, tostring(state.enabled), state.phase, tostring(state.available)))
end, true)

Run driveby 12 off, driveby 12 on or driveby 12 status in the dedicated server console, replacing 12 with the player's ID. Players running this restricted command need the ACL right command.driveby; see command permissions. The example prints results to the server log.

For an existing gamemode, put these calls at the start and end of its activity:

local function restrictPassenger(playerId)
    local ok, reason = Open77.players.setDriveByEnabled(playerId, false)
    if not ok then print(reason) end
    return ok
end

local function releasePassenger(playerId)
    local ok, reason = Open77.players.setDriveByEnabled(playerId, true)
    if not ok then print(reason) end
    return ok
end

If a respawn or revive is pending, the server can return transition_in_progress. Re-evaluate your rule and retry after that transition finishes.

Client example: a local restriction#

Use the client setter for a local mode or UI that should temporarily suppress passenger combat. The server's policy still applies.

For this client-only example, create open77.lua:

resource "driveby_local_demo"
version "1.0.0"
auto_start true

client_script "client/main.lua"
permissions { "players.driveby", "players.read" }

Then client/main.lua:

RegisterCommand("driveby_local", function(_, args)
    if args[1] ~= "off" and args[1] ~= "on" then
        print("Usage: driveby_local <off|on>")
        return
    end

    local ok, reason = Open77.players.setLocalDriveByEnabled(args[1] == "on")
    if not ok then
        print("Cannot change local drive-by: " .. tostring(reason))
        return
    end

    local enabled, readReason = Open77.players.isDriveByEnabled()
    if enabled == nil then
        print("Cannot read local policy: " .. tostring(readReason))
    else
        print("Drive-by currently allowed: " .. tostring(enabled))
    end
end, false)

Run driveby_local off, then driveby_local on in the client console. on releases this resource's restriction; the effective result can remain false while a server rule or another client resource blocks drive-by.

Call the client setter from a running resource callback or thread. A call made at script top level while the resource is still preparing returns false, "resource_not_running".

Read the action and its phases#

The usual sequence is none → entering → active → exiting → none. isInDriveBy and the state's active field include entering and exiting. Use state.phase == "active" for the window-combat loop specifically; even that phase does not mean the player fired a shot on this frame.

For example, add this to a client resource with players.read to report local phase changes without printing every frame:

CreateThread(function()
    local previous
    while true do
        local state, reason = Open77.players.getDriveByState()
        local status = state and (state.available and state.phase or "unavailable")
            or ("error: " .. tostring(reason))
        if status ~= previous then
            print("Passenger action: " .. status)
            previous = status
        end
        Wait(250)
    end
end)

To inspect another player, pass their network ID. This helper works on either runtime with its corresponding read permission:

local function describePassenger(playerId)
    local state, reason = Open77.players.getDriveByState(playerId)
    if not state then return nil, reason end
    if not state.available or state.phase ~= "active" then return nil end

    return ("Player %d: window combat in vehicle %d, seat %s")
        :format(playerId, state.vehicle, state.seat)
end

The server validates actions against the player's current seat, life and routing bucket. Missing or stale action data produces phase == "none" with available == false; it does not prove the player performed an exit animation. These reads are observations, not a history or a per-shot event stream. The client's fresh local none state may still have available == true.

Identify a driver or motorcycle rider#

The same reads and restrictions cover all three modes. Driver actions have phase == "active" while handheld combat is active, with duration == 0 and elapsed == 0; the timed entering/exiting phases belong to passenger window combat. A driver can use either first- or third-person camera locally; observers receive the native third-person pose.

-- Server callback; requires players.life.read.
RegisterCommand("riderstate", function(playerId)
    local state, reason = Open77.players.getDriveByState(playerId)
    if not state then return print(reason) end
    if not state.available or not state.active then return end

    if state.mode == "bike_driver" then
        print(("Rider %d on motorcycle %d: yaw %.1f, pitch %.1f")
            :format(playerId, state.vehicle, state.driverYaw, state.driverPitch))
    elseif state.mode == "car_driver" then
        print("Armed driver in vehicle " .. state.vehicle)
    else
        print("Passenger window combat: " .. state.seat)
    end
end, true)

Combining resources and cleanup#

Each resource owns one restriction per player on its runtime:

• false holds that resource's restriction; true releases only that hold.
• Repeated false calls do not add a counter. If several features in the same resource need a hold, combine their conditions before releasing it.
• Stopping or reloading a resource releases its own holds. Other owners remain effective; disconnect clears the connection's restrictions.
• Server restrictions survive death, respawn and routing-bucket changes for the current connection. A pending revive/respawn can defer resource-stop cleanup.
• The local client combines its own resource restrictions with server policy. Server reads and remote client reads cannot reveal another client's local-only restrictions. Use the server setter for an authoritative gameplay rule.

Disabling a passenger already in window combat requests a native exit. The state can remain exiting briefly after enabled becomes false. A successful setter acknowledges the policy change, not immediate animation completion. For a driver, disabling requests the native return to ordinary driving; the remote driver action clears when that state ends.

Windows and damage#

Open77 opens the passenger's window for replicated drive-by presentation, keeps it open through the exit, and restores the authored window state afterward. Each passenger has an independent window. Car-driver combat opens both front windows; motorcycles do not receive a window overlay. Your resource does not need to toggle vehicle windows or replay weapon shots to implement drive-by.

The occupant's ranged shots are filtered against their own vehicle and its occupants. The server also rejects ranged hits between occupants of the same vehicle. Exterior targets continue through the normal combat rules. Drive-by does not grant general invulnerability to the vehicle or its passengers.

Failure handling#

See the client players reference and server players reference for individual function signatures and examples.