VoidExpanse/modding

Overview

VoidExpanse is designed to have great modding potential. Almost every aspect of game can be modified and extended. There are no hardcoded scripts and in-game logic, everything you see in VoidExpanse now was created as a "core" mod. This concept is similar to early GameBryo versions.

The game uses so called "package files" to load all external content and logic, both for client and server.

Package files

All game data is loaded from two types of files: ".cpk" and ".mpk"

".cpk" stands for Core Package. It contains essential game functionality, basically foundation of the game. The game cannot run without a core package which contains all in-game assets and logic. Only one CPK file could be loaded at one time.

But ".mpk" files on the other hand are "mod packages", which can be added on top of the core package file to add new features or content, or to change something that is already present in the game. The game can have multiple mpk files loaded at the same time.

File precedents and overloading

When mod file (or several mod files) is loaded it will merge with the already loaded core files into a so called "virtual file system". Even though the contents of these separage packages are stored separately the game will treat them as one file system with shared paths. Now, what does it mean?

For example, if we have CPK (core package) with a file "/content/some_file.txt" and MPK (mod package) with file "/content/some_file.txt" which is the same path. What happens when we start the game? Since both files in core package and mod package share the same path the precedent will be given to the file store in mod package since it was loaded AFTER the core package. This mechanism is created to make it possible to override the core functionality and content extremely easy, without recompiling whole CPK or need to modify its content. The same principle works not just with content files, but with assets, scripts and any other type of files.

Virtual file system concepts

All mods are loaded into one virtual file system, with overwrite rule (see in "File precedents and overloading" section above for explanation).
Mods can use each other's files, so don't hesitate to use original game resources in your mods.
If two MPK files have the same file (path+name), the last one (by the order specified in ModsConfig.xml) will be taken.
All file names are not case-sensitive. QwEr.xml and qwer.xml are considered the same.

Mods header structure

Each mod (MPK file) must have a valid "header.xml", or it won't be loaded. It is a simple XML document describing how the game should treat the mod file.

The structure of the "header.xml" is:

<?xml version="1.0" encoding="utf-8"?>
<root>
	<id>unique_mod_id</id>
	<title>Name of the mod</title>
	<author>Author name</author>
	<description>Brief description for the mod.</description>
	<version>1.0.0</version> <!-- current mod version -->
	<updated>01.01.2015</updated> <!-- last updated date -->
	<modtype>2</modtype> <!-- 1 - server, 2 - client-server, 3 - client -->
</root>

All these elements are mandatory for a mod and must be properly specified.

The header file must be placed like so:

root
-->  header.xml
-->  content/
-->  data/

In the same folder with content and data, that is.

Now, the way the game treats mod files is actually a bit more tricky. This is because you might have different versions of the same mod in your mods folder and since they share the same ID how would the game know which one to load?

To resolve this when a mod is loaded version of the mod is specified as well, along with its ID. The full internal ID for a mod is [id]_[version]. For instance, unique ID of this mod from the above example would be unique_mod_id_1.0.0.

To determine which mods the game should load there's a file ModsConfig.xml (usually located in the user documents folder). All mods, that should be loaded, should be listed in this file.

Main article: Installing and using mods

Lastly, Modtype is a special parameter which defines whether a mod should be loaded on server, on client, or on both. For example, if we want to create a mod which just replaces some icons, that would be a typical client mod. Client-side mods will be ignored by server, if listed in ModsConfig.xml. On the other hand, mods that contains only server-side alterations, like new topics or scripts are typical server mods. If they are listed in ModsConfig.xml, server will load them, but the clients wont, and the server won't demand that the player have then in order to play. It means, that if server has server-side mod, and client is not - it's okay. Lastly ther is client-server mod, which is needed on both client and server. If a server was created with specific server-client mod, and client doesn't have the same one, server won't let client to connect.

Modding overview

Now, the modding itself consists of a few essential parts:

Assets modding - where you can add or change graphics, sounds, visuals and such.
Content modding - adding new ships, weapons, items, or new quests, and basically extending the game content in some way.
Scripting - creating new mechanics that were not present in the original game.

VoidExpanse Modding (Edit template)
Using mods: Installing and using mods Overview articles: Modding (main article), Package files structure Topic specific articles: Assets modding, Content Modding, Scripting overview, Scripting API, Scripting Events system, Localization Detailed scripting articles: Internal scripts, Global scripts, object scripts, Device scripts, Consumable scripting Tools: VE Physics Adjuster, VE Mod Uploader (Steam), AT Localization Utility