Please read this entire article before using the framework!
The sideloader framework can be used by mod authors to load additional package files in LE1, without messing with streaming states. It works using a new 2DA table that is merged into, BIOG_2DA_Mods_X.StreamingLevels. This article details how to use the 2DA to load your own package files.
Setting up the 2DA:
In the Miscellaneous Downloads section, you will find a starter 2DA file. This is the file that will be used to merge into the new 2DA table, and it should go in your mod's DLC folder. I'd suggest reading 55tumbl's 2DA merge tutorial to understand how this works. You will need to rename the file, and the package export (export 1) to include your mods name. You should also update the object index of the 2DA table to be unique, but I do not believe the indexes need to be sequential (so it's okay to have a StreamingLevels_part_2 and then a StreamingLevels_part_69420). You will also need to add the following line to your AutoLoad.ini file:
2DA1 = BIOG_2DA_MOD_YourMod_Mods_X
Obviously change "YourMod" to the name you used when renaming this file. If you have multiple 2DAs as part of your mod it may end up being 2DA4 or whatnot.
How to load files:
File loading works on a per-file, level prefix name basis. Each file you want to load should be a new row in the 2DA. Remember each row needs to have a unique index, so check other mods to make sure row IDs are distinct. Here is what a sample row looks like:
Here is an outline of what each column in the table does:
- LevelName - A name. The full name of the package file you would like to load, excluding ".pcc". A value of "BIOA_AMBIENTS" will load BIOA_AMBIENTS.pcc, as well as BIOA_AMBIENTS_LOC_INT.pcc if it exists. (Or whichever localized version the user has selected)
- LoadIfPrefix - A name. This is the important bit. This tells the framework which levels to load your new file with. You can give it a full level name, or a partial level name. If any levels matching this name/prefix are visible, your level will be visible. If all matching are loaded and not visible, your level will be loaded. If no loaded or visible levels match, your file will be unloaded. A value of "BIOA" would load your file all the time. A value of "BIOA_STA" would load your file everywhere a Citadel file is loaded. "BIOA_STA60" would load your file through the entire wards, while "BIOA_STA60_11A_DSG" would load your file at the same time as that file is loaded. You can use this to be very granular about when your file should be loaded.
- Conditional - An integer. If this number is greater than zero, this is a conditional ID to check when your file is loaded. If the conditional is false, your file will not be loaded. Be careful with this, as the conditional becoming true while in the loaded area may cause a blocking load on the next streaming trigger.
- State - An integer. If this number is greater than zero, this is a plot bool ID to check when your file is loaded. This works exactly the same as Conditional. If you provide both a conditional and a state, your file will only be loaded when both evaluate to true. Be careful with this, as the bool becoming true while in the loaded area may cause a blocking load on the next streaming trigger.
- LoadFirst - An integer. Unused, column exists for future expansion. This value is currently never read.
- ReplacePackage - A name. Unused, column exists for future expansion. This value is currently never read.
So, to recap. The example 2DA table from above will load the file BIOA_AMBIENTS.pcc whenever you have any loaded levels with the prefix "BIOA_UNC", which would be all uncharted worlds.
Other notes:
You can use the Streaming Levels HUD ASI found in the mod manager to see when levels load, and to ensure your level gets loaded at the right time. I'd suggest doing this frequently to make sure everything is working.
I'd also recommend rigorously testing entering and exiting the area you want your file to load in to make sure there are no unexpected blocking loads. This should include loading saves in that area. It is very easy to mess things up and create little blocking loads all over the place.
You can put the same LevelName in multiple rows if you want your level to load in multiple distinct areas, or want more granular control over where your level loads. The "highest" status takes effect, so if any rows return that the level should be visible, the level will be visible. Rows containing the same LevelName must be consecutive and adjacent to each other, or else unintended behavior may occur due to how the rows are checked. This feature is one that I would like to improve upon, so this caveat may go away in the future.
A note on "global" file loading: A LoadIfPrefix of "BIOA" would load your level at all times, but it does not ensure that your file loads first. You may have some success using this to overwrite assets without updating every instance, but it is not a guarantee. A LoadIfPrefix of "BIOA" is intended to be used for things such as console commands or other sequences that should be accessible from everywhere in the game.
This framework is in Beta. If you encounter any bugs, please open an issue on this mod page. If you have any concerns, ideas, or need help using the framework, feel free to reach out to me on the Mass Effect Modding Discord, or via Nexus PM.
0 comments