VoidExpanse/modding: Difference between revisions

From AtomicTorchWiki
No edit summary
 
(10 intermediate revisions by 3 users not shown)
Line 1: Line 1:
== Overview ==
== Overview ==
VoidExpanse was designed to have great modding potential. Almost every aspect of game can be modified and extended.
VoidExpanse is designed to have great modding potential. Almost every aspect of the game can be modified and extended.
There are no hardcoded scripts and in-game logics, everything you see in VoidExpanse now was created as a "core" mod. This concept is similar to
There are no hard-coded scripts or in-game logic. Everything you see in VoidExpanse was created as a "core" mod. This concept is similar to early GameBryo versions.
early GameBryo versions.
 
The game uses so-called "package files" to load all external content and logic, both for the client and server.


== Package files ==
== Package files ==
All game data is loaded from two types of files: ".cpk" and ".mpk"
All game data is loaded from two types of files: ".cpk" and ".mpk". Please note that basically, these files are just a regular .zip archive (with no compression) and they should contain files directly, not in an extra subfolder.
 
===Core Package (CPK)===
 
Core packages contain essential game functionality and are the foundation of the game. The game cannot run without a core package which contains all in-game assets and logic. Only one CPK file can be loaded at one time.
 
===Mod Package (MPK)===
 
Mod packages are loaded on top of the core package 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 a 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 the core and mod packages are stored separately, the game will treat them as one file system with shared paths. Now, what does that mean?
 
As an example, let's say we have a CPK with a file located at "/content/some_file.txt" and an MPK with a file "/content/some_file.txt" that has the same path and name. What happens when we start the game? Since both files in the CPK and the MPK share the same path, the file stored in the MPK will '''override''' the one in the CPK since it was loaded '''after''' the CPK. This mechanism makes it possible to override the core functionality and content easily without recompiling the whole CPK or modifying 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 ==
* The core and all mods are loaded into one virtual file system, with an overwrite rule (See "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.
* MPK files are loaded in the order listed in '''ModsConfig.xml'''. If two MPK files have the same file (path+name), the file in the later MPK will be loaded.
* File names are '''NOT''' case-sensitive. QWER.xml and qwer.xml are considered the same file!
 
== Mod header ==
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.
===Structure===
The structure of the "header.xml" is:
<pre>
<?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>
</pre>
All the elements are mandatory for a mod and must be properly specified.
 
'''Modtype''' is a special parameter which defines whether a mod should be loaded by a server, client, or both.
 
* '''client''' - 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 servers if listed in '''ModsConfig.xml'''.
* '''server''' - 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''', a server will load them but clients won't, and the server won't demand that the player have them in order to play. Again, clients do not need any server-side mods to connect.
* '''client-server''' - Lastly there is a client-server mod, which is needed on both client and server. If a server was created with a specific client-server mod and the client doesn't have the same one, the server won't let the client connect.


".cpk" files are so called core packages, basically foundation of the game. The game cannot run without a core package which contains all in-game assets and logic.
===Location===
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 header file must be placed in the root of the MPK like so:
<pre>
root
-->  header.xml
-->  content/
-->  data/
</pre>
The content and data folders are also on the same level.


Now, the modding itself consists of two essential parts:
===Version Handling===
* Assets modding - where you can change graphics, or add new ships, or new quests, and basically extend the game content in any way.
* Scripting - creating new mechanics that were not present in the game.


== Assets modding ==
The way the game treats mod files is actually a bit trickier. This is because you may 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?
All objects in the game are assets. They are, basically, XML files, which are located in "[MOD]/data/..." folders.
For example, if you want to add a new item or a ship - it'll be asset modding.


Let's take a look at ship hull "shuttle".
When a mod is loaded, the version of the mod must be specified along with its ID. The full internal ID for a mod is [id]_[version]. For instance, the unique ID of this mod from the above example would be '''unique_mod_id_1.0.0'''.
Hull of this ship is presented in "data/items/hulls/hull_shuttle.xml". This file includes all information needed for the game to make this hull work: weapons slots, model, textures, blinks, engine trails, physics, etc.


Basically, to add a new ship all that you need is to add one more hull items to "data/items" folder of your mod. And model with textures, of course.
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.  
To make ship adding easy, we've created a special tool - [[https://atomictorch.com/Files/PhysicsAdjuster.zip|VE Physics Adjuster]], which is quite easy to use.


[[VoidExpanse/Adding_Ships|Core Mod / Adding Ships]]
The management of this file is now handled by the game. It will scan any MPK files in the mods folder and active mods can be selected by using the '''Mods''' option at the main menu. However, you can still manually edit the '''ModsConfig.xml''' if you wish.


== Scripting ==
{{Main|VoidExpanse/installing_mods|Installing and using mods}}


Scripting is the most important and essential part of the game. Everything - from galaxy creation to damage and prices calculations - are scripted and moddable.
== Modding overview ==
Now, the modding itself consists of a few essential parts:
* [[VoidExpanse/Assets_modding|Assets modding]] - where you can add or change graphics, sounds, visuals and such.
* [[VoidExpanse/Content_modding|Content modding]] - adding new ships, weapons, items, or new quests, and basically extending the game content in some way.
* [[VoidExpanse/Scripting|Scripting]] - creating new mechanics that were not present in the original game.


More information on scripting is in [[VoidExpanse/scripting_api|Scripting section]] of this wiki.
{{Modding}}

Latest revision as of 11:50, 26 February 2018

Overview

VoidExpanse is designed to have great modding potential. Almost every aspect of the game can be modified and extended. There are no hard-coded scripts or in-game logic. Everything you see in VoidExpanse 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 the client and server.

Package files

All game data is loaded from two types of files: ".cpk" and ".mpk". Please note that basically, these files are just a regular .zip archive (with no compression) and they should contain files directly, not in an extra subfolder.

Core Package (CPK)

Core packages contain essential game functionality and are the foundation of the game. The game cannot run without a core package which contains all in-game assets and logic. Only one CPK file can be loaded at one time.

Mod Package (MPK)

Mod packages are loaded on top of the core package 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 a 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 the core and mod packages are stored separately, the game will treat them as one file system with shared paths. Now, what does that mean?

As an example, let's say we have a CPK with a file located at "/content/some_file.txt" and an MPK with a file "/content/some_file.txt" that has the same path and name. What happens when we start the game? Since both files in the CPK and the MPK share the same path, the file stored in the MPK will override the one in the CPK since it was loaded after the CPK. This mechanism makes it possible to override the core functionality and content easily without recompiling the whole CPK or modifying 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

  • The core and all mods are loaded into one virtual file system, with an overwrite rule (See "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.
  • MPK files are loaded in the order listed in ModsConfig.xml. If two MPK files have the same file (path+name), the file in the later MPK will be loaded.
  • File names are NOT case-sensitive. QWER.xml and qwer.xml are considered the same file!

Mod header

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.

Structure

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 the elements are mandatory for a mod and must be properly specified.

Modtype is a special parameter which defines whether a mod should be loaded by a server, client, or both.

  • client - 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 servers if listed in ModsConfig.xml.
  • server - 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, a server will load them but clients won't, and the server won't demand that the player have them in order to play. Again, clients do not need any server-side mods to connect.
  • client-server - Lastly there is a client-server mod, which is needed on both client and server. If a server was created with a specific client-server mod and the client doesn't have the same one, the server won't let the client connect.

Location

The header file must be placed in the root of the MPK like so:

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

The content and data folders are also on the same level.

Version Handling

The way the game treats mod files is actually a bit trickier. This is because you may 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?

When a mod is loaded, the version of the mod must be specified along with its ID. The full internal ID for a mod is [id]_[version]. For instance, the 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.

The management of this file is now handled by the game. It will scan any MPK files in the mods folder and active mods can be selected by using the Mods option at the main menu. However, you can still manually edit the ModsConfig.xml if you wish.


Main article: Installing and using mods

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