feat(citizen-server): add event listeners for routing bucket changes

[outsider31000]

Goal of this PR

This pull request adds routing bucket event listeners to help developers and server owners handle player/entities routing bucket changes.

with these listeners, it becomes much easier to manage features tied to virtual worlds.
for example, doors that need to stay in sync within a specific routing bucket can be tracked through events when players move or are removed, this allows clean separation of logic per virtual world, this is just one example.

How is this PR achieving the goal

By exposing these events, server-side scripts can register handlers to respond in real time when a player moves between buckets. this gives full control to manage entities/players or logic tied to specific virtual worlds, such as syncing doors, tracking world-specific data, etc.

AddEventHandler("onPlayerBucketChange", function(player, newBucket, oldBucket)
    print(("Player %s moved to %s from %s"):format(player, newBucket, oldBucket))
end)

AddEventHandler("onEntityBucketChange", function(entity, newBucket, oldBucket)
    print(("Entity %s moved to %s from %s"):format(entity, newBucket, oldBucket))
end)

This PR applies to the following area(s)

RedM/FiveM

Successfully tested on

Game builds: ..

Platforms: Windows, Linux
windows

Checklist

• Code compiles and has been tested successfully.
• Code explains itself well and/or is documented.
• My commit message explains what the changes do and what they are for.
• No extra compilation warnings are added by these changes.

Fixes issues

[Nobelium-cfx]

I'm probably missing something. But the events are added into SET_PLAYER_ROUTING_BUCKET and SET_ENTITY_ROUTING_BUCKET natives. Those natives are triggered by the server code. The even't don't send any additional information besides native arguments and old bucket that can be retrieved with GET_ENTITY_ROUTING_BUCKET/GET_PLAYER_ROUTING_BUCKET. So why do we need an event if server can just call any relevant processing code after it triggers the native?

[ChatDisabled]

I have a resource that attaches an object to the player. The player interacts with another resource that changes their routing bucket of which I'm not the author and the code is hidden behind escrow. The attached object disappears.

Instead of having an arbitrary thread checking if their bucket changed I can now listen to this event instead. Re-attach the object and clean it up in the previous bucket (if needed).

This is just an example, and it is not the end of the world if you do it arbitrarily. Just a nice to have to have these event listeners in an UGC environment where anything can happen

[outsider31000]

I'm probably missing something. But the events are added into SET_PLAYER_ROUTING_BUCKET and SET_ENTITY_ROUTING_BUCKET natives. Those natives are triggered by the server code. The even't don't send any additional information besides native arguments and old bucket that can be retrieved with GET_ENTITY_ROUTING_BUCKET/GET_PLAYER_ROUTING_BUCKET. So why do we need an event if server can just call any relevant processing code after it triggers the native?

You're right, but my changes allow us to detect bucket changes without constantly running native checks or applying natives everywhere they're needed. With events, code runs only when necessary, which leads to more optimized scripts especially on the server, where performance matters most.

[Nobelium-cfx]

The player interacts with another resource that changes their routing bucket of which I'm not the author and the code is hidden behind escrow.

Right, I wasn't thinking about it from different resources point of view. That makes sense.

Ok, the change itself looks good then. @outsider31000 I think we need to add docstring comment (e.g. see how it's done for entityRemoved and others) so the event documentation can be generated in https://docs.fivem.net/docs/scripting-reference/events/ .

[AvarianKnight]

If the reason for this native is to properly move attached props and such with routing bucket changes, would this not be better as a "default behavior" vs expecting script authors to take care of it?

We should just define the behavior for setting routing bucket changes instead of this, similar to how SET_ENTITY_ORPHAN_MODE works for trains, where it changes all attached trains orphan mode too.

Basic gist would be:

Prop attached to player gets it's routing bucket change -> reject with error (deattach first or change the players routing bucket)

Vehicle has its routing bucket change -> allow and change the routing bucket of everyone in the vehicle too

Ped has its routing bucket change -> allow and set all the props that are attached to the ped to that routing bucket too

[outsider31000]

@Nobelium-cfx done. let me know if thats all. thank you.

[ChatDisabled]

@AvarianKnight This is not the case for me, it was just an example given that I could come up with. There are probably a few more cases for whatever reason that someone wants to listen to these changes.

[Nobelium-cfx]

@Nobelium-cfx done. let me know if thats all. thank you.

If I'm not confusing anything - we only need one docstring comment. No need to duplicate it twice (I'm not sure if duplication will cause issues with docs generation or not, but we don't have any duplications like this currently). The comment can be written pretty much anywhere in the code - just the event trigger call usually ends up being a good place for it. So lets leave just the first comment and remove the second one.

[outsider31000]

Since they are 2 different events I thought it needed both ?
one for entity one for player

[Nobelium-cfx]

Since they are 2 different events I thought it needed both ? one for entity one for player

Ah, somehow I didn't notice that they were different. Sorry. You are right!

[outsider31000]

No problem, thank you for reviewing it.