Skip to content

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:

shader code
#define optionName //description
//#define optionName //description
#ifdef optionName
// code here only if optionName is "on"
#endif
#ifndef optionName
// code here only if optionName is "off"
#endif

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.

shader code
#if defined option1 && defined option2
// code here only if option1 and option2 are "on"
#endif

Numerical/Other Options

Any non-boolean option, such as a float or int, can be defined by specifying a value with the define:

shader code
#define optionName <defaultValue> // [<value1> <value2> ...] description
#if optionName == <intValue>
#endif

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:

shader code
const int shadowMapResolution = 2048; // [512 1024 2048 4096]

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:

shaders.properties
screen = <list_of_options>

<list_of_options> can be replaced with a space separated list of any of the following:

formatdescription
OPTIONa 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:

shaders.properties
screen = [screen_name] ...
screen.<screen_name> = <list_of_options>

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:

shaders.properties
screen.columns = <number_of_columns>
screen.<screen_name>.columns = <number_of_columns>

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:

shaders.properties
sliders = <list_of_options>

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:

shaders.properties
profile.<name> = <list_of_options>

<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:

formatdescription
OPTION:value OPTION=valueset the value of OPTION to value
OPTIONset boolean option OPTION “on”
!OPTIONset boolean option OPTION “off”
profile.PROFILE_NAMEinclude all options from profile PROFILE_NAME
!program.PROGRAM_NAMEdisable 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):

shaders.properties
screen = <empty> <profile> <empty> [SHADOWS] [LIGHTING] iScream uScream weAllScream forIceCream *
screen.SHADOWS = shadowMapResolution shadowFilter
screen.LIGHTING = SSAO SSR
screen.columns = 3
screen.SHADOWS.columns = 2
profile.LOW = !SSAO ShadowType=1 SSR:false !program.composite2
profile.MED = SSAO ShadowType=2 SSR:false !program.composite2
profile.HIGH = SSAO ShadowType=3 SSR:true
sliders = iScream uScream weAllScream forIceCream

.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:

.lang file
option.TAA = Temporal Anti-aliasing
option.SSBO = Ambient Occlusion

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:

.lang file
value.Shadow_Type.0=off
value.Shadow_Type.1=unfiltered
value.Shadow_Type.2=PCF
value.Shadow_Type.3=PCSS

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:

.lang file
prefix.Shadow_Type = (
suffix.Shadow_Type = )

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:

.lang file
option.TAA.comment = Smooths jagged edges
option.SSBO.comment = Adds shadows in the corners of objects

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:

.lang file
profile.comment = Potato - runs on anything. Low - better than potato. Medium - quality/performance balance. High - good quality, expensive. Ultra - for the ballers.