Callbacks (staff + developers)

Players never see this. It is how every NCRP script asks the server (or a player's game) for something and waits for the answer: open an inventory, check a job, read a vehicle's position. One shared helper in ncrp-core does it for every script, with the same safety rules everywhere.

What it does for the city

Never hangs. If the other side does not answer within 10 seconds, the script gets "timeout" and carries on.
A broken script can't freeze others. An error in one callback is caught, printed in the server console with the script's name, and the player just gets "error".
Spam protection. One player can make about 30 requests per second per script. More than that is refused and the console names the player.
Clean restarts. When a script stops, its callbacks are gone at once; when it starts again, they come back.

Staff commands

Command	Who	What it does
`/cbtest ping`	staff	Asks the server for a test answer and shows how long it took
`/cbtest error` / `slow` / `unknown` / `spam`	staff	Test a broken, a too-slow, a missing callback and spam protection
`/cbtest call <name>`	staff	Calls any callback by name, e.g. `ncrp-jobmenu:ping`
`cbowners [filter]`	staff / console	Lists every callback name and the script that owns it
`cbclient [server id]`	staff / console	Asks that player's game for its position

Every script that uses the helper answers <script>:ping for staff, so /cbtest call ncrp-jobmenu:ping tells you whether a script is running and answering.

For developers

Add shared_script '@ncrp-core/shared/callback.lua' (and dependency 'ncrp-core') to the resource. The full how-to sits at the top of that file. The short version:

```lua
-- server
Core.RegisterCallback('ncrp-myscript:getThing', function(src, id)
if type(id) ~= 'number' then return false end -- never trust the client
return true, LoadThing(id)
end, { rate = 5, oneAtATime = true })

-- client (inside a thread or event handler)
local ok, thing = Core.TriggerCallback('ncrp-myscript:getThing', 12)
if ok == nil then print('failed: ' .. tostring(thing)) end -- thing = 'timeout' / 'error' / 'rate' ...
```

Rules:

Never call heavy exports (anything that returns a big table) inside a loop in a callback. The old server froze from exactly that.
A failed call returns nil, reason, so never return nil as the first value on success.
Debug: setr ncrp_cb_debug 1 prints every callback slower than 100 ms on both sides.

Was this guide helpful?