From 6ce2f33f6a7013fff38cb02cee3c02b70e5da9c1 Mon Sep 17 00:00:00 2001 From: Jengas Date: Sun, 14 Apr 2024 22:49:01 +0200 Subject: [PATCH] Added README Documentation (#16) --- .github/ISSUE_TEMPLATE/bug-report---.md | 22 ++ .github/ISSUE_TEMPLATE/feature-request---.md | 15 + LICENSE.txt | 21 ++ README.md | 278 ++++++++++++++++++- package-lock.json | 4 + 5 files changed, 333 insertions(+), 7 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug-report---.md create mode 100644 .github/ISSUE_TEMPLATE/feature-request---.md create mode 100644 LICENSE.txt diff --git a/.github/ISSUE_TEMPLATE/bug-report---.md b/.github/ISSUE_TEMPLATE/bug-report---.md new file mode 100644 index 0000000..e74e7d0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report---.md @@ -0,0 +1,22 @@ +--- +name: "Bug report \U0001F41E" +about: Create a bug report +labels: bug + +--- + +## Describe the bug +A clear and concise description of what the bug is. + +### Steps to reproduce +Steps to reproduce the behavior. + +### Expected behavior +A clear and concise description of what you expected to happen. + +### Environment + - OS: [e.g. Arch Linux] + - Other details that you think may affect. + +### Additional context +Add any other context about the problem here. \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature-request---.md b/.github/ISSUE_TEMPLATE/feature-request---.md new file mode 100644 index 0000000..3bd987c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request---.md @@ -0,0 +1,15 @@ +--- +name: "Feature request \U0001F680" +about: Suggest an idea +labels: enhancement + +--- + +## Summary +Brief explanation of the feature. + +### Basic example +Include a basic example or links here. + +### Motivation +Why are we doing this? What use cases does it support? What is the expected outcome? \ No newline at end of file diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..9758a16 --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2023-2024 alt:V Multiplayer + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md index f333ed0..78365cd 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,276 @@ -# ragemp-altv-bridge + -### Build steps + +
+
+ + Logo + -1. `npm install` -2. `npm run build` +

RAGEMP - alt:V Multiplayer bridge

-Output is located in bindings/dist +

+ A bridge that enables a swift transition from the RAGE Multiplayer platform to alt:V Multiplayer. +
+ Explore the docs » +
+
+ View Demo + · + Report Bug + · + Request Feature +

-### Update generated natives +
-`npm run update-natives` \ No newline at end of file +> [!NOTE] +> This bridge only supports gamemodes written in JS, there is no bridge for C# at the moment. + + + + +
+ Table of Contents +
    +
  1. About The Project
    2. +
  2. + Getting Started + +
    3. +
  3. Usage
    4. +
  4. Incompatible Systems
    5. +
  5. Self-Building
    6. +
  6. Contributing
    7. +
  7. Commit Style
    8. +
  8. License
    9. +
  9. Acknowledgments
    10. +
+
+ + + + +## About The Project + +Over the past year, `alt:V Multiplayer` has been developing at a rapid pace, and there are no signs of it slowing down. In collaboration with `Majestic RP`, `alt:V Multiplayer` has developed a bridge that enables a swift transition from the `RAGE Multiplayer` platform to `alt:V Multiplayer`. This project provides a set of APIs that mimic the `RAGE Multiplayer` API. + + + + +## Getting Started + +Next we will explain how to install the bridge in alt:V, as well as explain the nuances that exist + +### Prerequisites + +Before installation, ensure that you have `alt:V` client and server modules installed on your system. Visit [alt:V Official Site](https://altv.mp/) for more details: + +1. Create empty folder and install alt:V server using `npx altv-pkg release` command inside new folder. (We recommend using the `release` version for release purposes. And `npx altv-pkg dev` for development purposes only (E.g to test new features or to test your server before release)) + +2. Create `resources` folder inside your project folder. + +### Installation + + +1. **Pre-requisites**: Before installation, ensure that you have `alt:V` client and server modules installed on your system. Visit [alt:V Official Site](https://altv.mp/) for more details. + +2. **Download**: Download the latest version of the bridge from the [Releases](https://github.com/altmp/ragemp-altv-bridge/releases) page. + +3. **Installation**: + + - Extract folder to resources directory of your `alt:V` server. (So it should look like `myproject/resources/bridge`) + - Create `server.toml` file, and adjust settings to your needs. Visit [alt:V Documentation](https://docs.altv.mp/articles/configs/server.html) for more details. + - For bridge to work, you need to add `bridge` resource to your server configuration file `server.toml` by including a line like: + ```toml + modules = [ + "js-module" + ] + + resources = [ + "dlc_resources/*", # aka client_packages/game_resources/dlcpacks folder + "game_resources", # aka client_packages/game_resources folder (common, raw, x64 and etc) + + "bridge", # Adding bridge resource + + "client_resources", # aka client_packages folder + "server_resources" # aka packages/myserver folder + ] + ``` + +4. For `client_resources`, create file `resource.toml` inside `client_resources` folder with this content: + ```toml + type = "js" + client-main = "index.js" + client-files = [ + "*" + ] + + # Adjust this to your needs + required-permissions = [ + "Screen Capture", + "WebRTC", + "Clipboard Access", + "Extended Voice API" + ] + + [config] + bridge-main = true + ``` + +5. For `server_resources`, create file `resource.toml` inside `server_resources` folder with this content: + ```toml + type = "js" + main = "index.js" + ``` + +6. **Start the Server**: Run your `alt:V` server as usual and ensure that the project module loads correctly. + + + +## Recommended settings +We recommend adding this settings in server.toml for best performance +```toml + + host = "1.2.3.4" # Your public IP address + outgoingInterface = "5.6.7.8" # If you have multiple IP addresses, you can specify the outgoing interface here for the server to use. For example 5.6.7.8 will be used to speak with masterlist server. + + mtu=1000 # Maximum safe value is 1200. Setting higher values may cause network issues. + highThreadPriority = true # Forces the server to prioritize CPU resources for itself. + hashClientResourceName = true # Hashes the resource names sent to the client. + + disableOptionalProps = true # Disables GTA:O extra world objects. (May cause FPS drops for high load servers) + + # Streamer settings, many high load servers in RAGEMP use ~200 distance for streaming. Majestic uses 300 in their server. + streamingDistance = 300.0 + migrationDistance = 200.0 + mapCellAreaSize = 100 + + + sendPlayerNames = false # Disables sending player names to the client. (Most RAGEMP servers use their own name tags system) + spawnAfterConnect = true # RAGEMP spawns players after they connect, alt:V don't spawn unless you do it manually. This setting will spawn players after they connect. + connectionQueue = false # Disables connection queue. (RAGEMP doesn't have connection queue) + + # In order to handle more players, you can increase the worker ports. (aka sockets.conf in RAGEMP). Recommended value is 300 players per worker. + worker-ports = [7770, 7771, 7772, 7773, 7774, 7775] + + # Values adjusted for Intel Xeon E-2388G CPU, for 2000 players. Adjust these values to your server's needs. + [threads] + streamer = 1 + migration = 1 + syncSend = 10 + syncReceive = 2 + + # Limiting streamed entities. (RAGEMP has a limit of 200 streamed peds in total. Play around with these values to find the best value for your server) + [maxStreaming] + entities = 560 # Maximum value in alt:V (Limit 560) + vehicles = 128 # Maximum streamed vehicles (Limit 128) + peds = 220 # Maximum streamed peds (Limit 220) + objects = 120 # Maximum streamed server-sided objects. Doesn't affect streamed client-sided objects. (Limit 120) + + # Disables collision checks so client sided natives like setNoCollision will work. + [antiCheat] + collision = false +``` + + +## DLC Resources +`alt:V` uses a different system for handling DLC resources. In `RAGE Multiplayer`, DLC resources are stored in `client_packages/game_resources/dlcpacks` folder, while in `alt:V` they are stored as separate resource. To port DLC resources from `RAGE Multiplayer` to `alt:V`, you will need to follow instuctions. Visit [alt:V Resource Documentation](https://docs.altv.mp/articles/resources.html) for more details. + +- `client_packages/game_resources/dlcpacks`: All your folders with `dlc.rpf` should be placed in `dlc_resources` folder in your `alt:V` server resources folder. (So it should look like `myproject/resources/dlc_resources`) + +- Anything that is not a `dlc.rpf` file should be placed in `game_resources` folder in your `alt:V` server resources folder. For example `x64`, `common`, `raw` and etc (So it should look like `myproject/resources/game_resources`). +- Also make sure to add `resource.toml` file inside `game_resources` folder with this content: + ```toml + type = 'rpf' + client-files = [ + 'raw/*', + 'x64/*', + 'common/*' + ] + ``` + + +## Incompatible Systems + +There are some systems that is impossible to port from `RAGE Multiplayer` to `alt:V` due to the differences in the platforms. Some of these systems include: + +- **Voice Chat**: `RAGE Multiplayer` uses different system for voice chat, while `alt:V` uses a channel voice chat system. To port voice chat, you will need to rewrite the voice chat system from scratch. Visit [alt:V Documentation](https://docs.altv.mp/articles/voice.html) for more details. +- **Weapon damage system**: `RAGE Multiplayer` uses client-sided damage events only, while `alt:V` uses both server-sided and client-sided event system. You will need to rewrite the weapon damage system, and adjust damage. (In `alt:V` it is very similar to `RAGE Multiplayer`. Visit [alt:V Documentation](https://docs.altv.mp/js/api/alt-server.IServerEvent.html#_altmp_altv_types_alt_server_IServerEvent_weaponDamage) for more details. +- **CEF Textures**: `RAGE Multiplayer` in March 2024 added `http://game-textures/put` endpoint to allow CEF textures to be loaded into game, which is currently not supported in `alt:V`. + +To rewrite this project for another platform, you will need deep understanding of the target platform’s API and possibly a complete overhaul of the networking code. + + + + +## Self-Building + +1. **Clone the Repository**: + ```bash + git clone https://github.com/altmp/ragemp-altv-bridge + cd ragemp-altv-bridge + npm install + ``` + +2. **Build the Project**: + ```bash + npm run build + ``` + +3. **Copy the Output**: + - Copy the `bindings/dist` folder to your `alt:V` server bridge resource folder. + + + +## Contributing + +Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. + +If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". +Don't forget to give the project a star! Thanks again! + +To align with `alt:V`'s commitment to maintaining a clean commit history, please ensure that your commit messages follow our conventional commit format. This aids in automatic changelog generation and streamlines the versioning process. (See [Commit Style](#commit-style) for more details). + +1. Fork the Project +2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`) +3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`) +4. Push to the Branch (`git push origin feature/AmazingFeature`) +5. Open a Pull Request + + +## Commit style +At alt:V Multiplayer we follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) style. + +Breaking change indication is preferred via ! after change type. + +Recommended change types: +- `fix` +- `feat` +- `build` +- `ci` +- `chore` +- `refactor` +- `test` +- `perf` +- `revert` + + +## License + +Distributed under the MIT License. See `LICENSE.txt` for more information. + + + +## Acknowledgments + +* [alt:V Documentation](https://docs.altv.mp/) +* [alt:V External voice chat](https://docs.altv.mp/articles/external_voice_server.html) +* [alt:V server.toml settings](https://docs.altv.mp/articles/configs/server.html) +* [alt:V CDN](https://docs.altv.mp/articles/cdn.html) + + +

(back to top)

\ No newline at end of file diff --git a/package-lock.json b/package-lock.json index 72dbb09..1abb683 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,10 +1,14 @@ { "name": "ragemp-altv-bridge", + "version": "0.0.1", "lockfileVersion": 2, "requires": true, "packages": { "": { + "name": "ragemp-altv-bridge", + "version": "0.0.1", "hasInstallScript": true, + "license": "MIT", "devDependencies": { "eslint": "^9.0.0", "shx": "^0.3.4"