Guide

Themes

A theme changes the colours of the whole game. A theme is one small JSON file inside a mod, so it is made, shared and switched on like any other mod. This page is for people who want to make one.

The quick way: in the game#

1. Main menu > Mods > Themes.
2. Pick a theme to start from. Picking one shows the whole game in it at once (it only stays if you press Use this theme).
3. Press New theme from this and give it a name. The game makes a mod folder for it in your mods folder (theme-<name>) and opens it for editing.
4. Change colours. Each colour has a swatch, what it paints, and its value. You can:
   • type a value (#rrggbb, #rrggbbaa or rgba(r, g, b, a)),
   • press the multi-colour button at the right of the field for the colour picker (drag in the square for saturation and brightness, the strip under it for the hue, the next one for opacity; the two-part swatch shows before and now, and a click on the before half puts it back),
   • or use the four sliders beside the picker (keyboard and controller). The game repaints as you change things. The At a glance panel at the top shows buttons, chips and meters.
5. Save changes writes the file. Use this theme makes it the game's theme (it also saves).

The theme in use is also in Settings > Display > Theme.

To share a theme, send the mod folder (or zip it). Open folder on the Themes page takes you to it.

The file#

my-theme/
  mod.json
  data/ui/themes/my-theme.json

mod.json is an ordinary mod manifest. Nothing in it is special for themes ("provides": ["themes"] is only a label):

{
  "id": "me.theme.sunset",
  "name": "Sunset theme",
  "version": "1.0.0",
  "gameVersion": ">=0.50.0",
  "authors": ["me"],
  "description": "Warm dark colours.",
  "provides": ["themes"],
  "tags": ["theme"]
}

The theme file:

{
  "id": "me.theme.sunset",
  "name": "Sunset",
  "description": "Warm dark colours.",
  "author": "me",
  "colours": {
    "bg-0": "#140c0a",
    "bg-1": "#1d120f",
    "accent": "#ff8a3d",
    "accent-ink": "#1a0d05"
  }
}

• id must be unique among themes. Letters, digits, dots, dashes and underscores.
• colours (or colors) sets a value per token. A token you leave out keeps the game's own colour, so a theme can be four lines or the whole list.
• A mod can hold several themes: several files in data/ui/themes/, or one file with a list [ {…}, {…} ]. The single file data/ui/themes.json is read too.
• A theme is offered only while its mod is switched on. If the theme in use disappears (mod removed or switched off), the game uses its own theme until it comes back.
• Mistakes in a file (an unknown token name, a colour that can't be read) are shown on the Themes page; the rest of the theme still loads.

The game's own theme, with every token written out, is core/data/ui/themes/default.json in the game's StreamingAssets folder. The example mods are in the example packs: example-theme-daylight, -paper (light themes), -nuke, -blackout, -deep-sea, -baize, -midnight.

The colours#

Tips#

• Light themes. Make the surfaces light and the text dark, and set overlay to a dark colour: the game draws many highlights as a see-through layer of the overlay colour, which must darken a light page instead of lightening it. Give shade some alpha below 1 (for example rgba(15, 23, 42, 0.22)), or shadows will look heavy on a light page. Give bg-glass a high alpha (0.9 or more) so the main menu's boxes read as clean panels.
• **accent-ink must read on accent**, and text on all four surfaces.
• If accent is red, pick a different danger (orange works), or warnings stop standing out.
• The steps between bg-0 … bg-3 should be small and even. Many in-between shades in the game are made from them.

What a theme does not change#

• The 3D stage, the players, the board on stage, darts and kit: they keep their own colours.
• Photographs and logos. (Washes over them do follow scrim.)
• Pure white and pure black written without transparency (white text on a coloured badge, a logo's plate).
• Trading cards, the kit and dart designers' drawings and controller glyphs.
• Fonts, sizes and layout. A theme is colours only.

How it works (for the curious, and for contributors)#

• Dtj.UI.ThemePalette holds the tokens and the theme in use. With the game's own theme nothing is touched, which is why the default look is identical to the game before themes existed.
• With another theme, every stylesheet the game attaches is swapped for a copy (ScaledSheets, the same mechanism the UI scale uses). In the copy the token variables take the theme's values, and every colour that was written out is mapped (ThemePalette.Map): a colour equal to a default token becomes the theme's colour for it (keeping its own alpha); white or black with alpha becomes the overlay or the shade; a colour that lies on the line between a surface and another token is taken to be a mix of the two (a color-mix) and is mixed again from the theme's colours.
• Colours drawn from code read Theme.Bg1, Theme.Accent … (the theme in use), or go through Theme.Map / Theme.Ui("#rrggbb"). Gradients (CssBackground) and shadows (BoxShadow) map their colours themselves.
• When you add UI: use the USS variables (var(--bg-1)), Theme.* in C#, and don't keep a theme colour in a static readonly field. A new written-out colour that is a token's value or a mix of tokens follows themes by itself; anything else stays as written.
• Theme files are found by Dtj.App.Services.ThemeLibrary (core pack, then each enabled mod). The setting is display.theme (written only when it isn't the game's own).
• Captures: --theme <id> on a capture state (the example theme mods are copied into the capture's mods folder). tools/editor/states/themes.txt has the states used to check themes.