ChaosMod

ChaosMod is a mod that provides a suite of tools and features for the 2003 video game Freelancer. These features and tools enable us to make the game more whacky, random, and overall more chaotic. As one would expect, these do not always make the game more enjoyable, but do provide a new and unique experience for this age old game.

Features

ChaosMod's suite contains a lot of different features. All are togglable and highly configurable through the provided configurator tool in game. By default, the mod's settings and menu can be accessed through the 'wheel menu' using the middle mouse button (Mouse 3), but this button can be remapped like any other key if desired.

Chaos

The 'Chaos' feature, for which the entire mod is named, is a periodic timer that will trigger random effects while in space. This could be beneficial like giving you OP weapons, or it could be detrimental where we spawn hostile NPCs. It could be neither where the effect just makes the universe different or annoying.

Chaos supports Twitch integration thanks to the work done on the GTAV chaos mod (linked in the credits). This allows Twitch chat to vote for what the next effect will be. Please see the docs for instructions on setting this up!

Patch Notes

The 'Patch Notes' feature allows the game to retroactively patch itself to alter equipment stats, good prices, global constants, and everything in between. These patches are permanent and not tied to the save state of the game.

The scope of these changes is based on the current value of whatever is being changed, and it's totally random. When a patch is generated it could decide the price of Oxygen is now globally set to 42, or it could decide that justice mk1 now has a refire rate of 39 shots per second.

Auto Saves

Due to the instability caused by the very nature of this mod, the 'Auto Save' feature provides regular in-space auto saves that are separate from the normal saves that occur during play.

Disclaimer: Chaos saves created during missions can break save states, and generally should not be trusted

Why?

Why would you install this when you're told it's main design goal is to make your experience worse? Because it's funny.

Installing

If you are just looking to play the mod, there is two ways of doing so. Within the release section there are nightly releases published (provided changes have occurred), these releases contain two 7zip files: an installer and an assets package.

Installer

The installer contains everything the mod is going to require, outside of a vanilla install of Freelancer. Running the installer requires a copy of vanilla Freelancer, but it will create a build of Freelancer HD Edition and then apply ChaosMod over the top of it.

Disclaimer: the installer's progress bar does not work correctly, and it takes a long time. It may look like it's frozen, but be patient.

Assets

If you do not want to use HD Edition as the base, you can download the assets zip instead. This contains an EXE folder and a DATA folder. Simply copy these two whatever Freelancer install you wish to use, replacing any files that are found. Please note that, unlike the installer, no support will be provided if issues are found when working with a non-vanilla/modified install of Freelancer.

Building

The project is built using the Clang compiler, MSVC toolchain, and CMake. As we use CMake presets, building it via the command line is fairly trivial.

Disclaimer: Only builds with Visual Studio 2022 + Clang 16 have been tested and confirmed to work.

Cloning & Building Locally

The following tools are required in order to setup ChaosMod on all operating systems:

7z (7-Zip Archive Manager)
Python 3.11+
CMake
MSVC Compiler supporting C++20 onwards (msvc-wine if on Linux)

Conan is used to setup the project and manage dependencies within ChaosMod. The FL_CHAOS_MOD environment variable can be set to inform chaos mod to copy any output DLL files after a build to the specified directory.

On both Linux and Windows (bash or powershell) run the following commands to get setup:

git clone --recurse-submodules https://github.com/TheStarport/ChaosMod
cd ChaosMod
python -m venv .venv

# Pick next command depending on your environment:
# Bash: source ./venv/bin/activate
# Powershell ./venv/bin/activate.ps1

pip install -r requirements.txt

After running the above commands you should be able to use the cli.py file in order to manage the repo. In order run the following commands to generate a build:

python cli.py requirements
python cli.py build

The requirements command will download needed dependencies, while the build command will install conan packages and prepare CMake presets. -r can be passed to the build command to prepare a release build on Windows. On the first run, a build will automatically be run to ensure everything works as intended.

After running the CLI, builds can be run manually via the following commands (for release, just change 'debug' to 'release'):

cmake --preset debug -S . -B ./build/Debug
cmake --build ./build/Debug --target ChaosMod --config Debug

If you prefer to use an IDE:

CLion supports presets out of the box and should automatically allow one to select them from the CMake profile window.
VSCode has a CMake extension that can handle presets. Documentation for it is available here.
Visual Studio itself supports CMake. Documentation for is available here.

Contributing

See contributing guidelines for more information.

Docs

Documentation for various features pending!!

Credits

Direct

Lazrius - Hi it me. I've done all the code and many other things.
IrateRedKite - Project management, THN intro, INI work, build scripts, workflows, ideas, etc. The list can go on for hours!
Aingar - Assistance with bug fixing crashes
Haste - Help with custom models.
Pillow - Work on AI pilot improvements.
KamiFaby - Large amounts of play testing to find and remove crashes.
BC46 - BC's work on HD edition which ChaosMod is directly built on top of and assistance with reverse engineering.
Ven - Assistance with reverse engineering and offset finding.
NekuraMew - ImGui style improvements (looks more Freelancer-y)
Beagle - The inspiration for the project.
The Entire Starport Community - Everyone within the Starport contributues to the continued survival and development of this game, and I am forever thankful.

External

pongo1231 - Creator of GTAV Chaos Mod, whose ideas and Twitch Integration have been used
Naveen Himal - Christ The Redeemer Model
CATENCODE - Flying Spaghetti Monster Model
savounited - Alduin Dragon Model
Milaein - Blunderbuss Model