Overrides

English | 日本語

Experimental. This came in with framework 1.4.0 and may change or go away in a later version.

Overrides (DragNWash.ModFramework.Overrides, version 1.5.0) lets you make mods with no code. A mod like this is just a folder that lists values to change in the game, like a heavier dragon, a warmer light or a slower sponge. Nothing gets compiled and no code runs. The library reads the files and writes the values in once the objects are there. The easiest way to make one is to change values in the Inspector and press Export as overrides.

If you want to change something when something happens, and not just whenever the object shows up, use Graphs instead. It lives in the same folder (a graphs/ next to the overrides/) and changes the same three things (objects.member.set, objects.material.set, objects.active.set), only at a moment you pick.

The design and research behind it are in pull request #48.

For players

Installing a data mod

An overrides mod is a folder. Put it into the game's BepInEx/plugins folder so it looks like this:

BepInEx/plugins/Heavier Dragon/
  mod.json
  overrides/main.json

You need the framework with the Overrides library. You don't need developer tools, because the values apply for everyone. Start the game and the mod shows up on the Mods screen (Options → Mods) with its name, authors and description, just like any other mod. If it changes private values of the game's scripts, its description tells you. (For it to be listed, you need the core from the same release. With an older core the values still apply, but the mod won't be on the Mods screen.)

Switching it off

• To turn off one mod, switch it off on the Mods screen. Like with any mod, this takes effect the next time you start the game (its mod.json is renamed to mod.json.disabled, and the library stops reading it). Switch it on there again to bring it back.
• To turn off all overrides mods at once, go to Mods → Drag'n Wash ModFramework: Overrides → Settings → [General] Enabled (it's on by default).
• To remove a mod, delete its folder.

Once a mod is off, the game goes back to its own values.

For mod makers

The folder

BepInEx/plugins/<Mod>/
  mod.json              name, authors, description, version
  overrides/*.json      the values to change

The library looks at every folder in BepInEx/plugins that has both a mod.json and an overrides folder. It reads every *.json file in overrides/, in name order.

mod.json

{
  "name": "Heavier Dragon",
  "authors": ["Tom"],
  "description": "A heavier dragon.",
  "version": "1.0.0"
}

Field	Meaning
name	The name on the Mods screen; the folder's name when left out
authors	A list of names ("author" with one name works too)
description	Shown in the mod's details
version	1.0.0 when left out
website	Optional link
guid	Optional; overrides.<folder name> when left out

overrides/*.json

{
  "format": 1,
  "overrides": [
    { "scene": "Wash", "path": "Dragon/Body", "component": "Rigidbody", "member": "mass", "value": "2.5" },
    { "scene": "Wash", "path": "Lights/Key", "component": "Light", "member": "color", "value": "#FFD9A8FF" },
    { "scene": "Wash", "path": "Dragon/Body", "material": "DragonSkin", "property": "_Smoothness", "value": "0.8" }
  ]
}

(The scene and object names above are only examples.)

Each row says where to look, what to change and what value to use:

Field	Meaning
scene	The scene the object is in. Left out: any scene
path	The object's path from its root object, as the Inspector shows it (Root/Child/Child)
component	The component's type name (Light, Rigidbody, a game script)
index	Which one, when the object has several components of that type (0 is the first, the default)
member	A field or property of the component
private	true to change a private field or property
material	For a material property: the material's name (without (Instance))
property	For a material property: the shader property (_Smoothness, _Color)
value	The value, always as text

A row needs path and value, plus either component and member or material and property. For a material, component is optional. It names the renderer that shows the material, and if you leave it out, the object's renderer is used. On a material you can change colours, vectors, numbers and whole numbers, but not textures (replacing pictures is the Assets library's job).

If a file has a newer format than the library can read, or it's larger than 2 MB, it gets skipped and the log says why.

Values

Type	Written as
numbers	2.5 (a dot for decimals)
bool	true / false (also on/off, yes/no, 1/0)
string	the text
enums	the value's name
Vector2, Vector3, Vector4, Vector2Int, Vector3Int	numbers separated by commas: 1, 0.5, 2
Quaternion	x, y, z, w, or three Euler angles
Color	#RRGGBB or #RRGGBBAA, or 3 or 4 numbers from 0 to 1
Color32	#RRGGBB or #RRGGBBAA, or 3 or 4 numbers from 0 to 255
Rect	x, y, width, height
Bounds	the centre's x, y, z, then the size's x, y, z

Some things can't be done with an override: references to other objects (a texture, a mesh, another object), list elements, mesh vertices, and adding or removing components. An override only changes values. It never removes anything, calls no methods and loads no code.

Private fields

The game's scripts keep most of their settings (speeds, strengths, thresholds) in private fields. You can see them in the Inspector with Show private. To change one, add "private": true to the row. The Mods screen will then say that the mod changes private values of the game's scripts.

When values apply, and when they come back

• Values are written a frame after each scene loads, and again a second later to catch anything the scene's scripts make in their first frames.
• Twice a second the library also looks for new root objects and applies the rows whose path starts with that root. Each level's dragon is made when the level starts, long after the scene loads, so a row for DragonRyanA (Clone)/... applies whenever that dragon turns up.
• Each object gets the value once. A new copy of the object gets it again.
• Before the first write, the library keeps a note of the game's value. overrides reload puts every value back before reading the files again, and a mod you switched off isn't applied from the next start.
• A row whose object isn't there isn't an error. The log lists the rows that found nothing in a scene. If a game update renames an object, you lose that one row, never the game. A row that can't be written (no such member, or a value of the wrong type) shows up as a warning in the log.
• The game's own scripts may set a value again (a dragon's sound volume, for example, or bones that an Animator moves every frame). Overrides doesn't fight them, so those values aren't worth overriding.

Two mods, one value

When two mods change the same thing, the one that loads later wins. Mods load in the order of their folder names. The log names both mods, so nobody's left wondering why their edit did nothing.

The console

If you have the Tool window installed, the Console has these commands:

Command	Does
overrides	each overrides mod, how many of its values are written so far, and the problems in its files
overrides reload	puts the game's values back, reads the files again and applies them: for editing a file while the game runs

From C# you have GameOverrides.Mods (the same report), GameOverrides.Reload() and GameOverrides.Guid for [BepInDependency].

Export from the Inspector

When the Overrides library is installed, the Inspector's History view has an Export as overrides button:

1. Change values in the Inspector (with Developer tools on, F1).
2. Open History and press Export as overrides.
3. Fill in Name (the folder's name, "My changes" when empty), Author and Description, and press Export.
4. Type overrides reload in the Console, or restart the game, to run it as a mod.

The export writes BepInEx/plugins/<Name>/mod.json and overrides/main.json, with one row for each place you changed and the value it has right now. Edits that you've set back to the game's value are left out. If you export into the same mod again, it adds a new file (inspector-<date>-<time>.json) and keeps the mod.json. Edits an override can't hold are also left out, and the log lists them with the reason. Those are list elements, mesh vertices, Animator parameters and clip swaps, GameObject rows, and a material's shader or render queue.

To share the mod, just send its folder.

Content policy

An override file holds values people changed by hand, plus the names needed to find the object (paths, component and member names). That fits the content policy, which says anything made or changed by hand is fine and game data copied unchanged is not. Export only writes what the History recorded as changed. It never dumps all of an object's values.