1. Object Config and Config Options

The CustomObjectConfig Class

The CustomObjectConfig class is how you register new custom objects and is the main interface for changing high-level properties of your objects without writing a new class. The goal for this class is to enable developers to easily create any basic object that isn't a complex trigger or anything not seen in the vanilla game, without interacting with any real object code.

---

To register a custom object and obtain its CustomObjectConfig is extremely simple. Just make sure to include the API header, and then register your object immediately when your mod loads using $execute or $on_mod(Loaded):

#include <glow12.custom-objects-api/include/CustomObjectsAPI.hpp>

// Run when your mod loads to properly register a new object
$execute {
    // You can configure your object inline
    CustomObjectsAPI::registerCustomObject("my_custom_object.png"_spr).setBoxSize(20, 20);

    // You can also save a variable and configure your object on multiple lines
    auto object1 = CustomObjectsAPI::registerCustomObject("my_other_object.png"_spr);
    object1.setBoxSize(20, 20);
}

The function CustomObjectsAPI::registerCustomObject takes your settings for the main sprite that your object will use. The sprite can be from a sprite sheet or simply a file, as the API will check for both when adding them to the sprite sheet. You can also change the size of your sprite as well as the sprite offset, which I will try to cover in the section for the CustomSpriteConfig. One good thing to know is that everywhere you can add or edit a sprite with this config, such as the Detail sprite and the Glow sprite, the format will be exactly the same (sprite name, size, offset).

(Note: If you disable batch rendering for your object, the sprite will not be automatically added to the sprite sheet, meaning that these settings WILL NOT WORK and that you are responsible for ensuring that the sprite is part of a sprite sheet and is the correct size / offset!)

---

Object IDs

One important thing to keep in mind is the object IDs of your objects. This API will assign all of your objects a "starting ID" based on your mod's ID. It does this by hashing your mod ID string, ensuring (theoretically) that there are no conflicts with other mods that use this API. All custom objects that your mod adds will always be given an object ID starting from the mod's "starting ID" and IN THE ORDER THEY ARE REGISTERED. For this reason it is recommended to register all of your objects in the same $execute block or the same function so that there is no ambiguity as to which object ID comes first.

Another thing to keep in mind is that if you change the order in which your object is registered or if you remove a registered object, your object IDs will change too, meaning that any level already using your custom objects will break! There are several workarounds provided by the API, but a general rule of thumb is to NEVER mess with your object IDs unless you know what you are doing and are aware of the consequences.

Removing Registered Objects

To safely remove a registered object, remove the call to CustomObjectsAPI::registerCustomObject that registers your object and replace it with CustomObjectsAPI::addIDPadding. This function simply adds a single object ID of padding, ensuring that any subsequent registered objects will not have their IDs changed.

Changing Editor Tab Order

Your custom objects are sorted in the custom editor tab based on the order in which they were registered. If you want to change the order of your objects in the editor tab without breaking any object IDs, use the setEditorTabPriority function in the config of the object that you want to change:

// This object will appear in the editor tab BEFORE other objects with a higher priority value, default priority is 0
CustomObjectsAPI::registerCustomObject("my_custom_object.png"_spr).setEditorTabPriority(-10);

Object ID Collisions

Lastly, it is theoretically possible for two mods to have the same "starting ID", or for them to be extremely close to each other. If by some miracle of unluckiness there is a known collision between your mod's object IDs and another mod's objects, you have a limited ability to offset your mod's "starting ID" so that it doesn't overlap with another mod.

$execute {
    // This must be set BEFORE you register any custom objects
    // This just manipulates what gets hashed to determine your "starting ID", it doesn't just add this number to the IDs
    CustomObjectsAPI::setCollisionOffset(67);
}

---

CustomObjectConfig Functions

wip