Proper intro

So you just downloaded OvenInjector. Great! Now where are the mods, you may ask? Well, you make them. Mods don't grow on trees, especially with a mod loader this new!

But how exactly are you gonna make mods..? This is where this page comes in!

Because this documentation is still a WIP, I recommend reading the included mods' scripts instead (if it's readable enough) for referencing.

Another note that the API may change significantly, and therefore none of the info here is quite 'final'.

Where are my mods.

Options -> Mod Menu -> Congratition! You can exit out of it via your back or escape bind.

The Structure

Let's just say there's a mod folder

mods/

next, we add a new folder that will hold all of the script and asset files of our mod

mods/
- Sample Mod/

with this, a mod.ini file is required, which contains all the information needed for a mod to work.

[meta]
name="Sample Mod"
description="An example mod."
author="haya3218"
version="1.0"
icon="path/to/your/icon.png"
icon_base64="this can also be used if you want your icon to be b64 encoded instead, CST1229 TL mod loader style!"

The meta block defines metadata and general info about the mod. An optional gml block can also be added, if you want your gml scripts properly named.

The gml block takes numerous event callbacks. Which are:

init
destroy
begin_step
step
end_step
begin_draw
draw
end_draw
begin_draw_gui
draw_gui
end_draw_gui
room_start
room_end

By default, the game would look for these names plus the gml extension on the scripts folder for these events, except for the gui events. The draw_ part is ommited from those.

Now the general structure should now look like this:

mods/
- Sample Mod/
  - scripts/
    - init.gml
    - step.gml
  - mod.ini

Organized as it probably should. Hopefully.

API Stuff

Custom Controllers

Each mod works with a custom object (or controller) that runs the compiled gml files at runtime. This is akin to running gml code via obj_custom on ToppinLoader, though this is done by the mod loader itself instead of by you.

You can still create new custom controller objects, though be wary of making them persistent and have a modname variable, which is the name value of your mod.ini's meta block. You can access the base object controller's modname via simply referencing the modname variable on it's own.

// Insert cool stuff here
with (instance_create(0, 0, obj_customcontroller))
{
    // custom object is now persistent, meaning it'll stay regardless of being in a new room or not.
    persistent = true;
    // best to pass in the base script's modname for referencing it when the mod is disabled
    modname = other.modname;
    // This custom controller will run even when paused.
    runPaused = true;
    // If you don't want to man handle the object created on different step files, you can also manually create gml snippets here as well!
    events.step = live_snippet_create(@'
        trace("Hello!");
    ');
}

Grabbing Assets

Assets are loaded mostly the same with ToppinLoader, though the path to the assets are defined automatically instead of making users put the mod folder at a specific path.

// Look ma, I'm loading my assets!
var assetpath = mod_dir + "assets/";
mu_lap3 = audio_create_stream(assetpath + "mu_lap3.ogg");

This will load assets/mu_lap3.ogg and store a stream id for use with audio functions relative to the path of the location of the mod's ini file.

Handling Music

Music is a pain. Namely FMOD is still unavailable during this time (which might change...) but music isn't too much of a hassle unless you REALLY want to change a lot. If so, use a custom controller instead.

Custom music can be handled via scr_play_external_music(path) and scr_stop_external_music(), which play and stop external music respectively. These also account for your volume config as well as the pause menu. Do note that scr_play_external_music will ALWAYS stop the current running FMOD music, though this may change.

You can also instance obj_musiccontroller yourself, though I don't recommend it. Just use obj_customcontroller instead.

Mod-Specific Options

You can now make players configure your mods via the options key in the meta block! Like so:

[meta]
name="yeah"
options="enable_something,another_toggle"

Pressing TAUNT on the mod menu while hovering an active mod will bring up the options related to that mod!

Options have a default value of zero, though these can be changed via the options block:

[options]
enable_something="1"

enable_something will now be "ON" by default.

You can access these via referencing the option name in your scripts.

if enable_something
    yeah();
else
    nah();

If the option enable_something is on, it'll call yeah() here, and if it's off, it will run nah() instead.

Do note that this is NOT a global constant yet, and therefore is specified in the custom controller itself, so to access it within a with block be sure to prefix it with other.

with (obj_player)
{
    // This will error!
    if enable_something { }
    // This won't 
    if other.enable_something { }
}