Skip to content

Submitting an Option

Migush edited this page Nov 16, 2026 · 15 revisions

Options are small JSON patches on top of a layout. People pick them on the website, and Themezer merges them into the layout before it builds the theme.

Structure

targets
└── 📂 [menu *]
    ├── 📂 [layout name *]
    |   └── 📁 options
    |       ├── 📂 [PRIORITY_TYPE_Name]   // TOGGLE, INTEGER, DECIMAL, STRING or COLOR
    |       |   └── 📄 enable.json *
    |       └── 📂 [PRIORITY_SELECT_Name]
    |           ├── 📄 [Choice 1].json *
    |           └── 📄 [Choice 2].json *
    └── 📂 _GLOBAL
        └── 📁 options
            └── 📂 [PRIORITY_TYPE_Name]

An option belongs to one layout. Options in a menu's _GLOBAL folder are offered for every layout of that menu.

Colours don't belong in global options: theme-wide colours are set with colour palettes, not layout options. A layout can still offer a COLOR option for a colour of its own.

📂 PRIORITY_TYPE_Name

The folder name has three parts, separated by underscores.

PRIORITY

A number that sets the order options are applied in. When someone picks several options, the one with the lowest priority is applied first, so the one with the highest priority wins where two options patch the same property. A layout's own options and its menu's _GLOBAL options are sorted together. Negative numbers are allowed.

TYPE

One of:

Type Shows as Values
TOGGLE a switch exactly one JSON
SELECT a dropdown two or more JSONs, one per choice
INTEGER a whole-number field exactly one JSON
DECIMAL a decimal field exactly one JSON
STRING a text field exactly one JSON
COLOR a colour picker exactly one JSON

INTEGER and DECIMAL can take a range, and STRING a length range: INTEGER(0,100), DECIMAL(0.5,2), STRING(1,20). For example: 4_INTEGER(1,10)_Cursor Border Size.

Name

The option's name on the website. Use spaces, not underscores.

The value JSON

A value JSON is a trimmed-down layout. Only these root properties are read:

  • HideOnlineBtn
  • TargetFirmware
  • Files
  • Anims

The uuid is added automatically; don't add it yourself.

For a TOGGLE or a field type, the file name doesn't matter (enable.json by convention). For a SELECT, each file name is a choice in the dropdown: Small.json, Large.json.

How a value is merged

{
    "HideOnlineBtn": false,
    "Files": [
        {
            "FileName": "blyt/Cursor3.bflyt",
            "Patches": [
                {
                    "PaneName": "P_Main",
                    "Visible": false
                },
                {
                    "PaneName": "P_Grow",
                    "UsdPatches": [
                        {
                            "PropName": "S_RoundRadius",
                            "__self": null
                        },
                        {
                            "PropName": "C_W",
                            "PropValues": ["34", "0", "0", "0"],
                            "type": 1
                        }
                    ]
                }
            ]
        }
    ]
}

This value:

  • sets HideOnlineBtn to false;
  • finds the Files entry with FileName blyt/Cursor3.bflyt, or adds it;
    • finds the Patches entry with PaneName P_Main, or adds it, and sets Visible to false;
    • finds the Patches entry with PaneName P_Grow, or adds it;
      • removes the UsdPatches entry with PropName S_RoundRadius;
      • finds the UsdPatches entry with PropName C_W, or adds it, and sets its PropValues and type.

Array entries are matched by FileName, PaneName, PropName, GroupName, MaterialName, Name, name or unknown. "__self": null removes the entry it's in.

Options with user input

INTEGER, DECIMAL, STRING and COLOR options insert what the user enters. Put a token in the value JSON where the value goes; you can use it as often as you like.

INTEGER and DECIMAL

Tokens: ??{integer}?? and ??{decimal}??.

The token can be an expression: ??{integer} * 2??, ??max({decimal}, 0.5)??. See the expression syntax.

When the token fills a whole string ("??{integer}??"), it becomes a number. Inside PropValues, which the installer reads as strings, it stays a string. Anywhere else, the result is put into the surrounding text:

"width": "??{integer}??"
// user enters 10 -->
"width": 10
"width": "??max({decimal}, 20.0)??"
// user enters 10.0 -->
"width": 20
"PropValues": ["??{integer} * 2??"]
// user enters 5 -->
"PropValues": ["10"]

STRING

Token: ??{string}??. The text is inserted as is, escaped for JSON.

"Text": "??{string}??!"
// user enters Hello -->
"Text": "Hello!"

COLOR

The user picks a colour; it's inserted in the format the token asks for:

  • ??{color:RRGGBBAA}??: hex pairs in any order, from one to four of RR, GG, BB and AA. Write the pairs in the order the layout field expects, for example ??{color:AABBGGRR}?? or ??{color:BBGGRR}??.
  • ??{color:R}??, ??{color:G}??, ??{color:B}??, ??{color:A}??: one channel as a number from 0 to 1, for USD colours such as S_DropShadowColor.
"ColorTL": "??{color:AABBGGRR}??"
// user picks #F9C000FF -->
"ColorTL": "FF00C0F9"

Submission example

Look at the options already in the repository for more examples.

  1. Open your layout's folder, or the menu's _GLOBAL folder, and create an options folder in it.
  2. Create a folder for the option, for example 5_DECIMAL(0.5,2)_Game Icon Size.
  3. Add the value JSON:
    • for a TOGGLE or a field type, one file such as enable.json;
    • for a SELECT, one file per choice, such as Small.json and Large.json.
  4. For a field type, put its token in the JSON, for example ??{decimal}??.
  5. Open a pull request. The workflow checks your option; its preview is rendered on the website when someone picks it.

Clone this wiki locally