How it works#

Load Order:#

• Defining an explicit load order is vital, and now mandatory for each awful project.
• If you've encountered No awful-config.json or Missing awful-config errors, keep reading.

Immersion:#

On load, awful immerses each file in an isolated bubble environment. Here are some things to note about it:

• Most protected API, by direct reference, is unlocked and/or modified to be consistent between all supported unlockers - default reads/writes are NOT from _G (global) environment.

• Each file is passed common namespaces as varargs to make use of our API and establish your own.

Understanding Load Order#

Dependencies first#

• You should plan an appropriate order for your files to load based on dependencies and dependents.. Here is a quick example:

.../project/project.lua (Dependency)#

local unlocker, awful, project = ...

project.print = function(str) print("(epicProject) >", str) end

• This file declares project.print as a function when first loaded, setting up a function we can use to make prints from our project fancier!

.../project/mage/fire.lua (Dependent)#

local unlocker, awful, project = ...
local mage = project.mage

-- routine actor
local fire = mage.fire

-- if player is not mage, stops code below from running
if not fire.ready then return end

-- Fancy Load Print!
project.print('Fire Mage Rotation Loaded')

• The above file calls project.print, the function we declared above, to print an OnLoad message for the mage rotation, as long as the player is on a mage. Note we declared and are accessing it through our project's namespace

Can you guess which one should load first?#

In this example it's clearly project.lua, but with a huge project containing many more files, it could become a much harder question to answer!

• We first have to declare the project.print function (as well as the mage table, our routine actor, etc.) before using them in fire.lua ... Now you have to consider this for your own personal project. Your variables, api, file structure, etc. will be unique to you, and the sooner you consider your explicit load order the better.

Configuring Load Order#

Creating awful-config.json#

Within your project's base directory ( awful/routines/project ), create a file named awful-config.json. You can assign a load order within this file. It must have either the .json or .jsonc extension, or it will not be recognized.

• The base directory is your project's base folder, ( awful/routines/project ). The load order is from top to bottom. Here is an example of the contents of a basic awful-config file

{
    "load": [
        "awful.lua",
        "spells/mage/mage.lua",
        "spells/mage/fire.lua",
        "actors/mage/fire.lua",
    ]
}

Now the listed files will be loaded from top-bottom.

⚠️ Important: If you don't list a file in your load order, it won't be loaded by Awful. Remember to always come back and add new files to your load order when you create them.

Cleaning it up#

• First, any file being loaded by awful will be of the .lua extension. You can omit these redundant file extensions from your awful-config if you want. Leading/traililng slashes will also be ignored.

{
     "load": [
        "awful",
        "spells/mage/mage",
        "spells/mage/fire",
        "actors/mage/fire"
    ]
}