From 39d220ddcbc33554e8900046585559717d4c3ce1 Mon Sep 17 00:00:00 2001 From: Dan Date: Mon, 30 Dec 2024 23:43:33 +0300 Subject: [PATCH 01/15] added docs for actor.py --- pysamp/actor.py | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/pysamp/actor.py b/pysamp/actor.py index 7df122d..d6dd62a 100644 --- a/pysamp/actor.py +++ b/pysamp/actor.py @@ -140,11 +140,31 @@ def is_valid(self) -> bool: return is_valid_actor(self.id) @event("OnActorStreamIn") - def on_stream_in(cls, actorid: int, forplayerid: int): - return (cls(actorid), Player(forplayerid)) + def on_stream_in(cls, actor_id: int, for_player_id: int): + """This event is called when an actor is streamed in by a player's \ + client. + + :param int actor_id: The ID of the actor. + :param int for_player_id: The ID of the player that streamed the \ + actor in. + :returns: No return value. + + .. note:: This event can also be called by NPC. + """ + return (cls(actor_id), Player(for_player_id)) @event("OnActorStreamOut") - def on_stream_out(cls, actorid: int, forplayerid: int): - return (cls(actorid), Player(forplayerid)) + def on_stream_out(cls, actor_id: int, for_player_id: int): + """This event is called when an actor is streamed out by a \ + player's client. + + :param int actor_id: The ID of the actor. + :param int for_player_id: The ID of the player that streamed the \ + actor out. + :returns: No return value. + + .. note:: This event can also be called by NPC. + """ + return (cls(actor_id), Player(for_player_id)) from pysamp.player import Player # noqa \ No newline at end of file From d9e7db7a1f9e104c708f5c4f08d261335f36da66 Mon Sep 17 00:00:00 2001 From: Dan Date: Mon, 30 Dec 2024 23:43:45 +0300 Subject: [PATCH 02/15] added docs for object.py --- pysamp/object.py | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/pysamp/object.py b/pysamp/object.py index 3353118..e98ad2e 100644 --- a/pysamp/object.py +++ b/pysamp/object.py @@ -239,5 +239,14 @@ def set_default_camera_col(disable: bool) -> bool: return set_objects_default_camera_col(disable) @event("OnObjectMoved") - def on_moved(cls, objectid: int): - return (cls(objectid),) + def on_moved(cls, object_id: int): + """This event is called when an object stops moving after \ + :meth:`Object.move()`. + + :param int object_id: The ID of the object that was moved. + :returns: No return value. + + .. note:: :meth:`set_position` does not work when used in this \ + event. To fix it, recreate the object. + """ + return (cls(object_id),) From e11ee88984f25377e6552de3ad969ba49d8b6c98 Mon Sep 17 00:00:00 2001 From: Dan Date: Mon, 30 Dec 2024 23:43:55 +0300 Subject: [PATCH 03/15] added docs for playerobject.py --- pysamp/playerobject.py | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/pysamp/playerobject.py b/pysamp/playerobject.py index c06d5fc..772304e 100644 --- a/pysamp/playerobject.py +++ b/pysamp/playerobject.py @@ -390,8 +390,15 @@ def set_material( ) @event("OnPlayerObjectMoved") - def on_moved(cls, playerid: int, objectid: int): - return (cls(objectid, playerid), Player(playerid)) + def on_moved(cls, player_id: int, object_id: int): + """This event is called when a player object is moved after \ + :meth:`PlayerObject.move()` (when it stops moving). + + :param int player_id: The player id the object is assigned to. + :param int object_id: The ID of the player object that was moved. + :returns: No return value. + """ + return (cls(object_id, player_id), Player(object_id)) from pysamp.player import Player # noqa from pysamp.vehicle import Vehicle # noqa From 8410d1869a6a3e2344286cdf9fe3aeaf8299c659 Mon Sep 17 00:00:00 2001 From: Dan Date: Mon, 30 Dec 2024 23:44:05 +0300 Subject: [PATCH 04/15] added docs for vehicle.py --- pysamp/vehicle.py | 141 ++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 123 insertions(+), 18 deletions(-) diff --git a/pysamp/vehicle.py b/pysamp/vehicle.py index 1b14ddd..6668f1d 100644 --- a/pysamp/vehicle.py +++ b/pysamp/vehicle.py @@ -358,44 +358,149 @@ def set_virtual_world(self, world_id: int) -> bool: return set_vehicle_virtual_world(self.id, world_id) @event("OnTrailerUpdate") - def on_trailer_update(cls, playerid: int, trailerid: int): - return (Player(playerid), cls(trailerid)) + def on_trailer_update(cls, player_id: int, trailer_id: int): + """This event is called when the player sent a trailer update. + + :param int player_id: The ID of the player who sent a trailer update. + :param int trailer_id: The trailer being updated. + :returns: No return value. + + .. warning:: + This event is called very frequently per second per trailer. + You should refrain from implementing intensive calculations \ + or intensive file writing/reading operations in this event. + """ + return (Player(player_id), cls(trailer_id)) @event("OnVehicleDamageStatusUpdate") - def on_damage_status_update(cls, vehicleid: int, playerid: int): - return (cls(vehicleid), Player(playerid)) + def on_damage_status_update(cls, vehicle_id: int, player_id: int): + """This event is called when a vehicle element such as \ + doors, tyres, panels, or lights change their damage status. + + :param int vehicle_id: The ID of the vehicle that was changed \ + its damage status. + :param int player_id: The ID of the player who synced the change in \ + the damage status (who had the car damaged or repaired) + :returns: No return value. + + .. note:: This does not include vehicle health changes. + """ + return (cls(vehicle_id), Player(player_id)) @event("OnVehicleDeath") - def on_death(cls, vehicleid: int, killerid: int): + def on_death(cls, vehicle_id: int, killer_id: int): + """This event is called when a vehicle is destroyed - either by \ + exploding or becoming submerged in water. + + :param int vehicle_id: The ID of the vehicle that was destroyed. + :param int killer_id: The ID of the player that reported the \ + vehicle's destruction (name is misleading). Generally the driver or \ + a passenger (if any) or the closest player. + :returns: No return value. + + .. note:: + This event will also be called when a vehicle enters water, but \ + the vehicle can be saved by teleportation or driving out. + The event won't be called a second time,\ + and the vehicle may disappear when the driver exits, or after a short time. + """ return ( - cls(vehicleid), - Player(killerid) if killerid != INVALID_PLAYER_ID else killerid, + cls(vehicle_id), + Player(vehicle_id) if killer_id != INVALID_PLAYER_ID else killer_id, ) @event("OnVehicleMod") - def on_mod(cls, playerid: int, vehicleid: int, componentid: int): - return (Player(playerid), cls(vehicleid), componentid) + def on_mod(cls, player_id: int, vehicle_id: int, component_id: int): + """This event is called when a vehicle is modded. + + :param int player_id: The ID of the driver of the vehicle. + :param int vehicle_id: The ID of the vehicle which is modded. + :param int component_id: The ID of the component which was added to \ + the vehicle. + :returns: No return value. + + .. note:: This event is NOT called by :meth:`Vehicle.add_component()`. + """ + return (Player(player_id), cls(vehicle_id), component_id) @event("OnVehiclePaintjob") - def on_paintjob(cls, playerid: int, vehicleid: int, paintjobid: int): - return (Player(playerid), cls(vehicleid), paintjobid) + def on_paintjob(cls, player_id: int, vehicle_id: int, paintjob_id: int): + """This event is called when a player previews a vehicle paintjob \ + inside a mod shop. + Watch out, this event is NOT called when the player buys the paintjob. + + :param int player_id: The ID of the player that changed the paintjob \ + of their vehicle. + :param int vehicle_id: The ID of the vehicle that had its \ + paintjob changed. + :param int paintjob_id: The ID of the new paintjob. + :returns: No return value. + + .. note:: This event isn't called by :meth:`Vehicle.change_paintjob()`. + """ + return (Player(player_id), cls(vehicle_id), paintjob_id) @event("OnVehicleRespray") def on_respray( - cls, playerid: int, vehicleid: int, color1: int, color2: int + cls, player_id: int, vehicle_id: int, color1: int, color2: int ): - return (Player(playerid), cls(vehicleid), color1, color2) + """This event is called when a player exits a mod shop, even if the \ + colors weren't changed. + + Watch out, the name is ambiguous, Pay 'n' Spray shops don't call \ + this event. + + :param int player_id: The ID of the player that is driving the vehicle. + :param int vehicle_id: The ID of the vehicle that was resprayed. + :param int color1: The color that the vehicle's primary color \ + was changed to. + :param int color2: The color that the vehicle's secondary color \ + was changed to. + :returns: No return value. + + .. note:: + This event is not called by :meth:`Vehicle.change_color()`. + Misleadingly, this event is not called for pay 'n' spray. + + .. warning:: + Known Bug(s): previewing a component inside a mod shop might call \ + this event. + """ + return (Player(player_id), cls(vehicle_id), color1, color2) @event("OnVehicleSirenStateChange") def on_siren_state_change( - cls, playerid: int, vehicleid: int, newstate: int + cls, player_id: int, vehicle_id: int, new_state: int ): - return (Player(playerid), cls(vehicleid), newstate) + """This event is called when a vehicle's siren is toggled. + + :param int player_id: The ID of the player that toggled the \ + siren (driver). + :param int vehicle_id: The ID of the vehicle of which the siren was \ + toggled for. + :param int new_state: ``0`` if siren was turned off, ``1`` if siren \ + was turned on. + :returns: No return value. + + .. note:: + This event is only called when a vehicle's siren is on or off, + NOT when the alternate siren is in use (holding horn). + """ + return (Player(player_id), cls(vehicle_id), new_state) @event("OnVehicleSpawn") - def on_spawn(cls, vehicleid: int): - """When a vehicle is respawning only.""" - return (cls(vehicleid),) + def on_spawn(cls, vehicle_id: int): + """This event is called when a vehicle respawns. + + :param int vehicle_id: The ID of the vehicle that spawned. + :returns: No return value. + + .. warning:: + This event is called only when vehicle respawns! + :meth:`Vehicle.create()` and :meth:`add_static_vehicle/ex` won't \ + trigger this event. + """ + return (cls(vehicle_id),) @event("OnVehicleStreamIn") def on_stream_in(cls, vehicleid: int, forplayerid: int): From 0cc094c4308826595087f8b8a5d249c0243e5efe Mon Sep 17 00:00:00 2001 From: Dan Date: Mon, 30 Dec 2024 23:50:15 +0300 Subject: [PATCH 05/15] added missing docs for vehicle.py --- pysamp/vehicle.py | 76 ++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 68 insertions(+), 8 deletions(-) diff --git a/pysamp/vehicle.py b/pysamp/vehicle.py index 6668f1d..7890318 100644 --- a/pysamp/vehicle.py +++ b/pysamp/vehicle.py @@ -503,18 +503,35 @@ def on_spawn(cls, vehicle_id: int): return (cls(vehicle_id),) @event("OnVehicleStreamIn") - def on_stream_in(cls, vehicleid: int, forplayerid: int): - return (cls(vehicleid), Player(forplayerid)) + def on_stream_in(cls, vehicle_id: int, for_player_id: int): + """This event is called when a vehicle is streamed for a \ + player's client. + + :param int vehicle_id: The ID of the vehicle that streamed in \ + for the player. + :param int for_player_id: The ID of the player who the vehicle \ + streamed in for. + :returns: No return value. + """ + return (cls(vehicle_id), Player(for_player_id)) @event("OnVehicleStreamOut") - def on_stream_out(cls, vehicleid: int, forplayerid: int): - return (cls(vehicleid), Player(forplayerid)) + def on_stream_out(cls, vehicle_id: int, for_player_id: int): + """This event is called when a vehicle is streamed out for a \ + player's client + + :param int vehicle_id: The ID of the vehicle that streamed out. + :param int for_player_id: The ID of the player who is no longer \ + streaming the vehicle. + :returns: No return value. + """ + return (cls(vehicle_id), Player(for_player_id)) @event("OnUnoccupiedVehicleUpdate") def on_unoccupied_update( cls, - vehicleid: int, - playerid: int, + vehicle_id: int, + player_id: int, passenger_seat: int, new_x: float, new_y: float, @@ -523,9 +540,52 @@ def on_unoccupied_update( vel_y: float, vel_z: float, ): + """This event is called when a player's client updates / syncs the \ + position of a vehicle they're not driving. + This can happen outside of the vehicle or when the player is a \ + passenger of a vehicle that has no driver. + + :param int vehicle_id: The ID of the vehicle that's position \ + was updated. + :param int player_id: The ID of the player that sent a vehicle \ + position sync update. + :param int passenget_seat: The ID of the seat if the player \ + is a passenger. + :param float new_x: The new X coordinate of the vehicle. + :param float new_y: The new Y coordinate of the vehicle. + :param float new_z: The new Z coordinate of the vehicle. + :param float vel_x: The new X velocity of the vehicle. + :param float vel_y: The new Y velocity of the vehicle. + :param float vel_z: The new Z velocity of the vehicle. + :returns: No return value. + + .. list-table:: Seats + :header-rows: 1 + + * - ID + - Definition + * - 0 + - Not in vehicle + * - 1 + - Front passenger + * - 2 + - Backleft + * - 3 + - Backright + * - 4+ + - Coach/Bus etc. + + .. warning:: + This event is called very frequently per second per \ + unoccupied vehicle. + You should refrain from implementing intensive calculations or \ + intensive file writing/reading operations in this event. + :meth:`Vehicle.get_pos()` will return the old coordinates of \ + the vehicle before this update. + """ return ( - cls(vehicleid), - Player(playerid), + cls(vehicle_id), + Player(player_id), passenger_seat, new_x, new_y, From bdb04cc0679ea362481ab3ca230a8f4fb8d03603 Mon Sep 17 00:00:00 2001 From: Dan Date: Mon, 30 Dec 2024 23:50:23 +0300 Subject: [PATCH 06/15] fixed missing EOL --- pysamp/actor.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pysamp/actor.py b/pysamp/actor.py index d6dd62a..8c3d7dd 100644 --- a/pysamp/actor.py +++ b/pysamp/actor.py @@ -167,4 +167,4 @@ def on_stream_out(cls, actor_id: int, for_player_id: int): """ return (cls(actor_id), Player(for_player_id)) -from pysamp.player import Player # noqa \ No newline at end of file +from pysamp.player import Player # noqa From f09e8ec2834fe530d2ab4e8ca2cacb89684805e5 Mon Sep 17 00:00:00 2001 From: Dan Date: Tue, 31 Dec 2024 01:00:20 +0300 Subject: [PATCH 07/15] added docs for player.py --- pysamp/player.py | 785 ++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 676 insertions(+), 109 deletions(-) diff --git a/pysamp/player.py b/pysamp/player.py index d21eb1d..528b50c 100644 --- a/pysamp/player.py +++ b/pysamp/player.py @@ -1826,7 +1826,7 @@ def allow_teleport(self, allow: bool) -> bool: :return: Nothing. .. warning:: Deprecated since 0.3d. - Please use the callback ``player.on_click_map`` instead. + Please use the event ``player.on_click_map`` instead. """ return allow_player_teleport(self.id, allow) @@ -2433,189 +2433,626 @@ def attach_camera_to_player_object( @event("OnEnterExitModShop") def on_enter_exit_mod_shop( - cls, playerid: int, enterexit: int, interiorid: int + cls, player_id: int, enter_exit: int, interior_id: int ): - return (cls(playerid), enterexit, interiorid) + """This event is called when a player enters or exits a mod shop. + + :param int player_id: The ID of the player that entered /exited \ + the modshop. + :param int enter_exit: ``1`` if the player entered or ``0`` if exited. + :param int interior_id: The interior ID of the modshop that \ + the player is entering (or ``0`` if exiting). + :returns: No return value. + + .. warning:: Players collide when they get into the same mod shop. + """ + return (cls(player_id), enter_exit, interior_id) @event("OnPlayerConnect") - def on_connect(cls, playerid: int): - return (cls(playerid),) + def on_connect(cls, player_id: int): + """This event is called when a player connects to the server. + + :param int player_id: The ID of the player that connected. + :returns: No return value. + + ..note:: This event can also be called by NPC. + """ + return (cls(player_id),) @event("OnPlayerDisconnect") - def on_disconnect(cls, playerid: int, reason: int): - return (cls(playerid), reason) + def on_disconnect(cls, player_id: int, reason: int): + """This event is called when a player disconnects from the server. + + :param int player_id: The ID of the player that disconnected. + :param int reason: The reason for the disconnection. + :returns: No return value. + + .. list-table:: Reasons for the disconnecting + :header-rows: 1 + + * - ID + - Reason + - Description + * - 0 + - Timeout/Crash + - The player's connection was lost. \ + Either their game crashed or their network had a fault. + * - 1 + - Quit + - The player purposefully quit, either using the /quit (/q) \ + command or via the pause menu. + * - 2 + - Kick/Ban + - The player was kicked or banned by the server. + * - 3 + - Custom + - Used by some libraries. Reserved for modes' private uses. + * - 4 + - Mode End + - The current mode is ending so disconnecting all players from \ + it (they are still on the server). + + .. warning:: Reasons 3 and 4 were added by the open.mp server. + """ + return (cls(player_id), reason) @event("OnPlayerSpawn") - def on_spawn(cls, playerid: int): - return (cls(playerid),) + def on_spawn(cls, player_id: int): + """This event is called when a player spawns. + (i.e. after caling :meth:`Player.spawn()`) + + :param int player_id: The ID of the player that spawned. + :returns: No return value. + + .. note:: The game sometimes deducts $100 from players after spawn. + """ + return (cls(player_id),) @event("OnPlayerDeath") - def on_death(cls, playerid: int, killerid: int, reason: int): + def on_death(cls, player_id: int, killer_id: int, reason: int): + """This event is called when a player dies. + + :param int player_id: The ID of the player that died. + :param int killer_id: The ID of the player that killed the player who \ + died, or ``INVALID_PLAYER_ID`` if there was none. + :param int reason: The ID of the reason (weapon id) for the \ + player's death. + :returns: No return value. + + Weapon IDs: https://www.open.mp/docs/scripting/resources/weapon_ids + + .. note:: The reason will return 37 from any fire sources. + The reason will return 51 from any weapon that creates an \ + explosion (e.g. RPG, grenade). + You do not need to check whether killer_id is valid before using \ + it in :meth:`Player.send_death_message()`. + ``INVALID_PLAYER_ID`` is a valid killer_id ID parameter in that \ + function. + player_id is the only one who can call the event. \ + (good to know for anti fake death) + + .. warning:: You MUST check whether ``killer_id`` is valid \ + (not ``INVALID_PLAYER_ID``) before using it anywhere. + """ return ( - cls(playerid), - killerid if killerid == INVALID_PLAYER_ID else cls(killerid), + cls(player_id), + killer_id if killer_id == INVALID_PLAYER_ID else cls(killer_id), reason, ) @event("OnPlayerText") - def on_text(cls, playerid: int, text: str): - return (cls(playerid), text) + def on_text(cls, player_id: int, text: str): + """This event is called when a player sends a chat message. + + :param int player_id: The ID of the player who typed the text. + :param str text: The text the player typed. + :returns: No return value. + + .. note:: This event can also be called by NPC. + + Example: + + .. code-block:: python + + @Player.on_text + def on_player_text(player: Player, text: str): + send_client_message_to_all(-1, f"[Text] {text}") + return False # Ignore the default text and send the custom one. + """ + return (cls(player_id), text) @event("OnPlayerCommandText") - def on_command_text(cls, playerid: int, command_text: str): - return (cls(playerid), command_text) + def on_command_text(cls, player_id: int, command_text: str): + """This event is called when a player enters a command into the \ + client chat window. + + Commands are anything that start with a forward slash, e.g. /help. + + :param int player_id: The ID of the player that entered a command. + :param str command_text: The command that was entered \ + (including the forward slash). + :returns: No return value. + + .. note:: This event can also be called by NPC. + + Example: + + .. code-block:: python + + @Player.on_command_text + def on_player_command_text(player: Player, cmdtext: str): + if cmdtext == "/help": + return player.send_client_message( + -1, "SERVER: This is the /help command!" + ) + """ + return (cls(player_id), command_text) @event("OnPlayerRequestClass") - def on_request_class(cls, playerid: int, classid: int): - return (cls(playerid), classid) + def on_request_class(cls, player_id: int, class_id: int): + """This event is called when a player changes class at class selection + (and when class selection first appears). + + :param int player_id: The ID of the player that changed class. + :param int class_id: The ID of the current class being viewed + (returned by :meth:`add_player_class`). + :returns: No return value. + + .. note:: This event is also called when a player presses F4. + """ + return (cls(player_id), class_id) @event("OnPlayerEnterVehicle") def on_enter_vehicle( cls, - playerid: int, - vehicleid: int, + player_id: int, + vehicle_id: int, is_passenger: bool, ): - return (cls(playerid), Vehicle(vehicleid), is_passenger) + """This event is called when a player starts to enter a vehicle, \ + meaning the player is not in vehicle yet at the time this event \ + is called. + + :param int player_id: ID of the player who attempts to enter a vehicle. + :param int vehicle_id: ID of the vehicle the player is attempting \ + to enter. + :param bool is_passenger: ``False`` if entering as driver. ``True`` \ + if entering as passenger. + :returns: No return value. + + .. note:: This event is called when a player BEGINS to enter a vehicle, + not when they HAVE entered it. See :meth:`Player.on_state_change`. + This event is still called if the player is denied entry \ + to the vehicle (e.g. it is locked or full). + """ + return (cls(player_id), Vehicle(vehicle_id), is_passenger) @event("OnPlayerExitVehicle") - def on_exit_vehicle(cls, playerid: int, vehicleid: int): - return (cls(playerid), Vehicle(vehicleid)) + def on_exit_vehicle(cls, player_id: int, vehicle_id: int): + """This event is called when a player starts to exit a vehicle. + + :param int player_id: The ID of the player that is exiting a vehicle. + :param int vehicle_id: The ID of the vehicle the player is exiting. + :returns: No return value. + + .. warning:: Not called if the player falls off a bike or is \ + removed from a vehicle + by other means such as using :meth:`Player.set_pos()`. + You must use :meth:`Player.on_state_change` and check if their \ + old state is ``PLAYER_STATE_DRIVER`` or ``PLAYER_STATE_PASSENGER``\ + and their new state is ``PLAYER_STATE_ONFOOT``. + """ + return (cls(player_id), Vehicle(vehicle_id)) @event("OnPlayerStateChange") - def on_state_change(cls, playerid, newstate: int, oldstate: int): - return (cls(playerid), newstate, oldstate) + def on_state_change(cls, player_id, new_state: int, old_state: int): + """This event is called when a player changes state. + + For example, when a player changes from being the driver of a vehicle \ + to being on-foot. + + :param int player_id: The ID of the player that changed state. + :param int new_state: The player's new state. + :param int old_state: The player's previous state. + :returns: No return value. + + List of all available player states: \ + https://www.open.mp/docs/scripting/resources/playerstates + + .. note:: This event can also be called by NPC. + """ + return (cls(player_id), new_state, old_state) @event("OnPlayerEnterCheckpoint") - def on_enter_checkpoint(cls, playerid: int): - return (cls(playerid),) + def on_enter_checkpoint(cls, player_id: int): + """This event is called when a player enters the checkpoint set for \ + that player. + + :param int player_id: The player who entered the checkpoint. + :returns: No return value. + + .. note:: This event can also be called by NPC. + """ + return (cls(player_id),) @event("OnPlayerLeaveCheckpoint") - def on_leave_checkpoint(cls, playerid: int): - return (cls(playerid),) + def on_leave_checkpoint(cls, player_id: int): + """This event is called when a player leaves the checkpoint set for \ + him by :meth:`Player.set_checkpoint()`. + + Only one checkpoint can be set at a time. + + :param int player_id: The ID of the player that left their checkpoint. + :returns: No return value. + + .. note:: This event can also be called by NPC. + """ + return (cls(player_id),) @event("OnPlayerEnterRaceCheckpoint") - def on_enter_race_checkpoint(cls, playerid: int): - return (cls(playerid),) + def on_enter_race_checkpoint(cls, player_id: int): + """This event is called when a player enters a race checkpoint. + + :param int player_id: The ID of the player who entered the checkpoint. + :returns: No return value. + + .. note:: This event can also be called by NPC. + """ + return (cls(player_id),) @event("OnPlayerLeaveRaceCheckpoint") - def on_leave_race_checkpoint(cls, playerid: int): - return (cls(playerid),) + def on_leave_race_checkpoint(cls, player_id: int): + """This event is called when a player leaves the race checkpoint. + + :param int player_id: The ID of the player that left the checkpoint. + :returns: No return value. + + .. note:: This event can also be called by NPC. + """ + return (cls(player_id),) @event("OnPlayerRequestSpawn") - def on_request_spawn(cls, playerid: int): - return (cls(playerid),) + def on_request_spawn(cls, player_id: int): + """This event is called when a player attempts to spawn via class \ + selection either by pressing SHIFT or clicking the 'Spawn' button. + + :param int player_id: The ID of the player that requested to spawn. + :returns: No return value. + + .. note:: This event can also be called by NPC. + """ + return (cls(player_id),) @event("OnPlayerPickUpPickup") - def on_pick_up_pickup(cls, playerid, pickupid: int): - return (cls(playerid), Pickup(pickupid)) + def on_pick_up_pickup(cls, player_id, pickup_id: int): + """This event is called when a player picks up a pickup created \ + with :meth:`Pickup.create()`. + + :param int player_id: The ID of the player that picked up the pickup. + :param int pickup_id: The ID of the pickup, returned \ + by :meth:`Pickup.create()`. + :returns: No return value. + """ + return (cls(player_id), Pickup(pickup_id)) @event("OnPlayerSelectedMenuRow") - def on_selected_menu_row(cls, playerid: int, row: int): - return (cls(playerid), row) + def on_selected_menu_row(cls, player_id: int, row: int): + """This event is called when a player selects an item from a menu. + + :param int player_id: The ID of the player that selected a menu item. + :param int row: The ID of the row that was selected. \ + The first row is ID 0. + :returns: No return value. + + .. note:: The menu ID is not passed to this event. \ + :meth:`Menu.get_player_menu()` must be used to determine which menu \ + the player selected an item on. + """ + return (cls(player_id), row) @event("OnPlayerExitedMenu") - def on_exited_menu(cls, playerid: int): - return (cls(playerid),) + def on_exited_menu(cls, player_id: int): + """This event is called when a player exits a menu. + + :param int player_id: The ID of the player that exited the menu. + :returns: No return value. + """ + return (cls(player_id),) @event("OnPlayerInteriorChange") def on_interior_change( cls, - playerid: int, - newinteriorid: int, - oldinteriorid: int, + player_id: int, + new_interior_id: int, + old_interior_id: int, ): - return (cls(playerid), newinteriorid, oldinteriorid) + """This event is called when a player changes interior. \ + Can be triggered by :meth:`Player.set_interior()` or when a player \ + enter / exits a building. + + :param int player_id: The player_id who changed interior. + :param int new_interior_id: The interior the player is now in. + :param int old_interior_id: The interior the player was in before. + :returns: No return value. + """ + return (cls(player_id), new_interior_id, old_interior_id) @event("OnPlayerKeyStateChange") - def on_key_state_change(cls, playerid: int, newkeys: int, oldkeys: int): - return (cls(playerid), newkeys, oldkeys) + def on_key_state_change(cls, player_id: int, new_keys: int, old_keys: int): + """This event is called when the state of any supported key is \ + changed (pressed/released). + + Directional keys do not trigger this event (up/down/left/right). + + :param int player_id: The ID of the player that \ + pressed or released a key. + :param int new_interior_id: A map (bitmask) of the keys currently held. + :param int old_interior_id: A map (bitmask) of the keys held prior to \ + the current change. + :returns: No return value. + + List of keys: https://www.open.mp/docs/scripting/resources/keys + + .. note:: This event can also be called by NPC. + """ + return (cls(player_id), new_keys, old_keys) @event("OnPlayerUpdate") - def on_update(cls, playerid: int): - return (cls(playerid),) + def on_update(cls, player_id: int): + """This event is called every time a client / player updates the \ + server with their status. It is often used to create custom events \ + for client updates that aren't actively tracked by the server, \ + such as health or armor updates or players switching weapons. + + :param int player_id: ID of the player sending an update packet. + :returns: No return value. + + .. note:: This event can also be called by NPC. + + .. warning:: + This event is called, on average, 30 times per second, per player. + Only use it when you know what it's meant for. + The frequency with which this event is called for \ + each player varies, depending on what the player is doing. \ + Driving or shooting will trigger a lot more updates than idling. + """ + return (cls(player_id),) @event("OnPlayerStreamIn") - def on_stream_in(cls, playerid: int, forplayerid: int): - return (cls(playerid), cls(forplayerid)) + def on_stream_in(cls, player_id: int, for_player_id: int): + """This event is called when a player is streamed by \ + some other player's client. + + :param int player_id: The ID of the player who has been streamed. + :param int for_player_id: The ID of the player that streamed the \ + other player in. + :returns: No return value. + + .. note:: This event can also be called by NPC. + """ + return (cls(player_id), cls(for_player_id)) @event("OnPlayerStreamOut") - def on_stream_out(cls, playerid: int, forplayerid: int): - return (cls(playerid), cls(forplayerid)) + def on_stream_out(cls, player_id: int, for_player_id: int): + """This event is called when a player is streamed \ + out from some other player's client. + + :param int player_id: The player who has been destreamed. + :param int for_player_id: The player who has destreamed the \ + other player. + :returns: No return value. + + .. note:: This event can also be called by NPC. + + .. warning:: + The event is not called for both players when a player disconnects. + """ + return (cls(player_id), cls(for_player_id)) @event("OnPlayerTakeDamage") def on_take_damage( cls, - playerid: int, - issuerid: int, + player_id: int, + issuer_id: int, amount: float, - weaponid: int, - bodypart: int, + weapon_id: int, + body_part: int, ): + """This event is called when a player takes damage. + + :param int player_id: The ID of the player that took damage. + :param int issuer_id: The ID of the player that caused the damage. \ + ``INVALID_PLAYER_ID`` if self-inflicted. + :param float amount: The amount of damage the player took \ + (health and armour combined). + :param int weapon_id: The ID of the weapon/reason for the damage. + :param int body_part: The body part that was hit. + :returns: No return value. + + Body parts: https://www.open.mp/docs/scripting/resources/bodyparts + + .. note:: + - The weapon_id will return 37 (flame thrower) from any \ + fire sources (e.g. molotov, 18). + - The weapon_id will return 51 from any weapon that creates an \ + explosion (e.g. RPG, grenade). + - player_id is the only one who can call the event. + - The amount is always the maximum damage the weaponid can do, \ + even when the health left is less than that maximum damage. + So when a player has 100.0 health and gets shot with a \ + Desert Eagle which has a damage value of 46.2, it takes 3 shots \ + to kill that player. All 3 shots will show an amount of 46.2, \ + even though when the last shot hits, the player only has \ + 7.6 health left. + + .. warning:: + - :meth:`Player.get_health()` and :meth:`Player.get_armour()` \ + will return the old amounts of the player before this event. + - Always check if issuer_id is valid before. + """ return ( - cls(playerid), - issuerid if issuerid == INVALID_PLAYER_ID else cls(issuerid), + cls(player_id), + issuer_id if issuer_id == INVALID_PLAYER_ID else cls(issuer_id), amount, - weaponid, - bodypart, + weapon_id, + body_part, ) @event("OnPlayerGiveDamage") def on_give_damage( cls, - playerid: int, - damagedid: int, + player_id: int, + damaged_id: int, amount: float, - weaponid: int, - bodypart: int, + weapon_id: int, + body_part: int, ): + """This event is called when a player gives damage to another player. + + :param int player_id: The ID of the player that gave damage. + :param int damaged_id: The ID of the player that received damage. + :param float amount: The amount of health / armour damaged_id has \ + lost (combined). + :param int weapon_id: The reason that caused the damage. + :param int body_part: The body part that was hit. + :returns: No return value. + + Body parts: https://www.open.mp/docs/scripting/resources/bodyparts + + .. note:: + - Keep in mind this function can be inaccurate in some cases. + - If you want to prevent certain players from damaging eachother, \ + use :meth:`Player.set_team()`. + - The weapon_id will return 37 (flame thrower) from any \ + fire sources (e.g. molotov, 18). + - The weapon_id will return 51 from any weapon that creates an \ + explosion (e.g. RPG, grenade). + - player_id is the only one who can call the event. + - The amount is always the maximum damage the weaponid can do, \ + even when the health left is less than that maximum damage. + So when a player has 100.0 health and gets shot with a \ + Desert Eagle which has a damage value of 46.2, it takes 3 shots \ + to kill that player. All 3 shots will show an amount of 46.2, \ + even though when the last shot hits, the player only has \ + 7.6 health left. + """ return ( - cls(playerid), - damagedid if damagedid == INVALID_PLAYER_ID else cls(damagedid), + cls(player_id), + damaged_id if damaged_id == INVALID_PLAYER_ID else cls(damaged_id), amount, - weaponid, - bodypart, + weapon_id, + body_part, ) @event("OnPlayerGiveDamageActor") def on_give_damage_actor( cls, - playerid: int, - damaged_actorid: int, + player_id: int, + damaged_actor_id: int, amount: float, - weaponid: int, - bodypart: int, + weapon_id: int, + body_part: int, ): + """This event is called when a player gives damage to an actor. + + :param int player_id: The ID of the player that gave damage. + :param int damaged_actor_id: The ID of the actor that received damage + :param float amount: The amount of health / armour actor has lost. + :param int weapon_id: The reason that caused the damage. + :param int body_part: The body part that was hit + :returns: No return value. + + Body parts: https://www.open.mp/docs/scripting/resources/bodyparts + + .. note:: + This event does not get called if the actor is set invulnerable \ + (WHICH IS BY DEFAULT). See :meth:`Actor.set_invulnerable()`. + """ return ( - cls(playerid), - Actor(damaged_actorid), + cls(player_id), + Actor(damaged_actor_id), amount, - weaponid, - bodypart, + weapon_id, + body_part, ) @event("OnPlayerClickMap") - def on_click_map(cls, playerid: int, x: float, y: float, z: float): - return (cls(playerid), x, y, z) + def on_click_map(cls, player_id: int, x: float, y: float, z: float): + """This event is called when a player places a target/waypoint \ + on the pause menu map (by right-clicking). + + :param int player_id: The ID of the player that placed a \ + target / waypoint. + :param float x: The X float coordinate where the player clicked. + :param float y: The Y float coordinate where the player clicked. + :param float z: The Z float coordinate where the player clicked. + :returns: No return value. + """ + return (cls(player_id), x, y, z) @event("OnPlayerClickTextDraw") - def on_click_textdraw(cls, playerid: int, clickedid: int): - return (cls(playerid), TextDraw(clickedid)) + def on_click_textdraw(cls, player_id: int, clicked_id: int): + """This event is called when a player clicks on a textdraw \ + or cancels the select mode with the Escape key. + + :param int player_id: The ID of the player clicked on the textdraw. + :param int clicked_id: The ID of the clicked textdraw. \ + ``INVALID_TEXT_DRAW`` if selection was cancelled. + :returns: No return value. + + .. warning:: + The clickable area is defined by :meth:`TextDraw.text_size()`. + The x and y parameters passed to that function \ + must not be zero or negative. + Do not use :meth:`TextDraw.cancel_select()` unconditionally \ + within this event. This results in an infinite loop. + """ + return (cls(player_id), TextDraw(clicked_id)) @event("OnPlayerClickPlayerTextDraw") - def on_click_playertextdraw(cls, playerid: int, playertextid: int): - return (cls(playerid), PlayerTextDraw(playertextid, cls(playerid))) + def on_click_playertextdraw(cls, player_id: int, player_text_id: int): + """This event is called when a player clicks on a player-textdraw. + It is not called when player cancels the select mode (ESC) \ + however, :meth:`Player.on_click_textdraw()` is. + + :param int player_id: The ID of the player that selected a textdraw. + :param int player_text_id: The ID of the player-textdraw \ + that the player selected. + :returns: No return value. + + .. warning:: + When a player presses ESC to cancel selecting a textdraw,\ + :meth:`Player.on_click_textdraw()` is called with a \ + textdraw ID of ``INVALID_TEXT_DRAW``.\ + :meth:`Player.on_click_playertextdraw()` won't be called also. + """ + return (cls(player_id), PlayerTextDraw(player_text_id, cls(player_id))) @event("OnPlayerClickPlayer") - def on_click_player(cls, playerid: int, clickedplayerid: int, source: int): - return (cls(playerid), cls(clickedplayerid), source) + def on_click_player(cls, player_id: int, clicked_player_id: int, source: int): + """This event is called when a player double-clicks on a player on \ + the scoreboard. + + :param int player_id: The ID of the player that clicked on a player \ + on the scoreboard. + :param int clickedplayer_id: The ID of the player that was clicked on. + :param int source: The source of the player's click. + :returns: No return value. + + .. note:: + There is currently only one source \ + (0 - ``CLICK_SOURCE_SCOREBOARD``). + The existence of this argument suggests that more sources may be \ + supported in the future. + """ + return (cls(player_id), cls(clicked_player_id), source) @event("OnPlayerEditObject") def on_edit_object( cls, - playerid: int, - is_playerobject: bool, - objectid: int, + player_id: int, + is_player_object: bool, + object_id: int, response: int, x: float, y: float, @@ -2624,9 +3061,30 @@ def on_edit_object( rot_y: float, rot_z: float, ): + """This event is called when a player finishes editing an object. + + :param int player_id: The ID of the player that edited an object. + :param bool is_player_object: `False` if it is a global object or \ + `True` if it is a playerobject. + :param int object_id: The ID of the edited object. + :param int response: The type of response. + :param float x: The X offset for the object that was edited. + :param float y: The Y offset for the object that was edited. + :param float z: The Z offset for the object that was edited. + :param float rot_x: The X rotation for the object that was edited. + :param float rot_y: The Y rotation for the object that was edited. + :param float rot_z: The Z rotation for the object that was edited. + :returns: No return value. + + .. warning:: + When using ``EDIT_RESPONSE_UPDATE`` be aware that this event will \ + not be called when releasing an edit in progress resulting in the \ + last update of ``EDIT_RESPONSE_UPDATE`` being out of sync of the \ + objects current position. + """ return ( - cls(playerid), - PlayerObject(objectid) if is_playerobject else Object(objectid), + cls(player_id), + PlayerObject(object_id) if is_player_object else Object(object_id), response, x, y, @@ -2639,11 +3097,11 @@ def on_edit_object( @event("OnPlayerEditAttachedObject") def on_edit_attached_object( cls, - playerid: int, + player_id: int, response: int, index: int, - modelid: int, - boneid: int, + model_id: int, + bone_id: int, offset_x: float, offset_y: float, offset_z: float, @@ -2654,12 +3112,37 @@ def on_edit_attached_object( scale_y: float, scale_z: float, ): + """This event is called when a player ends attached object \ + edition mode. + + :param int player_id: The ID of the player that ended edition mode. + :param int response: ``0`` if cancelled (ESC) \ + or ``1`` if clicked the save icon. + :param int index: The index of the object (0-9). + :param int model_id: The model of the object that was edited. + :param int bone_id: The bone of the object that was edited. + :param float offset_x: The X offset for the object that was edited. + :param float offset_y: The Y offset for the object that was edited. + :param float offset_z: The Z offset for the object that was edited. + :param float rot_x: The X rotation for the object that was edited. + :param float rot_y: The Y rotation for the object that was edited. + :param float rot_z: The Z rotation for the object that was edited. + :param float scale_x: The X scale for the object that was edited. + :param float scale_y: The Y scale for the object that was edited. + :param float scale_z: The Z scale for the object that was edited. + :returns: No return value. + + .. warning:: + Editions should be discarded if response was ``0``' (cancelled). + This must be done by storing the offsets etc. \ + BEFORE using :meth:`Player.edit_attached_object()`. + """ return ( - cls(playerid), + cls(player_id), response, index, - modelid, - boneid, + model_id, + bone_id, offset_x, offset_y, offset_z, @@ -2674,22 +3157,43 @@ def on_edit_attached_object( @event("OnPlayerSelectObject") def on_select_object( cls, - playerid: int, + player_id: int, type: int, - objectid: int, - modelid: int, + object_id: int, + model_id: int, x: float, y: float, z: float, ): + """This event is called when a player selects an object. + + :param int player_id: The ID of the player that selected an object. + :param int type: The type of selection. + :param int object_id: The ID of the selected object. + :param int model_id: The model of the selected object. + :param float x: The X position of the selected object. + :param float y: The Y position of the selected object. + :param float z: The Z position of the selected object. + :returns: No return value. + + .. list-table:: Select Object Types + :header-rows: 1 + + * - Value + - Definition + * - 1 + - ``SELECT_OBJECT_GLOBAL_OBJECT`` + * - 2 + - ``SELECT_OBJECT_PLAYER_OBJECT`` + """ object_cls = { SELECT_OBJECT_GLOBAL_OBJECT: Object, SELECT_OBJECT_PLAYER_OBJECT: PlayerObject, } return ( - cls(playerid), - object_cls[type](objectid), - modelid, + cls(player_id), + object_cls[type](object_id), + model_id, x, y, z, @@ -2698,14 +3202,77 @@ def on_select_object( @event("OnPlayerWeaponShot") def on_weapon_shot( cls, - playerid: int, - weaponid: int, - hittype: int, - hitid: int, + player_id: int, + weapon_id: int, + hit_type: int, + hit_id: int, x: float, y: float, z: float, ): + """This event is called when a player fires a shot from a weapon. + + Only bullet weapons are supported. + + Only passenger drive-by is supported \ + (not driver drive-by, and not sea sparrow / hunter shots). + + :param int player_id: The ID of the player that shot a weapon. + :param int weapon_id: The ID of the weapon shot by the player. + :param int hit_type: The type of thing the shot hit. + :param int hit_id: The ID of the player, vehicle or object that \ + was hit. + :param float x: The X coordinate that the shot hit. + :param float y: The X coordinate that the shot hit. + :param float z: The X coordinate that the shot hit. + :returns: No return value. + + See all weapon ID's here: + https://open.mp/docs/scripting/resources/weapon_ids + + .. list-table:: Bullet Hit Types + :header-rows: 1 + + * - Value + - Definition + * - 0 + - ``BULLET_HIT_TYPE_NONE`` + * - 1 + - ``BULLET_HIT_TYPE_PLAYER`` + * - 2 + - ``BULLET_HIT_TYPE_VEHICLE`` + * - 3 + - ``BULLET_HIT_TYPE_OBJECT`` + * - 4 + - ``BULLET_HIT_TYPE_PLAYER_OBJECT`` + + .. note:: + This event is only called when lag compensation is enabled. \ + If hit_type is: ``BULLET_HIT_TYPE_NONE``: the x, y and z \ + parameters are normal coordinates, will give 0.0 for coordinates \ + if nothing was hit (e.g. far object that the bullet can't reach). + + Others: the x, y and z are offsets relative to the hit_id. + + .. note:: + :meth:`Player.get_last_shot_vectors()` can be used in this event \ + for more detailed bullet vector information. + + .. warning:: + Known Bug(s): + Isn't called if you fired in vehicle as driver \ + or if you are looking behind with the aim enabled (air).\ + + It is called as ``BULLET_HIT_TYPE_VEHICLE`` with the correct \ + hit_id (the hit player's vehicle_id) if you are shooting a \ + player which is in a vehicle. It won't be called as \ + ``BULLET_HIT_TYPE_PLAYER`` at all. + + Partially fixed in SA-MP 0.3.7: If fake weapon data is sent \ + by a malicious user, other player clients may freeze or crash. + To combat this, check if the reported weapon_id can \ + actually fire bullets. + """ hit_cls = { BULLET_HIT_TYPE_NONE: lambda _: None, BULLET_HIT_TYPE_PLAYER: cls, @@ -2714,9 +3281,9 @@ def on_weapon_shot( BULLET_HIT_TYPE_PLAYER_OBJECT: PlayerObject, } return ( - cls(playerid), - weaponid, - hit_cls[hittype](hitid), + cls(player_id), + weapon_id, + hit_cls[hit_type](hit_id), x, y, z, From bf938a1fae0e54c71db4ee63c7a3c29ec4aeb1ec Mon Sep 17 00:00:00 2001 From: Dan Date: Tue, 31 Dec 2024 01:31:50 +0300 Subject: [PATCH 08/15] adde missing space --- pysamp/player.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pysamp/player.py b/pysamp/player.py index 528b50c..8438d1a 100644 --- a/pysamp/player.py +++ b/pysamp/player.py @@ -2455,7 +2455,7 @@ def on_connect(cls, player_id: int): :param int player_id: The ID of the player that connected. :returns: No return value. - ..note:: This event can also be called by NPC. + .. note:: This event can also be called by NPC. """ return (cls(player_id),) From b8ed353285b25e6ae191bd6e398238e19ca0d304 Mon Sep 17 00:00:00 2001 From: gsmj Date: Wed, 1 Jan 2025 23:54:56 +0300 Subject: [PATCH 09/15] removed \ --- pysamp/actor.py | 8 +- pysamp/object.py | 4 +- pysamp/player.py | 198 ++++++++++++++++++++--------------------- pysamp/playerobject.py | 2 +- pysamp/vehicle.py | 68 +++++++------- 5 files changed, 140 insertions(+), 140 deletions(-) diff --git a/pysamp/actor.py b/pysamp/actor.py index 8c3d7dd..b5a5c37 100644 --- a/pysamp/actor.py +++ b/pysamp/actor.py @@ -141,11 +141,11 @@ def is_valid(self) -> bool: @event("OnActorStreamIn") def on_stream_in(cls, actor_id: int, for_player_id: int): - """This event is called when an actor is streamed in by a player's \ + """This event is called when an actor is streamed in by a player's client. :param int actor_id: The ID of the actor. - :param int for_player_id: The ID of the player that streamed the \ + :param int for_player_id: The ID of the player that streamed the actor in. :returns: No return value. @@ -155,11 +155,11 @@ def on_stream_in(cls, actor_id: int, for_player_id: int): @event("OnActorStreamOut") def on_stream_out(cls, actor_id: int, for_player_id: int): - """This event is called when an actor is streamed out by a \ + """This event is called when an actor is streamed out by a player's client. :param int actor_id: The ID of the actor. - :param int for_player_id: The ID of the player that streamed the \ + :param int for_player_id: The ID of the player that streamed the actor out. :returns: No return value. diff --git a/pysamp/object.py b/pysamp/object.py index e98ad2e..1d7179a 100644 --- a/pysamp/object.py +++ b/pysamp/object.py @@ -240,13 +240,13 @@ def set_default_camera_col(disable: bool) -> bool: @event("OnObjectMoved") def on_moved(cls, object_id: int): - """This event is called when an object stops moving after \ + """This event is called when an object stops moving after :meth:`Object.move()`. :param int object_id: The ID of the object that was moved. :returns: No return value. - .. note:: :meth:`set_position` does not work when used in this \ + .. note:: :meth:`set_position` does not work when used in this event. To fix it, recreate the object. """ return (cls(object_id),) diff --git a/pysamp/player.py b/pysamp/player.py index 8438d1a..6f22145 100644 --- a/pysamp/player.py +++ b/pysamp/player.py @@ -562,7 +562,7 @@ def set_name(self, name: str) -> int: """Set a new name for the player. :param name: The name to set. Must be 2-24 characters long and only - contain valid characters (0-9, a-z, A-Z, [], (), \\$ @ . _ and =). + contain valid characters (0-9, a-z, A-Z, [], (),\$ @ . _ and =). :return: This method does not return anything. @@ -1387,7 +1387,7 @@ def get_pvars_upper_index(self) -> int: if player.get_pvar_type(var_name) is not 0: pvar_count = pvar_count + 1 - print(f"You have {pvar_count} player-variables set. \\ + print(f"You have {pvar_count} player-variables set.\ Upper index (highest ID):\\ {pvar_upper_index - 1}.") """ @@ -2437,10 +2437,10 @@ def on_enter_exit_mod_shop( ): """This event is called when a player enters or exits a mod shop. - :param int player_id: The ID of the player that entered /exited \ + :param int player_id: The ID of the player that entered /exited the modshop. :param int enter_exit: ``1`` if the player entered or ``0`` if exited. - :param int interior_id: The interior ID of the modshop that \ + :param int interior_id: The interior ID of the modshop that the player is entering (or ``0`` if exiting). :returns: No return value. @@ -2475,11 +2475,11 @@ def on_disconnect(cls, player_id: int, reason: int): - Description * - 0 - Timeout/Crash - - The player's connection was lost. \ + - The player's connection was lost. Either their game crashed or their network had a fault. * - 1 - Quit - - The player purposefully quit, either using the /quit (/q) \ + - The player purposefully quit, either using the /quit (/q) command or via the pause menu. * - 2 - Kick/Ban @@ -2489,7 +2489,7 @@ def on_disconnect(cls, player_id: int, reason: int): - Used by some libraries. Reserved for modes' private uses. * - 4 - Mode End - - The current mode is ending so disconnecting all players from \ + - The current mode is ending so disconnecting all players from it (they are still on the server). .. warning:: Reasons 3 and 4 were added by the open.mp server. @@ -2513,25 +2513,25 @@ def on_death(cls, player_id: int, killer_id: int, reason: int): """This event is called when a player dies. :param int player_id: The ID of the player that died. - :param int killer_id: The ID of the player that killed the player who \ + :param int killer_id: The ID of the player that killed the player who died, or ``INVALID_PLAYER_ID`` if there was none. - :param int reason: The ID of the reason (weapon id) for the \ + :param int reason: The ID of the reason (weapon id) for the player's death. :returns: No return value. Weapon IDs: https://www.open.mp/docs/scripting/resources/weapon_ids .. note:: The reason will return 37 from any fire sources. - The reason will return 51 from any weapon that creates an \ + The reason will return 51 from any weapon that creates an explosion (e.g. RPG, grenade). - You do not need to check whether killer_id is valid before using \ + You do not need to check whether killer_id is valid before using it in :meth:`Player.send_death_message()`. - ``INVALID_PLAYER_ID`` is a valid killer_id ID parameter in that \ + ``INVALID_PLAYER_ID`` is a valid killer_id ID parameter in that function. - player_id is the only one who can call the event. \ + player_id is the only one who can call the event. (good to know for anti fake death) - .. warning:: You MUST check whether ``killer_id`` is valid \ + .. warning:: You MUST check whether ``killer_id`` is valid (not ``INVALID_PLAYER_ID``) before using it anywhere. """ return ( @@ -2563,13 +2563,13 @@ def on_player_text(player: Player, text: str): @event("OnPlayerCommandText") def on_command_text(cls, player_id: int, command_text: str): - """This event is called when a player enters a command into the \ + """This event is called when a player enters a command into the client chat window. Commands are anything that start with a forward slash, e.g. /help. :param int player_id: The ID of the player that entered a command. - :param str command_text: The command that was entered \ + :param str command_text: The command that was entered (including the forward slash). :returns: No return value. @@ -2609,20 +2609,20 @@ def on_enter_vehicle( vehicle_id: int, is_passenger: bool, ): - """This event is called when a player starts to enter a vehicle, \ - meaning the player is not in vehicle yet at the time this event \ + """This event is called when a player starts to enter a vehicle, + meaning the player is not in vehicle yet at the time this event is called. :param int player_id: ID of the player who attempts to enter a vehicle. - :param int vehicle_id: ID of the vehicle the player is attempting \ + :param int vehicle_id: ID of the vehicle the player is attempting to enter. - :param bool is_passenger: ``False`` if entering as driver. ``True`` \ + :param bool is_passenger: ``False`` if entering as driver. ``True`` if entering as passenger. :returns: No return value. .. note:: This event is called when a player BEGINS to enter a vehicle, not when they HAVE entered it. See :meth:`Player.on_state_change`. - This event is still called if the player is denied entry \ + This event is still called if the player is denied entry to the vehicle (e.g. it is locked or full). """ return (cls(player_id), Vehicle(vehicle_id), is_passenger) @@ -2635,10 +2635,10 @@ def on_exit_vehicle(cls, player_id: int, vehicle_id: int): :param int vehicle_id: The ID of the vehicle the player is exiting. :returns: No return value. - .. warning:: Not called if the player falls off a bike or is \ + .. warning:: Not called if the player falls off a bike or is removed from a vehicle by other means such as using :meth:`Player.set_pos()`. - You must use :meth:`Player.on_state_change` and check if their \ + You must use :meth:`Player.on_state_change` and check if their old state is ``PLAYER_STATE_DRIVER`` or ``PLAYER_STATE_PASSENGER``\ and their new state is ``PLAYER_STATE_ONFOOT``. """ @@ -2648,7 +2648,7 @@ def on_exit_vehicle(cls, player_id: int, vehicle_id: int): def on_state_change(cls, player_id, new_state: int, old_state: int): """This event is called when a player changes state. - For example, when a player changes from being the driver of a vehicle \ + For example, when a player changes from being the driver of a vehicle to being on-foot. :param int player_id: The ID of the player that changed state. @@ -2656,7 +2656,7 @@ def on_state_change(cls, player_id, new_state: int, old_state: int): :param int old_state: The player's previous state. :returns: No return value. - List of all available player states: \ + List of all available player states: https://www.open.mp/docs/scripting/resources/playerstates .. note:: This event can also be called by NPC. @@ -2665,7 +2665,7 @@ def on_state_change(cls, player_id, new_state: int, old_state: int): @event("OnPlayerEnterCheckpoint") def on_enter_checkpoint(cls, player_id: int): - """This event is called when a player enters the checkpoint set for \ + """This event is called when a player enters the checkpoint set for that player. :param int player_id: The player who entered the checkpoint. @@ -2677,7 +2677,7 @@ def on_enter_checkpoint(cls, player_id: int): @event("OnPlayerLeaveCheckpoint") def on_leave_checkpoint(cls, player_id: int): - """This event is called when a player leaves the checkpoint set for \ + """This event is called when a player leaves the checkpoint set for him by :meth:`Player.set_checkpoint()`. Only one checkpoint can be set at a time. @@ -2713,7 +2713,7 @@ def on_leave_race_checkpoint(cls, player_id: int): @event("OnPlayerRequestSpawn") def on_request_spawn(cls, player_id: int): - """This event is called when a player attempts to spawn via class \ + """This event is called when a player attempts to spawn via class selection either by pressing SHIFT or clicking the 'Spawn' button. :param int player_id: The ID of the player that requested to spawn. @@ -2725,11 +2725,11 @@ def on_request_spawn(cls, player_id: int): @event("OnPlayerPickUpPickup") def on_pick_up_pickup(cls, player_id, pickup_id: int): - """This event is called when a player picks up a pickup created \ + """This event is called when a player picks up a pickup created with :meth:`Pickup.create()`. :param int player_id: The ID of the player that picked up the pickup. - :param int pickup_id: The ID of the pickup, returned \ + :param int pickup_id: The ID of the pickup, returned by :meth:`Pickup.create()`. :returns: No return value. """ @@ -2740,12 +2740,12 @@ def on_selected_menu_row(cls, player_id: int, row: int): """This event is called when a player selects an item from a menu. :param int player_id: The ID of the player that selected a menu item. - :param int row: The ID of the row that was selected. \ + :param int row: The ID of the row that was selected. The first row is ID 0. :returns: No return value. - .. note:: The menu ID is not passed to this event. \ - :meth:`Menu.get_player_menu()` must be used to determine which menu \ + .. note:: The menu ID is not passed to this event. + :meth:`Menu.get_player_menu()` must be used to determine which menu the player selected an item on. """ return (cls(player_id), row) @@ -2766,8 +2766,8 @@ def on_interior_change( new_interior_id: int, old_interior_id: int, ): - """This event is called when a player changes interior. \ - Can be triggered by :meth:`Player.set_interior()` or when a player \ + """This event is called when a player changes interior. + Can be triggered by :meth:`Player.set_interior()` or when a player enter / exits a building. :param int player_id: The player_id who changed interior. @@ -2779,15 +2779,15 @@ def on_interior_change( @event("OnPlayerKeyStateChange") def on_key_state_change(cls, player_id: int, new_keys: int, old_keys: int): - """This event is called when the state of any supported key is \ + """This event is called when the state of any supported key is changed (pressed/released). Directional keys do not trigger this event (up/down/left/right). - :param int player_id: The ID of the player that \ + :param int player_id: The ID of the player that pressed or released a key. :param int new_interior_id: A map (bitmask) of the keys currently held. - :param int old_interior_id: A map (bitmask) of the keys held prior to \ + :param int old_interior_id: A map (bitmask) of the keys held prior to the current change. :returns: No return value. @@ -2799,9 +2799,9 @@ def on_key_state_change(cls, player_id: int, new_keys: int, old_keys: int): @event("OnPlayerUpdate") def on_update(cls, player_id: int): - """This event is called every time a client / player updates the \ - server with their status. It is often used to create custom events \ - for client updates that aren't actively tracked by the server, \ + """This event is called every time a client / player updates the + server with their status. It is often used to create custom events + for client updates that aren't actively tracked by the server, such as health or armor updates or players switching weapons. :param int player_id: ID of the player sending an update packet. @@ -2812,19 +2812,19 @@ def on_update(cls, player_id: int): .. warning:: This event is called, on average, 30 times per second, per player. Only use it when you know what it's meant for. - The frequency with which this event is called for \ - each player varies, depending on what the player is doing. \ + The frequency with which this event is called for + each player varies, depending on what the player is doing. Driving or shooting will trigger a lot more updates than idling. """ return (cls(player_id),) @event("OnPlayerStreamIn") def on_stream_in(cls, player_id: int, for_player_id: int): - """This event is called when a player is streamed by \ + """This event is called when a player is streamed by some other player's client. :param int player_id: The ID of the player who has been streamed. - :param int for_player_id: The ID of the player that streamed the \ + :param int for_player_id: The ID of the player that streamed the other player in. :returns: No return value. @@ -2834,11 +2834,11 @@ def on_stream_in(cls, player_id: int, for_player_id: int): @event("OnPlayerStreamOut") def on_stream_out(cls, player_id: int, for_player_id: int): - """This event is called when a player is streamed \ + """This event is called when a player is streamed out from some other player's client. :param int player_id: The player who has been destreamed. - :param int for_player_id: The player who has destreamed the \ + :param int for_player_id: The player who has destreamed the other player. :returns: No return value. @@ -2861,9 +2861,9 @@ def on_take_damage( """This event is called when a player takes damage. :param int player_id: The ID of the player that took damage. - :param int issuer_id: The ID of the player that caused the damage. \ + :param int issuer_id: The ID of the player that caused the damage. ``INVALID_PLAYER_ID`` if self-inflicted. - :param float amount: The amount of damage the player took \ + :param float amount: The amount of damage the player took (health and armour combined). :param int weapon_id: The ID of the weapon/reason for the damage. :param int body_part: The body part that was hit. @@ -2872,21 +2872,21 @@ def on_take_damage( Body parts: https://www.open.mp/docs/scripting/resources/bodyparts .. note:: - - The weapon_id will return 37 (flame thrower) from any \ + - The weapon_id will return 37 (flame thrower) from any fire sources (e.g. molotov, 18). - - The weapon_id will return 51 from any weapon that creates an \ + - The weapon_id will return 51 from any weapon that creates an explosion (e.g. RPG, grenade). - player_id is the only one who can call the event. - - The amount is always the maximum damage the weaponid can do, \ + - The amount is always the maximum damage the weaponid can do, even when the health left is less than that maximum damage. - So when a player has 100.0 health and gets shot with a \ - Desert Eagle which has a damage value of 46.2, it takes 3 shots \ - to kill that player. All 3 shots will show an amount of 46.2, \ - even though when the last shot hits, the player only has \ + So when a player has 100.0 health and gets shot with a + Desert Eagle which has a damage value of 46.2, it takes 3 shots + to kill that player. All 3 shots will show an amount of 46.2, + even though when the last shot hits, the player only has 7.6 health left. .. warning:: - - :meth:`Player.get_health()` and :meth:`Player.get_armour()` \ + - :meth:`Player.get_health()` and :meth:`Player.get_armour()` will return the old amounts of the player before this event. - Always check if issuer_id is valid before. """ @@ -2911,7 +2911,7 @@ def on_give_damage( :param int player_id: The ID of the player that gave damage. :param int damaged_id: The ID of the player that received damage. - :param float amount: The amount of health / armour damaged_id has \ + :param float amount: The amount of health / armour damaged_id has lost (combined). :param int weapon_id: The reason that caused the damage. :param int body_part: The body part that was hit. @@ -2921,19 +2921,19 @@ def on_give_damage( .. note:: - Keep in mind this function can be inaccurate in some cases. - - If you want to prevent certain players from damaging eachother, \ + - If you want to prevent certain players from damaging eachother, use :meth:`Player.set_team()`. - - The weapon_id will return 37 (flame thrower) from any \ + - The weapon_id will return 37 (flame thrower) from any fire sources (e.g. molotov, 18). - - The weapon_id will return 51 from any weapon that creates an \ + - The weapon_id will return 51 from any weapon that creates an explosion (e.g. RPG, grenade). - player_id is the only one who can call the event. - - The amount is always the maximum damage the weaponid can do, \ + - The amount is always the maximum damage the weaponid can do, even when the health left is less than that maximum damage. - So when a player has 100.0 health and gets shot with a \ - Desert Eagle which has a damage value of 46.2, it takes 3 shots \ - to kill that player. All 3 shots will show an amount of 46.2, \ - even though when the last shot hits, the player only has \ + So when a player has 100.0 health and gets shot with a + Desert Eagle which has a damage value of 46.2, it takes 3 shots + to kill that player. All 3 shots will show an amount of 46.2, + even though when the last shot hits, the player only has 7.6 health left. """ return ( @@ -2965,7 +2965,7 @@ def on_give_damage_actor( Body parts: https://www.open.mp/docs/scripting/resources/bodyparts .. note:: - This event does not get called if the actor is set invulnerable \ + This event does not get called if the actor is set invulnerable (WHICH IS BY DEFAULT). See :meth:`Actor.set_invulnerable()`. """ return ( @@ -2978,10 +2978,10 @@ def on_give_damage_actor( @event("OnPlayerClickMap") def on_click_map(cls, player_id: int, x: float, y: float, z: float): - """This event is called when a player places a target/waypoint \ + """This event is called when a player places a target/waypoint on the pause menu map (by right-clicking). - :param int player_id: The ID of the player that placed a \ + :param int player_id: The ID of the player that placed a target / waypoint. :param float x: The X float coordinate where the player clicked. :param float y: The Y float coordinate where the player clicked. @@ -2992,19 +2992,19 @@ def on_click_map(cls, player_id: int, x: float, y: float, z: float): @event("OnPlayerClickTextDraw") def on_click_textdraw(cls, player_id: int, clicked_id: int): - """This event is called when a player clicks on a textdraw \ + """This event is called when a player clicks on a textdraw or cancels the select mode with the Escape key. :param int player_id: The ID of the player clicked on the textdraw. - :param int clicked_id: The ID of the clicked textdraw. \ + :param int clicked_id: The ID of the clicked textdraw. ``INVALID_TEXT_DRAW`` if selection was cancelled. :returns: No return value. .. warning:: The clickable area is defined by :meth:`TextDraw.text_size()`. - The x and y parameters passed to that function \ + The x and y parameters passed to that function must not be zero or negative. - Do not use :meth:`TextDraw.cancel_select()` unconditionally \ + Do not use :meth:`TextDraw.cancel_select()` unconditionally within this event. This results in an infinite loop. """ return (cls(player_id), TextDraw(clicked_id)) @@ -3012,17 +3012,17 @@ def on_click_textdraw(cls, player_id: int, clicked_id: int): @event("OnPlayerClickPlayerTextDraw") def on_click_playertextdraw(cls, player_id: int, player_text_id: int): """This event is called when a player clicks on a player-textdraw. - It is not called when player cancels the select mode (ESC) \ + It is not called when player cancels the select mode (ESC) however, :meth:`Player.on_click_textdraw()` is. :param int player_id: The ID of the player that selected a textdraw. - :param int player_text_id: The ID of the player-textdraw \ + :param int player_text_id: The ID of the player-textdraw that the player selected. :returns: No return value. .. warning:: When a player presses ESC to cancel selecting a textdraw,\ - :meth:`Player.on_click_textdraw()` is called with a \ + :meth:`Player.on_click_textdraw()` is called with a textdraw ID of ``INVALID_TEXT_DRAW``.\ :meth:`Player.on_click_playertextdraw()` won't be called also. """ @@ -3030,19 +3030,19 @@ def on_click_playertextdraw(cls, player_id: int, player_text_id: int): @event("OnPlayerClickPlayer") def on_click_player(cls, player_id: int, clicked_player_id: int, source: int): - """This event is called when a player double-clicks on a player on \ + """This event is called when a player double-clicks on a player on the scoreboard. - :param int player_id: The ID of the player that clicked on a player \ + :param int player_id: The ID of the player that clicked on a player on the scoreboard. :param int clickedplayer_id: The ID of the player that was clicked on. :param int source: The source of the player's click. :returns: No return value. .. note:: - There is currently only one source \ + There is currently only one source (0 - ``CLICK_SOURCE_SCOREBOARD``). - The existence of this argument suggests that more sources may be \ + The existence of this argument suggests that more sources may be supported in the future. """ return (cls(player_id), cls(clicked_player_id), source) @@ -3064,7 +3064,7 @@ def on_edit_object( """This event is called when a player finishes editing an object. :param int player_id: The ID of the player that edited an object. - :param bool is_player_object: `False` if it is a global object or \ + :param bool is_player_object: `False` if it is a global object or `True` if it is a playerobject. :param int object_id: The ID of the edited object. :param int response: The type of response. @@ -3077,9 +3077,9 @@ def on_edit_object( :returns: No return value. .. warning:: - When using ``EDIT_RESPONSE_UPDATE`` be aware that this event will \ - not be called when releasing an edit in progress resulting in the \ - last update of ``EDIT_RESPONSE_UPDATE`` being out of sync of the \ + When using ``EDIT_RESPONSE_UPDATE`` be aware that this event will + not be called when releasing an edit in progress resulting in the + last update of ``EDIT_RESPONSE_UPDATE`` being out of sync of the objects current position. """ return ( @@ -3112,11 +3112,11 @@ def on_edit_attached_object( scale_y: float, scale_z: float, ): - """This event is called when a player ends attached object \ + """This event is called when a player ends attached object edition mode. :param int player_id: The ID of the player that ended edition mode. - :param int response: ``0`` if cancelled (ESC) \ + :param int response: ``0`` if cancelled (ESC) or ``1`` if clicked the save icon. :param int index: The index of the object (0-9). :param int model_id: The model of the object that was edited. @@ -3134,7 +3134,7 @@ def on_edit_attached_object( .. warning:: Editions should be discarded if response was ``0``' (cancelled). - This must be done by storing the offsets etc. \ + This must be done by storing the offsets etc. BEFORE using :meth:`Player.edit_attached_object()`. """ return ( @@ -3214,13 +3214,13 @@ def on_weapon_shot( Only bullet weapons are supported. - Only passenger drive-by is supported \ + Only passenger drive-by is supported (not driver drive-by, and not sea sparrow / hunter shots). :param int player_id: The ID of the player that shot a weapon. :param int weapon_id: The ID of the weapon shot by the player. :param int hit_type: The type of thing the shot hit. - :param int hit_id: The ID of the player, vehicle or object that \ + :param int hit_id: The ID of the player, vehicle or object that was hit. :param float x: The X coordinate that the shot hit. :param float y: The X coordinate that the shot hit. @@ -3247,30 +3247,30 @@ def on_weapon_shot( - ``BULLET_HIT_TYPE_PLAYER_OBJECT`` .. note:: - This event is only called when lag compensation is enabled. \ - If hit_type is: ``BULLET_HIT_TYPE_NONE``: the x, y and z \ - parameters are normal coordinates, will give 0.0 for coordinates \ + This event is only called when lag compensation is enabled. + If hit_type is: ``BULLET_HIT_TYPE_NONE``: the x, y and z + parameters are normal coordinates, will give 0.0 for coordinates if nothing was hit (e.g. far object that the bullet can't reach). Others: the x, y and z are offsets relative to the hit_id. .. note:: - :meth:`Player.get_last_shot_vectors()` can be used in this event \ + :meth:`Player.get_last_shot_vectors()` can be used in this event for more detailed bullet vector information. .. warning:: Known Bug(s): - Isn't called if you fired in vehicle as driver \ + Isn't called if you fired in vehicle as driver or if you are looking behind with the aim enabled (air).\ - It is called as ``BULLET_HIT_TYPE_VEHICLE`` with the correct \ - hit_id (the hit player's vehicle_id) if you are shooting a \ - player which is in a vehicle. It won't be called as \ + It is called as ``BULLET_HIT_TYPE_VEHICLE`` with the correct + hit_id (the hit player's vehicle_id) if you are shooting a + player which is in a vehicle. It won't be called as ``BULLET_HIT_TYPE_PLAYER`` at all. - Partially fixed in SA-MP 0.3.7: If fake weapon data is sent \ + Partially fixed in SA-MP 0.3.7: If fake weapon data is sent by a malicious user, other player clients may freeze or crash. - To combat this, check if the reported weapon_id can \ + To combat this, check if the reported weapon_id can actually fire bullets. """ hit_cls = { diff --git a/pysamp/playerobject.py b/pysamp/playerobject.py index 772304e..706d2f2 100644 --- a/pysamp/playerobject.py +++ b/pysamp/playerobject.py @@ -391,7 +391,7 @@ def set_material( @event("OnPlayerObjectMoved") def on_moved(cls, player_id: int, object_id: int): - """This event is called when a player object is moved after \ + """This event is called when a player object is moved after :meth:`PlayerObject.move()` (when it stops moving). :param int player_id: The player id the object is assigned to. diff --git a/pysamp/vehicle.py b/pysamp/vehicle.py index 7890318..8b5a045 100644 --- a/pysamp/vehicle.py +++ b/pysamp/vehicle.py @@ -367,19 +367,19 @@ def on_trailer_update(cls, player_id: int, trailer_id: int): .. warning:: This event is called very frequently per second per trailer. - You should refrain from implementing intensive calculations \ + You should refrain from implementing intensive calculations or intensive file writing/reading operations in this event. """ return (Player(player_id), cls(trailer_id)) @event("OnVehicleDamageStatusUpdate") def on_damage_status_update(cls, vehicle_id: int, player_id: int): - """This event is called when a vehicle element such as \ + """This event is called when a vehicle element such as doors, tyres, panels, or lights change their damage status. - :param int vehicle_id: The ID of the vehicle that was changed \ + :param int vehicle_id: The ID of the vehicle that was changed its damage status. - :param int player_id: The ID of the player who synced the change in \ + :param int player_id: The ID of the player who synced the change in the damage status (who had the car damaged or repaired) :returns: No return value. @@ -389,17 +389,17 @@ def on_damage_status_update(cls, vehicle_id: int, player_id: int): @event("OnVehicleDeath") def on_death(cls, vehicle_id: int, killer_id: int): - """This event is called when a vehicle is destroyed - either by \ + """This event is called when a vehicle is destroyed - either by exploding or becoming submerged in water. :param int vehicle_id: The ID of the vehicle that was destroyed. - :param int killer_id: The ID of the player that reported the \ - vehicle's destruction (name is misleading). Generally the driver or \ + :param int killer_id: The ID of the player that reported the + vehicle's destruction (name is misleading). Generally the driver or a passenger (if any) or the closest player. :returns: No return value. .. note:: - This event will also be called when a vehicle enters water, but \ + This event will also be called when a vehicle enters water, but the vehicle can be saved by teleportation or driving out. The event won't be called a second time,\ and the vehicle may disappear when the driver exits, or after a short time. @@ -415,7 +415,7 @@ def on_mod(cls, player_id: int, vehicle_id: int, component_id: int): :param int player_id: The ID of the driver of the vehicle. :param int vehicle_id: The ID of the vehicle which is modded. - :param int component_id: The ID of the component which was added to \ + :param int component_id: The ID of the component which was added to the vehicle. :returns: No return value. @@ -425,13 +425,13 @@ def on_mod(cls, player_id: int, vehicle_id: int, component_id: int): @event("OnVehiclePaintjob") def on_paintjob(cls, player_id: int, vehicle_id: int, paintjob_id: int): - """This event is called when a player previews a vehicle paintjob \ + """This event is called when a player previews a vehicle paintjob inside a mod shop. Watch out, this event is NOT called when the player buys the paintjob. - :param int player_id: The ID of the player that changed the paintjob \ + :param int player_id: The ID of the player that changed the paintjob of their vehicle. - :param int vehicle_id: The ID of the vehicle that had its \ + :param int vehicle_id: The ID of the vehicle that had its paintjob changed. :param int paintjob_id: The ID of the new paintjob. :returns: No return value. @@ -444,17 +444,17 @@ def on_paintjob(cls, player_id: int, vehicle_id: int, paintjob_id: int): def on_respray( cls, player_id: int, vehicle_id: int, color1: int, color2: int ): - """This event is called when a player exits a mod shop, even if the \ + """This event is called when a player exits a mod shop, even if the colors weren't changed. - Watch out, the name is ambiguous, Pay 'n' Spray shops don't call \ + Watch out, the name is ambiguous, Pay 'n' Spray shops don't call this event. :param int player_id: The ID of the player that is driving the vehicle. :param int vehicle_id: The ID of the vehicle that was resprayed. - :param int color1: The color that the vehicle's primary color \ + :param int color1: The color that the vehicle's primary color was changed to. - :param int color2: The color that the vehicle's secondary color \ + :param int color2: The color that the vehicle's secondary color was changed to. :returns: No return value. @@ -463,7 +463,7 @@ def on_respray( Misleadingly, this event is not called for pay 'n' spray. .. warning:: - Known Bug(s): previewing a component inside a mod shop might call \ + Known Bug(s): previewing a component inside a mod shop might call this event. """ return (Player(player_id), cls(vehicle_id), color1, color2) @@ -474,11 +474,11 @@ def on_siren_state_change( ): """This event is called when a vehicle's siren is toggled. - :param int player_id: The ID of the player that toggled the \ + :param int player_id: The ID of the player that toggled the siren (driver). - :param int vehicle_id: The ID of the vehicle of which the siren was \ + :param int vehicle_id: The ID of the vehicle of which the siren was toggled for. - :param int new_state: ``0`` if siren was turned off, ``1`` if siren \ + :param int new_state: ``0`` if siren was turned off, ``1`` if siren was turned on. :returns: No return value. @@ -497,19 +497,19 @@ def on_spawn(cls, vehicle_id: int): .. warning:: This event is called only when vehicle respawns! - :meth:`Vehicle.create()` and :meth:`add_static_vehicle/ex` won't \ + :meth:`Vehicle.create()` and :meth:`add_static_vehicle/ex` won't trigger this event. """ return (cls(vehicle_id),) @event("OnVehicleStreamIn") def on_stream_in(cls, vehicle_id: int, for_player_id: int): - """This event is called when a vehicle is streamed for a \ + """This event is called when a vehicle is streamed for a player's client. - :param int vehicle_id: The ID of the vehicle that streamed in \ + :param int vehicle_id: The ID of the vehicle that streamed in for the player. - :param int for_player_id: The ID of the player who the vehicle \ + :param int for_player_id: The ID of the player who the vehicle streamed in for. :returns: No return value. """ @@ -517,11 +517,11 @@ def on_stream_in(cls, vehicle_id: int, for_player_id: int): @event("OnVehicleStreamOut") def on_stream_out(cls, vehicle_id: int, for_player_id: int): - """This event is called when a vehicle is streamed out for a \ + """This event is called when a vehicle is streamed out for a player's client :param int vehicle_id: The ID of the vehicle that streamed out. - :param int for_player_id: The ID of the player who is no longer \ + :param int for_player_id: The ID of the player who is no longer streaming the vehicle. :returns: No return value. """ @@ -540,16 +540,16 @@ def on_unoccupied_update( vel_y: float, vel_z: float, ): - """This event is called when a player's client updates / syncs the \ + """This event is called when a player's client updates / syncs the position of a vehicle they're not driving. - This can happen outside of the vehicle or when the player is a \ + This can happen outside of the vehicle or when the player is a passenger of a vehicle that has no driver. - :param int vehicle_id: The ID of the vehicle that's position \ + :param int vehicle_id: The ID of the vehicle that's position was updated. - :param int player_id: The ID of the player that sent a vehicle \ + :param int player_id: The ID of the player that sent a vehicle position sync update. - :param int passenget_seat: The ID of the seat if the player \ + :param int passenget_seat: The ID of the seat if the player is a passenger. :param float new_x: The new X coordinate of the vehicle. :param float new_y: The new Y coordinate of the vehicle. @@ -576,11 +576,11 @@ def on_unoccupied_update( - Coach/Bus etc. .. warning:: - This event is called very frequently per second per \ + This event is called very frequently per second per unoccupied vehicle. - You should refrain from implementing intensive calculations or \ + You should refrain from implementing intensive calculations or intensive file writing/reading operations in this event. - :meth:`Vehicle.get_pos()` will return the old coordinates of \ + :meth:`Vehicle.get_pos()` will return the old coordinates of the vehicle before this update. """ return ( From 40074fe85293d0887d7732286a1544719f29a4c5 Mon Sep 17 00:00:00 2001 From: gsmj Date: Sun, 18 May 2025 16:58:57 +0300 Subject: [PATCH 10/15] replaced 'function' word with 'event' to keep consistency --- pysamp/player.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pysamp/player.py b/pysamp/player.py index 6f22145..267f402 100644 --- a/pysamp/player.py +++ b/pysamp/player.py @@ -2920,7 +2920,7 @@ def on_give_damage( Body parts: https://www.open.mp/docs/scripting/resources/bodyparts .. note:: - - Keep in mind this function can be inaccurate in some cases. + - Keep in mind this event can be inaccurate in some cases. - If you want to prevent certain players from damaging eachother, use :meth:`Player.set_team()`. - The weapon_id will return 37 (flame thrower) from any From 5f702291b089de6e0ed6bdc7c96039a1cc46750d Mon Sep 17 00:00:00 2001 From: gsmj Date: Sun, 18 May 2025 17:39:01 +0300 Subject: [PATCH 11/15] actor docs update --- pysamp/actor.py | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/pysamp/actor.py b/pysamp/actor.py index b5a5c37..d765540 100644 --- a/pysamp/actor.py +++ b/pysamp/actor.py @@ -144,12 +144,14 @@ def on_stream_in(cls, actor_id: int, for_player_id: int): """This event is called when an actor is streamed in by a player's client. - :param int actor_id: The ID of the actor. - :param int for_player_id: The ID of the player that streamed the + :param Actor actor: The instance of the actor class. + :param Player for_player: The instance of the player class that streamed the actor in. :returns: No return value. .. note:: This event can also be called by NPC. + + Wraps: https://open.mp/docs/scripting/callbacks/OnActorStreamIn """ return (cls(actor_id), Player(for_player_id)) @@ -158,12 +160,14 @@ def on_stream_out(cls, actor_id: int, for_player_id: int): """This event is called when an actor is streamed out by a player's client. - :param int actor_id: The ID of the actor. - :param int for_player_id: The ID of the player that streamed the + :param Actor actor: The instance of the actor class. + :param Player for_player: The instance of the player class that streamed the actor out. :returns: No return value. .. note:: This event can also be called by NPC. + + Wraps: https://open.mp/docs/scripting/callbacks/OnActorStreamOut """ return (cls(actor_id), Player(for_player_id)) From f9541d99a3bee689d1898ce8ba8de05d8865a9f2 Mon Sep 17 00:00:00 2001 From: gsmj Date: Sun, 18 May 2025 17:39:10 +0300 Subject: [PATCH 12/15] object docs update --- pysamp/object.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/pysamp/object.py b/pysamp/object.py index 1d7179a..5f5476e 100644 --- a/pysamp/object.py +++ b/pysamp/object.py @@ -243,10 +243,12 @@ def on_moved(cls, object_id: int): """This event is called when an object stops moving after :meth:`Object.move()`. - :param int object_id: The ID of the object that was moved. + :param Object object: The insinstance of the object that was moved. :returns: No return value. .. note:: :meth:`set_position` does not work when used in this event. To fix it, recreate the object. + + Wraps: https://open.mp/docs/scripting/callbacks/OnObjectMoved """ return (cls(object_id),) From 07c2849a6f89c042b321199fe47290dbc73f8aeb Mon Sep 17 00:00:00 2001 From: gsmj Date: Sun, 18 May 2025 17:39:21 +0300 Subject: [PATCH 13/15] playerobject docs update --- pysamp/playerobject.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/pysamp/playerobject.py b/pysamp/playerobject.py index 706d2f2..e63c99e 100644 --- a/pysamp/playerobject.py +++ b/pysamp/playerobject.py @@ -394,9 +394,12 @@ def on_moved(cls, player_id: int, object_id: int): """This event is called when a player object is moved after :meth:`PlayerObject.move()` (when it stops moving). - :param int player_id: The player id the object is assigned to. - :param int object_id: The ID of the player object that was moved. + :param Player player: The player instance the object is assigned to. + :param PlayerObject object: The instance of the player object that was + moved. :returns: No return value. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerObjectMoved """ return (cls(object_id, player_id), Player(object_id)) From 7bb7a3db8540a98b63e56b3b8b972d5738ef31c1 Mon Sep 17 00:00:00 2001 From: gsmj Date: Sun, 18 May 2025 18:05:20 +0300 Subject: [PATCH 14/15] vehicle docs update --- pysamp/vehicle.py | 80 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 54 insertions(+), 26 deletions(-) diff --git a/pysamp/vehicle.py b/pysamp/vehicle.py index 8b5a045..f454e4f 100644 --- a/pysamp/vehicle.py +++ b/pysamp/vehicle.py @@ -361,14 +361,17 @@ def set_virtual_world(self, world_id: int) -> bool: def on_trailer_update(cls, player_id: int, trailer_id: int): """This event is called when the player sent a trailer update. - :param int player_id: The ID of the player who sent a trailer update. - :param int trailer_id: The trailer being updated. + :param Player player: The ID of the player who sent a trailer update. + :param Vehicle trailer: The instance of trailer (vehicle) + being updated. :returns: No return value. .. warning:: This event is called very frequently per second per trailer. You should refrain from implementing intensive calculations or intensive file writing/reading operations in this event. + + Wraps: https://open.mp/docs/scripting/callbacks/OnTrailerUpdate """ return (Player(player_id), cls(trailer_id)) @@ -377,13 +380,16 @@ def on_damage_status_update(cls, vehicle_id: int, player_id: int): """This event is called when a vehicle element such as doors, tyres, panels, or lights change their damage status. - :param int vehicle_id: The ID of the vehicle that was changed + :param Vehicle vehicle: The instance of the vehicle that was changed its damage status. - :param int player_id: The ID of the player who synced the change in - the damage status (who had the car damaged or repaired) + :param Player player: The instance of the player who synced the change + in the damage status (who had the car damaged or repaired). :returns: No return value. .. note:: This does not include vehicle health changes. + + Wraps: + https://open.mp/docs/scripting/callbacks/OnVehicleDamageStatusUpdate """ return (cls(vehicle_id), Player(player_id)) @@ -392,17 +398,19 @@ def on_death(cls, vehicle_id: int, killer_id: int): """This event is called when a vehicle is destroyed - either by exploding or becoming submerged in water. - :param int vehicle_id: The ID of the vehicle that was destroyed. - :param int killer_id: The ID of the player that reported the - vehicle's destruction (name is misleading). Generally the driver or - a passenger (if any) or the closest player. + :param Vehicle vehicle: The instance of the vehicle that was destroyed. + :param Player killer: The instance of the player that reported the + vehicle's destruction (name is misleading). Generally the driver or a + passenger (if any) or the closest player. :returns: No return value. .. note:: This event will also be called when a vehicle enters water, but the vehicle can be saved by teleportation or driving out. - The event won't be called a second time,\ + The event won't be called a second time, and the vehicle may disappear when the driver exits, or after a short time. + + Wraps: https://open.mp/docs/scripting/callbacks/OnVehicleDeath """ return ( cls(vehicle_id), @@ -413,13 +421,16 @@ def on_death(cls, vehicle_id: int, killer_id: int): def on_mod(cls, player_id: int, vehicle_id: int, component_id: int): """This event is called when a vehicle is modded. - :param int player_id: The ID of the driver of the vehicle. - :param int vehicle_id: The ID of the vehicle which is modded. + :param Player player: The instance of the driver (player) of the + vehicle. + :param Vehicle vehicle: The instance of the vehicle which is modded. :param int component_id: The ID of the component which was added to the vehicle. :returns: No return value. .. note:: This event is NOT called by :meth:`Vehicle.add_component()`. + + Wraprs: https://open.mp/docs/scripting/callbacks/OnVehicleMod """ return (Player(player_id), cls(vehicle_id), component_id) @@ -429,14 +440,16 @@ def on_paintjob(cls, player_id: int, vehicle_id: int, paintjob_id: int): inside a mod shop. Watch out, this event is NOT called when the player buys the paintjob. - :param int player_id: The ID of the player that changed the paintjob + :param Player player: The instance of the player that changed the paintjob of their vehicle. - :param int vehicle_id: The ID of the vehicle that had its + :param Vehicle vehicle: The instance of the vehicle that had its paintjob changed. :param int paintjob_id: The ID of the new paintjob. :returns: No return value. .. note:: This event isn't called by :meth:`Vehicle.change_paintjob()`. + + Wraps: https://open.mp/docs/scripting/callbacks/OnVehiclePaintjob """ return (Player(player_id), cls(vehicle_id), paintjob_id) @@ -450,8 +463,9 @@ def on_respray( Watch out, the name is ambiguous, Pay 'n' Spray shops don't call this event. - :param int player_id: The ID of the player that is driving the vehicle. - :param int vehicle_id: The ID of the vehicle that was resprayed. + :param Player player: The instance of the player that is driving the + vehicle. + :param Vehicle vehicle: The instance of the vehicle that was resprayed. :param int color1: The color that the vehicle's primary color was changed to. :param int color2: The color that the vehicle's secondary color @@ -465,6 +479,8 @@ def on_respray( .. warning:: Known Bug(s): previewing a component inside a mod shop might call this event. + + Wraps: https://open.mp/docs/scripting/callbacks/OnVehicleRespray """ return (Player(player_id), cls(vehicle_id), color1, color2) @@ -474,10 +490,10 @@ def on_siren_state_change( ): """This event is called when a vehicle's siren is toggled. - :param int player_id: The ID of the player that toggled the + :param Player player: The instance of the player that toggled the siren (driver). - :param int vehicle_id: The ID of the vehicle of which the siren was - toggled for. + :param Vehicle vehicle: The instance of the vehicle of which the siren + was toggled for. :param int new_state: ``0`` if siren was turned off, ``1`` if siren was turned on. :returns: No return value. @@ -485,6 +501,9 @@ def on_siren_state_change( .. note:: This event is only called when a vehicle's siren is on or off, NOT when the alternate siren is in use (holding horn). + + Wraps: + https://open.mp/docs/scripting/callbacks/OnVehicleSirenStateChange """ return (Player(player_id), cls(vehicle_id), new_state) @@ -492,13 +511,15 @@ def on_siren_state_change( def on_spawn(cls, vehicle_id: int): """This event is called when a vehicle respawns. - :param int vehicle_id: The ID of the vehicle that spawned. + :param Vehicle vehicle: The instance of the vehicle that was spawned. :returns: No return value. .. warning:: This event is called only when vehicle respawns! :meth:`Vehicle.create()` and :meth:`add_static_vehicle/ex` won't trigger this event. + + Wraps: https://open.mp/docs/scripting/callbacks/OnVehicleSpawn """ return (cls(vehicle_id),) @@ -507,11 +528,13 @@ def on_stream_in(cls, vehicle_id: int, for_player_id: int): """This event is called when a vehicle is streamed for a player's client. - :param int vehicle_id: The ID of the vehicle that streamed in + :param Vehicle vehicle: The instance of the vehicle that streamed in for the player. - :param int for_player_id: The ID of the player who the vehicle + :param Player for_player: The instance of the player who the vehicle streamed in for. :returns: No return value. + + Wraps: https://open.mp/docs/scripting/callbacks/OnVehicleStreamIn """ return (cls(vehicle_id), Player(for_player_id)) @@ -520,10 +543,12 @@ def on_stream_out(cls, vehicle_id: int, for_player_id: int): """This event is called when a vehicle is streamed out for a player's client - :param int vehicle_id: The ID of the vehicle that streamed out. - :param int for_player_id: The ID of the player who is no longer + :param Vehicle vehicle: The instance of the vehicle that streamed out. + :param Player for_player: The instance of the player who is no longer streaming the vehicle. :returns: No return value. + + Wraps: https://open.mp/docs/scripting/callbacks/OnVehicleStreamOut """ return (cls(vehicle_id), Player(for_player_id)) @@ -545,9 +570,9 @@ def on_unoccupied_update( This can happen outside of the vehicle or when the player is a passenger of a vehicle that has no driver. - :param int vehicle_id: The ID of the vehicle that's position + :param Vehicle vehicle: The instance of the vehicle that's position was updated. - :param int player_id: The ID of the player that sent a vehicle + :param Player player: The instance of the player that sent a vehicle position sync update. :param int passenget_seat: The ID of the seat if the player is a passenger. @@ -582,6 +607,9 @@ def on_unoccupied_update( intensive file writing/reading operations in this event. :meth:`Vehicle.get_pos()` will return the old coordinates of the vehicle before this update. + + Wraps: + https://open.mp/docs/scripting/callbacks/OnUnoccupiedVehicleUpdate """ return ( cls(vehicle_id), From 63d7d8c871e40770830ad620da365254f6b2d4f1 Mon Sep 17 00:00:00 2001 From: gsmj Date: Sun, 18 May 2025 18:32:17 +0300 Subject: [PATCH 15/15] player docs update --- pysamp/player.py | 203 ++++++++++++++++++++++++++++++++++------------- 1 file changed, 148 insertions(+), 55 deletions(-) diff --git a/pysamp/player.py b/pysamp/player.py index 267f402..9d47270 100644 --- a/pysamp/player.py +++ b/pysamp/player.py @@ -2437,7 +2437,7 @@ def on_enter_exit_mod_shop( ): """This event is called when a player enters or exits a mod shop. - :param int player_id: The ID of the player that entered /exited + :param Player player: The instance of the player that entered / exited the modshop. :param int enter_exit: ``1`` if the player entered or ``0`` if exited. :param int interior_id: The interior ID of the modshop that @@ -2445,6 +2445,8 @@ def on_enter_exit_mod_shop( :returns: No return value. .. warning:: Players collide when they get into the same mod shop. + + Wraps: https://open.mp/docs/scripting/callbacks/OnEnterExitModShop """ return (cls(player_id), enter_exit, interior_id) @@ -2452,10 +2454,12 @@ def on_enter_exit_mod_shop( def on_connect(cls, player_id: int): """This event is called when a player connects to the server. - :param int player_id: The ID of the player that connected. + :param Player player: The instance of the player that connected. :returns: No return value. .. note:: This event can also be called by NPC. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerConnect """ return (cls(player_id),) @@ -2463,7 +2467,7 @@ def on_connect(cls, player_id: int): def on_disconnect(cls, player_id: int, reason: int): """This event is called when a player disconnects from the server. - :param int player_id: The ID of the player that disconnected. + :param Player player: The instance of the player that disconnected. :param int reason: The reason for the disconnection. :returns: No return value. @@ -2493,6 +2497,8 @@ def on_disconnect(cls, player_id: int, reason: int): it (they are still on the server). .. warning:: Reasons 3 and 4 were added by the open.mp server. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerDisconnect """ return (cls(player_id), reason) @@ -2501,10 +2507,12 @@ def on_spawn(cls, player_id: int): """This event is called when a player spawns. (i.e. after caling :meth:`Player.spawn()`) - :param int player_id: The ID of the player that spawned. + :param Player player: The instance of the player that spawned. :returns: No return value. .. note:: The game sometimes deducts $100 from players after spawn. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerSpawn """ return (cls(player_id),) @@ -2512,9 +2520,9 @@ def on_spawn(cls, player_id: int): def on_death(cls, player_id: int, killer_id: int, reason: int): """This event is called when a player dies. - :param int player_id: The ID of the player that died. - :param int killer_id: The ID of the player that killed the player who - died, or ``INVALID_PLAYER_ID`` if there was none. + :param Player player: The instance of the player that died. + :param Player killer: The instance of the player that killed the + player who died, or ``INVALID_PLAYER_ID`` if there was none. :param int reason: The ID of the reason (weapon id) for the player's death. :returns: No return value. @@ -2533,6 +2541,8 @@ def on_death(cls, player_id: int, killer_id: int, reason: int): .. warning:: You MUST check whether ``killer_id`` is valid (not ``INVALID_PLAYER_ID``) before using it anywhere. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerDeath """ return ( cls(player_id), @@ -2544,7 +2554,7 @@ def on_death(cls, player_id: int, killer_id: int, reason: int): def on_text(cls, player_id: int, text: str): """This event is called when a player sends a chat message. - :param int player_id: The ID of the player who typed the text. + :param Player player: The instance of the player who typed the text. :param str text: The text the player typed. :returns: No return value. @@ -2558,6 +2568,8 @@ def on_text(cls, player_id: int, text: str): def on_player_text(player: Player, text: str): send_client_message_to_all(-1, f"[Text] {text}") return False # Ignore the default text and send the custom one. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerText """ return (cls(player_id), text) @@ -2568,7 +2580,7 @@ def on_command_text(cls, player_id: int, command_text: str): Commands are anything that start with a forward slash, e.g. /help. - :param int player_id: The ID of the player that entered a command. + :param Player player: The instance of the player that entered a command. :param str command_text: The command that was entered (including the forward slash). :returns: No return value. @@ -2585,6 +2597,8 @@ def on_player_command_text(player: Player, cmdtext: str): return player.send_client_message( -1, "SERVER: This is the /help command!" ) + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerCommandText """ return (cls(player_id), command_text) @@ -2593,12 +2607,14 @@ def on_request_class(cls, player_id: int, class_id: int): """This event is called when a player changes class at class selection (and when class selection first appears). - :param int player_id: The ID of the player that changed class. + :param Player player: The instance of the player that changed class. :param int class_id: The ID of the current class being viewed (returned by :meth:`add_player_class`). :returns: No return value. .. note:: This event is also called when a player presses F4. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerRequestClass """ return (cls(player_id), class_id) @@ -2613,9 +2629,10 @@ def on_enter_vehicle( meaning the player is not in vehicle yet at the time this event is called. - :param int player_id: ID of the player who attempts to enter a vehicle. - :param int vehicle_id: ID of the vehicle the player is attempting - to enter. + :param Player player: The instance of the player who attempts to + enter a vehicle. + :param Vehicle vehicle: The instance of the vehicle the player is + attempting to enter. :param bool is_passenger: ``False`` if entering as driver. ``True`` if entering as passenger. :returns: No return value. @@ -2624,6 +2641,8 @@ def on_enter_vehicle( not when they HAVE entered it. See :meth:`Player.on_state_change`. This event is still called if the player is denied entry to the vehicle (e.g. it is locked or full). + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerEnterVehicle """ return (cls(player_id), Vehicle(vehicle_id), is_passenger) @@ -2631,8 +2650,10 @@ def on_enter_vehicle( def on_exit_vehicle(cls, player_id: int, vehicle_id: int): """This event is called when a player starts to exit a vehicle. - :param int player_id: The ID of the player that is exiting a vehicle. - :param int vehicle_id: The ID of the vehicle the player is exiting. + :param Player player: The instance of the player that is + exiting a vehicle. + :param Vehicle vehicle: The instance of the vehicle the player is + exiting. :returns: No return value. .. warning:: Not called if the player falls off a bike or is @@ -2641,6 +2662,8 @@ def on_exit_vehicle(cls, player_id: int, vehicle_id: int): You must use :meth:`Player.on_state_change` and check if their old state is ``PLAYER_STATE_DRIVER`` or ``PLAYER_STATE_PASSENGER``\ and their new state is ``PLAYER_STATE_ONFOOT``. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerExitVehicle """ return (cls(player_id), Vehicle(vehicle_id)) @@ -2651,7 +2674,7 @@ def on_state_change(cls, player_id, new_state: int, old_state: int): For example, when a player changes from being the driver of a vehicle to being on-foot. - :param int player_id: The ID of the player that changed state. + :param Player player: The instance of the player that changed state. :param int new_state: The player's new state. :param int old_state: The player's previous state. :returns: No return value. @@ -2660,6 +2683,8 @@ def on_state_change(cls, player_id, new_state: int, old_state: int): https://www.open.mp/docs/scripting/resources/playerstates .. note:: This event can also be called by NPC. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerStateChange """ return (cls(player_id), new_state, old_state) @@ -2668,10 +2693,13 @@ def on_enter_checkpoint(cls, player_id: int): """This event is called when a player enters the checkpoint set for that player. - :param int player_id: The player who entered the checkpoint. + :param Player player: The instance of player who entered the + checkpoint. :returns: No return value. .. note:: This event can also be called by NPC. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerEnterCheckpoint """ return (cls(player_id),) @@ -2682,10 +2710,13 @@ def on_leave_checkpoint(cls, player_id: int): Only one checkpoint can be set at a time. - :param int player_id: The ID of the player that left their checkpoint. + :param Player player: The instance of the player that left their + checkpoint. :returns: No return value. .. note:: This event can also be called by NPC. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerLeaveCheckpoint """ return (cls(player_id),) @@ -2693,10 +2724,14 @@ def on_leave_checkpoint(cls, player_id: int): def on_enter_race_checkpoint(cls, player_id: int): """This event is called when a player enters a race checkpoint. - :param int player_id: The ID of the player who entered the checkpoint. + :param Player player: The instance of the player who entered the race + checkpoint. :returns: No return value. .. note:: This event can also be called by NPC. + + Wraps: + https://open.mp/docs/scripting/callbacks/OnPlayerEnterRaceCheckpoint """ return (cls(player_id),) @@ -2704,10 +2739,14 @@ def on_enter_race_checkpoint(cls, player_id: int): def on_leave_race_checkpoint(cls, player_id: int): """This event is called when a player leaves the race checkpoint. - :param int player_id: The ID of the player that left the checkpoint. + :param Player player: The instance of the player that left the race + checkpoint. :returns: No return value. .. note:: This event can also be called by NPC. + + Wraps: + https://open.mp/docs/scripting/callbacks/OnPlayerLeaveRaceCheckpoint """ return (cls(player_id),) @@ -2716,10 +2755,13 @@ def on_request_spawn(cls, player_id: int): """This event is called when a player attempts to spawn via class selection either by pressing SHIFT or clicking the 'Spawn' button. - :param int player_id: The ID of the player that requested to spawn. + :param Player player: The instance of the player that requested to + spawn. :returns: No return value. .. note:: This event can also be called by NPC. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerRequestSpawn """ return (cls(player_id),) @@ -2728,10 +2770,12 @@ def on_pick_up_pickup(cls, player_id, pickup_id: int): """This event is called when a player picks up a pickup created with :meth:`Pickup.create()`. - :param int player_id: The ID of the player that picked up the pickup. - :param int pickup_id: The ID of the pickup, returned + :param Player player: The instance of the player that picked up the pickup. + :param Pickup pickup: The instance of the pickup, returned by :meth:`Pickup.create()`. :returns: No return value. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerPickUpPickup """ return (cls(player_id), Pickup(pickup_id)) @@ -2739,7 +2783,8 @@ def on_pick_up_pickup(cls, player_id, pickup_id: int): def on_selected_menu_row(cls, player_id: int, row: int): """This event is called when a player selects an item from a menu. - :param int player_id: The ID of the player that selected a menu item. + :param Player player: The instance of the player that selected a + menu item. :param int row: The ID of the row that was selected. The first row is ID 0. :returns: No return value. @@ -2747,6 +2792,8 @@ def on_selected_menu_row(cls, player_id: int, row: int): .. note:: The menu ID is not passed to this event. :meth:`Menu.get_player_menu()` must be used to determine which menu the player selected an item on. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerSelectedMenuRow """ return (cls(player_id), row) @@ -2754,8 +2801,10 @@ def on_selected_menu_row(cls, player_id: int, row: int): def on_exited_menu(cls, player_id: int): """This event is called when a player exits a menu. - :param int player_id: The ID of the player that exited the menu. + :param Player player: The instance of the player that exited the menu. :returns: No return value. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerExitedMenu """ return (cls(player_id),) @@ -2770,10 +2819,12 @@ def on_interior_change( Can be triggered by :meth:`Player.set_interior()` or when a player enter / exits a building. - :param int player_id: The player_id who changed interior. + :param Player player: The instance of player who changed interior. :param int new_interior_id: The interior the player is now in. :param int old_interior_id: The interior the player was in before. :returns: No return value. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerInteriorChange """ return (cls(player_id), new_interior_id, old_interior_id) @@ -2784,8 +2835,8 @@ def on_key_state_change(cls, player_id: int, new_keys: int, old_keys: int): Directional keys do not trigger this event (up/down/left/right). - :param int player_id: The ID of the player that - pressed or released a key. + :param Player player: The instance of the player that pressed or + released a key. :param int new_interior_id: A map (bitmask) of the keys currently held. :param int old_interior_id: A map (bitmask) of the keys held prior to the current change. @@ -2794,6 +2845,8 @@ def on_key_state_change(cls, player_id: int, new_keys: int, old_keys: int): List of keys: https://www.open.mp/docs/scripting/resources/keys .. note:: This event can also be called by NPC. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerKeyStateChange """ return (cls(player_id), new_keys, old_keys) @@ -2804,7 +2857,8 @@ def on_update(cls, player_id: int): for client updates that aren't actively tracked by the server, such as health or armor updates or players switching weapons. - :param int player_id: ID of the player sending an update packet. + :param Player player: The instance of the player sending an + update packet. :returns: No return value. .. note:: This event can also be called by NPC. @@ -2815,6 +2869,8 @@ def on_update(cls, player_id: int): The frequency with which this event is called for each player varies, depending on what the player is doing. Driving or shooting will trigger a lot more updates than idling. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerUpdate """ return (cls(player_id),) @@ -2823,12 +2879,14 @@ def on_stream_in(cls, player_id: int, for_player_id: int): """This event is called when a player is streamed by some other player's client. - :param int player_id: The ID of the player who has been streamed. - :param int for_player_id: The ID of the player that streamed the + :param Player player: The instance of the player who has been streamed. + :param Player for_player: The instance of the player that streamed the other player in. :returns: No return value. .. note:: This event can also be called by NPC. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerStreamIn """ return (cls(player_id), cls(for_player_id)) @@ -2837,15 +2895,18 @@ def on_stream_out(cls, player_id: int, for_player_id: int): """This event is called when a player is streamed out from some other player's client. - :param int player_id: The player who has been destreamed. - :param int for_player_id: The player who has destreamed the - other player. + :param Player player: The instance of the player who has been + destreamed. + :param Player for_player: The instance of the player who has + destreamed the other player. :returns: No return value. .. note:: This event can also be called by NPC. .. warning:: The event is not called for both players when a player disconnects. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerStreamOut """ return (cls(player_id), cls(for_player_id)) @@ -2860,8 +2921,9 @@ def on_take_damage( ): """This event is called when a player takes damage. - :param int player_id: The ID of the player that took damage. - :param int issuer_id: The ID of the player that caused the damage. + :param Player player: The instance of the player that took damage. + :param Player issuer: The instance of the player that caused + the damage. ``INVALID_PLAYER_ID`` if self-inflicted. :param float amount: The amount of damage the player took (health and armour combined). @@ -2889,6 +2951,8 @@ def on_take_damage( - :meth:`Player.get_health()` and :meth:`Player.get_armour()` will return the old amounts of the player before this event. - Always check if issuer_id is valid before. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerTakeDamage """ return ( cls(player_id), @@ -2909,8 +2973,8 @@ def on_give_damage( ): """This event is called when a player gives damage to another player. - :param int player_id: The ID of the player that gave damage. - :param int damaged_id: The ID of the player that received damage. + :param Player player: The instance of the player that gave damage. + :param Player damaged: The instance of the player that received damage. :param float amount: The amount of health / armour damaged_id has lost (combined). :param int weapon_id: The reason that caused the damage. @@ -2935,6 +2999,8 @@ def on_give_damage( to kill that player. All 3 shots will show an amount of 46.2, even though when the last shot hits, the player only has 7.6 health left. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerGiveDamage """ return ( cls(player_id), @@ -2955,8 +3021,9 @@ def on_give_damage_actor( ): """This event is called when a player gives damage to an actor. - :param int player_id: The ID of the player that gave damage. - :param int damaged_actor_id: The ID of the actor that received damage + :param Player player: The instance of the player that gave damage. + :param Actor damaged_actor: The instance of the actor that + received damage :param float amount: The amount of health / armour actor has lost. :param int weapon_id: The reason that caused the damage. :param int body_part: The body part that was hit @@ -2967,6 +3034,8 @@ def on_give_damage_actor( .. note:: This event does not get called if the actor is set invulnerable (WHICH IS BY DEFAULT). See :meth:`Actor.set_invulnerable()`. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerGiveDamageActor """ return ( cls(player_id), @@ -2981,12 +3050,14 @@ def on_click_map(cls, player_id: int, x: float, y: float, z: float): """This event is called when a player places a target/waypoint on the pause menu map (by right-clicking). - :param int player_id: The ID of the player that placed a + :param Player player: The instance of the player that placed a target / waypoint. :param float x: The X float coordinate where the player clicked. :param float y: The Y float coordinate where the player clicked. :param float z: The Z float coordinate where the player clicked. :returns: No return value. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerClickMap """ return (cls(player_id), x, y, z) @@ -2995,8 +3066,9 @@ def on_click_textdraw(cls, player_id: int, clicked_id: int): """This event is called when a player clicks on a textdraw or cancels the select mode with the Escape key. - :param int player_id: The ID of the player clicked on the textdraw. - :param int clicked_id: The ID of the clicked textdraw. + :param Player player: The instance of the player clicked on the + textdraw. + :param TextDraw clicked: The instance of the clicked textdraw. ``INVALID_TEXT_DRAW`` if selection was cancelled. :returns: No return value. @@ -3006,6 +3078,8 @@ def on_click_textdraw(cls, player_id: int, clicked_id: int): must not be zero or negative. Do not use :meth:`TextDraw.cancel_select()` unconditionally within this event. This results in an infinite loop. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerClickTextDraw """ return (cls(player_id), TextDraw(clicked_id)) @@ -3015,8 +3089,9 @@ def on_click_playertextdraw(cls, player_id: int, player_text_id: int): It is not called when player cancels the select mode (ESC) however, :meth:`Player.on_click_textdraw()` is. - :param int player_id: The ID of the player that selected a textdraw. - :param int player_text_id: The ID of the player-textdraw + :param Player player: The instance of the player that selected a + textdraw. + :param PlayerTextDraw player_text: The instance of the player-textdraw that the player selected. :returns: No return value. @@ -3025,6 +3100,9 @@ def on_click_playertextdraw(cls, player_id: int, player_text_id: int): :meth:`Player.on_click_textdraw()` is called with a textdraw ID of ``INVALID_TEXT_DRAW``.\ :meth:`Player.on_click_playertextdraw()` won't be called also. + + Wraps: + https://open.mp/docs/scripting/callbacks/OnPlayerClickPlayerTextDraw """ return (cls(player_id), PlayerTextDraw(player_text_id, cls(player_id))) @@ -3033,9 +3111,10 @@ def on_click_player(cls, player_id: int, clicked_player_id: int, source: int): """This event is called when a player double-clicks on a player on the scoreboard. - :param int player_id: The ID of the player that clicked on a player + :param Player player: The instance of the player that clicked on a player on the scoreboard. - :param int clickedplayer_id: The ID of the player that was clicked on. + :param Player clickedplayer: The instance of the player that was + clicked on. :param int source: The source of the player's click. :returns: No return value. @@ -3044,6 +3123,8 @@ def on_click_player(cls, player_id: int, clicked_player_id: int, source: int): (0 - ``CLICK_SOURCE_SCOREBOARD``). The existence of this argument suggests that more sources may be supported in the future. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerClickPlayer """ return (cls(player_id), cls(clicked_player_id), source) @@ -3063,10 +3144,10 @@ def on_edit_object( ): """This event is called when a player finishes editing an object. - :param int player_id: The ID of the player that edited an object. + :param Player player: The instance of the player that edited an object. :param bool is_player_object: `False` if it is a global object or `True` if it is a playerobject. - :param int object_id: The ID of the edited object. + :param PlayerObject / Object object: The instance of the edited object. :param int response: The type of response. :param float x: The X offset for the object that was edited. :param float y: The Y offset for the object that was edited. @@ -3081,6 +3162,8 @@ def on_edit_object( not be called when releasing an edit in progress resulting in the last update of ``EDIT_RESPONSE_UPDATE`` being out of sync of the objects current position. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerEditObject """ return ( cls(player_id), @@ -3115,7 +3198,8 @@ def on_edit_attached_object( """This event is called when a player ends attached object edition mode. - :param int player_id: The ID of the player that ended edition mode. + :param Player player: The instance of the player that ended + edition mode. :param int response: ``0`` if cancelled (ESC) or ``1`` if clicked the save icon. :param int index: The index of the object (0-9). @@ -3136,6 +3220,9 @@ def on_edit_attached_object( Editions should be discarded if response was ``0``' (cancelled). This must be done by storing the offsets etc. BEFORE using :meth:`Player.edit_attached_object()`. + + Wraps: + https://open.mp/docs/scripting/callbacks/OnPlayerEditAttachedObject """ return ( cls(player_id), @@ -3167,9 +3254,11 @@ def on_select_object( ): """This event is called when a player selects an object. - :param int player_id: The ID of the player that selected an object. + :param Player player: The instance of the player that selected an + object. :param int type: The type of selection. - :param int object_id: The ID of the selected object. + :param PlayerObject / Object object: The instance of the selected + object. :param int model_id: The model of the selected object. :param float x: The X position of the selected object. :param float y: The Y position of the selected object. @@ -3185,6 +3274,8 @@ def on_select_object( - ``SELECT_OBJECT_GLOBAL_OBJECT`` * - 2 - ``SELECT_OBJECT_PLAYER_OBJECT`` + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerSelectObject """ object_cls = { SELECT_OBJECT_GLOBAL_OBJECT: Object, @@ -3217,11 +3308,11 @@ def on_weapon_shot( Only passenger drive-by is supported (not driver drive-by, and not sea sparrow / hunter shots). - :param int player_id: The ID of the player that shot a weapon. + :param Player player: The instance of the player that shot a weapon. :param int weapon_id: The ID of the weapon shot by the player. :param int hit_type: The type of thing the shot hit. - :param int hit_id: The ID of the player, vehicle or object that - was hit. + :param Vehicle / Object / PlayerObject hit: The instance of the player, + vehicle or object that was hit. :param float x: The X coordinate that the shot hit. :param float y: The X coordinate that the shot hit. :param float z: The X coordinate that the shot hit. @@ -3272,6 +3363,8 @@ def on_weapon_shot( by a malicious user, other player clients may freeze or crash. To combat this, check if the reported weapon_id can actually fire bullets. + + Wraps: https://open.mp/docs/scripting/callbacks/OnPlayerWeaponShot """ hit_cls = { BULLET_HIT_TYPE_NONE: lambda _: None,