Browse docs

Test Drive Events & Blockers

Control and integrate with the Coinsystem test drive lifecycle.

Overview

Coinsystem emits local client- and server-side events when a confirmed test drive starts or ends. Use these events to integrate fuel, HUD, logging, telemetry, vehicle handling, or other resources without modifying the test drive logic.

Server Blockers

Blockers are local, cancelable server events. Call CancelEvent() synchronously inside a listener to reject the operation. Coinsystem shows the player a localized generic notification when a blocker rejects the request.

Block Test Drive Start

Fires after Coinsystem validates the requested model and confirms that the player has no existing session and that a test drive slot is available, but before it assigns a routing bucket or enables godmode.

server.lua

AddEventHandler("sky_coinsystem:server:beforeTestDriveStart", function(player_id, model)
    -- Replace this with your own server-side condition.
    if Player(player_id).state.in_jail then
        CancelEvent()
    end
end)

Parameter	Type	Description
`player_id`	`number`	Server ID of the player requesting the test drive.
`model`	`string`	Validated and normalized vehicle spawn name.

Block Manual Test Drive End

Fires before Coinsystem authorizes a manual test drive end. The authorization is bound to the player's active server session and expires after five seconds.

server.lua

AddEventHandler("sky_coinsystem:server:beforeTestDriveEnd", function(player_id, model, reason)
    -- Replace this with your own server-side condition.
    if Player(player_id).state.test_drive_exit_locked then
        CancelEvent()
    end
end)

Parameter	Type	Description
`player_id`	`number`	Server ID of the active test driver.
`model`	`string`	Validated and normalized vehicle spawn name.
`reason`	`string`	Always `manual` for this blocker.

Only a manual end can be blocked. Safety cleanup caused by leaving the vehicle, leaving the test area, death, a missing vehicle, disconnecting, or a resource stop always ends the session so the player cannot remain stuck in a routing bucket or protected state.

Do not call Wait() or perform asynchronous work before CancelEvent(). Event cancellation only applies to the current local event invocation, and canceling does not prevent other registered listeners from running.

Client Events

Test Drive Started

Fires after the test vehicle has spawned and the player has been placed inside it.

client.lua

AddEventHandler("sky_coinsystem:client:testDriveStarted", function(vehicle, model)
    print(("Test drive started: %s, entity %s"):format(model, vehicle))

    -- Example integration:
    -- exports["your_fuel_resource"]:SetFuel(vehicle, 100.0)
end)

Parameter	Type	Description
`vehicle`	`number`	Local entity handle of the spawned test vehicle.
`model`	`string`	Normalized vehicle spawn name.

The vehicle also exposes a replicated state bag value for integrations that process vehicles independently of the lifecycle event:

client.lua

if Entity(vehicle).state.sky_coinsystem_test_drive then
    return
end

Use this marker to exclude temporary test vehicles from wear, damage, mileage, fuel consumption, or persistence. sky_mechanicjob detects it automatically and disables its wear, oil leak, and wheel damage systems for the test vehicle.

Test Drive Ended

Fires after the client has cleaned up the test vehicle and restored the player.

client.lua

AddEventHandler("sky_coinsystem:client:testDriveEnded", function(model, reason)
    print(("Test drive ended: %s (%s)"):format(model, reason))
end)

Parameter	Type	Description
`model`	`string`	Normalized vehicle spawn name.
`reason`	`string`	Reason why the test drive ended.

Server Events

Test Drive Started

Fires only after the server-authorized session has been confirmed by the client following a successful vehicle spawn.

server.lua

AddEventHandler("sky_coinsystem:server:testDriveStarted", function(player_id, model)
    print(("Player %s started a test drive with %s"):format(player_id, model))
end)

Parameter	Type	Description
`player_id`	`number`	Server ID of the test driver.
`model`	`string`	Normalized vehicle spawn name.

Test Drive Ended

Fires only for a previously confirmed test drive session.

server.lua

AddEventHandler("sky_coinsystem:server:testDriveEnded", function(player_id, model, reason)
    print(("Player %s ended the %s test drive (%s)"):format(player_id, model, reason))
end)

Parameter	Type	Description
`player_id`	`number`	Server ID of the test driver.
`model`	`string`	Normalized vehicle spawn name.
`reason`	`string`	Reason why the test drive ended.

End Reasons

Reason	Description
`manual`	The player ended the test drive using the configured interaction key.
`left_vehicle`	The player is no longer inside the assigned test vehicle.
`out_of_bounds`	The player left the configured test drive radius.
`vehicle_missing`	The test vehicle no longer exists.
`dead`	The player was detected as dead.
`player_dropped`	The player disconnected during a confirmed test drive. Server event only.
`resource_stop`	Coinsystem stopped while the test drive was active.
`unknown`	No recognized end reason was available.

Treat reason as informational on the server. Coinsystem verifies the active session, but normal in-game end reasons originate from the player's client and should not be the sole authority for rewards, payments, or other security-sensitive actions.

Notes

These are local resource events. Listen with AddEventHandler; do not register them as network events.
Failed vehicle spawns and unconfirmed sessions do not emit lifecycle events.
The client end event does not include the vehicle entity because the test vehicle has already been removed.
Test vehicles are invincible, cannot receive visible damage, and cannot burst tyres during the session.

Custom Rewards

Battle Pass V3