diff --git a/docs/.gitbook/assets/Untitled.png b/docs/.gitbook/assets/Untitled.png new file mode 100644 index 0000000..7769a74 Binary files /dev/null and b/docs/.gitbook/assets/Untitled.png differ diff --git a/docs/.gitbook/assets/icon.png b/docs/.gitbook/assets/icon.png new file mode 100644 index 0000000..0f88abb Binary files /dev/null and b/docs/.gitbook/assets/icon.png differ diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..fff66aa --- /dev/null +++ b/docs/README.md @@ -0,0 +1,22 @@ +# Welcome to the Rust+.py Docs! + +![](.gitbook/assets/icon.png) + +Welcome to Rust+.py! Here you'll find all the documentation you need to get up and running with API. + +## Want to jump right in? + +Feeling like an eager beaver? Jump in to the quick start docs and get making your first requests: + +{% content-ref url="getting-started/quick-start.md" %} +[quick-start.md](getting-started/quick-start.md) +{% endcontent-ref %} + +## Want to take a look at our source? + +Head over to our GitHub repository [here](https://github.com/olijeffers0n/rustplus) + +## Need some help? + +Head over to our discord server [here](https://lt.ollieee.xyz/rplusdiscord) + diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 0000000..e5265e9 --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,42 @@ +# Table of contents + +## Getting Started + +* [Welcome to the Rust+.py Docs!](README.md) +* [Quick Start](getting-started/quick-start.md) +* [Getting Player Details](getting-started/getting-player-details/README.md) + * [FCM Listener](getting-started/getting-player-details/fcm-listener.md) + * [Getting Entity ID's](getting-started/getting-player-details/getting-entity-ids.md) +* [RustSocket](getting-started/rustsocket/README.md) + * [Rate Limiting](getting-started/rustsocket/rate-limiting.md) + +## API methods + +* [Removing Listeners](api-methods/removing-listeners.md) +* [Getting Team Info](api-methods/getting-team-info.md) +* [Getting Team Chat](api-methods/getting-team-chat.md) +* [Getting Server Info](api-methods/getting-server-info.md) +* [Getting the Map](api-methods/getting-the-map.md) +* [Sending Messages](api-methods/sending-messages.md) +* [Getting the Time](api-methods/getting-the-time.md) +* [Getting Entity Information](api-methods/getting-entity-information.md) +* [Getting Map Markers](api-methods/getting-map-markers.md) +* [Getting Current Map Events](api-methods/getting-current-map-events.md) +* [Getting Contents of Monitors](api-methods/getting-contents-of-monitors.md) +* [Promoting Players to Team Leader](api-methods/promoting-players-to-team-leader.md) +* [Toggling Smart Switches](api-methods/toggling-smart-switches.md) + +## Command System + +* [Commands Overview](command-system/commands-overview.md) +* [Command Options](command-system/command-options.md) +* [Command Decorator](command-system/command-decorator.md) +* [Hanging The Socket](command-system/hanging-the-socket.md) + +## Event System + +* [Events Overview](event-system/events-overview.md) + +## Cameras + +* [Camera Managers](cameras/camera-managers.md) diff --git a/docs/api-methods/getting-contents-of-monitors.md b/docs/api-methods/getting-contents-of-monitors.md new file mode 100644 index 0000000..5b3f588 --- /dev/null +++ b/docs/api-methods/getting-contents-of-monitors.md @@ -0,0 +1,21 @@ +# Getting Contents of Monitors + +Calling `rust_socket.get_contents(eid: int, combine_stacks: bool)` returns a `RustContents` object: + + + +```python +class RustContents with fields: + +protection_time: timedelta +has_protection: bool +contents : List[RustItem] + +class RustItem with fields: + +name: str +item_id: int +quantity: int +is_blueprint: bool +``` + diff --git a/docs/api-methods/getting-current-map-events.md b/docs/api-methods/getting-current-map-events.md new file mode 100644 index 0000000..c0f1532 --- /dev/null +++ b/docs/api-methods/getting-current-map-events.md @@ -0,0 +1,12 @@ +# Getting Current Map Events + +The following are all defined as "events": + +* Explosions (Bradley / Attack Helicopter) +* Cargo Ship +* CH47 (Chinook) +* Locked Crates +* Attack Helicopter + +Calling `rust_socket.get_current_events()` returns a list of all current `RustMarker`'s that are the above events. This can be used for working out whether Cargo Ship / Oil Rig etc has been taken / is being taken. See [Here ](getting-map-markers.md)for information on `RustMarker` + diff --git a/docs/api-methods/getting-entity-information.md b/docs/api-methods/getting-entity-information.md new file mode 100644 index 0000000..7b774d5 --- /dev/null +++ b/docs/api-methods/getting-entity-information.md @@ -0,0 +1,29 @@ +# Getting Entity Information + +Calling `rust_socket.get_entity_info(entity_id: int)` will return a `RustEntityInfo` object with the following data: + +```python +class RustEntityInfo with fields: + +type: int +value: bool +items : RustEntityInfoItem +capacity: int +has_protection: bool +protection_expiry: int + +class RustEntityInfoItem with fields: + +item_id: int +quantity: int +item_is_blueprint: bool +``` + +The entity type is an integer value which corresponds to these values: + +``` +Switch = 1 +Alarm = 2 +StorageMonitor = 3 +``` + diff --git a/docs/api-methods/getting-map-markers.md b/docs/api-methods/getting-map-markers.md new file mode 100644 index 0000000..782232a --- /dev/null +++ b/docs/api-methods/getting-map-markers.md @@ -0,0 +1,52 @@ +# Getting Map Markers + +Calling `rust_socket.get_markers()` returns a `List[RustMarker]` with the following data: + +```python +class RustMarker with fields: + +id: int +type: int +x: float +y: float +steam_id: int +rotation: float +radius: float +colour1 : RustColour +colour2 : RustColour +alpha: float +name: str +sell_orders : List[RustSellOrder] + +class RustColour with fields: + +x: float +y: float +z: float +w: float + +class RustSellOrder with fields: + +item_id: int +quantity: int +currency_id: int +cost_per_item: int +item_is_blueprint: bool +currency_is_blueprint: bool +amount_in_stock: int +``` + +#### These are the types of the RustMarker + +``` +Types: + Player = 1 + Explosion = 2 + VendingMachine = 3 + CH47 = 4 + CargoShip = 5 + Crate = 6 + GenericRadius = 7 + PatrolHelicopter = 8 +``` + diff --git a/docs/api-methods/getting-server-info.md b/docs/api-methods/getting-server-info.md new file mode 100644 index 0000000..bb2385f --- /dev/null +++ b/docs/api-methods/getting-server-info.md @@ -0,0 +1,17 @@ +# Getting Server Info + +Calling `rust_socket.get_info()` will return a `RustInfo` object with the following data: + +```python +class RustInfo with fields: + +url: str +name: str +map: str +size: int +players: int +max_players: int +queued_players: int +seed: int +``` + diff --git a/docs/api-methods/getting-team-chat.md b/docs/api-methods/getting-team-chat.md new file mode 100644 index 0000000..18e68ab --- /dev/null +++ b/docs/api-methods/getting-team-chat.md @@ -0,0 +1,14 @@ +# Getting Team Chat + +Calling `rust_socket.get_team_chat()` will return a `List[RustChatMessage]` objects with fields: + +```python +class RustChatMessage with fields: + +steam_id: int +name: str +message: str +colour: str +time: int +``` + diff --git a/docs/api-methods/getting-team-info.md b/docs/api-methods/getting-team-info.md new file mode 100644 index 0000000..8a84c83 --- /dev/null +++ b/docs/api-methods/getting-team-info.md @@ -0,0 +1,37 @@ +# Getting Team Info + +Calling `rust_socket.get_team_info()` returns a `RustTeamInfo` object with the following data: + +```python +class RustTeamInfo with fields: + +leader_steam_id: int +members : List[RustTeamMember] +map_notes : List[RustTeamNote] +leader_map_notes : List[RustTeamNote] + +class RustTeamMember with fields: + +steam_id: int +name: str +x: float +y: float +is_online: bool +spawn_time: int +is_alive: bool +death_time: int + +class RustTeamNote with fields: + +type +x: float +y: float +``` + +So, to get the name of the first member in the team you can do: + +```python +info = await rust_socket.get_team_info() +print(info.members[0].name) +``` + diff --git a/docs/api-methods/getting-the-map.md b/docs/api-methods/getting-the-map.md new file mode 100644 index 0000000..4911719 --- /dev/null +++ b/docs/api-methods/getting-the-map.md @@ -0,0 +1,27 @@ +# Getting the Map + +### Getting the Image + +Calling `rust_socket.get_map(add_icons: bool, add_events: bool, add_vending_machines: bool, override_images: dict)` will return a `PIL.Image` with the respective additions. + +### Getting the Map Data + +Calling `rust_socket.get_raw_map_data()` will return a `RustMap` object with the following data: + +```python +class RustMap with fields: + +width: int +height: int +jpg_image: bytes +margin: int +monuments : List[RustMonument] +background: str + +class RustMonument with fields: + +token: str +x: float +y: float +``` + diff --git a/docs/api-methods/getting-the-time.md b/docs/api-methods/getting-the-time.md new file mode 100644 index 0000000..90a258f --- /dev/null +++ b/docs/api-methods/getting-the-time.md @@ -0,0 +1,14 @@ +# Getting the Time + +Calling `rust_socket.get_time()` returns a `RustTime` object with the following info: + +```python +class RustTime with fields: + +day_length: float +sunrise: str +sunset: str +time: str +raw_time: float +``` + diff --git a/docs/api-methods/promoting-players-to-team-leader.md b/docs/api-methods/promoting-players-to-team-leader.md new file mode 100644 index 0000000..963ba27 --- /dev/null +++ b/docs/api-methods/promoting-players-to-team-leader.md @@ -0,0 +1,4 @@ +# Promoting Players to Team Leader + +Calling `rust_socket.promote_to_team_leader(steam_id: int)` will promote the player in your team to the leader. + diff --git a/docs/api-methods/removing-listeners.md b/docs/api-methods/removing-listeners.md new file mode 100644 index 0000000..16f0245 --- /dev/null +++ b/docs/api-methods/removing-listeners.md @@ -0,0 +1,10 @@ +# Removing Listeners + +### Registered Listeners + +A registered listener is a wrapper object around the coroutine itself that will allow the listener to be removed later on. Should you need the coroutine back, call `RegisteredListener.get_coro()`. + +### Removing The listener + +Removing a listener is as simple as calling `RustSocket.remove_listener(RegisteredListener)` and will return a boolean value. True if a listener was removed and false otherwise + diff --git a/docs/api-methods/sending-messages.md b/docs/api-methods/sending-messages.md new file mode 100644 index 0000000..638c80d --- /dev/null +++ b/docs/api-methods/sending-messages.md @@ -0,0 +1,8 @@ +# Sending Messages + +Calling `rust_socket.send_team_message(message: str)` will send the message to the team chat as the player who you are logged in as in the [`RustSocket`](../getting-started/rustsocket/) . For example: + +```python +await rust_socket.send_team_message("Hi! This was sent with Rust+.py") +``` + diff --git a/docs/api-methods/toggling-smart-switches.md b/docs/api-methods/toggling-smart-switches.md new file mode 100644 index 0000000..86d4f26 --- /dev/null +++ b/docs/api-methods/toggling-smart-switches.md @@ -0,0 +1,8 @@ +# Toggling Smart Switches + +Calling `rust_socket.turn_on_smart_switch(eid: int)` and `rust_socket.turn_off_smart_switch(eid: int)` can be used to toggle smart switches on and off from code. To get the entity\_ids look at: + +{% content-ref url="../getting-started/getting-player-details/getting-entity-ids.md" %} +[getting-entity-ids.md](../getting-started/getting-player-details/getting-entity-ids.md) +{% endcontent-ref %} + diff --git a/docs/cameras/camera-managers.md b/docs/cameras/camera-managers.md new file mode 100644 index 0000000..d475a16 --- /dev/null +++ b/docs/cameras/camera-managers.md @@ -0,0 +1,55 @@ +# Camera Managers + +A camera manager facilitates all operations with cameras inside Rust. + +Creation: + +```python +# Get the camera manager from the socket: +camera_manager = await socket.get_camera_manager("drone") +# The parameter is the camera ID +``` + +**Only one Camera Manager can exist at once**. Once a new one is created the old one will go stale. + +## Re Subscribing + +Subscriptions only last around 15 seconds. After this, you must resubscribe by doing: + +```python +if time.time() - camera_manager.time_since_last_subscribe > 10: + await camera_manager.resubscribe() +``` + +## Getting Frames + +Camera frames can be fetched for the camera using the following: + +```python +camera_manager = await socket.get_camera_manager("drone") +image = await camera_manager.get_frame() # PIL Image +``` + +This returns a `PIL` Image that can be saved or displayed. When the Camera Manager is first created there is no camera frame available. Use: `camera_manager.has_frame_data()` to check for this. + +## Controlling Drones and Cameras + +There are many possible movement options that can be sent via the following code: + +```python +# Check that it is possible to zoom the camera in and out +if camera_manager.can_move(CameraMovementOptions.FIRE) and \ + camera_manager.can_move(CameraMovementOptions.MOUSE): + # Send a MovementControl action to the camera + await camera_manager.send_actions([MovementControls.FIRE_PRIMARY]) + # You can also send just mouse movement or both at the same time: + await camera_manager.send_mouse_movement(Vector(1, 1)) + await camera_manager.send_combined_movement( + [MovementControls.FIRE_PRIMARY], Vector(1, 1)) + + await asyncio.sleep(1) + # You must clear the movement after you are done + # as otherwise the mouse will continue to move and the server + # Will consider the mouse still clicked down + await camera_manager.clear_movement() +``` diff --git a/docs/command-system/command-decorator.md b/docs/command-system/command-decorator.md new file mode 100644 index 0000000..ad6f780 --- /dev/null +++ b/docs/command-system/command-decorator.md @@ -0,0 +1,44 @@ +# Command Decorator + +The command decorator is used to mark a coroutine as a command listener. Usage: + +```python +@rust_socket.command +async def hi(command: Command): + print("Command Ran!") +``` + +The fact that the coroutine's name is `hi` means that the command will be `hi` . + +You also get access to this `Command` object which has a slew of useful information about the how the command was called. + +| Field | Value | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `sender_name` | The name of the person that called the command, e.g. `olijeffers0n` | +| `sender_steamid` | The steamID of the person that called the command | +| `time` | The time that the command was called, as a `CommandTime` object. This wraps a `datetime` object, and the raw UNIX Epoch time | +| `command` | The name of the command that was called, e.g. `hi` | +| `args` | A list of strings that was passed as arguments to the command. E.g. - `!hi one two three` would result in args being `["one", "two, "three"]` | + +This decorator returns a [`RegisteredListener`](../api-methods/removing-listeners.md#registered-listeners) instance + +### Aliases + +You don't want to have to register 100's of commands for every permutation of phrasing, so why should you! + +```python +@rust_socket.command(aliases=["hello", "hey"]) +async def hi(command: Command): + print("Command Ran!") +``` + +This is a simple example of how you could incorporate different function names into one command, but sometimes we need more than that! + +```python +@rust_socket.command(alais_func=lambda x: x.lower() == "test") +async def pair(command: Command): + print("Command Ran!") +``` + +This will allow you to check ANY string as it is passed in and perform checking on it. You just have to provide a callable, so a lambda or function reference will work! It will provide the current command as an argument and you can perform any logic you need! + diff --git a/docs/command-system/command-options.md b/docs/command-system/command-options.md new file mode 100644 index 0000000..5d2848c --- /dev/null +++ b/docs/command-system/command-options.md @@ -0,0 +1,14 @@ +# Command Options + +Command options are what you use to tell the [`RustSocket`](../getting-started/rustsocket/) what the general structure of your commands will be. These define the prefix for the command, as well as any "overruling commands" which are commands that do not require a prefix. Usage: + +```python +from rustplus import RustSocket + +options = CommandOptions(prefix="!", overruling_commands = ["time"]) + +# Prefix is a string, and the overruling_commands are a list of strings which would be the name of the coroutines +``` + +You can then just pass these into the RustSocket constructor using the `overruling_commands` kwarg. + diff --git a/docs/command-system/commands-overview.md b/docs/command-system/commands-overview.md new file mode 100644 index 0000000..962709d --- /dev/null +++ b/docs/command-system/commands-overview.md @@ -0,0 +1,17 @@ +# Commands Overview + +Commands allow the triggering of custom coroutines when a specific keyword is sent in the **team** chat. Basic Usage: + +{% code title="main.py" %} +```python +from rustplus import RustSocket, CommandOptions, Command + +options = CommandOptions(prefix="!") # Use whatever prefix you want here +rust_socket = RustSocket("IP", "PORT", STEAMID, PLAYERTOKEN, command_options=options) + +@rust_socket.command +async def hi(command : Command): + await socket.send_team_message(f"Hi, {command.sender_name}") +``` +{% endcode %} + diff --git a/docs/command-system/hanging-the-socket.md b/docs/command-system/hanging-the-socket.md new file mode 100644 index 0000000..2d1c445 --- /dev/null +++ b/docs/command-system/hanging-the-socket.md @@ -0,0 +1,10 @@ +# Hanging The Socket + +When using commands in a script, the script will terminate before you have a chance to listen to any commands. This is why you will need to hang the script. + +```python +await rust_socket.hang() +``` + +This, however, is non-recoverable and will be stuck here until you force close the program. + diff --git a/docs/event-system/events-overview.md b/docs/event-system/events-overview.md new file mode 100644 index 0000000..40e8019 --- /dev/null +++ b/docs/event-system/events-overview.md @@ -0,0 +1,77 @@ +# Events Overview + +Socket Events are called whenever a specific action / event happens. There are currently 4 possible types of event that you could listen for: + +* Chat Event +* Entity Event +* Team Event +* Protobuf Event + +These will be called by the socket when the respective events occur. Here are some example usages: + +{% code title="listeners.py" %} +```python +from rustplus import EntityEvent, TeamEvent, ChatEvent + +@rust_socket.entity_event(ENTITYID) +async def alarm(event : EntityEvent): + value = "On" if event.value else "Off" + print(f"{entity_type_to_string(event.type)} has been turned {value}") + +@rust_socket.team_event +async def team(event : TeamEvent): + print(f"The team leader's steamId is: {event.team_info.leader_steam_id}") + +@rust_socket.chat_event +async def chat(event : ChatEvent): + print(f"{event.message.name}: {event.message.message}") + +@rust_socket.protobuf_received +async def proto(data: bytes): + print(data) +``` +{% endcode %} + +### Entity Event + +The `entity_event` decorator takes an extra parameter of the [entity id](../getting-started/getting-player-details/getting-entity-ids.md) that you are listening for changes to. The `EntityEvent` object holds information on the entity: + +| Name | Description | +| ------------------- | ------------------------------------- | +| `type` | The type of entity, as an `int` | +| `entity_id` | The Entity Id | +| `value` | The value of the entity, `boolean` | +| `capacity` | The capacity of the entity | +| `has_protection` | Whether the entity is protected by TC | +| `protection_expiry` | When the protection by TC will expire | +| `items` | The items that the entity contains | + +### Team Event + +This event is typically called when the team changes, e.g. a player leaves or joins. The `team_event` decorator will pass a `TeamEvent` object as a parameter with the following information: + +| Name | Description | +| ------------- | ------------------------------------------------------------------------------- | +| `player_info` | The `player_id` of the changed information | +| `team_info` | The [`team info`](../api-methods/getting-team-info.md) on the team that changed | + +### Chat Event + +This event is called when a message is sent to the team chat. It will give you a `ChatEvent` object when called with this information: + +| Name | Description | +| --------- | ---------------------------------------------------------------- | +| `message` | The [message](../api-methods/getting-team-chat.md) that was sent | + +### Protobuf Event + +This event is called when protobuf is received over the websocket connection. This is for monitoring only. You are given the raw bytes of the message as a parameter. + +### Removing + +To remove any listener see: + +{% content-ref url="../api-methods/removing-listeners.md" %} +[removing-listeners.md](../api-methods/removing-listeners.md) +{% endcontent-ref %} + diff --git a/docs/getting-started/getting-player-details/README.md b/docs/getting-started/getting-player-details/README.md new file mode 100644 index 0000000..9a25014 --- /dev/null +++ b/docs/getting-started/getting-player-details/README.md @@ -0,0 +1,68 @@ +--- +description: This will show you how to get your personal player details using the RustCli +--- + +# Getting Player Details + +This process is designed to be as easy as possible for you to get your details.\ +\ +The Steam ID is unique to your steam account, so can be used for any server you connect to. However, the `PlayerToken` is unique to each server & player. There are two ways to get this data: + +#### As a Server Owner: + +You can go to the server files where you will find a database called `player.tokens.db` containing all of these codes. You can use a tool such as [this](https://sqlitebrowser.org/) to get the codes, or access them programmatically. + +#### **As a player:** + +There is a [Chrome Extension](https://chrome.google.com/webstore/detail/rustpluspy-link-companion/gojhnmnggbnflhdcpcemeahejhcimnlf?hl=en) so that you can automatically sign in with the Facepunch servers and get your details. Once installed, click on its icon to be redirected to the login page. Follow the sign in instructions and you will land on my website with a box of FCM Details you can either, + +1\) Copy to Clipboard \ +2\) Download to file \ +3\) Use on the website to - get this - listen for notifications on the web! + +### Web Listener: + +This will allow you to listen for paring notifications without even opening an IDE. The messages are listened for, and then sent to your browser via a WebSocket connection. If you have any issues with them not coming through you can refresh the page and they should be there! + +Obviously, you can still listen from Python and see the docs here: + +{% content-ref url="fcm-listener.md" %} +[fcm-listener.md](fcm-listener.md) +{% endcontent-ref %} + +When you refresh the page it will store whatever you had in that box for next time as each time you generate new details it invalidates your previous ones. To listen for notifications click "Listen for notifications" in the middle. + +{% hint style="info" %} +Note: If you have previously already paired with the server you will need to unpair and re-pair. +{% endhint %} + +In order to get your data, you need to: + +* Click the Chrome extension icon to open the Facepunch Page +* Login through Steam to authenticate yourself +* You will be redirected to my page where you will have a box of credentials at the top. THESE ARE NOT YOUR LOGIN CREDENTIALS. +* The box at the bottom contains all FCM Notifications. +* In-Game, send a pairing notification, You should get data like this: + +``` +{ + "desc": "",se + "id": "", + "img": "", + "ip": "", <- This is the IP + "logo": "", + "name": "", + "playerId": "", <- This is your steam player ID + "playerToken": "", <- This is your unique token + "port": "", <- This is the token + "type": "", + "url": "" +} +``` + +You can then use these details in the Python Wrapper here: + +```python +rust_socket = RustSocket("IPADDRESS", "PORT", 64BITSTEAMID, PLAYERTOKEN) +``` + diff --git a/docs/getting-started/getting-player-details/fcm-listener.md b/docs/getting-started/getting-player-details/fcm-listener.md new file mode 100644 index 0000000..bf13f09 --- /dev/null +++ b/docs/getting-started/getting-player-details/fcm-listener.md @@ -0,0 +1,31 @@ +# FCM Listener + +Should you need to listen for additional messages, like pairing requests, this is built into the library too! + +{% code title="main.py" %} +```python +from rustplus import FCMListener +import json + +with open("rustplus.py.config.json", "r") as input_file: + fcm_details = json.load(input_file) + +class FCM(FCMListener): + + def on_notification(self, obj, notification, data_message): + print(notification) + +FCM(fcm_details).start() +``` +{% endcode %} + +The `on_notification` method will be called everytime a message is recieved from the game server. + +The `rustplus.py.config.json` is the file created by the RustCli, when you register for FCM notifications. See: + +{% content-ref url="./" %} +[.](./) +{% endcontent-ref %} + + + diff --git a/docs/getting-started/getting-player-details/getting-entity-ids.md b/docs/getting-started/getting-player-details/getting-entity-ids.md new file mode 100644 index 0000000..2932d67 --- /dev/null +++ b/docs/getting-started/getting-player-details/getting-entity-ids.md @@ -0,0 +1,12 @@ +# Getting Entity ID's + +You can get entity ID's by hitting the entity in-game and then using your `combatlog` + +![ID's Shown above](../../.gitbook/assets/Untitled.png) + +You can also get the Entity Id's though the smart device pairing notifications received through FCM messages, see here for that: + +{% content-ref url="./" %} +[.](./) +{% endcontent-ref %} + diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md new file mode 100644 index 0000000..2360b5f --- /dev/null +++ b/docs/getting-started/quick-start.md @@ -0,0 +1,33 @@ +# Quick Start + +In order to access the API, you must first install the package using pip: + +```shell +pip install rustplus +``` + +You must then get your Personal details using the RustCli, as shown here: + +{% content-ref url="getting-player-details/" %} +[getting-player-details](getting-player-details/) +{% endcontent-ref %} + +{% code title="main.py" %} +```python +import asyncio +from rustplus import RustSocket + +async def main(): + socket = RustSocket("IP", "PORT", STEAMID, PLAYERTOKEN) + await socket.connect() + + print(f"It is {(await socket.get_time()).time}") + + await socket.disconnect() + +asyncio.run(main()) +``` +{% endcode %} + +This will run, and print the time on the Rust Server + diff --git a/docs/getting-started/rustsocket/README.md b/docs/getting-started/rustsocket/README.md new file mode 100644 index 0000000..2c05f38 --- /dev/null +++ b/docs/getting-started/rustsocket/README.md @@ -0,0 +1,16 @@ +# RustSocket + +The `RustSocket` is where everything happens in Rust+.py. Constructing one is super easy. There are only 4 required arguments, the Ip, Port, SteamId and Token. But that doesn't mean that's all! + +```python +from rustplus import RustSocket + +socket = RustSocket(ip, port, steam_id, player_token, + command_options, raise_ratelimit_exception, ratelimit_limit, + ratelimit_refill, use_proxy) +``` + +
NameTypeWhat it is
ipstrThe Ip of the Server
portstrThe port of the server
steam_idintYour SteamID
player_tokenintYour player token
command_optionsCommandOptionsThe Command Options
raise_ratelimit_exceptionboolWhether to raise an exception if you run into the ratelimit. Set to false to automatically wait until you can afford the request
ratelimit_limitintThe upper limit of the TokenBucket
ratelimit_refillintThe refill rate of the TokenBucket
use_proxyboolWhether to use the Facepunch Proxy. False by default
+ + + diff --git a/docs/getting-started/rustsocket/rate-limiting.md b/docs/getting-started/rustsocket/rate-limiting.md new file mode 100644 index 0000000..2563733 --- /dev/null +++ b/docs/getting-started/rustsocket/rate-limiting.md @@ -0,0 +1,27 @@ +# Rate Limiting + +The server uses a '[Token Bucket](https://en.wikipedia.org/wiki/Token\_bucket)' approach meaning that you should be careful how many requests you send, however if you are sensible, this should be a non-issue... + +You get: 50 tokens max per IP address with 15 replenished per second 25 tokens max per PlayerID with 3 replenished per second + +And these are the costs: + +``` +get_map = 5 or 6 (depending on what you add to the map) +get_time = 1 +get_info = 1 +get_markers = 1 +send_team_chat = 2 +get_team_info = 1 +turn_on_switch = 1 +turn_off_switch = 1 +get_entitiy_info = 1 +promote_to_team_leader = 1 +get_tc_storage_contents = 1 +get_current_events = 1 + +Registering Entity Events = 1 +``` + +RustPlus.py now handles ratelimiting automatically. It can either raise exceptions when you are going to exceed the limit or it can wait and send it later when you have enough tokens. Change this in the `RustSocket` constructor (`raise_ratelimit_exception`). This defaults to `True`, so set it to false if you want the socket to wait until you can afford the operations. +