Add support for driving and being a passenger in client-side vehicles, client-side vehicle damage and animated vehicle entering/exiting through new functions for client-side peds/local players

[MegadreamsBE]

Summary

This pull request makes it possible for players to drive client-side vehicles or be a passenger in them (a ped can be scripted to drive the vehicle). Similarly it also makes it possible to damage client-side vehicles.

While Multi Theft Auto always was a mod to allow multiple players to play with each other it has grown into something so much bigger. This PR gives a greater control to server owners (in the end it is up to them to either allow or not allow a player to be desynced from others).

There are enough occasions where you may require a vehicle to be in there (cutscenes for example or being flown from one airport to another in a plane) that other players do not need to see but that, if we want our player to be in there, requires us to create a server-side vehicle instead. This removes that need. Similarly allowing client-side vehicles from taking on damage from weapons and/or driving makes them more useful overall.

Fixes #1352

New features

• It is now possible to get into and drive client-side vehicles as a player.
• It is now possible to damage client-side vehicles unless this is disabled through scripting.
• Added various new functions/events for client-side peds listed below.

New functions [CLIENT-SIDE ONLY]

• getPedNearestVehicleEntryPoint(ped, checkDriverDoor, checkPassengersDoors)
  This function returns a valid entry point (number) for the nearest vehicle to the ped/player and the vehicle itself.
• getPedEnterVehicleTarget(ped)
  This function returns the vehicle together with the seat and entry point of the vehicle the ped is trying to enter.
• getVehicleEntryPoints(vehicle)
  This functions returns all entry points for a given vehicle with the entry point id (starting at 0) as the index and then the coordinates of the entry point.
• setPedEnterVehicle(ped, vehicle, seat)
  This function makes a client-side ped enter a client-side vehicle. This function also works on the local player whom can also enter server-side vehicles with it.
• setPedExitVehicle(ped)
  This function makes a client-side ped (or the local player) leave their current vehicle.
• cancelPedEnterVehicle(ped)
  This function makes a client-side ped (or the local player) stop trying to enter a vehicle.

New events [CLIENT-SIDE ONLY]

• onClientPedStartEnterVehicle - ped is the source.
  This event is triggered when a ped is starting to enter a car. It can be cancelled.
  • vehicle: the vehicle the ped is entering.
  • seat: the seat the ped will be in.
  • door: the door the ped is entering through.
  • jacking: if the ped is carjacking, the ped/local player being carjacked is stored in here.
• onClientPedStartExitVehicle - ped is the source.
  This event is triggered when a ped is starting to exit a car (or being carjacked). It can be cancelled.
  • vehicle: the vehicle the ped is entering.
  • seat: the seat the ped is in.
  • door: the door the ped is exiting through.
  • jacker: if the ped is being carjacked, the ped/local player responsible is stored in here.
• onClientPedEnterVehicle - ped is the source.
  This event is triggered when a ped has entred a car.
  • vehicle: the vehicle the ped is entering.
  • seat: the seat the ped will be in.
  • jacking: if the ped carjacked, the ped/local player that was carjacked is stored in here.
• onClientPedExitVehicle - ped is the source.
  This event is triggered when a ped has exited a car (or was carjacked).
  • vehicle: the vehicle the ped is entering.
  • seat: the seat the ped is in.
  • jacker: if the ped was carjacked, the ped/local player responsible is stored in here.

TODO

• Add support for damage to cars without requiring the player to enter the car first.
• Add support for ped jacking (client-side only)
• Add function to gracefully enter a car instead of warping (client-side only, players sync).
• Add function to check if a player or a ped is near a car that can be entered and through which door.
• Add support for "onClientVehicleStartEnter", "onClientVehicleEnter", "onClientVehicleStartExit" and "onClientVehicleExit" events.
• Add support for cancelling the entering process of a ped. - cancelPedEnterVehicle(ped)
• Add support for getting the seats you can access through a specific entry point. - getVehicleSeats(vehicle, entryPointId)
• Add support for getting all available entry points for a given vehicle. - getVehicleEntryPoints(vehicle)
• Add support for receiving the current target vehicle a ped is trying to enter. getPedEnterVehicleTarget(ped)
• Properly handle ped jacking (when you carjack from a ped), this currently does not update the status of the ped who still thinks he/she is in the car.
• Properly handle falling off a bike.
• Fix a glitch through which a ped thinks it is inside a vehicle while it is not when forced to run behind the vehicle it is trying to enter.
• Much needed code cleanup such as bringing the code up to current standards.
• Fix entry points not always being accurate.

[MegadreamsBE]

Please help by testing this PR to verify that it does not break any existing functionality and is stable. Any ideas to still be added (or existing functionality to be modified) are always welcome.

[MegadreamsBE]

Projectiles (from vehicles like rhino/hunter) have been found to still sync. This should probably be fixed before this PR gets merged. The minigun on the hunter however does not sync.

[MegadreamsBE]

I know the explosion check is not a 100% accurate but it's very close to that. The only case I know where you could make a legit explosion not sync is when you shoot a rocket into the air and within that time-span manage to get into a client-side vehicle. This requires the door to be open beforehand and is quite neglectable as the chance of this happening is so tiny.

It's still better than client-side vehicle projectile explosions syncing and until we have a better way of knowing the exact cause of a explosion this should do fine.

[qaisjp]

Nice work. What does it look like to other players when you're in a vehicle?

[MegadreamsBE]

Thanks! To other players it looks like you're sliding around (or floating if in a helicopter/plane). When using certain controls (like "fire") you may perform animations like punching on their screen. It is really up to the server owners though to prevent other players from seeing this. (Although it is funny)

[FileEX]

Now if we will use client-side vehicle as argument in triggerSeverEvent, the event don't will be triggered. This PR fix it too?

[MegadreamsBE]

No, client-side vehicles can at no point exist on the server nor on the client of another player. It wouldn't make any sense for the vehicle to be allowed as a parameter in this event. It's not a bug.

[FileEX]

Sure, but should be show info about this in debug. Because user may don't know why him code don't work and why trigger isn't triggered.

[MegadreamsBE]

Fair point, but that should be done in its own pull request. I suggest to open up an issue about this.

[MegadreamsBE]

Also tested states in which the ped is blocked from getting into the vehicle or getting out. Both acted the way it should, when a ped tries to get into a vehicle but is unable to the ped keeps on trying (and if you're driving - following the car).

When exiting the game teleports out the ped if it's blocked from stepping out (can be prevented using the events by the scripters).

Perhaps a future PR could still add setPedCancelEnterVehicle or setPedCancelExitVehicle or something, but setPedAnimation may also interrupt this (yet to be tested).

[MegadreamsBE]

Using setPedAnimation it is indeed possible to cancel out trying to enter the vehicle IF you first set an actual animation and cancel out of that. This however makes the ped still believe it is trying to get in and setPedExitVehicle needs to be called after that to return things back to normal.

Either a setPedCancelEnterVehicle should be implemented or setPedAnimation should automatically cancel the entering of a vehicle and restore its state properly (recommended).

I also found a glitch that can be reproduced as follows:

1. Get in a client-side vehicle.
2. Use setPedEnterVehicle on a client-side vehicle.
3. When the ped opens the door and is about to get in drive backwards AND turn steeply.
4. The ped has abandoned getting in but actually believes it is inside the vehicle.

Will need to address this.

[MegadreamsBE]

The entry points given in the events and when checking your target vehicle are not always 100% accurate, that's due to limitations at this stage. Once again, I will look into this when I add entry point/door support to setPedEnterVehicle in a separate PR, for now they're more of a guidance.

[MegadreamsBE]

Will continue my research in the ability to force a ped to use a specific door very soon. It will likely require partially rewriting the logic behind the task that handles this.

[MegadreamsBE]

Dropping the functionality that allows you to specify what door you want a NPC or player to use for now. This will be in a different PR. The methods getVehicleEntryPoints and getVehicleSeats will still be made available so that it's possible to manipulate what door will be used using scripts for the time being (ex. making the NPC first walk to the entry point before triggering the setPedEnterVehicle method).

[MegadreamsBE]

PR #1748 introduces setPedEnterVehicle client-side which is different from the setPedEnterVehicle introduced in this PR:
setPedEnterVehicle(ped, [, vehicle = nil, seat = 0 ])
vs
setPedEnterVehicle(ped [, vehicle = nil, passenger = false ])

In which seat is numerical in my PR (as there is one driver seat but multiple passenger seats to choose from) whereas the mentioned PR prefers using a bool which does not give that same control. A solution for this conflict should be found. However I do not see the point of downgrading my function in favor of the one introduced in that PR.

[qaisjp]

However I do not see the point of downgrading my function in favor of the one introduced in that PR

I agree yours is more powerful.

However, we can change the API later as both of these will be merged into the same version of MTA.

What do you think about overloading here?

[MegadreamsBE]

What do you think about overloading here?

Works for me.

[MegadreamsBE]

Since I can't really seem to push this PR forwards I might just split up parts of it and introduce them as their own PRs.

[MegadreamsBE]

Although... I had forgotten I had dropped support for telling a ped to go to a specific seat. Can someone just give me a kick or something so I finally finish this PR?

[github-actions]

This draft pull request is stale because it has been open for at least 90 days with no activity. Please continue on your draft pull request or it will be closed in 30 days automatically.

[github-actions]

This draft pull request was closed because it has been marked stale for 30 days with no activity.