MODDINGWIKI Developers General Adding a load order page

This is using Hogwarts Legacy as a example.

Need to register a load order by using context.registerLoadOrder inside of main(). A few wrapped async () => await are needed so we can use async/await properly instead of Promises and other JS garbage.

context.registerLoadOrder({
    gameId: NEXUS_ID,
    validate: async () => Promise.resolve(undefined), // no validation needed
    deserializeLoadOrder: async () => await DeserializeLoadOrder(context),
    serializeLoadOrder: async (loadOrder, previousLoadOrder) => 
  			await SerializeLoadOrder(context, loadOrder, previousLoadOrder),
    toggleableEntries: false,
    usageInstructions: "Re-position entries by draging and dropping them " +
  			"- note that the mod further down the list will be loaded last and win any conflicts."
});

validate isn't needed here (which is why it’s just returning Promise.resolve(undefined)). No files need to be checked in order for this load ordering to work.

serializeLoadOrder is taking the current load order state, converting it to JSON, and writing to a file in the game folder inside of the Vortex AppData folder. \AppData\Roaming\Vortex\hogwartslegacy\<profile id>_loadOrder.json. After the file is written, setDeploymentNecessary is sent to the UI informing the user they need to Deploy. We can’t auto deploy as no way of knowing when the user has finished dragging and dropping etc.

deserializeLoadOrder is taking the current state of mods, removing any that aren’t enabled, trying to load the serialized data that serializeLoadOrder wrote to file, checking to see if any mods have been added since the data got serialized and returning the final mods that have passed all these checks. These are then displayed on the ‘Load Order’ screen that can then be dragged and dropped.

Reference

Property	Type	Description
gameId	string	Nexus game id
validate	function	Called to validate a load order entry. See below.
deserializeLoadOrder	function	Called to deserialize the load order from disk. See below.
serializeLoadOrder	function	Called to serialize the load order to disk. See below.
toggleableEntries	bool	Do we need toggles next to the load order entries? Normally false
usageInstructions	string	Displayed on right hand side of the Load Order screen

validate(previous, current)

previous LoadOrder The load order array state before the serialization/deserialization functionality has been executed.

current LoadOrder The load order array state we either want to serialize, or have deserialized and want to ensure its valid.

Returns: Promise<IValidationResult> which is an array of IInvalidResult. A validation result specifying any invalid entries - these will be displayed to the user in the load order page (accompanied by an error notification). Validation passes if the validate function call returns undefined, signifying that no invalid entries have been found.

Called to validate a load order object - it is the game extension's responsibility to ensure that the object is formatted correctly and that it does not breach any set rules (e.g. a locked entry had been moved to an invalid position).

deserializeLoadOrder()

Returns: Promise<LoadOrder> which is an array of ILoadOrderEntry. An object containing a deserialized array of load order entries.

Game extension should parse the Load Order file stored on disk using the same format used when serializing it in serializeLoadOrder and provide a populated load order array in the correct order.

Please note that the validate functor will be called to verify the deserialized load order object immediately after the deserialization functor completes its operation to ensure that any newly inserted element (through manual intervention or through the game's interface) is valid.

If for any reason the change is not valid or the deserialization operation had failed, the load order will be reverted and locked until the the error is handled by the user. An error notification will be raised notifying the user of any errors.

Deserialization will be called:

• As soon as the Load Order page is mounted/loaded.
• After the user exits a configured tool or the game to regenerate the load order in case the user had changed it while using said tool/game.
• If the user changes profiles.
• On deploy/purge to ensure the user hadn't modified the mod list manually or through an external tool.

serializeLoadOrder(loadOrder, previousLoadOrder)

loadOrder LoadOrder An array consisting of load order objects which we want stored on disk. Please note that the load order array sent to the game extension’s serialize functor will be sorted in the expected load order.

previousLoadOrder LoadOrder The load order array state before serialization.

Returns: void

The load order page will call this functor whenever it is necessary to write a change to disk. It is up to the game extension developer to decide where/how to store this information. Obviously - the data should be formatted in a way where it is easily deserializeable by the deserializeLoadOrder function.

This function will always be called AFTER the validate function had a chance to ensure that any changes made to the load order are not invalid. (It will not be called at all if change is not valid).

Expect the functor to be called whenever a load order change is applied (drag-drop, props update, etc.)