Skip to content

Submitting an Option

Migush edited this page Jun 19, 2022 · 15 revisions

Layout options are small JSON files with patches for the original layout. This way you can customize a layout even more. Submitting an option is a bit more advanced, though they're really awesome! Options also work with the JSON format.

Below you can see a relevant part of the structure I showed you before:

Structure

..
└── 📁 options
    ├── 📂 [option name]
    |   ├── 📄 option.json * // type: TOGGLE, INTEGER, DECIMAL, STRING, COLOR
    |   └── 📂 values *
    |       ├── 📄 enable.json *
    |       └── 🖼️ enable.png *
    |       // this is a checkbox, integer field, decimal field, textbox, or color picker respectively
    |
    └── 📂 [option name]
        ├── 📄 option.json * // type: SELECT
        └── 📂 values *
            ├── 📄 [Choice1].json *
            ├── 🖼️ [Choice1].png *
            ├── 📄 [Choice2].json *
            └── 🖼️ [Choice2].png *
            // this is a dropdown

Note the difference between 'option' and 'value'. An option is a customization option (e.g., 'Icon Position'). A value is the possible value the user can pick from (e.g., 'center', 'bottom') or input themselves (e.g. '12', '00FF0AFF'). An option can have multiple values.

Options are normally part of a single layout, however, they can also be made available for all layouts of a menu on the website using the target filename/global folder as shown below.

.
└── 📂 [target filename *]
    ├── 📂 [layout name *]
    |   └── 📁 options
    └── 📂 global
        └── 📁 options

📂 option name

The name of this folder determines the name of the option. It is displayed on the website.

📄 option.json

This file contains some basic information about the option. It is required.

// option.json
{
	"description": "",
	"type": "",
	"typeOptions": {
		"min": 0,
		"max": 100
	},
	"priority": 1
}

description (optional)

Not required, but you could list a few possible values here or something. Don't make it too long. Leave empty if you don't need this

type

Required. Either TOGGLE, SELECT, INTEGER, DECIMAL, STRING, or COLOR. See options without user input and options with user input for more details.

typeOptions

Not required. The min and max fields are only supported for INTEGER values, DECIMAL values, or STRING length.

priority

Not required. The priority determines the order in which options are applied. For example, if the user applies one option with priority 1 and one with 4. The option with priority 1 will be applied to the layout JSON first. Negative values are allowed as well. You may need this in case options modify values that are very close to each other. Normal options may use priority range -∞ up to and including 99. All values of 100 and above are reserved for global options, such that they are always applied after layout-specific options.

📂 values

This is where it gets a bit more advanced. This folder can hold different values. A value JSON is a trimmed down layout

📄 value.json

JSON with support for only three root properties: HideOnlineBtn, Files, and Anims.

An example of a value.json is shown below

// exampleValue.json
{
	"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
						}
					]
				}
			]
		}
	],
	"Anims": []
}

What the value above will do is:

  • add or overwrite the HideOnlineBtn property with false
  • try to find or add an entry in Files with FileName blyt/Cursor3.bflyt
    • then try to find or add an entry in Patches with PaneName P_Main and set the Visible property to false
    • then try to find or add an entry in Patches with PaneName P_Grow
      • then try to find or add an entry in UsdPatches with PropName S_RoundRadius and remove it from the UsdPatches array
      • then try to find or add an entry in UsdPatches with PropName C_W and set the PropValues to ["34", "0", "0", "0"] and set type to 1
  • ignore the Anims property

In addition to being able to find elements by FileName, PaneName, and PropName, it will also try to find array entries by the keys GroupName, name, MaterialName, and unknown.

"__self": null is a special property. By adding it to an element, it will remove the element itself from the parent array.

Layout options support a few different types:

  • Options without user input (finalized by you)
  • Options that use user input (finalized by a user of the website)

Note that an option only supports one type at a time, meaning you can only let the user enter a single INTEGER value that you can use in your whole value JSON!

Options without user input

This applies to types:

  • TOGGLE (on/off)
  • SELECT (select between multiple values)
TOGGLE

A toggle will show as a checkbox on the website. A TOGGLE only needs 1 value JSON + overlay PNG pair. The name of the value does not matter, though, the JSON and PNG should have the same name.

SELECT

A select will show as a dropdown on the website. A SELECT requires multiple pairs of value JSONs and overlay PNGs, such as shown in the second example structure above. For this, the name of the values does matter. The name of the value JSON file (and thus PNG file as well) will be displayed on the website in the dropdown.

Options with user input

This applies to types:

  • INTEGER (number without decimal)
  • DECIMAL (number with decimal)
  • STRING (text)
  • COLOR (hex color code in #RRGGBBAA).

In order to work with user input, you have to do a bit of magic. In the JSON file, you have to add a special string. The Themezer website eventually replaces this with the value input by the user. You can use this value anywhere and how often you like in the json value.

INTEGER

Special string: ??{integer}??
INTEGER supports arithmetic operations. For example: ??{integer} * 2??, ??max({integer}, 5)??
For a list of all supported arithmetic operations see this
Note: If the special string is the only thing between the quotation marks ("), the expression will be evaluated as a number, else it will be kept inside a string. See the examples below.

Usage
See DECIMAL

DECIMAL

Special string: ??{decimal}??
DECIMAL supports arithmetic operations. For example: ??{integer} * 2.0??, ??min({integer}, 5.0)??
For a list of all supported arithmetic operations see this
Note: If the special string is the only thing between the quotation marks ("), the expression will be evaluated as a number, else it will be kept inside a string. See the examples below.

Usage
The following are a few examples for INTEGER and DECIMAL:

"width": "??{integer}??"
// user inputs '10' -->
"width": 10

Decimals also work

"width": "??max({decimal}, 20.0)??"
// user inputs '10.0' -->
"width": 20.0

If the expression is not the only thing between the quotation marks

"animation": "length: ??{integer} + 5??"
// user inputs '10' -->
"animation": "length: 15"
STRING

Special string: ??{string}??
This value will always simply be inserted as string. No parsing is done.

Usage

"name": "??{string}??!!!"
// user inputs "Hello World" -->
"name": "Hello World!!!"
COLOR

Special string: ??{color:RRGGBBAA}?? This value will always be inserted as string. The RRGGBBAA denotes the order of colors. User input is always treated as RRGGBBAA, but it can be inserted into the layout in a different format. This may be required for some color fields.

Usage

"ColorTL": "??{color::RRGGBBAA}??"
// user inputs "F9C000FF" (RRGGBBAA) -->
"ColorTL": "F9C000FF"
"ColorTL": "??{color::AABBGGRR}??"
// user inputs "F9C000FF" (RRGGBBAA) -->
"ColorTL": "FF00C0F9"

🖼️ value.png

A value JSON should always be accompanied by a special PNG (called an 'overlay') with the same name. This overlay is used to preview the value on the website. See the example structure above

Generating an Overlay

As mentioned before, each value also requires a PNG overlay. View those instructions here.

Option Submission Example

Note: I recommend you to look at the files already in this repository.

  1. Enter a layout's folder or the global folder.
  2. Create an options folder, enter it.
  3. Create a folder for the option you want, enter it. For example, Game icons size (this is displayed on Themezer).
  4. Create an option.json file. For example:
    // option.json
    {
    	"description": "Change the size of the game icons. `1` is the stock value. Value used in the preview is `0.5`",
    	"type": "DECIMAL",
    	"typeOptions": {
    		"min": 0.5,
    		"max": 1.8
    	},
    	"priority": 100
    }
  5. Create a values folder, enter it.
  6. Create a value pair (a combination of a JSON and PNG) as follows:

Decimal

  1. Create a json file e.g. enable.json, open it.

This basically has the same structure as a layout.json file, but the only four root (the first depth) fields it should have are HideOnlineBtn, Files, Anims and uuid (so no AuthorName etc.). The uuid is generated by Themezer, don't add this yourself.

  1. Add the special keyword somewhere in your enable.json: ??{decimal}??.

The values you add in this JSON will overwrite (or add if they don't exist) the values in the normal layout.json

  1. Create an overlay using the 'Creating Overlays' guide. Make sure to select your option JSON when building the NXThemes. Save the PNG as enable.png. It must always have the same file name (not file extension) as the JSON file.

Toggle

Note that typeOptions is not supported for the TOGGLE type and that you should remove it
Now if you want to have a simple checkbox you only have to create a single value:

  1. Create a json file e.g. enable.json, open it.
  2. Create an overlay using the 'Creating Overlays' guide. Make sure to select your option JSON when building the NXThemes. Save the PNG as enable.png. It must always have the same file name (not file extension) as the JSON file.

Select

Note that typeOptions is not supported for the TOGGLE type and that you should remove it
If you prefer a dropdown with multiple choices, follow steps #7 and #8 above multiple times. Do note though that the filenames now represent the value name shown in the dropdown.

An example:

  1. Create a folder: Scale, enter it.
  2. Create a value pair: 70%.json with a 70%.png.
  3. Create another value pair: 50%.json with a 50%.png.

If with the above instructions, you're still not sure what to do, dm me (Migush#4096) on Discord.

Clone this wiki locally