Write a description

What a mod's description, overtone.mod.toml, is, and every key it takes: switches, looks, conditions, parts, textures, materials and their shaders, layers, pieces, hidden parts, meshes and sliders.

What a description is

Every mod Overtone draws has one file beside it, overtone.mod.toml, its description. It says what the mod is, which switches it has, and what each one shows and wears. Overtone reads it; it never runs scripts.

Timbre writes it for you. It does so when it imports a WWMI mod, from the mod's ini files, and when you dump a character. After that it is yours: an update of the mod is merged into it, and what you changed stays.
You edit it. The mod's Inside tab reads it out; a click on a row opens the file beside it, which marks a problem on its line as you type. Save refuses a file that does not read, saying not saved: and why. Any text editor works too.
Names, not numbers. You name switches, choices and pieces. The only numbers are the game's part numbers and the mod's shape keys.
The game picks it up. It shows a change a moment after you save it (See your changes in game).
An update keeps your changes. Where the author's new version changes a line you changed too, the Inside lists it under Changed by you and the update, with Apply to take the author's.
.overtone/ beside it holds what Overtone works out from it. Never edit those files.

It is TOML. These three spellings mean the same, so write whichever reads best:

[option.Hair.Long]
show = ["Hair 1"]

[option.Hair]
Long.show = ["Hair 1"]

[option.Hair]
Long = { show = ["Hair 1"] }

A key Overtone does not know is not an error, but Timbre points it out, and the game's log names its line.

The top of the file

format = 27
id     = "18d3a98a9189469c0053"
name   = "Summer Dress"
object = "carlotta"

Key	What it is
`format`	Always `26`. A `24` or `25` is written again as `26` when Timbre opens the library, or by `overtone-mod migrate`; left out, or any other number, the file is refused.
`id`	Made once by Timbre. It is how the list of what you draw, and your loadouts, find the mod, so it survives a renamed folder. A folder copied whole keeps the same id, and then only one of the two draws: give the copy an `id` of your own, any text no other mod uses.
`name`	The mod's name in Timbre and in game. Left out, its folder and the one it is in, such as `carlotta/Summer Dress`.
`object`	The character or weapon it dresses, as the game's list names it (`carlotta`, `rover`, `abysssurges`). Timbre writes it; change it if it is wrong.
`game`	The game it is for, such as `wuwa`; left out, the game this Overtone runs in.
`author`, `link`, `about`, `version`	Who made it, where it came from, what it is, and its version, such as `1.0.0`.
`folders`	The mod's own folders, where it has more than one.

Switches: `[option.<name>]`

A switch is on or off, or steps through choices.

[option.Hat]
key     = "5"
default = "off"
on.show = ["Straw hat"]

[option.Hair]
choices    = ["Short", "Long"]
default    = "Long"
key        = "/"
Short.show = ["Hair 0"]
Long.show  = ["Hair 1"]

A switch with no choices is on or off: its choices are on and off, and it starts on unless default = "off".

Key	What it does
`choices`	The choices, in the order a key press steps through them: names, or numbers, not both in one list. A name that reads as a number is that number.
`default`	The choice it starts at, where that is not the first. Your own choice is kept apart, in `.overtone/state.toml`.
`key`	The key that steps it, as printed on the keyboard, with any modifiers: `5`, `Ctrl+Up`, `Alt+5`. A press goes to the key naming the most of what is held, so `5` and `Alt+5` never fire each other within this mod; another mod on the same key still fires.
`back`	The key that steps it back.
`more_keys`, `more_back`	Other keys that step it forward or back, as a list.
`when`	A condition: while false, a key press does nothing.
`name`	What the switch is called in Timbre and in game, where that is not its key.
`group`	A heading to list it under, beside others of that heading.
`labels`	Names for numbered choices: `{ 0 = "Short hair" }`.
`wrap`	`false`: stepping stops at the last choice instead of going back to the first.

Timbre writes a few more when it imports a WWMI mod; you rarely write them yourself:

Key	What it does
`kind`	How it moves: `cycle` or `toggle` (a key that flips between two values) by its key, `menu` by the mod's own menu, `detected` by what the game draws. Left out, `cycle` for a switch with a key, else `menu`.
`smart`	`false`: a press does not first look for the choice the mod's values already stand at.
`drawn`	The meshes its key works for, while one of them is drawn.
`also`	Other values the same press moves: a list of `{ variable, values, default }`.
`follows`	Folders of other mods whose switch this one is.
`does`	What it changes that the file does not say: `geometry`, `textures`, `drives`, `hides`.

What a choice does

Under each choice, or under on and off:

Key	What it does
`show`	The pieces drawn while it is chosen. A bare name is every piece of that name; `3/Name` is the one in part 3.
`wear.<part or piece>`	What a part or a piece wears while it is chosen. A material's name fills each role the part does not state itself (Which texture wins). A table of roles, `{ diffuse = "Textures/Blue.dds" }`, beats the part's own for those roles; `over` names a material to start from.
`shapekeys`	The weight of each shape key it drives: `{ 110 = 0.5 }`. A key one choice names weighs 0 at the choices that leave it out.
`scale`	The whole mesh's scale while it is chosen; 1 where a choice leaves it out.
`outline`	The outline's scale for the pieces it shows. Not drawn yet.

To rename a switch, right-click its row in Timbre's Inside for Rename a switch, so your choice follows it. A choice renamed by hand is refused on Save; reordering choices changes only the order a key steps through them. A choice cannot be called choices, default, when or a key of the tables above: its table would read as that key.

Looks: `[look.<name>]`

A look puts on several choices at once, from its key, the overlay or Timbre.

[look."Night out"]
key    = "F5"
Hair   = "Long"
Hat    = false

[look.Swim]
key   = "-"
back  = "Alt+-"
steps = [{ Top = "Bikini", Shoes = false }, { Top = "Shirt" }]

A look sets only what it names.

Key	What it does
a switch's name	The choice it puts on: a choice's name, a number, or `true` and `false` for an on-off switch.
`steps`	Choices put on one step a press, in turn. A step may hold its own `when`; a list inside a step puts on the first of it whose `when` holds.
`key`, `back`, `more_keys`, `more_back`, `when`, `wrap`, `smart`, `drawn`	As a switch's.

Conditions

A condition is a string, written in a when and in a piece's cut. Single quotes need no escapes.

Written	Means
`Hair is Long`, `Hair is not Long`	That switch is, or is not, at that choice
`Hair in [Short, Long]`, `Hair not in [Short, Long]`	It is, or is not, at one of those
`Hat`, `not Hat`	An on-off switch is on, or off
`a and b`, `a or b`, `not (…)`	`and` binds tighter than `or`; brackets group
`Size < 3` (also `<=`, `>`, `>=`)	A numbered choice compared
`Figure is Ice`, `Figure in [Ice, Liberation]`	The character is in that form, as the game's list names her forms. A switch is never called `Figure`.
`never`	Never true

Quote a choice whose name has a space: Outfit is "Night out".

Give a condition you use often a name under [when], and use the name anywhere a condition goes but inside another [when]:

[when]
bare_legs = 'not Socks and Skirt is Short'

Parts and textures: `[part.<n>]`

A part is one section the game draws, a [part.<n>] table by its number (Part 3 in Blender). Write one only where you say something about it.

[part.3]
diffuse   = "Textures/Body_D.dds"
normalmap = "game"

[part.skirt]
replaces = 4
diffuse  = "Textures/Skirt.dds"

A part states what it wears by default. What it wears at a switch's choice goes under that choice (wear), or in a rule (below); a role written as a list of conditions is refused.

Key	What it does
a role	What the part wears in that role (below).
`replaces`	The part's number, where you give it a name of your own as its key.
`material`	A material its pieces wear where theirs says nothing. Its own roles win over the material's.
`draws = "game"`	The game draws this part itself, as without the mod.
`mesh`	Which mesh it belongs to, where the mod has several.
`outline`	The outline's scale: 1 the game's, 0 none. Not drawn yet.
`sheets_move_with`	The switches its textures change under. Overtone works this out, so you rarely write it.

The roles Overtone places: diffuse (colours), lightmap, normalmap (bumps), materialmap and highlight (hair highlight). fx is a mask a piece's cut uses. glow, cutoutmap and specialmap are kept but never drawn.

A role's value	Means
`"Textures/Body_D.dds"`	A file, from the mesh's folder; a leading `/` starts at the mod's own folder. DDS is drawn in its own format; PNG and JPEG uncompressed, without mipmaps.
`"game"`	The game's own texture.
`"#rrggbb"` or `"#rrggbbaa"`	One flat colour that replaces the texture; it never tints.
`"neutral"`	The game's typical value; for now the same as `"game"`.

Materials: `[material.<name>]`

A material is a named set of roles that parts, pieces and choices can wear.

[material.leather]
diffuse   = "Textures/Leather_D.dds"
normalmap = "Textures/Leather_N.dds"

[material.leather_red]
over    = "leather"
diffuse = "#8a1010"

[piece.Buttons]
material = "leather_red"

Key	What it does
a role	What the material places in that role, as a part's; its files start at the mod's own folder.
`over`	The material it takes the roles it does not state from: another, `game`, `neutral`, or `own` for the roles of what wears it.
`hlsl`	The shader your mod ships for it: `{ vertex = "Shaders/Body.hlsl", pixel = "Shaders/Body.hlsl" }`. A stage you leave out draws as the part does.
`inputs`, `params`	What that shader reads beside your textures, keyed as your ini binds it (`ps-cb4`, `ps-t11`): a file of your mod, `false` for nothing, or `{ game = "ps-cb4" }` for what the game bound there; and the `x`, `y`, `z` and `w` values your ini sets for it, `params = { x200 = "Shoes", x255 = { time = 1 } }`, each a number, a switch or the clock.
`blend`, `depth_write`, `depth`, `write`	`"alpha"`, `"add"` or `"multiply"`: how it lands on what is drawn under it; `depth_write = false` draws it without hiding what is behind; `depth = "equal"` draws it only where the part is drawn already, as an ini's `depth_func`; `write = "rgb"` writes only the colour, as an ini's `mask`.
`two_sided`	`true` to draw both sides, as an ini's `cull = none`.
`game_shader`	A part of the game whose own shader draws it: `{ object = "galbrena", part = 15702 }`. Yours goes before `hlsl`, and stays when the mod is read again.

game, neutral and own are built in: a [material.game] or a name holding a / is read past, and Timbre says so.

Overtone writes every key but game_shader from your ini, and over = "own" where your ini gives the material no textures.

Layers: `[layer.<name>]`

A layer draws a material again over a part or a piece, after it, such as wet skin or oil. Overtone writes one where your ini draws again in a shader of yours over what another of its draws draws:

[layer.Oil]
on       = "Body"
material = "Oil"
when     = 'Oil is on'

Key	What it does
`on`	The part or the piece it is drawn over.
`material`	The material it wears, which says how it blends.
`when`	Where it is drawn, within where `on` is; left out, wherever `on` is. Overtone writes none yet.

Rules: `[[rule]]`

What to wear while a condition holds that no single choice spells:

[[rule]]
when   = 'Colour is Red and Hat'
wear.3 = { diffuse = "Textures/Brim_Red.dds" }

Key	What it does
`when`	The condition; a rule has one.
`wear.<part or piece>`	What it wears while that holds, as a choice's `wear`.

Write a rule only where no single choice says it: Timbre marks one a choice's wear would say. Two rules, or a rule and a choice, that set one role under the same condition, or under conditions that each hold where the other does not and both hold somewhere, are refused. Conditions that never hold together, or one inside the other, are fine: the narrower wins.

Which texture wins

A piece with its own material wears that material instead of its part's roles. Otherwise a role is taken from the first of these that states it:

A choice's wear table or a rule naming the piece, the narrowest condition first.
A choice's wear table or a rule naming the part, the narrowest condition first.
The part's own roles.
A material a choice wears.
The part's material.
The game's texture.

So a texture you change under [part.3] shows only where no piece's material, and no wear table or rule, covers it: if your change does not show, look for one.

Pieces: `[piece.<name>]`

A piece is one object of the mod's model, by its name in Blender. A piece is drawn while every switch that shows it is at a choice that shows it, and every [piece] when covering it holds. A piece nothing mentions is always drawn.

[piece."*"]
when = 'Outfit is not Swim'

[piece."skirt/Frills"]
cut = 'Sheer'

Key	What it does
`when`	Drawn only while this holds too.
`material`	The material it wears, in whichever part it is drawn.
`cut`	Cut by its part's `fx` mask: `true` always, a condition while it holds, `false` never.
`label`	What it is called in Timbre and in game; the piece keeps its name.
`outline`	The outline's scale for it. Not drawn yet.

[piece."*"] covers every piece and [piece."3/*"] every piece of part 3. For cut and material, a piece named outright wins over 3/*, which wins over *; every when among them must hold. A piece a switch shows takes its condition from that switch: Timbre marks a when on it.

Hide the game's parts: `[remove.<key>]` and `[adjust.<key>]`

[remove.6]

[remove.hair_accessory]
mesh     = "hair_accessory"
replaces = [0]
when     = 'not (Hair is Short and Hat)'

[remove.6] hides the game's part 6 of the mod's own mesh. With a name as the key:

Key	What it does
`mesh`	The mesh it is of, where that is not its key.
`replaces`	The parts it hides.
`when`	Hidden only while this holds, where the mod draws nothing of that mesh; otherwise the part is always hidden.
`folder`	The mod folder it came from; turning that folder off brings the part back.

An [adjust.<key>] takes the same keys and keeps the game's parts drawn as the game draws them, with an outline and a material of its own. It is read and kept, but not drawn yet.

Meshes: `[mesh.<key>]`

A mesh's own settings, by its key; a mod's own folder is main.

Key	What it does
`model`	The `.glb` it is built from. Saving it in Blender rebuilds the mod.
`scale`	Scales the whole mesh.
`when`	The mesh is drawn only while this holds.
`folder`	The mod folder it came from.
`sheets_move_with`	As a part's.
`defaults`	Written by older imports; it changes nothing, but each value must be one of its switch's choices.

Sliders: `[slider.<name>]`

A value that moves smoothly rather than in steps, such as a body shape.

[slider.bbs]
range   = [-0.2, 1.0]
default = 0.0
key     = "Up"
back    = "Down"
rate    = 0.6
drives  = [{ shapekey = 110 }]

Key	What it does
`drives`	What it moves: `{ shapekey = 110 }`, or `{ mesh_scale = true }`. A slider that drives nothing is ignored.
`range`	The lowest and highest value; left out, 0 to 1 (0.1 to 5 for the mesh's scale).
`default`	Where it starts; left out, 0.
`key`, `back`	Held, raise and lower it; with `stops`, step forward and back.
`rate`	How much a held key moves it each second.
`stops`	Values a press steps through, instead of moving while held.

Not built yet

[adjust.<key>], every outline, a material's shader keys and layers are read and kept, but not drawn yet. Figure is read, but Overtone does not yet tell which form a character is in, so what you hold to a form draws as the game's.

How to create a mod: a description's switches and textures, step by step.
Edit a mod in Blender: the pieces a description names.
When a mod does not draw right: a change that does not show.

#What a description is

#The top of the file

#Switches: [option.<name>]

#What a choice does

#Looks: [look.<name>]

#Conditions

#Parts and textures: [part.<n>]

#Materials: [material.<name>]

#Layers: [layer.<name>]

#Rules: [[rule]]

#Which texture wins

#Pieces: [piece.<name>]

#Hide the game's parts: [remove.<key>] and [adjust.<key>]

#Meshes: [mesh.<key>]

#Sliders: [slider.<name>]

#Not built yet

#Next