Ostra.Autoloader

Ostra.Autoloader is a simple tool that automatically generates your loading_order.json file for Ostranauts mods. No more manual editing or guesswork!

Why use Ostra.Autoloader?

• No manual JSON editing: Mod authors can include a special Autoload.Meta.toml file in their mod folder, and Ostra.Autoloader will read it to figure out how to load the mod.
• Supports mods outside the default folder: Mods placed in other folders like BepInEx/Plugins (used by some mod managers) will be discovered automatically.
  • This means mod managers can install mods for you, finally, no more manual installing!
• Automatic dependency handling: Mods can declare dependencies on other mods, and Ostra.Autoloader will make sure those dependencies load first. This helps avoid common mistakes where mods fail because their dependencies are missing or loaded in the wrong order.

How it works

1. Scan for mods: Ostra.Autoloader looks through your Mods folder and the BepInEx/Plugins folder for any mod folders containing an Autoload.Meta.toml file.
2. Read mod info: It reads the mod's mod_info.json and Autoload.Meta.toml to gather information about the mod and its dependencies.
3. Resolve dependencies: It figures out which mods depend on others and generates a correct loading order for you.
4. Create loading_order.json: Finally, it writes out a loading_order.json file automatically, so the game knows the right order to load your mods. No more invalid json errors!

Configuration

Ostra.Autoloader will generate a configuration file on first run. Use your mod manager's config editor or manually edit BepInEx/config/Ostra.Autoloader.cfg to modify these values

• BackupNeeded: Managed automatically by Autoloader to determine if it needs to backup the existing load_order.json file. Will backup your load order the first time it runs if a backup doesn't already exist.
• UninstallMode: Will clean up all changes made to the game and restore the backed up load_order.json file if it can. Once this flag is set Autoloader will no longer function until it is unset. Set this flag then run the game again prior to removal to ensure a completely clean uninstall process.

Installation

Manually (Not Recommended)

[!NOTE] There are no pre-built releases yet. Ostra.Autoloader is in pre-release so you will have to build it yourself, sorry.

• Download the Ostra.Autoloader.dll from a release and place it in your BepInEx/Plugins folder
• Place any downloaded mods that support Ostra.Autoloader under your game's Mods directory or BepInEx/Plugins for discovery

Automatically (Easy)

• Download a mod manager that supports the Ostranauts community on the Thunderstore
• Select the Ostranauts community and create a new profile
• Browse the available mods and press "Install" on any that support Ostra.Autoloader. Autoloader will be downloaded as a dependency
• If the mod manager indicates there is an update for the mod, you should generally always do so. It is recommended to keep Ostra.Autoloader at its latest version since the manifest and loading methods may change.

Mod Managers:

• Gale Mod Manager
• R2 Mod Manager

Example mod folder structure

Mods/
└── MyCoolMod/
    ├── mod_info.json
    └── Autoload.Meta.toml

BepInEx/
└── Plugins/
    └── AnotherAwesomeMod/
        ├── mod_info.json
        └── Autoload.Meta.toml

Notes for mod authors

• Include an Autoload.Meta.toml file that lists dependencies and loading group or Ostra.Autoloader will skip your mod entirely
• Ostra.Autoloader will handle the rest, ensuring your mod loads after its dependencies.

See the default Autoload file for more information on how to use Autoload files

How to package for the Thunderstore

Mod managers that install from the thunderstore will modify your folder structure. Please be familiar with the package documentation

Sample Package Layout:

[!NOTE] As shown in the image, your mod's DLL files must be under a folder named /plugins.

Individual JSON mods should also be underneath /plugins in their own folders. Each JSON mod should have an Autoload.Meta.toml file right next to their mod_info.json.

Finally, all your Thunderstore package files should be directly on the root of the zip you create. That means there should be no folders before you can see manifest.json, README.md and icon.png

Feel free to examine this ExamplePackage to get a better feel for how to package your mod.

Best Practices for Mod Load Order Coordination

Here's some basic guidelines on when you should use what type of dependency for your mod:

• Declare hard dependencies for required mods:
  If your mod requires another mod to function, declare it as a hard dependency. This guarantees your mod loads after it.

• Use soft dependencies for optional compatibility:

  If your mod adds features when another mod is present but can work without it, declare a soft dependency to load after that mod if it’s installed.

[!IMPORTANT] A soft dependency won't cause resolution failure so your mod will still work without it present!

• Communicate with other mod authors:
  Coordinate load order needs, especially when your mod overrides or patches behavior in another mod. Work together with other modders to coordinate hard and soft dependencies, especially with patch or fix mods that work conditionally.

• Document load order requirements clearly:
  Include instructions or metadata so users and tools know how to load your mod relative to others.

• Follow community standards and conventions:
  Participate in modding community discussions and adhere to established best practices for declaring dependencies and load order.

These practices ensure users or tools like Ostra.Autoloader will have an easy time installing and using your mods.

I want to use a mod that doesn't support autoload files

[!IMPORTANT] These instructions will only work for simple mods that do not have any dependencies. More complex mods should have their Autoload.Meta.toml file tailored to work by the mod's author.

First, install the mod manually to your Mods folder like normal.

Then, try placing the default Autoload file in the mod's directory next to the mod_info.json file. If the mod doesn't depend on FFU, you should be set and it should just load correctly. If the mod depends on FFU, you should change the LoadGroup in the Autoload file to AfterFFU.

Troubleshooting / Common Problems

• If your mod isn't loading, check the log file (BepInEx/LogOutput.txt) in your profile for warnings about missing dependencies or malformed meta files.
• Ensure the Autoload meta file is properly formatted
• Ensure the Autoload meta file is named exactly Autoload.Meta.toml

License

This project is licensed under the GNU Public License Version 3, see License for more information

Contact

For questions or support, please join the Blue Bottle Games discord and contact the mod author, Robyn, or open an issue in the github repository

Enjoy hassle-free mod loading with Ostra.Autoloader!