Motor Town Mods

Powered by UE4SS lua scripts! This mod focuses primarily towards dedicated server. Some commands work on client-side, though results may vary depending on the game's replication system.

Usage

Installation

Download the latest releases here. Extract its contents to path/to/ue4ss/Mods/ directory. The Lua static modules are also available in the relase as shared.zip. Download and extract the contents into the path/to/ue4ss/Mods/shared directory.

Building from source

1. Clone this repository into your ue4ss/Mods directory.

   git -C <path/to/ue4ss/Mods> clone https://github.com/drpsyko101/MotorTownMods.git

(Optional) Lua module

For a full functionality of the mod, download and extract luasocket to path/to/ue4ss/Mods/shared directory to use the HTTP server. For webhook functionality or any instability while using the REST API, build Luasec either from source or using Luarocks for Win64. Install lua-bcrypt to enable server API authentication with bcrypt hashing algorithm.

(Optional) C++ module

The C++ module is included in the release. Any changes to the C++ files need a recompile.

Cross-Compilation with Nix (Recommended)

This project supports cross-compiling to Windows from macOS/Linux using Nix. No Windows machine or Visual Studio required!

Prerequisites:

• Nix package manager with flakes enabled

Build Steps:

# Enter the development shell
nix develop

# Run the build (downloads MSVC headers automatically via xwin)
nix run

Your compiled DLL will be at build-cross/MotorTownMods/MotorTownMods.dll.

Copy or symlink it to ue4ss/Mods/MotorTownMods/dlls/main.dll.

Alternative: Windows with CMake

If you prefer building natively on Windows:

1. Clone this repository
2. Open the project in Visual Studio or use standard CMake commands
3. Ensure Boost 1.87.0 is available (CMake will fetch it if not found)
4. Build in Release mode
5. Copy the DLL to ue4ss/Mods/MotorTownMods/dlls/main.dll

Lua Type Annotations

This project includes Lua type definitions for IDE IntelliSense support.

See docs/LuaTypeAnnotations.md for setup and usage.

Quick start:

1. Enter dev shell: nix develop (creates types/ue4ss symlink)
2. Install Lua extension in VSCode
3. Open MTDediMod as your workspace root

Configuration

Most of the server settings can be configured using environment variables:

Variable name	Default value	Description
MOD_MANAGEMENT_PORT	5000	Management port. Used for managing mods in the dedicated server
MOD_SERVER_PORT	5001	Lua HTTP port. This only applies if luasocket module is installed
MOD_SERVER_PROCESS_AMOUNT	5	The amount of cumulative connection to process. Higher number correspond to quicker response, in return slower event hook.
MOD_SERVER_LOG_LEVEL	2	The server log level. 0=ERROR, 1=WARNING, 2=INFO, 3=VERBOSE, 4=DEBUG
MOD_WEBHOOK_URL	none	Webhook URL to send the events to. Requires luasec to function
MOD_WEBHOOK_METHOD	POST	Webhook request method
MOD_WEBHOOK_EXTRA_HEADERS	none	Webhook extra headers in a JSON object
MOD_WEBHOOK_ENABLE_EVENTS	all	Enable event hook individually. See webhook documentation for a complete list.
MOD_SERVER_API_URL	none	Server API to call from client side
MOD_SERVER_PASSWORD	none	Authenticate server request with Authorization: Basic header
MOD_SERVER_SEND_PARTIAL	none	Limit server response chunks to 40 bytes (Set to true for older luasocket compatibility)
MOD_AUTO_FPS_ENABLE	none	Enable automatic server traffic adjustment based on the server's FPS

Reloading mod

Due to the webserver being ran on a separate thread, a stop command must be issued before reloading the mods.

1. Send POST /stop to the MOD_SERVER_PORT server. A message Webserver stopped will show up in the UE4SS.log indicating the webserver has stopped.
2. Send POST /mods/reload to the MOD_SERVER_PORT server. This will reload all the Lua mods including this mod.

Documentation

More detailed instructions can be found in the docs.

Release Pipeline

This repository uses an automated CI/CD pipeline via GitHub Actions to manage releases and compiled binaries.

Versioning & Branches

We use a branch-based versioning system. All official releases are maintained on branches named release/v<number> (e.g., release/v19).

• master branch: Used for active development of Lua scripts and C++ source code.
• release/* branches: Used for stable deployments. These branches contain both the Lua scripts and the pre-compiled dlls/main.dll.

Automated Build Process

When a push occurs on any branch matching release/*:

1. GitHub Actions triggers the Build and Release workflow.
2. It sets up a Windows environment with the necessary MSVC toolset and xmake.
3. The project is compiled into a Shipping DLL.
4. The compiled DLL is then automatically committed and pushed back to the same release branch.
5. A GitHub Release is created/updated with the packaged zip artifacts.

Git LFS

Binary files, specifically dlls/main.dll, are tracked using Git LFS. Ensure you have Git LFS installed locally if you intend to work with these files:

git lfs install

Contributing

More contributions are welcomed! Read how to contribute here.