[Tutorial] Batch mode installation

[DavidW]

One of the annoying things about installing mods by WEIDU is that the installer asks you about each component, installs that component, and then asks you about the next one. If some components take a while to install, this can mean a lot of sitting around waiting until you can make the next component selection  - SCS is particularly bad here since some components can take 10-20 minutes to install.

For the last couple of years, SCS has been using an experimental 'batch mode' installer, that instead asks you about every component first, and only then installs them all. The overall install time is the same but the player gets to make the install choices up-front.

Recently @CamDawgand @argent77 started looking at batch mode, and their ideas have enormously improved and streamlined it. Using their ideas, I've now (I think) got batch mode simple enough to make it available for others to use. This thread aims to explain how.

 

[DavidW]

Requirements for batch mode

Batch mode should work for most mods (provided you're on the latest version of WEIDU), but it imposes certain limitations on how your TP2 is structured. (These are basically the same requirements for making your mod compatible with Project Infinity.)

(1) When checking whether a component can be installed, you can only check which other mod components are installed (and static things like what game this is). You can't check to see if a previous component has installed a file and then choose whether to install on that basis. For instance, this is fine:

BEGIN "my component" DESIGNATED 100
REQUIRE_PREDICATE GAME_IS BGEE "This mod is only for BGEE"
FORBID_COMPONENT ~stratagems/setup-stratagems.tp2~ 5900 "This mod must be installed before Sword Coast Stratagems"

But this isn't:

BEGIN "my component" DESIGNATED 100
REQUIRE_PREDICATE FILE_EXISTS "weidu_external/markers/dw#main_component.mrk" "This mod requires the main component to have been installed".

The reason is hopefully clear: in batch mode, checked-for files that other components create won't actually have been created yet. (You can check for files installed by other components in the body of the component; you just can't do it in REQUIRE_PREDICATE.)

You will also have to slightly edit any checks for other components of the same mod; I'll cover this under 'installation'.

(2) Your mod can't use ACTION_READLN to get real-time info from the user. Or, to be more precise: it can, but the user will be prompted for info in the middle of installation rather than at the beginning, which is what we're trying to avoid. (There are ways around this but they make setting up batch mode a lot more complicated, and since generally ACTION_READLN is a bad idea anyway, I won't talk about them.)

EDIT: actually, the version here has a limitation with detecting already-installed components of the same mod. For now, this approach doesn't handle that correctly; watch this space.

[DavidW]

Installing batch mode

(1) Put the attached file, batch_mode.tpc, into your mod, say at %MOD_FOLDER%/lib/batch_mode.tpc.

(2) INCLUDE this file as the first line of the ALWAYS block (it must be the first line, so that batch mode can take over and bypass any other code before it has a chance to run).

ALWAYS	
	INCLUDE "%MOD_FOLDER%/lib/batch_mode.tpc"
	[the rest of the always block]
END

(3) Add a new component, designated 0, right at the beginning of your list of components. It should have no content at all (the ALWAYS include does all the work).

BEGIN "Batch install (ask about all components at once before installing any)" DESIGNATED 0

(4) If your mod does not have components that check whether other components are installed, you're done. If it does, then in batch mode a check for component x becomes a check for whether the variable '%MOD_FOLDER%_component_%x%_installed' (always lower-case) has been set. (It should suffice to use IS_AN_INT or VARIABLE_IS_SET). That means your checks need to become disjunctive. For instance,

REQUIRE_COMPONENT "stratagems/setup-stratagems.tp2" 5900 @1000

becomes

REQUIRE_PREDICATE (MOD_IS_INSTALLED "stratagems/setup-stratagems.tp2" 5900) || IS_AN_INT stratagems_component_5900_installed) @1000

and

FORBID_COMPONENT "stratagems/setup-stratagems.tp2" 5900 @1000

becomes

REQUIRE_PREDICATE ! ( (MOD_IS_INSTALLED "stratagems/setup-stratagems.tp2" 5900) || IS_AN_INT stratagems_component_5900_installed ) @1000

Note that you should only do this for checks within your mod for its own components. Don't do it for other mods' components.

And that's it! When you run the mod, if you install the first component then all the other components install in batch mode. The installer also spits out a bat file (or linux equivalent) to weidu_external/batch/%MOD_FOLDER% that you can use to reinstall the same component choices.

 

batch_mode.tpc

[DavidW]

Changing the DESIGNATED number of the batch-install component

If for some reason it's not convenient to have the batch-install component designated as component 0 (e.g., because you are already using that number) you can use a different one, but you need to declare which one it is by setting the variable SFO_batch_mode_component_number before INCLUDEing batch_mode.tpc. 

ALWAYS
	OUTER_SET SFO_batch_mode_component_number=100
	INCLUDE "%MOD_FOLDER%/lib/batch_mode.tpc"
	[the rest of your ALWAYS block]
END

[language declarations]

BEGIN "Batch mode installer (ask about all components before installing any)" DESIGNATED 100

The DESIGNATED value doesn't have to be numerically before other components, but it's still vital that the batch-install component is actually before all the others in your TP2.

[DavidW]

I should of course add that all this is experimental and probably has kinks that need to be worked out, but my test install seems to be working pretty smoothly

[jmerry]

*looks at my collection of ~50 tweaks, and the update I've been halfheartedly working on*

Yeah, this is probably something I should include. Downloaded, and I'll see how it works with my stuff.

[CamDawg]

I've got about 95% of this implemented in Tweaks if you want to check the current repo for working code. David just dropped the WeiDU prompt trick on me today so that's not in yet, otherwise I think it's all there.

One other thing: Tweaks does prompt (and save) ACTION_READLN info during batch mode; you can see it in action in components 3176 (Accelerate/Decelerate Romances), 3183 (Romance Cheats), and 3210 (Minimum Stats Cheat).

[guyudennis]

Wouldn't an ini file moot the problem of ACTION_READLN?

I somehow always thought of ini files as a hard perquisite for batch-mode...

for what's its worth, my own private mod is structured in such a way that in the tp2 only the top-level installation choices are present (ie. "Druid Revisions"), then all the class features are individually turned on/off or chosen (when more than one choices are presented) through a settings.ini file. In this sense the ini file becomes mandatory rather than optional or "only for advanced users".

[CamDawg]

Yes. Tweaks has it both ways--it has cdtweaks.txt for pre-filling these questions to enable unattended installs and, in its absence, you'll get the normal prompts. Batch mode will still use cdtweaks.txt instead of prompts, if it's available.

Without ACTION_READLN I'd need to e.g. break up the unitary Minimum Stats Cheat into 60 components, which is why it's still being used.

[DavidW]

The latest version (beta 2) of Talents of Faerun uses this method and library. (Tweaks Anthology implements the same idea but the exact code is a bit different - partly because TA has to handle ACTION_READLN).

[Morgoth]

I have a request for this - would it be possible to add an exported file containing what you've chosen with batch mode that the user could copy, so when you reinstall the mod, you simply click the mod .exe, choose the starting option about the language, then an option "is a batch here" appear, so it basically would become simply "read from the batch, install what's in the batch".

Edited December 19, 2023 by Morgoth

[DavidW]

Already done! Look in weidu_external/batch/[mod name].