Format

A Shaderpack changes how Viewpoint draws the world: its light, its sky, its colours, and which effects run. It is a folder of GLSL files and one pack.properties. It has no Java. The player chooses one Shaderpack at a time on the Graphics page.

• Directorymedia/viewpoint/shaderpacks/example.dusk/

  • pack.properties
  • icon.png
  • CHANGELOG.md
  • Directoryshaders/

    • lib/shade.glsl
    • post.frag
  • Directorytextures/

    • …

• The folder name must be the same as the id.
• shaders/ holds your GLSL files. See Library files.
• textures/ is optional. It holds the images that your shaders read.
• One mod can hold many Shaderpacks.
• The id of the package is also the id of the pack.

The descriptor

pack.properties

format=1
id=example.dusk
name=Dusk
version=1.0.0
author=Example
description=The default look with a warmer grade and softer shadows.
icon=icon.png
license=MIT
game.min=42.21
base=default
changelog=CHANGELOG.md

options=warmth grain
option.warmth.label=Warmth
option.warmth.tooltip=How much the grade leans towards orange.
option.warmth.range=0 1 0.05
option.warmth.default=0.4

option.grain.label=Film grain
option.grain.default=false

presets=fast balanced
preset.default=balanced
preset.fast.label=Fast
preset.fast=warmth=0 grain=false
preset.balanced=

pipeline.bloom=true
pipeline.shadowCascades=2

The file is a Java properties file in UTF-8. A long value can go on over several lines with \ at the end of each line. A Shaderpack has no jar, entry, api or permissions key, because it has no code.

Package keys

These keys are the same as in the other descriptors. See Descriptor.

Key	Required	Meaning
format, id, name, version	Yes	As for all packages.
game.min	Yes	The oldest game build.
game.max, viewpoint.min, viewpoint.max	No	The ranges that you tested.
author, description, icon, license, changelog	No	Shown on the card. The card shows the licence, or No licence given.
requires, conflicts	No	Other packages. A package that is your base must be in requires.
library	No	The Viewpoint version that you made the pack for (planned). See Library files.

Pack keys

Key	Meaning
base	The pack that yours starts from: its files, options and pipeline. If you leave it out, the pack starts from the library alone. See Build on another pack.
dropOptions	The options of the base that your pack leaves out, by id. They are gone from the window, and their defines are not set.
options	The ids of your own options, in the order that the window lists them.
presets	The ids of your own presets, in the order of the Quality list.
preset.default	The preset that a new install starts with.
passes, pass.<id>.*, targets, target.<name>	Passes of your own. See Passes & inputs.
pipeline.<knob>	Which passes of the renderer run, and their sizes. See The pipeline.

Options

An option is a setting that the player can change on the Graphics page. Your shaders read it as a define.

Key	Meaning
option.<id>.label, .tooltip	The text that the window shows.
option.<id>.default	The default value. Required.
option.<id>.values	A choice. Its values have spaces between them. Use letters, digits, _, . and -.
option.<id>.value.<value>	The text that the window shows for one value of a choice.
option.<id>.range	A number: min max step.
option.<id>.kept	true: only the player sets it. No preset sets it, and a change never makes the preset Custom.
option.<id>.disabledBy	Another toggle or choice of the pack. While it is on, the window greys out this option and keeps its value.

An option with no values and no range is a toggle: true or false.

Names in GLSL. Every shader stage gets these defines after its #version line:

• OPTION_<ID> for each option: shadowResolution becomes OPTION_SHADOW_RESOLUTION. A toggle is 1 or 0. A number is its value. A choice of words is the index of the chosen word. Each word also gets a define with its index, for example OPTION_SKY_FLAT 0 and OPTION_SKY_GRADIENT 1.
• PIPELINE_<KNOB> for each pipeline knob, in capitals with underscores: PIPELINE_SHADOW_RESOLUTION 2048.

A library file that reads an option gives it a default with #ifndef. A pack that does not have the option does not define it.

Saved values. Each option is a live setting named pack.<encoded id>.<option id> in Zomboid/viewpoint-live.properties. The encoded id writes . and - as _. For example.dusk, the setting for warmth is pack.example_dusk.warmth. See Package kinds.

Presets

The Quality list is the first option of a pack on the Graphics page. It lists your presets, then Custom. When the player chooses a preset, Viewpoint sets the options to its values. When the player changes an option away from the preset, the list shows Custom.

• preset.<id> lists values as option=value, with spaces between them. An option that the line leaves out takes its default.
• preset.<id>.label is the name in the list. Without it, the id in words: veryHigh is “Very high”.
• The preset of preset.default must give every option its default. Its line is usually empty. Viewpoint tells you if it does not, because the list would show Custom from the start.
• This list is not the Preset of the Graphics page (Potato to Ultra). That one sets the mod’s own settings, never an option of a pack.

A line of a preset names the option or the preset that is wrong. Viewpoint leaves out a pack that has an error in pack.properties. The Graphics page lists it under Left out with the reason.

The pipeline

The pipeline says which passes of the renderer run for your pack, and their sizes. A knob that you leave out keeps the value of the base. A pass that is off is not drawn. This is where a light pack saves its time.

A value can follow an option: pipeline.shadowResolution=${shadowResolution}.

Knob	Library value	What it switches
shadows	true	The shadows of the sun and the moon.
shadowResolution	2048	The texels along one side of each shadow map, 256 to 16384.
shadowCascades	3	The number of shadow maps about the player: 1, 2 or 3.
flashlightShadow	true	The shadow of the flashlight, and of a muzzle flash.
lampShadows	2	How many of the nearest lamps cast shadows, 0 to 8.
farShadows	true	The shadows of the far world.
clouds	true	The volumetric clouds.
cloudResolution	50	The size of the clouds’ image as a share of the frame, in percent, 25 to 100.
volumetrics	true	The light in the air: haze, god rays, halos of lamps and the beam of the flashlight.
occlusion	true	The occlusion of ambient light.
bounce	true	The light that the floors bounce.
bloom	true	The bloom.
antialiasing	taaPlus	One of off, fxaa, smaa, taa, taaFxaa, taaPlus.
puddles	true	Wet ground and puddles.

The renderer has more knobs. The library file that uses a knob names it in its first lines.

Build on another pack

base= names the pack that yours starts from. It can be one of these:

Base	Meaning
library	The full look as the renderer draws it, with its options. The model for a pack that changes a little: replace post.frag for a new grade.
vivid	The full look, warmer and bolder. It holds still as Viewpoint changes.
default	The pack that the Modern mode uses until the player chooses another. It goes further than vivid, and it changes as Viewpoint changes.
The id of a folder pack	A pack that the player has in their folder.
The id of another package	A Shaderpack from another mod.

If you want a look that holds still, start from library or vivid.

A pack starts with the options, presets and pipeline lines of its base. Then it adds its own.

• An option with the id of a base option replaces it, in the same place in the list.
• A preset.<id> line for a preset of the base adds values over the base’s line.
• Pipeline lines work in the same way.

Chaining across packages

When the base is another package, these rules apply:

• Put the base in requires. Without it, the pack does not start, and the card says requires its base.
• While the base is not active, the card shows Waiting for <base>. The pack starts when the base is active.
• A cycle of bases is refused.
• A change to a base reads its dependents again. No pack keeps an old base.
• Shaderpacks are not in an order. They never stack by their place in a list. The only stacking is base=.

Note

The pass API of Shaderpacks has a version. An addon asks for it with Version.has("passes", generation). Set viewpoint.min for a Shaderpack that needs a newer Viewpoint.

Limits

A Shaderpack that comes as a package is read one time, when Viewpoint finds the package, and Viewpoint compiles from this copy. These limits are for such a package.

Limit	Value
One file	16 MiB
All files of one pack	64 MiB
Files in one pack	1,000
Links	None. A link, a junction or a special file in the pack folder makes Viewpoint refuse the pack.
File names	No device names (aux, nul), no :, and no name that ends with a dot or a space
Text files	pack.properties and the files in shaders/ must be UTF-8

If a pack is over a limit, Viewpoint refuses it. The card names the file.

When something is wrong

• In pack.properties: Viewpoint leaves out the pack. The Graphics page lists it under Left out with the reason. console.txt has the same line.
• In a GLSL file: the renderer keeps the pack that it had, or the library at the start. The Graphics page shows the compiler’s errors with file names and line numbers. console.txt has them also.

The files that the player accepted are the files that Viewpoint compiles.