Modding Guide: Scripting in Beta 1.4

The way scripts work internally has changed in Beta 1.4, most mods from before then won't work afterwards and vice versa. This guide replaces the old modding guide at https://madodev.itch.io/lewdest-dungeon/devlog/635930/modding-guide-part-2-scrip...

How do I find what scripts exist?

In the Mod Editor, go to the Main tab. 

In there, select the Scripts tab.

This will show you all scripts that exist in the game, including a small description (the same thing that gets shown in the tooltips). There are a lot of scripts, but you mostly only need five.

What scripts exist?

Scriptablescripts (passive scripts)

The basic scripts are under Scriptablescript, these just do stuff and don't need any extra help. This goes from the basics, like adding Damage to changing the wearer's haircolor, to adding or removing moves, to hiding parts of their puppet, and so on. Whenever the game needs to check something like a stat or a haircolor or whatever, it loops over all items and checks every scriptablescript. For example:

set_haircolor,pink_hair
DMG,5
taunt

This will turn the characters hair pink, gives her 5% more damage and a constant taunt effect (as if having the taunt token).

Conditionalscripts (scripts after IF)

Then we move on to the more complex behavior. Starting with Conditionalscript. These are conditions under which the other scripts function. For example, if you write IF:LUST,60, all scripts below that will only work if the girl's lust is above 60. You can also combine this with ELSE:, which means the scripts will only function if the earlier IF wasn't true, and ELIF: which is a combination of ELSE and IF. You can end your IF statements with ENDIF if you want to do some other stuff afterwards, but it isn't needed. For example:

IF:LUST,60
    set_haircolor,pink_hair
ELIF:LUST,40
    set_haircolor,purple_hair
ELSE:
    set_haircolor,red_hair
ENDIF
DMG,10

This will turn the girl's hair pink if her lust is above 60. It will turn it purple if the lust is between 60 and 40, and will turn it red otherwise. It will always give her a 10% damage boost. You can view all haircolors in Colors btw.

Whenscripts (active scripts)

Unlike Scriptablescripts, these scripts are only triggered at certain actions. For example at the start of a turn, the end of combat, etc... At those times, these will cause a certain action to happen. For example:

add_tokens,block
die
add_morale,15

Understandably, these scripts have no use if they aren't preceded by the time when they have to trigger.

Temporalscripts (scripts after WHEN)

This type of script exists for actions that happen at specific moments in time. For example, receiving tokens at the start of your turn. To do this, you combine the temporalscript with whenscripts. You write WHEN:<temporalscript> and then follow up with whenscripts (since the actions that can be done in such moments are very specific. For example:

WHEN:combat_start
    IF:chance,5
        die
ENDWHEN
WHEN:dungeon_end
    crest,crest_of_purity,5

This script means the girl has a 5% chance to die at the start of combat, and at after completing a dungeon her Crest of Purity will grow by 5.

ENDWHEN isn't actually needed here, since the game knows that you can't be at combat_start and at dungeon_end at the same time, so assumes you meant to write it. Still, write it for consistency please.

Counterscripts (scripts after FOR)

Use this type of script if you want an effect to trigger for each copy you have of something. These scripts have to start with FOR:, and you can optionally end them with ENDFOR. For example:

FOR:token,block
    REC,50

This will mean the girl takes 50% more damage for every block token (or blockplus, or blockminus) that she has. Concretely it multiplies every number in every subsequent script by the multiplier. So:

WHEN:turn
    FOR:maid_efficiency,20
        token_chance,20,crit
        dots,bleed,3,3

At 100 maid efficiency will give a 100% chance of getting a crit token while receiving a 15 damage bleed for 15 turns.

Scopes:

You can precede any script with a scope, this will apply the given script to the characters in the scope. You can find all scopes in the Scopes tab.

For examples:

FRONT:DMG,5
IF:ANY_ALLY:has_token,block
    ALL_ENEMIES:saves,-10

This grants 5% DMG to the character in front of the girl, and if any ally of the girl has a block token, it reduces the saves of all enemies by 10.

There is an exception. You can also add a scope at the end of a temporalscript. This will apply what follows to everyone in the scope:

WHEN:turn:ALL_ALLIES
    tokens,block

This will apply block tokens to all allies at the start of the girl's turn. Compare with:

WHEN:OTHER_ALLIES:turn
    tokens,block

Which means that all allies will get a block token on their turn.

Modifier:

There is only one modifier, NOT, you can place it in front of a conditionalscript to invert its purpose. For example, IF:NOT:has_tokens,block means "If not has tokens block". Complex stuff, I know.

What scripts can be used where?

Let's first define complex_scripts as a mix of scriptablescripts, whenscripts, temporalscripts, conditionalscripts, and counterscripts. Let's also define complex_when_scripts as complex_scripts but with the passive scriptablescripts. When using conditionals, I mean a list of conditionalscripts, all of which need to be true. I'll go through all data in the order that they are listed in the editor.

Some scripts types aren't mentioned above, these are simple lists of scripts without any special syntax, scopes or modifiers won't work for them.

Wearables -> complex_scripts, conditionals for the requirements
Afflictions -> complex_scripts
Barks -> conditionals for the requirements (tag)
Buildingeffects -> buildingscripts
Classes -> complex_scripts
Corruption -> complex_when_scripts
Crests -> complex_scripts
Curiochoices -> complex_when_scripts, conditionals for the requirements
Curios -> curio_scripts
Effects -> complex_scripts
EffectsGuild -> complex_scripts
Enemies -> complex_scripts, aiscript for their AI
Enemymoves -> complex_scripts, conditionals for the requirements
Expressions -> conditionals
Goals -> goalscript
Jobs -> buildingscripts
Levelgoals -> goalscript, conditionals for the requirements
Morale -> complex_when_scripts
Parasites-> complex_scripts
Parties -> complex_scripts
Playermoves -> complex_scripts, conditionals for the requirements
Quirks -> complex_scripts
Quest -> quest_scripts, complex_when_scripts for the rewards
Sensitivities -> complex_scripts
Sets -> complex_scripts
Suggestions -> complex_scripts
Tokens -> complex_scripts, usage_scripts for their usag