Difference between revisions of "Modding internals"

Latest revision as of 12:33, 2 October 2017

General

When talking about "Modding", we refer to editing existing content as well as creating your own. This pack of custom content is called a "mod".
This page explains how these edits to existing content are handled by the system. (New content is simply loaded and added to the other content.)

In the editor, you work with projects. When publishing a project in the editor, it puts itself online for others to download and enable in their game.
"Project" is simply what we call a mod in the editor for ease of use.
So, when people talk about "modding", "creating mods",... they are talking about creating/publishing/downloading projects other people made in the editor.

Dependencies

To be able to edit existing content, you need to be able to load that content. That's what dependencies are for. A project can be dependent on any number of other projects.
While in the editor, these can be defined in the Project settings window.
On top of its own data, a project loads all data (levels, resources, root templates, scripts,...) from its dependent projects.
So via dependencies, you are able to load and view/edit existing content in your own projects.
Anything you edit is stored in your own project under the same folder structure and ID as in the dependent project.

Hence, to edit existing content, you do the following:

1. Create a project, dependent on the project containing the items you which to edit
2. Open those items and change what you want to change
3. Save your project

Overriding existing items

Everything has a unique identifier. Levels have unique names, items have unique ID numbers (GUIDs),... All data is stored under its unique ID.
During loading, the system checks if an ID already exists or not. If the same ID was loaded before, the data currently loaded overrides the old data associated with that ID.
Remember that you can use dependencies to view and edit data from other projects and those edits are stored separately in your project under the same ID.
This way, it is possible to create a project that contains the same ID multiple times, which will cause one to override the other.

_{The dependency order makes it so in the final version both swords have been overridden.}

Project Types

There is an extra restriction on projects: the project type. The two available types are: Adventure and Add-on.
Adventures are full campaigns, like the main story. When creating your own adventure, you are expected to create your own story, or edit a dependent one, and do the necessary scripting.
Add-ons are (smaller) projects that can be toggled on/off while playing an adventure. An example would be an add-on that adds 2 new swords to the game.

This separation exists to allow drop-in/out mods.
Any changes to the game's story get stored when saving the game. This makes that savegame incompatible with the previous version of the game.
To avoid making savegames incompatible when downloading and enabling mods, story editing is disabled in Add-ons.
Thus, an Add-on can be enabled/disabled as often as a user wants while playing a campaign.

Adventures, on the other hand, have story editing enabled. The game always runs on the story data of one adventure.
This story can be fully contained in that adventure, or be a compilation of its own story data and that of all its dependencies.

Load Order

To ensure that your item overrides the original one, it needs to be loaded after the original one. This "load order" is defined naturally by the concept of dependencies.
First, all dependencies are loaded, then your own project.
When working with multiple dependencies, you need to be aware of their load order because two or more dependent projects might also have the same item defined, as visible in the image above.
To make sure that dependencies load in the correct order, the dependency load order can be defined in the Project settings window

In-game add-ons

In the editor, you only load a project and its dependencies.
The same goes for in game where, depending on the game mode, you load a specific adventure and its dependencies.
But you are also allowed to enable any number of additional add-ons.
To ensure correct loading and overriding of items, an add-on's dependencies are loaded after the adventure's dependencies, but before the adventure.
The add-on itself is loaded after the adventure. This load order ensures that things get loaded as expected, as illustrated in the image below

_{First we load adventure dependencies. Then the main adventure. Then all add-on dependencies, then add-ons.}

EXCEPTION: The standard modules for Story, Arena and GM are always loaded before the main adventure!
This ensures that no custom content gets accidentally reverted by an add-on that depends on one of the original modules.

Data Location

When creating a project, data gets stored in three locations in your editor's data folder:

• Editor-only data: "Data/Editor/"
• Game data: "Data/Mods/" and "Data/Public"