Repository navigation
Submitting an Option
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:
..
└── 📁 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
The name of this folder determines the name of the option. It is displayed on the website.
This file contains some basic information about the option. It is required.
// option.json
{
"description": "",
"type": "",
"typeOptions": {
"min": 0,
"max": 100
},
"priority": 1
}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
Required. Either TOGGLE, SELECT, INTEGER, DECIMAL, STRING, or COLOR. See options without user input and options with user input for more details.
Not required. The min and max fields are only supported for INTEGER values, DECIMAL values, or STRING length.
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.
This is where it gets a bit more advanced. This folder can hold different values. A value JSON is a trimmed down layout
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
HideOnlineBtnproperty withfalse - try to find or add an entry in
FileswithFileNameblyt/Cursor3.bflyt- then try to find or add an entry in
PatcheswithPaneNameP_Mainand set theVisibleproperty tofalse - then try to find or add an entry in
PatcheswithPaneNameP_Grow- then try to find or add an entry in
UsdPatcheswithPropNameS_RoundRadiusand remove it from theUsdPatchesarray - then try to find or add an entry in
UsdPatcheswithPropNameC_Wand set thePropValuesto["34", "0", "0", "0"]and settypeto1
- then try to find or add an entry in
- then try to find or add an entry in
- ignore the
Animsproperty
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!
This applies to types:
-
TOGGLE(on/off) -
SELECT(select between multiple values)
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.
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.
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.
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
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": 10Decimals also work
"width": "??max({decimal}, 20.0)??"
// user inputs '10.0' -->
"width": 20.0If the expression is not the only thing between the quotation marks
"animation": "length: ??{integer} + 5??"
// user inputs '10' -->
"animation": "length: 15"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!!!"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"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
As mentioned before, each value also requires a PNG overlay. View those instructions here.
Note: I recommend you to look at the files already in this repository.
- Enter a layout's folder or the
globalfolder. - Create an
optionsfolder, enter it. - Create a folder for the option you want, enter it. For example,
Game icons size(this is displayed on Themezer). - Create an
option.jsonfile. 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 }
- Create a
valuesfolder, enter it. - Create a value pair (a combination of a JSON and PNG) as follows:
- 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.
- 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
- 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.
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:
- Create a json file e.g.
enable.json, open it. - 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.
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:
- Create a folder:
Scale, enter it. - Create a value pair:
70%.jsonwith a70%.png. - Create another value pair:
50%.jsonwith a50%.png.
If with the above instructions, you're still not sure what to do, dm me (Migush#4096) on Discord.