Published 3 years, 3 months ago

In this tutorial you'll set up your project workspace. If you already have a C development workflow, feel free to skip this tutorial.

Note: This tutorial is for an outdated version of the mod runtime environment.

Contents

1 System

The MDK expects certain things to be true about your system in order to function.

1.1 Environment Variables

To start, you'll need to create an environment variable that tells the MDK (and aerman) where Hyper Light Drifter is installed on your system. Different Linux distributions have different methods of setting environment variables, but it generally involves adding an export entry to a bash script in your home directory. This script is likely called .profile, .bash_profile or .bashrc. (Though it could have another name. If in doubt, search "(your_linux_distro) add environment variable" on the internet.)

Once you've located this script, add the following entry to it:

export AER_GAMEDIR="$HOME/.local/share/Steam/steamapps/common/HyperLightDrifter"

This should be fine if you use the Steam version of HLD, but if your game installation is located somewhere else, make sure this environment variable reflects that.

Now you may have to log out and back in for this change to take effect.

1.2 AER Framework

Next, you'll need to make sure the AER modding framework, itself, has been installed to the location pointed to by the AER_GAMEDIR environment variable. See this tutorial for more information.

1.3 C Compiler

Now you'll need a somewhat recent version of a C compiler installed on your system. Using your package manager, make sure you have one of GCC or Clang installed. Either should work fine, but the MDK uses GCC by default, so you'll have to do some extra configuration if you use Clang.

Trying to compile a C project with just the compiler is a particularly error-prone task, so you'll also need the CMake build system. You should be able to install this using your package manager as well.

1.4 Visual Studio Code

Finally, you'll need an editor/IDE in which to do your development. There are a host of potential editors/IDEs that you can use for C development on Linux; it's really a matter of preference. The MDK uses Visual Studio Code, which is somewhere in between an editor and an IDE. It has its issues, but I felt that it offered the easiest and most straightforward mod development experience. Your package manager should be able to install this tool.

Note that VS Code comes in two variants: proprietary and open-source. Either will work fine for mod development, but there are a couple extensions you'll need that the proprietary variant can automatically install. If you use the open-source variant, you'll have to manually install these extensions (which I'll walk you through later). Personally, I use the open-source variant, but you should be able to follow along in this series of tutorials exactly the same using the proprietary variant.

2 Mod Development Kit

With your system properly configured, you're ready to setup your development workspace.

2.1 Setup

The first step is to download a copy of the MDK. There are several different ways you could do this, but downloading it from here is likely the easiest. Then extract the archive and name the resulting folder whatever you want to name your mod. Your mod's name should only contain lowercase ASCII letters, numbers, and underscores.

Now open VS Code. If all goes well, it should look something like this:

If you've never used VS Code before, I strongly suggest that you watch this guide by Microsoft before continuing.

Next, click on the File menu, then select the Open Folder... option:

Navigate to and select the MDK folder you just extracted and renamed. Depending on which variant of VS Code you installed, there will be pop-up boxes in the bottom-right corner either recommending extensions or warning that VS Code can't find certain recommended extensions. Just close these boxes for now; you'll install extensions a bit later.

Then, from the Explorer tab on the activity bar, open the file .vscode/settings.json. Edit the mdk.modName entry to reflect the mod name you chose earlier:

Following that, open the file CMakeLists.txt and edit the project command to reflect the same mod name:

2.2 Extensions

Now you're ready to install the VS Code extensions that I've recommended with the MDK.

2.2.1 Proprietary

If you use the proprietary variant of VS Code, navigate to the Extensions tab of the activity bar and install the first four recommended extensions. There may be other extensions after the first four, but just ignore those:

2.2.2 Open-Source

If you use the open-source variant of VS Code, navigate to the Extensions tab of the activity bar and install the first two recommended extensions. There may be other extensions after the first two, but just ignore those:

Next, download these two extensions from the VS Code Marketplace: C/C++ and Clang-Format. Then click the ... in the top-right corner of the Extensions tab and select Install from VSIX...:

Then install the two extension files you just downloaded.

2.3 Clang

If you prefer to use the Clang compiler over GCC, then open the file .vscode/settings.json. Change the C_Cpp.default.compilerPath entry from /usr/bin/gcc to /usr/bin/clang and change the C_Cpp.default.intelliSenseMode entry from gcc-x86 to clang-x86:

2.4 Tasks

VS Code uses the concept of "tasks" to allow users to configure custom build commands. I've included a number of these tasks in the MDK, and you can view and run them by hitting Ctrl+P then typing "task " with a space at the end:

Most of these tasks are just internal dependencies for other tasks. The main ones you'll be interested in are:

The debug build includes ELF debugging symbols and other constructs that make it feasible to run your mod using a proper debugging tool. Generally speaking, you should be using debug builds when developing your mod and release builds when giving your mod to others/the public.

Since you'll likely be running the Build Debug task a lot throughout development, I've mapped it to the keyboard shortcut Ctrl+Shift+B.

2.5 Project Files

A mod project consists of the following key files and directories:

2.5.1 CMakeLists.txt

The CMakeLists.txt file is the main build script of your mod. The tasks I added to the MDK use this script in order to build and package your mod. It uses the CMake Language.

The version option of the project command should generally follow the Semantic Versioning Standard. Technically, the version just needs to have between 1 and 3 numbers in it separated by periods.

You'll also need to add new entries to the:

set(SRC
  src/moddef.c
  )

command near the top of the file as you add new C source files to your mod.

2.5.2 ModInfo.json

The ModInfo.json file is the definitive source of metadata about your mod. The AER framework, itself, doesn't actually use this file, but I chose to make it part of the standard so that mod managers like "aerman" can get important information about mods at a glance.

Most of the fields are automatically populated from CMakeLists.txt, but I want to give configuration special mention. It lets external tools know how to configure your mod. You'll learn more about this field in a future tutorial.

2.5.3 Assets

While the MDK doesn't come with this by default, many mods will also need an assets directory at the root of their project. For now this is just used to hold mod sprites, but it will also be used for audio once the AER framework adds that support. Mods that don't add any custom sprites don't need an assets directory.

2.5.4 Sources

The src directory is where all of your C implementation files (the ones ending in ".c") should go. You are free to create whatever directory structure you want within this directory.

2.5.5 Headers

The include directory is where all of your C header files (the ones ending in ".h") should go. As was the case with src, you're free to organize the files within this directory however you want.

2.5.6 Copyright

While it is not a requirement, you are strongly encouraged to provide licensing and copyright information about your mod.

A basic LICENSE.txt file is provided in the root of your project. Users will have to accept this license before being able to install your mod (but you can delete it if you want). This license file should be used for both source code and asset licenses.

Here is a list of many pre-designed software licenses you can use. Note that there are even more than this website suggests. Most of the software in the AER framework uses the Apache 2.0 license.

Creative Commons provides a lot of great asset licenses. Most of the assets in the AER framework use either CC0 1.0 or CC BY 1.0.

The ACKNOWLEDGMENTS directory is where you can acknowledge the external libraries that you use. The copyright information for "aermdk" and "libaermre" have been pre-populated.

2.5.7 Build

The build directory is where your compiled/packaged mod assets are staged. Debug builds will go in build/debug and release builds will go in build/release. Your built mod library will be a file in either of those two sub-directories with the name lib<mod_name>.so, and the installable mod archive will have the name lib<mod_name>-<mod_version>.tar.xz.

3 First Compilation

Open the file src/moddef.c:

Notice the red squiggle underneath the line #include "export.h"? This is because CMake hasn't generated your build system yet. This is automatically handled any time you build, package or debug your mod, so go ahead and build your mod by pressing Ctrl+Shift+B. Now you may have to reload your mod project (just this once):

Now that you've generated your mod's build system (and also built the mod, itself), the IntelliSense tool provided by the C/C++ extension understands where all of your mod source and header files are located. As a result, the red squiggle from earlier is gone, and now you can hover your mouse over globals, structures and functions imported from the AER mod runtime environment to display a condensed documentation panel.

With that, your modding workspace is ready!

Note: This tutorial is for an outdated version of the mod runtime environment.

#dev #moddevtut