You can find a collection of developed mods on the Discord server in the mods channel.
¶ Modding Documentation
The mod loader interprets any subfolder in the mods folder as a mod. The loading order is currently determined purely through alphabetic ordering, so if you want some mod to be loaded after/before another mod, you can achieve that b changing the name accordingly.
A mod essentially performs a resource redirection, so if the game were to request for a resource path/to/resource, and a mod A provides a file at mods/A/path/to/resource, the mod loader will change the resource url to the latter.
The resource paths in a mod must reproduce the directory structure of the original!
In order for a mod to provide a file, it must also register it in the Meta.json and describe how it should be merged in. The default operation would be to completely replace the original resource with the modded resource, however, this approach would cause mods to very quickly break each other. For example, if two mods were to customize two different items, they would both change the data/Items.json and only the last mod to be loaded by the mod loader would successfully apply its customization. The Meta.json can be used to fine-tune the way mod data gets applied to the base game.
¶ Meta.json
The Meta.json contains all information needed to load a mod. It has several sections for registering files that are documented in the following sections. The file itself has the following mandatory properties:
version: VERSION: The version of the mod.enabled: true / false: Whether the mod is enabled or not.
You can also find the property "$schema": "../../schemas/auramz/mod-meta.schema.json", which provides editors with information as to how the Meta.json is structured to provide intellisense features. You can ignore this property and shouldn't have to touch it.
Finally, you can define the following optional properties:
encryptedImages: false: Set this flag if the mod uses non-encrypted images but the game is set to encrypted images.encryptedAudio: false: Set this flag if the mod uses non-encrypted audio but the game is set to encrypted images.
¶ QUICK START
If you don't care about maximizing mod compatibility and just want a simple setup, list the affected files in the
filessection together with the affected object IDs in anoverrideoperation.
Minimal Example:
{
"$schema": "../../schemas/auramz/mod-meta.schema.json",
"version": "1.0.0",
"enabled": true,
"files" : {
"data/Skills.json" : { "override": [200, 201] }
}
}
This mod would override the skills with the IDs 200 and 201. For your mod, replace the Skills.json with whichever file your mod overrides and the IDs with the corresponding object IDs.
¶ Files Section
The files property redirects resource requests to the mod files.
Each entry has the form "path/to/file": operation whereas operation can be:
true
Redirect the url to the mod file, fully replacing the original.{ "append": objects }
Appends the data from the mod to the original data.{ "override": objects }
Overrides the original data with the mod data.
An entry can also contain both an append and an override.
To describe the affected objects, the following syntax is used:
true
Affects the full object. Use when overriding non-array properties.[objectIDs] OR "*"
Uses the objects of given IDs or all object ids from the modded file in case of the wildcard*.{ "property": objects}
Instead of affecting the full parent object, limits the operation to only affect the objects in theproperty.
Finally, the file path also allows a wilcard, so multiple resources can be registered in the mod via the syntax path/to/files/*.
"files" : {
"img/pictures/si/aura/Clothing_0.png" : true,
"data/Items.json" : { "override": * },
"data/Map001.json" : { "override": { "events": [1] } },
"data/Map005.json" : { "append": { "events": [29] }, "override": { "displayName": true } }
}
Will have the following effects:
- The mod will serve all requests for the resource
img/pictures/si/aura/Clothing_0.png. - All items in the mod's
Items.jsonwill replace the data of the corresponding items in the original items database. - The first event of
data/Map001.jsonis overwritten by the first event in the corresponding mod'sdata/Map001.jsonfile. - The mod's event of id 29 is inserted into the event list of
data/Map005.json - The display name of
data/Map005.jsonis overwritten by the display name of the modded map.
¶ Folders Section
The folders property redirects all urls which have one of the entries as a prefix to the mod.
This allows registering nested sets of folder structures but loses the ability of fine-tuned merging control.
Each entry is of the form "my/folder/prefix": true/false.
"files" : {
"img/pictures/hcg" : true
}
Will redirect all requests whose url starts with img/pictures/hcg to this mod.
¶ Plugins Section
The plugins property allows to register new plugins into the game's plugin list.
Each entry must follow the formatting of the game's js/plugins.js.
Plugins loaded by the mod loader are always loaded after all main game plugins have been loaded.
"plugins": [
{"name":"sample_mod_plugin","status":true,"description":"Sample Mod Plugin","parameters":{}}
]
Will register the javascript plugin sample_mod_plugin located in mods/mymod/js/plugins/ in the game's plugin manager and load it.
¶ Recommended Mod Creation Workflow
- Modify the base game files. You can either do this directly or using RPGMaker MZ if you own it.
To open the game with RPGMaker, create a file calledgame.rmmzprojectwith the contentRPGMZ [VERSION OF RPGMAKER MZ]. The value of the RPGMaker version number itself doesn't seem to matter, but it's important to be present to open the game - After performing your modifications, create a folder
mods/mymodnameand put the changed files into the appropirate directories.
EXAMPLE If you changed the file
data/Enemies.json, put it intomods/mymodname/data/Enemies.json.
- Create the Meta.json according to the above documentation. If you are using wilcards
*, make sure to clean up any content that should not be overwritten by the mod. - Test your mod and make sure that you have reverted the files in the original game back to normal so you know any changes actually come from the mod folder.
- Share your mod in the Discord by making a new post in the #mods forum.
¶ (Optional) Creating an executable installer
If you want to automate the installation process so the user doesn't have to find the mods folder and unzip the mod files into it, you can use an installer generator to create a patch exe.
-
Install the tool Make NSIS. Add the makensis variable to your system path variables so you can easily call it form the command line.
-
Create the following directory structure:
MY_PARENT_FOLDER/
├─ build/
│ ├─ MY_MOD/
│ │ ├─ MY_MOD_FILES
│ ├─ MY_MOD-installer/
├─ releng/
│ ├─ mod-installer
│ │ ├─ mod_installer.nsi
│ │ ├─ ...
and download the mod installer files from the AuraMZ Repository into the correspondingreleng/mod-installerfolder. -
In the
mod_installer.nsiedit the config values to fit your mod.
The mandatory config options have to be set, the optional ones can be removed.
Mandatory
!define GAME_NAME "Star Knightess Aura"
!define BUILD_NAME "MY_MOD"
!define MOD_NAME "MY_MOD"
!define MOD_DESCRIPTION "MY_MOD_DESCRIPTION."
Optional
!define MOD_AUTHOR "YOUR_NAME"
!define MOD_LICENSE "PATH_TO_YOUR_LICENSE_FILE"
!define MOD_BANNER "PATH_TO_BANNER.bmp"
- Open a terminal in
MY_PARENT_FOLDERand execute the command
makensis -DMOD_VERSION="MY_MOD_VERSION" ./releng/mod-installer/mod_installer.nsi
You should find the built exe file in the folder MY_MOD-installer.
¶ More Examples
¶ Adding New Variables
Meta.json:
"files" : {
"data/System.json": { "override": { "variables" : [1401] } }
},
Explanation:
Will put the variable at position 1401 from the modded System.json into the variable list of the original System.json at position 1401.
¶ Extending Common Events Without Conflicts
Meta.json:
"files" : {
"data/CommonEvents.json" : { "append": {"[6]": { "list": "*" }} }
},
Explanation:
Will append all code from the modded common event at index 6 into the execution list of the original common event at index 6 of CommonEvents.json. Should another mod do the same, they will both add their code into the execution list.
¶ Modifying an Object's Meta Properties
Meta.json:
"files" : {
"data/Skills.json" : { "override": {"*" : { "meta.score_cost" : true } }}
}
Explanation:
Accesses meta.score_cost of all skills listed in the modded Skills.json and writes them into the original.
Note that { "meta.score_cost" : true } gets parsed as { "meta" : { "score_cost" : true }.
All notetags in the info section of an object with the form
<notetag: value>are at run-time a subproperty of the "meta" of an object. Tags of the form[tag value](such as skill cost tags) on the other hand cannot be found under "meta". In order to override such a tag, the entire note property has to be overriden.
Example for overwriting the complete note field:
"files" : {
"data/Skills.json" : { "override": { "*" : { "note" : true } } }
}
¶ Tips & Tricks
¶ Meta.json Auto-Complete and Validation
When creating complex Meta.json files, it's recommended to edit them using VS Code. This will give you some validation checks to warn you if something is wrong with the file's structure and also provides various forms of auto-complete suggesions.
¶ Mod Ideas
SKA: The Power of Nightmares. A design document for a potential mod that adds depth to Luciela's gameplay in the mental world.