Framework Tutorial

Published 3 years, 3 months ago

Whether you want to play Hyper Light Drifter with mods or create mods of your own, this tutorial will show you how to install and manage the AER modding framework.

1 Preface
2 Aerman
3 Installation
3.1 GUI
3.2 CLI
4 Mod Management
5 Modpack Management

1 Preface

This modding framework only works on Linux for the time being. It's possible that a Windows version might come out someday, but that wouldn't be for quite a while. I really am sorry about this... I know having to use Linux is a rather big inconvenience for most.

If you've never used Linux before and you're willing to try it in order to use mods, then I'd recommend Ubuntu.

Beyond that, it's possible that the framework only works for the Steam version of HLD and not the GOG version. If you have the GOG version and you use Linux, I'd greatly appreciate a status report!

2 Aerman

Separate from the AER framework itself (which consists of the "executable patch" and the "mod runtime environment") are AER user interfaces. Think of these as the actual "mod managers" that you use to install mods and the like. I tried to design the framework in a way that doesn't favor any one method of managing mods because I wanted to allow people to develop third-party AER UIs that work in different ways.

I'm not particularly skilled at developing user interfaces in general, so I focused most of my development effort on making the AER patch and runtime. Regardless, ya'll still need some method of managing mods right now, so I whipped up aerman (short for "AER Manager"). It's a bare-bones command-line AER UI you can use to install the framework and manage mods. It does have an experimental GUI front-end that uses the Zenity toolkit .

To use aerman, download the latest release (either archive of the source code is fine), extract it where ever you like and then open a terminal window in the newly extracted directory:

Run the following command to see if it's working:

$ ./aerman.sh help

3 Installation

You can use either the command-line interface or the graphical user interface to install the AER framework.

3.1 GUI

Run the following command to start the GUI:

$ ./aerman.sh gui

Now double click the "Framework" entry:

Then double click the "Install the Latest Framework Patch and Mod Runtime Environment" entry:

3.2 CLI

Run the following command to install the latest version of the framework:

$ ./aerman.sh framework-complete-install

4 Mod Management

Note: The remained of this guide uses the CLI, but the GUI can perform all of the same operations.

With a working installation of the framework, you can now start installing mods (such as the latest release of the balloons mod.

To install a mod, run (but substitute in the correct name and version number):

$ ./aerman.sh mod-install path/to/libmod-X.X.X.tar.xz

If you want to install several mods at once, you can pass them all to that command, and it'll install them all together.

To see which mods you have installed, run:

$ ./aerman.sh mod-list

5 Modpack Management

Installing a mod with aerman doesn't mean that it will be enabled. That's where the concept of "modpacks" comes in. The AER framework expects to find mod libraries and assets in certain places, and it expects to find a TOML configuration file called aer/conf.toml that tells it which mods to load and what their settings are. The framework, itself, has no idea what a modpack is, it's simply a result of aerman swapping the right mod files and configuration file into the right places just before starting the game.

To create a new modpack, run the command:

$ ./aerman.sh pack-create name_of_new_modpack name_of_mod_1 name_of_mod_2...

This reads all of the listed mods' configuration data and creates an AER conf file with all the default settings.

To change any mod settings specific to that modpack, run the command:

$ ./aerman.sh pack-edit name_of_modpack

This will open that modpack's TOML configuration file for editing, and it'll probably look something like:

# ================================
#  MODPACK:  main
#  CREATED:  2021-01-14T23:24:59Z
#  TOOL:     aerman (1.0.0)
# ================================
 
# ================================
# MRE
# ================================
[mre]
# Mods in this modpack from highest priority to lowest.
mods = [
"balloons",
]
 
# ================================
# BALLOONS
# ================================
[balloons]
# Keyboard binding to spawn a balloon.
#input.keybind.spawn_balloon = [160,66]
# Keyboard binding to pop all balloons.
#input.keybind.pop_balloons = [160,80]
# Alarm index to use for balloon carcass object fading.
#alarm.balloon_carcass.fade = 0

Finally, once you're happy with the configuration, you can launch the modpack by running:

$ ./aerman.sh pack-run name_of_modpack

#nondevtut