Logic World Wednesdays #132: The Single-File Edition

Single-file mods - Ecconia

Ever since Logic World released in early access, mod loading has been supported. Mods generally are dropped in the [c]GameData/[/c] folder.

Most mods are distributed as folders containing all their assets. But Logic World always offered to also load mods as archive files ([c].zip[/c], renamed as [c].lwmod[/c]). But due to how Logic World was structured internally, archive mods have been missing much of the functionality available to folder mods. This made them unattractive for modders that knew of them.

At the beginning of 2025, I had enough of distributing my mods as folders, and I decided I wanted to use archive mods from then on. So, I set out to fix the deficiencies of archive mods. Now a year later, I can announce that archive mods are now fully supported by the game!

Why do we want to support archive mods?

Modders have always used folder mods. Folders are easy to edit, restructure and view, exactly what modders need. Even if you are not the creator of a mod, you can open up any mod and tweak it to your preference.

On the other side, if you wish to share a folder mod you will have to create an archive first. If you wish to download it, you must extract the archive you download. Most mods are distributed via GitHub, you can't just download a folder from a browser, it has to be archived. With folders mods you easily can move files into the wrong place and then enjoy wondering why things are not functional. Some modders host multiple mods in the same Git repository. Finding and selecting the right mods and folders from there has always caused confusion.

These are a lot of unnecessary steps for mod users. Why have these extra steps?

Archive mod files can be downloaded from a browser and used without file extraction. You can easily search for them due to the [c].lwmod[/c] file ending. If you ever wish to tweak an archive mod, simply extract it to convert it to a folder mod.

What did I need to fix?

There were two main problems with archive mods:

1. Many types of mod data could not be provided in archive mods, including sound effects, music, and DLLs.

2. The performance of archive mods was much slower compared to folder mods.

The first issue comes from technical limitations where these files must actually exist on disk. I fixed it by extending the mod data cache system -- which was previously only used to cache compiled C# code -- to also cache files that need to be extracted from archive mods.

The second issue was due to various inefficiencies in the way mod data was scanned, accessed and loaded. I reworked the problematic algorithms and it's all much speedier now.

As of today's preview release (more on that below), archive mods work great and have full parity with folder mods, while having the ease-of-distribution benefits that come from being a single file. I'm currently repackaging all my mods into [c].lwmod[/c] files, and they'll be available in that format soon!

Other modding improvements - Ecconia

While fixing the issues with archive mods, I was diving deep into Logic World's modding systems and I saw a lot of opportunities for enhancing them. Here are some of the improvements I made.

• The [c]GameData/[/c] folder is now scanned for mods recursively. You can now sort your mods in folders. Folders with a name starting with [c].[/c] and folders that contain an [c]ignore[/c] file are ignored. This allows you to sort mods and more quickly manage groups of mods at once. You also are able to dump modders' Git repositories into [c]GameData/[/c] and have the game find the mods inside automatically.

• Previously the game would skip mods if something was wrong with them. You mostly would notice this by other mods lacking dependenices and there being a console message. Now the game will go straight to the error screen, showing you that something is wrong with your mod setup.

• To count how often players deleted the base mod [c]MHG[/c] and wondered why the game does not start I need more than 2 hands. Now the game shows an error if the [c]MHG[/c] mod cannot be found instead of cryptic "settings could not be loaded" messages.

• JECS parsing errors now (finally) contain the full file path.

• Mods are now sorted by priority and alphabetically. Component definition files are also sorted alphabetically. This means modded components will now have the same order in the Selection Menu on every Logic World installation, no matter the OS or file system.

• On the server, some DLLs like [c]System.IO.Compression[/c] and [c]MessagePack.Annotation[/c] were not being loaded automatically. This caused a bunch of mods to break unless either mod [c]CheeseLoader[/c] or [c]AssemblyLoader[/c] are installed. This is now fixed. The server will now always load all its built-in DLLs before loading any mods.

• It is now possible to load DLL files automatically. The game loads them before compiling a mod. This is inspired by the mod [c]AssemblyLoader[/c] and uses the same structure. All DLLs must be in the [c]assemblies/ /[/c] folder, where [c] [/c] is either [c]client[/c], [c]server[/c] or [c]shared[/c]. If [c].pdb[/c] files are provided, these will be loaded as well.

Ok, I will launch a Patreon - Jimmy

Thank you to all the people who responded to last month's LWW on the subject of crowdfunding future development. Across logic.world, discord, steam, and email, dozens of people have told me how much Logic World means to them and said they intend to make a recurring donation.

I'm really touched by it all. Thank you for caring about this video game and being willing to support our work on it on an ongoing basis.

So, yes, I will launch a Patreon! Hopefully about a week from now.

I'm very eager to get back into full-time Logic World work and make this game the best it can be. I'm hopeful that crowdfunding is a path to doing that sustainably. If you have any thoughts you haven't shared with me yet on how you'd like the Patreon to look, please let me know, I'd really like to hear them.

Changelog: v0.92.3 Preview 98

A new update is out now on the public previews branch! You can get it by opting in to the beta on steam, like so:

Here's the full changelog for today's update, since Preview 57.

Modding

• Archive mods now have full feature parity with folder mods.

• Improved performance of archive mods.

• Improved performance of loading mod settings and localizations.

• Mods can now provide DLLs which the game will automatically load. DLLs must be provided in folders [c]assemblies/client/[/c], [c]assemblies/shared/[/c], [c]assemblies/server[/c].

• Mods can now be loaded from sub-directories of [c]GameData/[/c]. Folders which start with a [c].[/c] or which contain an [c]ignore[/c] file won't be scanned for mods.

• Renaming mod folders no longer breaks mod resource references. These references are now based on the mod ID specified in [c]manifest.jecs[/c], not the folder name.

• Updated the structure of the [c]cache/[/c] folder to allow caching mod resources.

• Mods are now sorted by priority and mod identifier to ensure consistent load order.

• Component definition files are now sorted by path to ensure consistent order in selection window.

• The server now makes sure all its assemblies are fully loaded before any mods are loaded. This fixes compilation errors with mods that used [c]System.IO.Compression[/c] and [c]MessagePack.Annotation[/c].

• Broken mod setups and manifest files now trigger an error screen instead of only logging the issue and skipping the mod.

• Improved error messages in the server console when a mod fails to load.

• [c]IModFiles.EnumeratingFiles()[/c] now requires a search pattern argument. This enforces efficient filtering, since you shouldn't be checking every file as that is quite slow.

• Replaced [c]GameData.Mods[/c] commands with [c]ModRegistry.Installed[/c] and [c]ModRegistry.Loaded[/c].

• Removed archive mod tampering detection.

• Fixed the game using files from mods which are not loaded (#348).

• Fixed mod identifier regex matching invalid mod identifiers.

• Fixed collision error if multiple mods provide the same instrument sample name.

Building

• When you Grab or Clone a component that was placed with fine rotation, its rotation will no longer be snapped to 90 degrees; the fine rotation is now preserved.

• Fixed various weird inconsistencies when using fine rotation during a Multi-Grab or Multi-Clone operation.

Miscellaneous

• A much more helpful error is now shown during startup if the base mod [c]MHG[/c] is not installed.

• JECS parsing errors now show the full file path in the stacktrace and the error screen.

• Fixed chat messages not appearing until you open chat.