Resource: add LiveAPI documentation

r5dev/resource/docs/liveapi_readme.txt

@@ -0,0 +1,96 @@
+# Quick Start
+
+This API is built on top of WebSockets and Google's Protocol Buffer (protobuf) technology. All gameplay events and
+requests supported by the LiveAPI are documented in the `events.proto` protobuf file that lives in this directory.
+If you're not familiar with protobuf, visit https://developers.google.com/protocol-buffers to learn more.
+
+Protobuf bindings can be easily generated for your language of choice after you obtain the Protobuf Compiler `protoc`.
+For example, to generate bindings for Python, use:
+`protoc.exe --proto_path=<current directory of this readme> --python_out=<your project output directory> events.proto`
+
+The bindings can then be included into your app code. In order to consume the events, your app will have to open a
+WebSocket server that the running game server can connect and send events to.
+
+# Configuration
+
+The game server must also be running with additional configurations to activate the LiveAPI and connect to the app.
+The configuration file is located in `platform/cfg/liveapi.cfg` (relative from the game executable `r5apex_ds.exe`).
+
+For example, if the app has a websocket server in port 7777 of the same machine the game server is running on, the
+following settings can be applied in the aforementioned configuration file to connect the game server to the app:
+
+liveapi_enabled           "1"
+liveapi_websocket_enabled "1"
+liveapi_servers           "ws://127.0.0.1:7777"
+
+Upon launching with these parameters, the game server will connect to the WebSocket server at 127.0.0.1 in port 7777.
+Gameplay events are sent to the WebSocket server app once the game server has started.
+
+The game can also be configured to write events to a local JSON file on the disk. The event logs will be located in
+`platform/liveapi/logs/<session_uuid>/match_<matchNum>.json` (relative from the game executable `r5apex_ds.exe`).
+
+The following settings can be applied in the aforementioned configuration file to log events to a local JSON file:
+
+liveapi_enabled           "1"
+liveapi_print_enabled     "1"
+liveapi_print_pretty      "1"
+
+- You can run the WebSocket and local JSON logging simultaneously.
+
+# Scripting
+
+The Squirrel scripting API of the LiveAPI is quite simple, there are 5 main functions:
+
+LiveAPI_IsValidToRun()
+- Whether the LiveAPI system was initialized and is currently able to run, check on this before calling the functions
+  `LiveAPI_WriteLogUsingDefinedFields()` and `LiveAPI_WriteLogUsingCustomFields()`to save unnecessary load on the game
+  server.
+
+LiveAPI_StartLogging()
+- This is used to start the logging of LiveAPI events to a local JSON file, if a log session is already active by the
+  time this function is called, the previous log session will be closed and a new one will be started. The new session
+  will be written to a new json file.
+- Needs ConVar `liveapi_enabled` and `liveapi_print_enabled` set to 1, else this function will not do anything.
+
+LiveAPI_StopLogging()
+- This is used to stop the logging of LiveAPI events to a local JSON file. Calling this will finish off the file and
+  stop the logging of new events.
+
+LiveAPI_WriteLogUsingDefinedFields()
+- This function takes 3 parameters, an event type (must be one registered in the 'eLiveAPI_EventTypes' enum, see
+  the file `src/game/server/liveapi/liveapi.cpp` for available event types, or alternatively, see the events.proto
+  file, event names must start with a lower case !!!), an array of data, and an array of field indices. The order of
+  the 2 arrays are important, as the entries in the data array map directly to the data in the field indices array; if
+  event type is eLiveAPI_EventTypes.playerKilled, and if the first entry of the data array is "someString", and the
+  first entry in the field indices array is '3', then "someString" will be set to the third field index of the
+  PlayerKilled event message. Make sure to study the event messages, and their respective field numbers in the
+  `events.proto` file before assigning new events!
+
+NOTE: Since there was a high demand for custom events, we added an event named `CustomEvent` which can be used to send
+game data in any structure from the game's scripting API. This is useful if you wish to log your own data from the
+game (e.g. a custom gamemode that has something the current protocol doesn't support). The following function utilizes
+this special event message:
+
+LiveAPI_WriteLogUsingCustomFields()
+- This function takes 3 parameters, an event name (can be any string, the purpose of this is to identify your custom
+  event!), an array of data, and an array of field names. You can entirely define the structure of the data yourself;
+  if entry 6 in data array is "world!", and entry 6 in the field names array is "hello", then message variable "hello"
+  becomes "world!". The data array can take any of the following types: bool|int|float|string|vector|array|table.
+  NOTE: with tables, the key must be a string as this will be used to determine the custom field names, the values can
+  be any of the aforementioned types.
+- Tables and arrays cannot be nested into them selfs as this would cause infinite recursion, and the maximum nesting
+  depth of a table or array is 64.
+
+For more technical information about the scripting API of the system, see the file
+`platform/scripts/vscripts/_live_api.gnut` (relative from the game executable `r5apex_ds.exe`).
+
+# Technical Information
+
+By popular demand, we tried our best to keep the protocol and documentation the same as that of the retail version of
+the game to maintain compatibility with existing apps. As of the release of this build, the file `events.proto` is
+synced with the retail build `R5pc_r5-201_J29_CL6350311_EX6402312_6403685_2024_03_22`.
+
+# Contact & Feedback
+
+If you have a question, suggestion, or encountered an issue in the system, you can send me (Kawe Mazidjatari) an email
+at `amos@r5reloaded.com`.