From 2d6a6c0698b1fd203cd6643cfd4371d23f3d062d Mon Sep 17 00:00:00 2001 From: Dan <55022836+Ykpauneu@users.noreply.github.com> Date: Wed, 6 Mar 2024 21:19:32 +0300 Subject: [PATCH 1/4] Documentation for callbacks --- pysamp/actor.py | 20 +++ pysamp/object.py | 8 + pysamp/pickup.py | 1 - pysamp/player.py | 338 ++++++++++++++++++++++++++++++++++++++++- pysamp/playerobject.py | 7 + pysamp/vehicle.py | 145 +++++++++++++++++- 6 files changed, 516 insertions(+), 3 deletions(-) diff --git a/pysamp/actor.py b/pysamp/actor.py index 7df122d..919fec4 100644 --- a/pysamp/actor.py +++ b/pysamp/actor.py @@ -141,10 +141,30 @@ def is_valid(self) -> bool: @event("OnActorStreamIn") def on_stream_in(cls, actorid: int, forplayerid: int): + """This callbackis called when an actor is streamed in\ + by a player's client. + + :param int actorid: The ID of the actor. + :param int forplayerid: The ID of the player\ + that streamed the actor in. + :returns: No return value. + + .. note:: This callbackcan also be called by NPC. + """ return (cls(actorid), Player(forplayerid)) @event("OnActorStreamOut") def on_stream_out(cls, actorid: int, forplayerid: int): + """This callbackis called when an actor is streamed\ + out by a player's client. + + :param int actorid: The ID of the actor. + :param int forplayerid: The ID of the player\ + that streamed the actor out. + :returns: No return value. + + .. note:: This callbackcan also be called by NPC. + """ return (cls(actorid), Player(forplayerid)) from pysamp.player import Player # noqa \ No newline at end of file diff --git a/pysamp/object.py b/pysamp/object.py index 3353118..0f976f8 100644 --- a/pysamp/object.py +++ b/pysamp/object.py @@ -240,4 +240,12 @@ def set_default_camera_col(disable: bool) -> bool: @event("OnObjectMoved") def on_moved(cls, objectid: int): + """This callbackis called when an object stops moving after :meth:`move`. + + :param int objectid: 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(objectid),) diff --git a/pysamp/pickup.py b/pysamp/pickup.py index 326dccd..abadc17 100644 --- a/pysamp/pickup.py +++ b/pysamp/pickup.py @@ -1,6 +1,5 @@ from pysamp import ( create_pickup, destroy_pickup, - # add_static_pickup ) diff --git a/pysamp/player.py b/pysamp/player.py index d21eb1d..257a313 100644 --- a/pysamp/player.py +++ b/pysamp/player.py @@ -1848,7 +1848,7 @@ def set_camera_look_at( def set_camera_behind(self) -> bool: """Restore the camera to a place behind the player, after using ex. - :py:meth:`Player.set_camera_pos`. + :meth:`Player.set_camera_pos`. :returns: This method does not return anything. """ @@ -2435,22 +2435,99 @@ def attach_camera_to_player_object( def on_enter_exit_mod_shop( cls, playerid: int, enterexit: int, interiorid: int ): + """This callbackis called when a player enters or exits a mod shop. + + :param int playerid: The ID of the player that entered/exited the modshop. + :param int enterexit: 1 if the player entered or 0 if they exited. + :param int interiorid: 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(playerid), enterexit, interiorid) @event("OnPlayerConnect") def on_connect(cls, playerid: int): + """This callbackis called when a player connects to the server. + + :param int playerid: The ID of the player that connected. + :returns: No return value. + + ..note:: This callback can also be called by NPC. + """ return (cls(playerid),) @event("OnPlayerDisconnect") def on_disconnect(cls, playerid: int, reason: int): + """This callbackis called when a player disconnects from the server. + + :param int playerid: 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(playerid), reason) @event("OnPlayerSpawn") def on_spawn(cls, playerid: int): + """This callbackis called when a player spawns. + (i.e. after caling :meth:`spawn`) + + :param int playerid: The ID of the player that spawned. + :returns: No return value. + + .. note:: The game sometimes deducts $100 from players after spawn. + """ return (cls(playerid),) @event("OnPlayerDeath") def on_death(cls, playerid: int, killerid: int, reason: int): + """This callbackis called when a player dies. + + :param int playerid: The ID of the player that died. + :param int killerid: 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/weaponids + + .. 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 killerid is valid before using it in :meth:`send_death_message`. + ``INVALID_PLAYER_ID`` is a valid killerid ID parameter in that function. + playerid is the only one who can call the event. (good to know for anti fake death) + + .. warning:: You MUST check whether ``killerid`` is valid (not ``INVALID_PLAYER_ID``) + before using it anywhere. + """ return ( cls(playerid), killerid if killerid == INVALID_PLAYER_ID else cls(killerid), @@ -2459,14 +2536,57 @@ def on_death(cls, playerid: int, killerid: int, reason: int): @event("OnPlayerText") def on_text(cls, playerid: int, text: str): + """This callbackis called when a player sends a chat message. + + :param int playerid: The ID of the player who typed the text. + :param str text: The text the player typed. + :returns: No return value. + + .. note:: This callbackcan 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(playerid), text) @event("OnPlayerCommandText") def on_command_text(cls, playerid: int, command_text: str): + """This callback 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 playerid: 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 callbackcan 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(playerid), command_text) @event("OnPlayerRequestClass") def on_request_class(cls, playerid: int, classid: int): + """This callbackis called when a player changes class at class selection + (and when class selection first appears). + + :param int playerid: The ID of the player that changed class. + :param int classid: The ID of the current class being viewed + (returned by :meth:`add_player_class`). + :returns: No return value. + + .. note:: This callbackis also called when a player presses F4. + """ return (cls(playerid), classid) @event("OnPlayerEnterVehicle") @@ -2476,22 +2596,73 @@ def on_enter_vehicle( vehicleid: int, is_passenger: bool, ): + """This callback is called when a player starts to enter a vehicle, + meaning the player is not in vehicle yet at the time this callback is called. + + :param int playerid: ID of the player who attempts to enter a vehicle. + :param int vehicleid: 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 callback is called when a player BEGINS to enter a vehicle, + not when they HAVE entered it. See :meth:`Player.on_state_change`. + This callback is still called if the player is denied entry to the vehicle + (e.g. it is locked or full). + """ return (cls(playerid), Vehicle(vehicleid), is_passenger) @event("OnPlayerExitVehicle") def on_exit_vehicle(cls, playerid: int, vehicleid: int): + """This callback is called when a player starts to exit a vehicle. + + :param int playerid: The ID of the player that is exiting a vehicle. + :param int vehicleid: 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:`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(playerid), Vehicle(vehicleid)) @event("OnPlayerStateChange") def on_state_change(cls, playerid, newstate: int, oldstate: int): + """This callback 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 playerid: The ID of the player that changed state. + :param int newstate: The player's new state. + :param int oldstate: 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 callbackcan also be called by NPC. + """ return (cls(playerid), newstate, oldstate) @event("OnPlayerEnterCheckpoint") def on_enter_checkpoint(cls, playerid: int): + """This callback is called when a player enters the checkpoint set for that player. + + :param int playerid: The player who entered the checkpoint. + :returns: No return value. + + .. note:: This callbackcan also be called by NPC. + """ return (cls(playerid),) @event("OnPlayerLeaveCheckpoint") def on_leave_checkpoint(cls, playerid: int): + """This callback is called when a player leaves the checkpoint set for them + by :meth:`set_checkpoint`. Only one checkpoint can be set at a time. + + :param int playerid: The ID of the player that left their checkpoint. + :returns: No return value. + + .. note:: This callbackcan also be called by NPC. + """ return (cls(playerid),) @event("OnPlayerEnterRaceCheckpoint") @@ -2596,18 +2767,68 @@ def on_give_damage_actor( @event("OnPlayerClickMap") def on_click_map(cls, playerid: int, x: float, y: float, z: float): + """This callbackis called when a player places a target/waypoint + on the pause menu map (by right-clicking). + + :param int playerid: 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(playerid), x, y, z) @event("OnPlayerClickTextDraw") def on_click_textdraw(cls, playerid: int, clickedid: int): + """This callback is called when a player clicks on a textdraw\ + or cancels the select mode with the Escape key. + + :param int playerid: The ID of the player that clicked on the textdraw. + :param int clickedid: 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 callback. + This results in an infinite loop. + """ return (cls(playerid), TextDraw(clickedid)) @event("OnPlayerClickPlayerTextDraw") def on_click_playertextdraw(cls, playerid: int, playertextid: int): + """This callback 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 playerid: The ID of the player that selected a textdraw. + :param int playertextid: 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(playerid), PlayerTextDraw(playertextid, cls(playerid))) @event("OnPlayerClickPlayer") def on_click_player(cls, playerid: int, clickedplayerid: int, source: int): + """This callback is called when a player double-clicks\ + on a player on the scoreboard. + + :param int playerid: The ID of the player\ + that clicked on a player on the scoreboard. + :param int clickedplayerid: 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(playerid), cls(clickedplayerid), source) @event("OnPlayerEditObject") @@ -2624,6 +2845,25 @@ def on_edit_object( rot_y: float, rot_z: float, ): + """This callback is called when a player finishes editing an object. + + :param int playerid: The ID of the player that edited an object. + :param bool is_playerobject: `False` if it is a global object or `True` if it is a playerobject. + :param int objectid: 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 callback 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), @@ -2654,6 +2894,28 @@ def on_edit_attached_object( scale_y: float, scale_z: float, ): + """This callback is called when a player ends attached object edition mode. + + :param int playerid: 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 attached object (0-9). + :param int modelid: The model of the attached object that was edited. + :param int boneid: The bone of the attached object that was edited. + :param float offset_x: The X offset for the attached object that was edited. + :param float offset_y: The Y offset for the attached object that was edited. + :param float offset_z: The Z offset for the attached object that was edited. + :param float rot_x: The X rotation for the attached object that was edited. + :param float rot_y: The Y rotation for the attached object that was edited. + :param float rot_z: The Z rotation for the attached object that was edited. + :param float scale_x: The X scale for the attached object that was edited. + :param float scale_y: The Y scale for the attached object that was edited. + :param float scale_z: The Z scale for the attached 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), response, @@ -2682,6 +2944,27 @@ def on_select_object( y: float, z: float, ): + """This callback is called when a player selects an object. + + :param int playerid: The ID of the player that selected an object. + :param int type: The type of selection. + :param int objectid: The ID of the selected object. + :param int modelid: 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, @@ -2706,6 +2989,59 @@ def on_weapon_shot( y: float, z: float, ): + """This callback 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 playerid: The ID of the player that shot a weapon. + :param int weaponid: The ID of the weapon shot by the player. + :param int hittype: The type of thing the shot hit. + :param int hitid: 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/weaponids + + .. 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 callback is only called when lag compensation is enabled. If hittype 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 hitid. + + .. note:: + :meth:`Player.get_last_shot_vectors()`\ + can be used in this callback 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 (shooting in air). + It is called as ``BULLET_HIT_TYPE_VEHICLE`` with the correct hitid (the hit player's vehicleid)\ + 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 weaponid can actually fire bullets. + """ hit_cls = { BULLET_HIT_TYPE_NONE: lambda _: None, BULLET_HIT_TYPE_PLAYER: cls, diff --git a/pysamp/playerobject.py b/pysamp/playerobject.py index c06d5fc..93595ff 100644 --- a/pysamp/playerobject.py +++ b/pysamp/playerobject.py @@ -391,6 +391,13 @@ def set_material( @event("OnPlayerObjectMoved") def on_moved(cls, playerid: int, objectid: int): + """This callback is called when a player object is moved after\ + :meth:`PlayerObject.move()` (when it stops moving). + + :param int playerid: The playerid the object is assigned to. + :param int objectid: The ID of the player object that was moved. + :returns: No return value. + """ return (cls(objectid, playerid), Player(playerid)) from pysamp.player import Player # noqa diff --git a/pysamp/vehicle.py b/pysamp/vehicle.py index 1b14ddd..067ba02 100644 --- a/pysamp/vehicle.py +++ b/pysamp/vehicle.py @@ -359,14 +359,49 @@ def set_virtual_world(self, world_id: int) -> bool: @event("OnTrailerUpdate") def on_trailer_update(cls, playerid: int, trailerid: int): + """This callback is called when a player sent a trailer update. + + :param int playerid: The ID of the player who sent a trailer updat. + :param int trailerid: The trailer being updated. + :returns: No return value. + + .. warning:: + This callback is called very frequently per second per trailer. + You should refrain from implementing intensive calculations\ + or intensive file writing/reading operations in this callback. + """ return (Player(playerid), cls(trailerid)) @event("OnVehicleDamageStatusUpdate") def on_damage_status_update(cls, vehicleid: int, playerid: int): + """This callback is called when a vehicle element such as\ + doors, tyres, panels, or lights change their damage status. + + :param int vehicleid: The ID of the vehicle that was changed its damage status. + :param int playerid: 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(vehicleid), Player(playerid)) @event("OnVehicleDeath") def on_death(cls, vehicleid: int, killerid: int): + """This callback is called when a vehicle\ + is destroyed - either by exploding or becoming submerged in water. + + :param int vehicleid: The ID of the vehicle that was destroyed. + :param int killerid: 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 callback will also be called when a vehicle enters water,\ + but the vehicle can be saved from destruction by teleportation or driving out. + The callback 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, @@ -374,35 +409,105 @@ def on_death(cls, vehicleid: int, killerid: int): @event("OnVehicleMod") def on_mod(cls, playerid: int, vehicleid: int, componentid: int): + """This callback is called when a vehicle is modded. + + :param int playerid: The ID of the driver of the vehicle. + :param int vehicleid: The ID of the vehicle which is modded. + :param int componentid: The ID of the component which was added to the vehicle. + :returns: No return value. + + .. note:: This callback is NOT called by :meth:`Vehicle.add_component()`. + """ return (Player(playerid), cls(vehicleid), componentid) @event("OnVehiclePaintjob") def on_paintjob(cls, playerid: int, vehicleid: int, paintjobid: int): + """This callback is called when a player previews a vehicle paintjob inside a mod shop. + Watch out, this callback is not called when the player buys the paintjob. + + :param int playerid: The ID of the player that changed the paintjob of their vehicle. + :param int vehicleid: The ID of the vehicle that had its paintjob changed. + :param int paintjobid: The ID of the new paintjob. + :returns: No return value. + + .. note:: This callback is not called by :meth:`Vehicle.change_paintjob()`. + """ return (Player(playerid), cls(vehicleid), paintjobid) @event("OnVehicleRespray") def on_respray( cls, playerid: int, vehicleid: int, color1: int, color2: int ): + """This callback 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 callback. + + :param int playerid: The ID of the player that is driving the vehicle. + :param int vehicleid: 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 primary color was changed to. + :returns: No return value. + + .. note:: + This callback is not called by :meth:`Vehicle.change_color()`. + Misleadingly, this callback is not called for pay 'n' spray (only modshops). + + .. warning:: + Known Bug(s): previewing a component inside a mod shop might call this callback. + """ return (Player(playerid), cls(vehicleid), color1, color2) @event("OnVehicleSirenStateChange") def on_siren_state_change( cls, playerid: int, vehicleid: int, newstate: int ): + """This callback is called when a vehicle's siren is toggled. + + :param int playerid: The ID of the player that toggled the siren (driver). + :param int vehicleid: The ID of the vehicle of which the siren was toggled for. + :param int newstate: ``0`` if siren was turned off, ``1`` if siren was turned on. + :returns: No return value. + + .. note:: + This callback is only called when a vehicle's siren is toggled on or off,\ + NOT when the alternate siren is in use (holding horn). + + """ return (Player(playerid), cls(vehicleid), newstate) @event("OnVehicleSpawn") def on_spawn(cls, vehicleid: int): - """When a vehicle is respawning only.""" + """This callback is called when a vehicle respawns. + + :param int vehicleid: The ID of the vehicle that spawned. + :returns: No return value. + + .. warning:: + This callback is called only when vehicle respawns! + :meth:`Vehicle.create()` and :meth:`add_static_vehicle/ex` won't trigger this callback. + """ return (cls(vehicleid),) @event("OnVehicleStreamIn") def on_stream_in(cls, vehicleid: int, forplayerid: int): + """This callback is called when a vehicle\ + is streamed to a player's client. + + :param int vehicleid: The ID of the vehicle that streamed in for the player. + :param int forplayerid: The ID of the player who the vehicle streamed in for. + :returns: No return value. + """ return (cls(vehicleid), Player(forplayerid)) @event("OnVehicleStreamOut") def on_stream_out(cls, vehicleid: int, forplayerid: int): + """This callback is called when a vehicle\ + is streamed out for a player's client + + :param int vehicleid: The ID of the vehicle that streamed out. + :param int forplayerid: The ID of the player who is no longer streaming the vehicle. + :returns: No return value. + """ return (cls(vehicleid), Player(forplayerid)) @event("OnUnoccupiedVehicleUpdate") @@ -418,6 +523,44 @@ def on_unoccupied_update( vel_y: float, vel_z: float, ): + """This callback 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 vehicleid: The ID of the vehicle that's position was updated. + :param int playerid: 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 callback is called very frequently per second per unoccupied vehicle. + You should refrain from implementing intensive calculations or intensive file\ + writing/reading operations in this callback. + :meth:`Vehicle.get_pos()` will return the old coordinates of the vehicle before this update. + """ return ( cls(vehicleid), Player(playerid), From a746424b9c9dfacfa14074d8b2a29459f37091db Mon Sep 17 00:00:00 2001 From: Dan <55022836+Ykpauneu@users.noreply.github.com> Date: Thu, 16 May 2024 04:40:01 +0300 Subject: [PATCH 2/4] typo error fix --- pysamp/actor.py | 4 ++-- pysamp/object.py | 2 +- pysamp/player.py | 18 +++++++++--------- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/pysamp/actor.py b/pysamp/actor.py index 919fec4..0b84eb4 100644 --- a/pysamp/actor.py +++ b/pysamp/actor.py @@ -141,7 +141,7 @@ def is_valid(self) -> bool: @event("OnActorStreamIn") def on_stream_in(cls, actorid: int, forplayerid: int): - """This callbackis called when an actor is streamed in\ + """This callback is called when an actor is streamed in\ by a player's client. :param int actorid: The ID of the actor. @@ -155,7 +155,7 @@ def on_stream_in(cls, actorid: int, forplayerid: int): @event("OnActorStreamOut") def on_stream_out(cls, actorid: int, forplayerid: int): - """This callbackis called when an actor is streamed\ + """This callback is called when an actor is streamed\ out by a player's client. :param int actorid: The ID of the actor. diff --git a/pysamp/object.py b/pysamp/object.py index 0f976f8..5a3ae26 100644 --- a/pysamp/object.py +++ b/pysamp/object.py @@ -240,7 +240,7 @@ def set_default_camera_col(disable: bool) -> bool: @event("OnObjectMoved") def on_moved(cls, objectid: int): - """This callbackis called when an object stops moving after :meth:`move`. + """This callback is called when an object stops moving after :meth:`move`. :param int objectid: The ID of the object that was moved. :returns: No return value. diff --git a/pysamp/player.py b/pysamp/player.py index 257a313..0628ad3 100644 --- a/pysamp/player.py +++ b/pysamp/player.py @@ -2435,7 +2435,7 @@ def attach_camera_to_player_object( def on_enter_exit_mod_shop( cls, playerid: int, enterexit: int, interiorid: int ): - """This callbackis called when a player enters or exits a mod shop. + """This callback is called when a player enters or exits a mod shop. :param int playerid: The ID of the player that entered/exited the modshop. :param int enterexit: 1 if the player entered or 0 if they exited. @@ -2449,7 +2449,7 @@ def on_enter_exit_mod_shop( @event("OnPlayerConnect") def on_connect(cls, playerid: int): - """This callbackis called when a player connects to the server. + """This callback is called when a player connects to the server. :param int playerid: The ID of the player that connected. :returns: No return value. @@ -2460,7 +2460,7 @@ def on_connect(cls, playerid: int): @event("OnPlayerDisconnect") def on_disconnect(cls, playerid: int, reason: int): - """This callbackis called when a player disconnects from the server. + """This callback is called when a player disconnects from the server. :param int playerid: The ID of the player that disconnected. :param int reason: The reason for the disconnection. @@ -2497,7 +2497,7 @@ def on_disconnect(cls, playerid: int, reason: int): @event("OnPlayerSpawn") def on_spawn(cls, playerid: int): - """This callbackis called when a player spawns. + """This callback is called when a player spawns. (i.e. after caling :meth:`spawn`) :param int playerid: The ID of the player that spawned. @@ -2509,7 +2509,7 @@ def on_spawn(cls, playerid: int): @event("OnPlayerDeath") def on_death(cls, playerid: int, killerid: int, reason: int): - """This callbackis called when a player dies. + """This callback is called when a player dies. :param int playerid: The ID of the player that died. :param int killerid: The ID of the player that killed @@ -2536,7 +2536,7 @@ def on_death(cls, playerid: int, killerid: int, reason: int): @event("OnPlayerText") def on_text(cls, playerid: int, text: str): - """This callbackis called when a player sends a chat message. + """This callback is called when a player sends a chat message. :param int playerid: The ID of the player who typed the text. :param str text: The text the player typed. @@ -2577,7 +2577,7 @@ def on_player_command_text(player: Player, cmdtext: str): @event("OnPlayerRequestClass") def on_request_class(cls, playerid: int, classid: int): - """This callbackis called when a player changes class at class selection + """This callback is called when a player changes class at class selection (and when class selection first appears). :param int playerid: The ID of the player that changed class. @@ -2585,7 +2585,7 @@ def on_request_class(cls, playerid: int, classid: int): (returned by :meth:`add_player_class`). :returns: No return value. - .. note:: This callbackis also called when a player presses F4. + .. note:: This callback is also called when a player presses F4. """ return (cls(playerid), classid) @@ -2767,7 +2767,7 @@ def on_give_damage_actor( @event("OnPlayerClickMap") def on_click_map(cls, playerid: int, x: float, y: float, z: float): - """This callbackis called when a player places a target/waypoint + """This callback is called when a player places a target/waypoint on the pause menu map (by right-clicking). :param int playerid: The ID of the player that placed a target/waypoint. From 4c443e7fa7c235d55dcdec75304e2a9adcaaa400 Mon Sep 17 00:00:00 2001 From: Dan <55022836+Ykpauneu@users.noreply.github.com> Date: Thu, 16 May 2024 15:56:38 +0300 Subject: [PATCH 3/4] typo fix (again) --- pysamp/actor.py | 4 ++-- pysamp/player.py | 10 +++++----- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/pysamp/actor.py b/pysamp/actor.py index 0b84eb4..273e5c6 100644 --- a/pysamp/actor.py +++ b/pysamp/actor.py @@ -149,7 +149,7 @@ def on_stream_in(cls, actorid: int, forplayerid: int): that streamed the actor in. :returns: No return value. - .. note:: This callbackcan also be called by NPC. + .. note:: This callback can also be called by NPC. """ return (cls(actorid), Player(forplayerid)) @@ -163,7 +163,7 @@ def on_stream_out(cls, actorid: int, forplayerid: int): that streamed the actor out. :returns: No return value. - .. note:: This callbackcan also be called by NPC. + .. note:: This callback can also be called by NPC. """ return (cls(actorid), Player(forplayerid)) diff --git a/pysamp/player.py b/pysamp/player.py index 0628ad3..41ec32e 100644 --- a/pysamp/player.py +++ b/pysamp/player.py @@ -2542,7 +2542,7 @@ def on_text(cls, playerid: int, text: str): :param str text: The text the player typed. :returns: No return value. - .. note:: This callbackcan also be called by NPC. + .. note:: This callback can also be called by NPC. Example: @@ -2563,7 +2563,7 @@ def on_command_text(cls, playerid: int, command_text: str): :param str command_text: The command that was entered (including the forward slash). :returns: No return value. - .. note:: This callbackcan also be called by NPC. + .. note:: This callback can also be called by NPC. Example: @@ -2638,7 +2638,7 @@ def on_state_change(cls, playerid, newstate: int, oldstate: int): List of all available player states: https://www.open.mp/docs/scripting/resources/playerstates - .. note:: This callbackcan also be called by NPC. + .. note:: This callback can also be called by NPC. """ return (cls(playerid), newstate, oldstate) @@ -2649,7 +2649,7 @@ def on_enter_checkpoint(cls, playerid: int): :param int playerid: The player who entered the checkpoint. :returns: No return value. - .. note:: This callbackcan also be called by NPC. + .. note:: This callback can also be called by NPC. """ return (cls(playerid),) @@ -2661,7 +2661,7 @@ def on_leave_checkpoint(cls, playerid: int): :param int playerid: The ID of the player that left their checkpoint. :returns: No return value. - .. note:: This callbackcan also be called by NPC. + .. note:: This callback can also be called by NPC. """ return (cls(playerid),) From 1b7e7179e5fefb56b443284309513f720c6f40fc Mon Sep 17 00:00:00 2001 From: Dan <55022836+Ykpauneu@users.noreply.github.com> Date: Thu, 16 May 2024 16:28:52 +0300 Subject: [PATCH 4/4] Sphinx fixes --- pysamp/object.py | 4 ++-- pysamp/player.py | 3 +++ 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/pysamp/object.py b/pysamp/object.py index 5a3ae26..ad570e9 100644 --- a/pysamp/object.py +++ b/pysamp/object.py @@ -245,7 +245,7 @@ def on_moved(cls, objectid: int): :param int objectid: 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. + .. note:: :meth:`set_position` does not work when used in this\ + event. To fix it, recreate the object. """ return (cls(objectid),) diff --git a/pysamp/player.py b/pysamp/player.py index 41ec32e..89a2a33 100644 --- a/pysamp/player.py +++ b/pysamp/player.py @@ -1747,6 +1747,7 @@ def set_marker(self, showplayer: "Player", color: int) -> bool: :param showplayer: The player that should see the change. :param color: The desired color in RGBA/Hex/Int format. This should only be used with the square icon (ID: 0). + :return: Returns nothing. .. code-block:: python @@ -2547,6 +2548,7 @@ def on_text(cls, playerid: int, text: str): Example: .. code-block:: python + @Player.on_text def on_player_text(player: Player, text: str): send_client_message_to_all(-1, f"[Text] {text}") @@ -2568,6 +2570,7 @@ def on_command_text(cls, playerid: int, command_text: str): Example: .. code-block:: python + @Player.on_command_text def on_player_command_text(player: Player, cmdtext: str): if cmdtext == "/help":