Skip to content

Introduction

Jump to bottom
TheCSDev edited this page Nov 5, 2026 · 1 revision

Introduction

This mod lets vanilla resource-pack post-effect shaders read client-side values through named bindings.

This page documents the bindings available in this mod.

Declaring bindings

Add a "shaderboard:bindings" array at the root of a post-effect JSON, next to "targets" and "passes". Here is an example:

{
	"targets": { ... },
	"passes": [ ... ],

	"shaderboard:bindings":
	[
		{
			"uniform_name": "u_Health",
			"type": "shaderboard:local_player_health"
		}
	]
}

Note: "Local player" bindings refer to the player using the client, not the camera's target. When no local player is available, their values are usually zero.

Bindings declared at the root apply to every pass. You can also place a "shaderboard:bindings" array inside an individual pass to apply bindings only to that pass.

Use distinct uniform names, and avoid uniform names that are already taken/used by the game.

Every binding requires these JSON fields:

Field Description
uniform_name Name of the GLSL uniform block. Must match the block name in your shader exactly.
type Binding ID from the reference below.

Reading values in GLSL

Declare the matching layout(std140) uniform block in your shader. As an example, for the example binding named above:

layout(std140) uniform u_Health {
	float health;
	float maxHealth;
	float absorption;
};

Table of contents

Scoreboard objective

shaderboard:scoreboard_objective

Reads a score or an array of scores, from an objective on the client's scoreboard.

Important: Scoreboard scores are server-sided and by default do not synchronize with clients. Use /scoreboard objectives setdisplay ... to get an objective's scores to synchronize with clients, so post-effect shaders can read them.

JSON field Description
objective Required. Scoreboard objective name.
target Required. Object selecting which score or scores to read. See below.

Fields for target object

Field Description
type Required. local_player, player, top_player, or array.
name Required for type player. Name of player or score holder.
include_hidden Optional. Whether to include hidden scores (ones whose names start with #). Defaults to false. Intended for top_player and array types.
count/size/length For type array. Fixed array length, from 1 to 128 (as of v2.3.0).
sort Optional. For type array. Non-empty array of sorting rules. Defaults to vanilla sidebar order.
offset Optional. For types top_player and array. Number of entries to skip after filtering and sorting. Must not be negative. Defaults to 0.

For type sort; Each sort rule requires by (name or value) and order (ascending or descending). Rules are applied in their declared order.
Note that you cannot have multiple sorting rules with the same by key.

Single score

Example JSON:

{
	"uniform_name": "u_MyScore",
	"type": "shaderboard:scoreboard_objective",
	"objective": "example_1",
	"target": { "type": "local_player" }
}

Example GLSL:

layout(std140) uniform u_MyScore {
	int myScore;
};

Score array

Example JSON:

{
	"uniform_name": "u_SortedScoresAZ",
	"type": "shaderboard:scoreboard_objective",
	"objective": "example_1",
	"target":
	{
		"type": "array",
		"size": 16,
		"include_hidden": true,
		"sort": [
			{ "by": "name", "order": "ascending" }
		],
		"offset": 0
	}
}

Example GLSL:

layout(std140) uniform u_SortedScoresAZ {
	int sortedScores[16];
};

The GLSL array length must match count/size/length. Missing entries have their values be 0, so they cannot be distinguished from actual scores with values of 0.

Local player health

shaderboard:local_player_health

Reads the local player's health, maximum health, and absorption.

Example JSON:

{
	"uniform_name": "u_Health",
	"type": "shaderboard:local_player_health"
}

Example GLSL:

layout(std140) uniform u_Health {
	float health;
	float maxHealth;
	float absorption;
};
Member Description
health Current health points. Two points equal one heart.
maxHealth Maximum health points.
absorption Additional absorption health points.

Note: In the backend, the game uses decimals (float) to keep track of health values, so GLSL too gets float inputs.

Local player food

shaderboard:local_player_food

Reads the local player's hunger and saturation.

Example JSON:

{
	"uniform_name": "u_Food",
	"type": "shaderboard:local_player_food"
}

Example GLSL:

layout(std140) uniform u_Food {
	int foodLevel;
	float saturationLevel;
};
Member Description
foodLevel Food points, normally from 0 to 20. Two points equal one hunger icon.
saturationLevel Current saturation points.

Local player experience

shaderboard:local_player_xp

Reads local player's experience values.

Example JSON:

{
	"uniform_name": "u_Xp",
	"type": "shaderboard:local_player_xp"
}

Example GLSL:

layout(std140) uniform u_Xp {
	int expLevel;
	float expProgress;
	int expTotal;
};
Member Description
expLevel Current experience level.
expProgress Progress toward the next level (from 0.0 to 1.0).
expTotal Total experience points tracked by the client (includes all levels combined).

Local player air supply

shaderboard:local_player_air_supply

Reads local player's remaining and maximum air supply. Typically for when breathing underwater.

Example JSON:

{
	"uniform_name": "u_AirSupply",
	"type": "shaderboard:local_player_air_supply"
}

Example GLSL:

layout(std140) uniform u_AirSupply {
	int airSupply;
	int maxAirSupply;
};
Member Description
airSupply Remaining air.
maxAirSupply Maximum air supply.

Note: The game's code measures air supply in ticks (as of 26.3, that's 300 max air supply), not in "air bubbles" shown on screen.

Local player attribute

shaderboard:local_player_attribute

Reads the local player's base and effective attribute values.

JSON field Description
attribute Required. Attribute ID (ex. minecraft:movement_speed).

Example JSON:

{
	"uniform_name": "u_MovementSpeed",
	"type": "shaderboard:local_player_attribute",
	"attribute": "minecraft:movement_speed"
}

Example GLSL:

layout(std140) uniform u_MovementSpeed {
	float baseValue;
	float value;
};
Member Description
baseValue Attribute's base value, before modifiers.
value Effective value after modifiers.

Note: Not all attributes are synchronized with the client, so their values may differ from server-side values.

Note: Movement-speed attribute is not a measurement of the player's current velocity.

Local player status effect

shaderboard:local_player_status_effect

Reads the local player's duration and strength a potion/status effect.

JSON field Description
effect Required. Effect ID (ex. minecraft:speed).

Example JSON:

{
	"uniform_name": "u_SpeedEffect",
	"type": "shaderboard:local_player_status_effect",
	"effect": "minecraft:speed"
}

Example GLSL:

layout(std140) uniform u_SpeedEffect {
	int duration;
	int amplifier;
	int isInfinite;
};
Member Description
duration Remaining duration. Infinite effects use -1.
amplifier Zero-based strength: 0 for level I, 1 for level II, and so on.
isInfinite 1 if duration is infinite, otherwise 0.

Local player motion state

shaderboard:local_player_motion_state

Reads the local player's movement-related state flags.

Example JSON:

{
	"uniform_name": "u_MotionState",
	"type": "shaderboard:local_player_motion_state"
}

Example GLSL:

layout(std140) uniform u_MotionState {
	int isOnGround;
	int isCrouching;
	int isSprinting;
	int isSwimming;
	int isUnderwater;
	int isFlying;
	int isGliding;
	int isRiding;
};
Member Meaning when 1
isOnGround Player is on the ground.
isCrouching Player is crouching.
isSprinting Player is sprinting.
isSwimming Player is in the swimming state.
isUnderwater Player's eyes are submerged in water.
isFlying Player is using ability-based flight, such as creative mode flight.
isGliding Player is gliding with an elytra.
isRiding Player is a passenger of another entity.

Note: These flags describe separate states, and are not mutually exclusive.

Clone this wiki locally