Add more guest events to scripting API (re-implementation of #19324)

[KatieZeldaKat]

This pull request will re-implement #19324 after its discussion went unresolved and went stale. It's more or less copy-paste but with a few minor changes:

• Add guest.drown hook
• Since Add Plugin API for managing a guest's items #21062 was merged, the GuestShopArgs uses the GuestItem type to represent what item was bought
• The original implementation of localization strings has been removed, as it was discussed that a dedicated localization interface would be better suited for this purpose in the future
• Add new items to the HookType, which also fixes HookType missing values #17512 (seen as I was already adding hooks, I thought fixing this issue made sense, but I can also make this a separate pull request if desired)

[ZehMatt]

I think this might have a pretty solid impact on the performance on bigger parks, DukTape is unfortunately painfully slow and given to how many hook types were added we should take measurements first. I suggest we use the EverythingPark to first measure the FPS on develop and then have one plugin with all the hooks setup to see if there is any change.

[KatieZeldaKat]

To test, I'm using Linux Mint 21.3 Cinnamon (the OS I normally use) to build using cmake. Regardless of whether I subscribe to all hooks or neglect having a plugin at all, the results are the same. I originally tested using the default build mode (Debug):

develop Debug: 5 or 6 frames (most common 6)
changes Debug: 6 or 7 frames (most common 6)

Since this was strange that the changes improved performance, I wanted to have the frame rate a little higher and see the difference with more significant figures (building using Release):

develop Release: 56 to 61 (mostly 60 with a few dips)
changes Release: 56 to 61 (mostly 59 or 60)

These results definitely vary depending on how long you are spending in the park. I tried to be as consistent with how I was looking at the frame counter. The difference seems pretty negligible.

I confirmed that the develop branch I was testing against was the exact same as my pull's branch, just before I added commits (and both branches in my fork say that they are an equal number of commits behind OpenRCT2:develop).

---

I've attached the plugin I was using. It does return early if the guest doesn't match, but that shouldn't be the reason for better performance, as the CPP code will still call the hook regardless while creating a DukValue object. I have tested all hooks, and they appear to be working well (after I fixed a few oversights). Should be ready to review.

guest-events.zip

[Basssiiie]

I had a quick test as well with your plugin, here are the results:

Guest count	Latest develop	Build from this PR
~11.500	~550 fps	~475 fps
~27.000	~120 fps	~32-50 fps
~45.000	~53-60 fps	~10 fps

• While the impact is pretty bad with a crazy amount of guests, I do think the API's themself would be very useful.
• They'd be more performant than doing a manual map.getEntities("guest") and keeping track of these changes.
• Also, most plugins may not use all of them at the same time and most players may not get that many guests in any park.

I wouldn't be against adding this APIs but I do understand ZehMatts performance concern. To be fair, at first I expected the impact to be way bigger for parks with less than 12.000 guests.

[ZehMatt]

I had a quick test as well with your plugin, here are the results:

Guest count Latest develop Build from this PR
~11.500 ~550 fps ~475 fps
~27.000 ~120 fps ~32-50 fps
~45.000 ~53-60 fps ~10 fps

• While the impact is pretty bad with a crazy amount of guests, I do think the API's themself would be very useful.
• They'd be more performant than doing a manual map.getEntities("guest") and keeping track of these changes.
• Also, most plugins may not use all of them at the same time and most players may not get that many guests in any park.

I wouldn't be against adding this APIs but I do understand ZehMatts performance concern. To be fair, at first I expected the impact to be way bigger for parks with less than 12.000 guests.

That's quite the impact. It doesn't need one plugin, if a few plugins are installed using one of these hooks it boils down to the same result. I know those hooks can be pretty useful and I'm definitely for more scripting possibilities however the fact we picked DukTape is in retrospective a pretty big mistake, its very unfortunate that we are limited by it.

[Basssiiie]

...however the fact we picked DukTape is in retrospective a pretty big mistake, its very unfortunate that we are limited by it.

We are all well aware of that. Anything feasible we could do to make it better now? 😛

[KatieZeldaKat]

I must be doing something wrong since I still see no significant difference, even when running 10 copies of the guest event plugin. I'll leave the zip here of the plugins so others can test a bit better (if needed).

multi-guest-events.zip

[github-actions]

This pull request has been marked as stale and will be closed in 14 days if no action is taken. To keep it open, leave a comment or remove the stale-pr label. If you're awaiting feedback from a developer, please send us a reminder (either here or on Discord).