Shader Pack Settings
Optifine/Iris use preprocessor directives to define user options that appear in the “Shader Pack Settings” screen. These options should be defined as macros in the shader files using #define
. The value of an option can be checked in shader files with #ifdef
, #ifndef
, #if
, etc. The option macro must be defined in all files which it is used in, and if it is defined in multiple files it must be defined identically in all files.
Boolean Options
A boolean option can be defined and checked in shader code with like the following:
The option will be “on” (defined) by default, however commenting out the #define line will keep the option but make the default value “off” (not defined).
Optionally, a comment after the macro can be used to add a description to the option, shown when hovering over the option in the “Shader Pack Settings” screen.
#if defined
can be used to check multiple options in one line (for example see below). However for Iris/Optifine to recognize a boolean option, it must be checked at least once using #ifdef
or #ifndef
.
Numerical/Other Options
Any non-boolean option, such as a float or int, can be defined by specifying a value with the define:
A comment should be placed after the macro, and the possible values for the option should be placed square brackets directly after the comment starts. The values should be separated by spaces only. Any text after the values list will be treated as a description for the option, shown when hovering over the option in the “Shader Pack Settings” screen.
These options can be used directly in shader code like a variable, and will be replaced with the option’s value before compilation. Additionally, int options only can be checked using #if
.
Constants
Iris/Optifine define numerous constants to control certain aspects of the shader pipeline. If a value list is added in a comment after the declaration of a numeric const, it can be added to the shaders screen like a shader define option. For example:
Configuring the Settings Screen
By default, the “Shader Pack Settings” screen is automatically populated with all valid shader options that Iris finds in the shader pack.
Alternatively, the screen
directive can be used to control which shader options are displayed in the “Shader Pack Settings” screen and how they are displayed. Options can be added to the “Shader Pack Settings” screen by adding them to the screen
direction in the shaders.properties file as follows:
<list_of_options>
can be replaced with a space separated list of any of the following:
format | description |
---|---|
OPTION | a shader option named “OPTION” |
[SCREEN] | a link to a sub-screen named “SCREEN” |
<profile> | a button that changes the current shader profile |
<empty> | an empty spot, i.e. a spacer |
* | any remaining shader options not already in a screen |
Sub-Screens
A sub-screen (a menu within the “Shader Pack Settings” menu) can be created as follows:
A button will be created in whichever screen or sub-screen [screen_name]
is placed in, which when clicked will switch to the sub-screen. Sub-screens may include all of the same type of items as the main screen. Sub-screens can be nested by including other [screen_name]
’s within the sub-screen list, and there may be multiple links to a particular sub-screen from screens/sub-screens.
Columns
By default the shader options will be displayed in two columns, unless there are too many to fit on screen then three columns are used. Alternatively, column counts can be specified per screen/sub-screen as follows:
Sliders
The sliders
directive is a list of non-boolean options which are made into sliders in the “Shader Pack Settings” screen. The directive can be added to the shaders.properties file as follows:
Replace <list_of_options>
with a space separated list of shader options to display as sliders in the “Shader Pack Settings” screen and/or sub-screens. Any options which are not in the sliders
list are treated as buttons, where clicking the buttons cycles through the option values. Sliders however let you drag a bar to change option values.
The values in the slider are defined by the commented value list where the option is defined. The order of values in the slider is determined exclusively by the order in the commented value list. For example if the list is not defined in numerical order the slider values will not be in numerical order.
There should only be one sliders
list in shaders.properties, and options from any sub-screens should be included in that single list (the sliders will still appear in the sub-screen they are defined in using screen
).
Profiles
The profile
directive allows defining of profiles, which are pre-configured sets of user options selectable through a <profile>
button in the “Shader Pack Settings” screen. Profiles can be configured by adding the following directive to the shaders.properties file:
<name>
should be replaced with the name of the profile, and <list_of_options>
can be replaced with a space separated list of any of the following:
format | description |
---|---|
OPTION:value OPTION=value | set the value of OPTION to value |
OPTION | set boolean option OPTION “on” |
!OPTION | set boolean option OPTION “off” |
profile.PROFILE_NAME | include all options from profile PROFILE_NAME |
!program.PROGRAM_NAME | disable program PROGRAM_NAME , may include dimension (e.g. world1/composite5 ) |
A button to switch between active profiles can be added to the “Shader Pack Settings” screen by adding <profile>
to a screen or sub-screen through the screen
directive.
Example
Here’s a nice example to hopefully clear things up (I hope you like ice cream):
.lang Files
.lang
files can be added for any supported languages to add use friendly labels and tooltips to shader options. All .lang
files should be located in the shaders/lang
folder inside the shaderpack. Files should be named <lang_id>.lang
where <lang_id>
is replaced by the language ID, for example en_us.lang
.
Option Labels
Option labels replace a shader option’s name in the shader options screen. They can be specified with option.<option_name> = <label>
in a lang file. Replace <option_name>
with the options name as defined in shaders.properties, and <label>
with the label to be displayed in the shader options screen. For example:
Value Labels
Value labels replace the display name of a specific value of a non-boolean shader option. They can be specified with value.<option_name>.<value> = <value_label>
in a lang file. Replace <option_name>
with the options name as defined in shaders.properties, <value>
with value to replace, and <value_label>
with the user-friendly value label to be displayed in the shader options screen. For example:
A prefix and suffix can be added to before and after the values of an option with prefix.<option_name> = <prefix>
and suffix.<option_name> = <suffix>
in a lang file. Replace <option_name>
with the options name as defined in shaders.properties, and <prefix>
or <suffix>
with the user-friendly value label to be displayed in the shader options screen. For example the following surrounds a value in parenthesis:
Option Tooltips
Option tooltips are shown in a tooltip when the user hovers over the shader option. They can be specified with option.<option_name>.comment = <comment>
in a lang file. Replace <option_name>
with the options name as defined in shaders.properties, and <comment>
with the tooltip comment to be displayed in the shader options screen. For example:
A tooltip can be added to the profile button with the with profile.comment = <comment>
in a .lang
file. Replace <comment>
with the tooltip comment to be displayed in the shader options screen. For example: