Downpour Reference/Modification Files

Modification files are a method to specify rules to partially modify the contents an existing (non-binary) file, rather than replacing that file's contents completely. For compatibility between mods, these are preferable, as multiple mods can apply modifications to the same file without overwriting each other's changes. Think of this like the file system equivalent of a hook mod versus a patch mod.

Modification Directory Structure

Targeting a file for modification works similarly to targeting a file for overwriting. The difference is that these modification files are placed within an additional subdirectory within your mod folder called modify. For example, for the file:

Assets/StreamingAssets/world/gates/locks.txt

Placing a file at:

your-mod-folder/world/gates/locks.txt

Would cause the entire contents of locks.txt to be overwritten by the entire contents of the locks.txt file in your mod's folder. However, placing a modification file at:

your-mod-folder/modify/world/gates/locks.txt

Would apply the modification syntax within that locks.txt file to partially modify the contents of the original locks.txt file.

Modification File Syntax

Each line of a modification file includes an operation followed by the text that the operation uses for applying its effect.

Available operations

Keyword	Action
[ADD]	Appends the specified text to the end of the file.
[ADD_XX]	Inserts the specified text after the XXth line in the file.
[FIND]	Set a specific string as a target for a subsequent replace operation.
[FINDREGEX]	Set a specific regex pattern as the target for a subsequent replace operation.
[FINDLINE]	Target an entire line in the file which contains the given substring, for a subsequent replace operation.
[FINDLINEREGEX]	Target an entire line in the file which contains the given regular expression match, for a subsequent replace operation.
[FINDLINESTART]	Target an entire line in the file which starts with the given substring, for a subsequent replace operation.
[FINDLINEEND]	Target an entire line in the file which ends with the given substring, for a subsequent replace operation.
[TARGETLINE]	Target the entire line in the file at the given line number, for a subsequent replace operation.
[REPLACE]	Replace all instances of the target from the preceding find operation with the given text.
[REPLACE_XX]	Replace the XXth instance of the target from the preceding find operation with the given text. Note: If used with a FIND operation that targets a substring/pattern, this affects the XXth instance of that pattern in the file. If used with a FIND operation that targets a line, this affects the XXth instance of a line that contains the pattern (not necessarily the line which contains the XXth instance of the pattern). This and the other "_XX" operations cannot be used together with [TARGETLINE].
[ADDBEFORE]	Add the given string before all instances of the targeted text from the preceding find operation.
[ADDBEFORE_XX]	Add the given string before the XXth occurrence of the targeted text from the preceding find operation. (Same targeting/affecting behavior as REPLACE_XX)
[ADDAFTER]	Add the given string after all instances of the targeted text from the preceding find operation.
[ADDAFTER_XX]	Add the given string after the XXth occurrence of the targeted text from the preceding find operation. (Same targeting/affecting behavior as REPLACE_XX)

If a new-line character needs to be matched or added, use the \n escape character to represent the new line. Also note that you can effectively do a delete operation as well by using [FIND]/[REPLACE] operations to replace the target with an empty string.

Below is an example modification file:

[ADD]Hello World
[ADD_5]Slugcat\nRain World
[FIND]Spider
[REPLACE]Centipede
[FINDREGEX](Green,Blue,Pink)
[REPLACE_1]Red

The above example modification file performs the following actions:

1. Appends a new line to the end of the file containing the text "Hello World".
2. Inserts two new lines after line 5 in the file, the first containing the text "Slugcat" and the second containing the text "Rain World".
3. Finds all instances of the text "Spider" in the file and replaces all those instances with the text "Centipede".
4. Finds any instances of the text "Green", "Blue", or "Pink" in the file, and replaces only the first instance it finds with the text "Red".

Merge Operation

Modification files have one more operation that is used by placing any number of lines of text between a [MERGE] and an [ENDMERGE] tag. The contents within will be "merged" with the contents of the original file in a way that is context dependent on the file you are applying the merge to. This section describes how this merging works for different vanilla source files:

Files	Merge behaviour
mpmusic.txt, regions.txt, egates.txt	Applying merging to one of the files above will take any lines within the merge context and append them to the file, only if that line does not already exist in the file.
default aligments.txt, sounds.txt, locks.txt, properties.txt, map_XX.txt	Applies merging similarly to above, but takes key-value context into account. If a key doesn't exist in the file, the key-value pair will be appended to the file. If a key does exist in the file, then its value will be replaced by the new value in the merge context.
Room Settings files	Applies merging similarly to above, but certain keys have special handling. Effects, PlacedObjects, AmbientSounds, and Triggers will be merged additively, so the resulting room settings file will have all of the objects from the original room settings file, plus all of the new objects specified within the merge context.
world_XX files	Applies merging of world file contents in a CRS-style fashion.
short_strings file	Applying merging to a short_strings file will unencrypt the short_strings file, append any key-value pairs within the merge context if the key doesn't already exist (otherwise update the value to the new value), and then finally encrypt the short_strings file again.
anything else	Any other files not described above, will have their entire contents simply replaced with the contents of the merge context.