DOCSEARCHbyAlgolia
Submit Docs

open.mp Documentation

repository·master·Indexed 20 days ago

https://github.com/openmultiplayer/open.mp

A high-performance multiplayer server framework featuring a modular architecture with components and extensions designed for ABI compatibility. The documentation covers build instructions for Windows, Mac, and Linux (via Ubuntu 18.04, 20.04, and 22.04 Docker images), repository structure, C++ SDK parameter passing best practices, and the integration of the Pawn component and C-API.

Tokens
3.8K
Snippets
12
Records
18
Agent score
71%

What's inside open.mp

  1. Understand the open.mp repository structure

    master

    The repository is organized into specific directories that dictate stability and usage patterns. When developing, pay close attention to which headers are stable and which are internal implementation details.

    Stable Headers (Safe for SDK usage)

    • SDK/include: Core SDK headers. These are stable between versions.
    • SDK/include/Server/Components/*/: Component/plug-in SDK headers. These are stable between versions.

    Unstable/Internal Headers (Do NOT use for external development)

    • Shared/NetCode/: Netcode headers (RPC and packet read/write structures). NOT stable between versions.
    • Shared/Network/: Network utility headers. NOT stable between versions.
    • Server/Source/: Core server implementation. NOT stable; do not use headers outside the Source folder.
    • Server/Components/*/: Component/plug-in implementation. NOT stable; do not use headers outside the specific component's folder.

  2. Core concepts in open.mp

    master

    To work with open.mp, you should understand its primary abstractions:

    • Entity: Something that can appear in the 3D world of the game.
    • Pool: A container of something with a limited amount of IDs.
    • Component: A module representing something conceptually distinct enough to be separated.
    • Extensible: A system designed to allow extensions while preserving ABI compatibility.
    • Extension: A feature that adds functionality to an extensible system while preserving ABI compatibility.

  3. Build open.mp on Mac

    master

    If you installed Conan via Homebrew, the cmake-conan script may not detect it in the default location. You must create a symbolic link to /usr/local/bin/conan before building.

    Follow these steps to build:

    brew install conan
sudo ln -s /usr/local/opt/conan/bin/conan /usr/local/bin/conan
cd open.mp
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make

  4. Build open.mp using the Ubuntu 20.04 Docker image

    master

    You can use the provided Docker build image to compile open.mp on Linux. This process involves building the Docker image and then running a container that mounts your local source directory to perform the build.

    Steps to build

    1. Build the Docker image:

      docker build -t open.mp/build:ubuntu-20.04 .

    2. Run the build container: Mount your local open.mp source directory to /omp inside the container and set the working directory to /omp.

      docker run --rm -ti -v /path/to/omp/sources:/omp -w /omp open.mp/build:ubuntu-20.04

    3. Locate the output: Once the build completes, the compiled binaries will be available in your local source directory under the build folder: /path/to/omp/sources/build.

    Build Configurations

    You can control the build type by passing the CONFIG environment variable during the docker run command:

    • Debug: For development and debugging.
    • RelWithDebInfo: For release builds that still include debug information.
    docker build -t open.mp/build:ubuntu-20.04 .
docker run --rm -ti -v /path/to/omp/sources:/omp -w /omp -e CONFIG=RelWithDebInfo open.mp/build:ubuntu-20.04

  5. C++ SDK Parameter Passing Best Practices

    master

    When developing with the open.mp SDK in C++, follow these rules for parameter passing to ensure performance and ABI stability:

    When to use Pass-by-Value

    Use pass-by-value for:

    • Basic types (e.g., int, char, etc.)
    • StringView or Span types
    • Mathematical vectors: Vector2, Vector3, Vector4, and GTAQuat

    When to use Pass-by-Reference

    For most other types, prefer passing by reference. Specifically, in SDK headers:

    • ALWAYS pass ABI-stable dynamic memory allocating objects by const reference. Examples include StaticArray, FlatHashMap, and FlatHashSet.
    • ALWAYS pass StaticString by const reference (though it is preferred to pass a StringView instead).

    What to Avoid in SDK Headers

    • NEVER use ABI-unstable STL objects (such as std::string, std::vector, etc.) in SDK headers.

  6. Install required build tools

    master

    Building open.mp requires the following tools:

    • CMake 3.19+
    • Conan 2.x: Can be installed via pip using pip install conan or pip3 install conan.

    Windows specific requirements:

    • Visual Studio 2019+ with the Desktop development with C++ workload and the C++ Clang tools for Windows component installed.

  7. Build open.mp using the Ubuntu 22.04 Docker image

    master

    You can use the provided Docker image to build open.mp in a controlled Ubuntu 22.04 environment. This requires having the open.mp source code available on your host machine.

    1. Build the Docker image: Run the build command from within the docker/build_ubuntu-22.04/ directory.
    2. Run the container: Mount your local source directory to /omp inside the container and set the working directory to /omp.
    3. Build the project: Execute the build commands inside the running container.
    4. Retrieve binaries: The built files will be located in the build subdirectory of your local source directory.

    You can control the build configuration by passing the CONFIG environment variable during the docker run command.

    # 1. Build the image
docker build -t open.mp/build:ubuntu-22.04 .

# 2. Run the container (replace /path/to/omp/sources with your actual path)
# Use -e CONFIG=Debug or -e CONFIG=RelWithDebInfo to change build type
docker run --rm -ti -v /path/to/omp/sources:/omp -w /omp -e CONFIG=RelWithDebInfo open.mp/build:ubuntu-22.04

  9. Clone the open.mp repository

    master

    Because the repository contains submodules, you must use the --recursive flag when cloning.

    # With HTTPS:
git clone --recursive https://github.com/openmultiplayer/open.mp

# With SSH:
git clone --recursive git@github.com:openmultiplayer/open.mp

  10. Build open.mp using the Ubuntu 18.04 Docker image

    master

    You can use the provided Docker image to build open.mp in a controlled Ubuntu 18.04 environment. This involves building the image and then running a container that mounts your local source code directory to perform the build.

    Build Steps

    1. Build the Docker image:

      docker build -t open.mp/build:ubuntu-18.04 .

    2. Run the build container: Mount your local open.mp source directory to the /omp directory inside the container. Replace /path/to/omp/sources with the actual absolute path to your source code.

      docker run --rm -ti -v /path/to/omp/sources:/omp -w /omp open.mp/build:ubuntu-18.04

    3. Locate the output: Once the build process completes, the compiled binaries will be available in the build subdirectory of your local source directory: /path/to/omp/sources/build.

    Configuration

    You can control the build type by passing the CONFIG environment variable during the docker run command:

    • Debug: For development builds.
    • RelWithDebInfo: For release builds containing debug information.
    docker build -t open.mp/build:ubuntu-18.04 .
docker run --rm -ti -v /path/to/omp/sources:/omp -w /omp open.mp/build:ubuntu-18.04

  11. The C-API Component

    master

    The CAPIComponent is the entry point for the C-API implementation within the open.mp server. It implements the IComponent interface and is responsible for initializing the ComponentManager, which manages various server-side entities such as actors, vehicles, objects, and more.

    When the component is loaded, it hooks into the core system and initializes the event system and the component manager to handle the lifecycle of server objects.

  12. How the Pawn component manages scripts

    master

    The Pawn component operates using a hierarchy of scripts managed by the PawnManager:

    1. Main Script: The primary entry point for the game mode. Accessed via mainScript().
    2. Side Scripts: Additional scripts loaded via configuration. Accessed via sideScripts().
    3. AMX Mapping: The component maintains a mapping between AMX* handles and IPawnScript instances, allowing the core to resolve which script owns a specific virtual machine instance via getScript(AMX* amx).

    Scripts are loaded during the onReady phase of the component lifecycle.