PBR API
anvil.api.pbr
Anvil PBR API.
Provides classes for configuring physically-based rendering (PBR) features in Minecraft Bedrock Edition's Deferred Rendering pipeline, including lighting, atmospherics, shadows, water settings, color grading, local lighting, fallback settings, texture sets, and cubemaps.
Texture Sets
anvil.api.pbr.texture_set
TextureComponents
dataclass
PBR texture components for blocks, items, and entities.
Attributes:
| Name | Type | Description |
|---|---|---|
color |
str
|
Base color texture filename or color value |
normal |
str | HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255 | None
|
Normal map texture filename or color value (mutually exclusive with heightmap) |
heightmap |
str | HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255 | None
|
Height/displacement map texture filename or color value (mutually exclusive with normal) |
mer |
str | HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255 | None
|
MER texture filename or color value (mutually exclusive with mers) |
mers |
str | HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255 | None
|
MERS texture filename or color value (mutually exclusive with mer) |
has_aux()
Checks if the texture components have any auxiliary texture maps (normal, height, mer, or mers).
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if at least one auxiliary texture component is configured, False otherwise. |
TextureSet
Bases: JsonFile[_TextureSetFile]
Represents a PBR Texture Set configuration for Minecraft Bedrock Edition.
Allows linking base color textures with physical property maps (normal, height, MER, MERS) and handles copying the files to the resource pack layout.
Documentation reference
identifier
property
The file's identifier.
name
property
The identifier's name, without its namespace.
__export__()
Copies queued texture image assets to the destination resource pack and compiles the texture set definition JSON.
__init__(texture_name, target, overriding_vanilla=False)
Initializes a new TextureSet instance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
texture_name
|
str
|
The name of the texture. |
required |
target
|
Literal['blocks', 'items']
|
The target directory layout/namespace. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If PBR is not enabled in the configuration and auxiliary maps are specified. |
__schema__()
classmethod
The JSON Schema (draft 2020-12) of this file: the schema of its _document_type, with
the file's type as title and where it is written under x-anvil-file.
Raises:
| Type | Description |
|---|---|
TypeError
|
When the class is an abstract file base, with no document type. |
__set_individual_textures(source, components)
Queues individual texture files to be copied and populates the texture set definition content.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source
|
str
|
The source folder under 'assets/' (e.g., 'textures/items'). |
required |
components
|
TextureComponents
|
The PBR texture components. |
required |
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If configured texture image files do not exist in 'assets/'. |
__validate(components)
Validates PBR texture components for mutual exclusivity and format correctness.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
components
|
TextureComponents
|
The texture components to validate. |
required |
Returns:
| Type | Description |
|---|---|
|
dict[str, str]: A dictionary of PBR maps and their validated/converted hex values. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If mutually exclusive components are provided. |
ValueError
|
If auxiliary maps are used when PBR is disabled in configuration. |
queue(directory=None)
Queues the addon object for processing and logs the event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
directory
|
str
|
The directory of the addon object. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
self |
'JsonFile[D]'
|
The instance of the current JsonFile. |
set_blockbench_textures(blockbench, components)
Sets texture components using standard Blockbench exporter conventions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
blockbench
|
str
|
The name of the blockbench model asset directory. |
required |
components
|
TextureComponents
|
The PBR texture components. |
required |
set_item_textures(components)
Sets the texture components specifically for an item texture set.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
components
|
TextureComponents
|
The PBR texture components for the item. |
required |
set_particle_textures(components)
Sets the texture components specifically for a particle texture set.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
components
|
TextureComponents
|
The PBR texture components for the particle. |
required |
set_vanilla_texture(blockbench, components, subfolder='')
Sets texture components for overriding a vanilla texture.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
blockbench
|
str
|
The name of the blockbench model asset directory. |
required |
components
|
TextureComponents
|
The PBR texture components. |
required |
subfolder
|
str
|
Subfolder under RP_PATH/textures/blocks. Defaults to "". |
''
|
Lighting
anvil.api.pbr.lighting
LightingSettings
Bases: JsonFile[_LightingSettingsFile]
Global lighting settings for Vibrant Visuals (PBR) rendering.
Documentation reference
identifier
property
The file's identifier.
name
property
The identifier's name, without its namespace.
__export__()
Exports the addon object after potentially shortening its content and replacing backslashes. Logs the event and writes the object to a file.
__init__(name='default_lighting')
Initializes a LightingSettings instance.
Raises:
| Type | Description |
|---|---|
ValueError
|
If PBR is not enabled in the config. |
__schema__()
classmethod
The JSON Schema (draft 2020-12) of this file: the schema of its _document_type, with
the file's type as title and where it is written under x-anvil-file.
Raises:
| Type | Description |
|---|---|
TypeError
|
When the class is an abstract file base, with no document type. |
ambient(illuminance, color)
Controls how surfaces are lit when there are no other light sources available.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
illuminance
|
float | list[tuple[float, float]]
|
Minimum fallback light strength in lux (lx). Valid range: 0.0 to 5.0. |
required |
color
|
HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255 | list[tuple[float, HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255]]
|
Color of the ambient fallback light. Supports RGB array or HEX string. |
required |
emissive(desaturation)
Configures global settings for emissive light sources.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
desaturation
|
float
|
Factor (0.0 to 1.0) controlling how much the albedo of a given pixel is desaturated. |
required |
flash_light(illuminance, color)
Configures the End flash light source (exclusive to the End dimension).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
illuminance
|
float
|
Peak brightness of the End flash in lux (lx). |
required |
color
|
HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255
|
Color contributed by the End flash. Supports RGB array or HEX string. |
required |
orbital_lights(sun_illuminance=None, sun_color=None, moon_illuminance=None, moon_color=None, orbital_offset_degrees=None)
Configures the orbital celestial lights (sun and moon).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sun_illuminance
|
float | list[tuple[float, float]]
|
Brightness of the sun in lux (lx). |
None
|
sun_color
|
HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255 | list[tuple[float, HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255]]
|
Color contributed by the sun. Supports RGB array or HEX string. |
None
|
moon_illuminance
|
float | list[tuple[float, float]]
|
Brightness of the moon in lux (lx). |
None
|
moon_color
|
HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255 | list[tuple[float, HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255]]
|
Color contributed by the moon. Supports RGB array or HEX string. |
None
|
orbital_offset_degrees
|
float | list[tuple[float, float]]
|
Rotational offset of celestial bodies from standard orbital axis. |
None
|
sky(intensity)
Controls indirect lighting contribution from the sky.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
intensity
|
float | list[tuple[float, float]]
|
Energy scaling factor. Valid range: 0.1 to 1.0. |
required |
LocalLighting
Bases: JsonFile[_LocalLightingFile]
The blocks that give off light in Vibrant Visuals: point lights and static lights.
Documentation reference
identifier
property
The file's identifier.
lights
property
The lights, by block identifier.
name
property
The identifier's name, without its namespace.
__export__()
Exports the addon object after potentially shortening its content and replacing backslashes. Logs the event and writes the object to a file.
__init__()
Creates the local lighting settings.
Raises:
| Type | Description |
|---|---|
ValueError
|
If PBR is not enabled in the config. |
__schema__()
classmethod
The JSON Schema (draft 2020-12) of this file: the schema of its _document_type, with
the file's type as title and where it is written under x-anvil-file.
Raises:
| Type | Description |
|---|---|
TypeError
|
When the class is an abstract file base, with no document type. |
add_local_light(block_identifier, color, light_type='point_light')
Makes a block give off light.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
block_identifier
|
Block | BlockDescriptor | str
|
The block. |
required |
color
|
HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255
|
The light's color. |
required |
light_type
|
Literal['static_light', 'point_light']
|
Defaults to
|
'point_light'
|
add_point_light(block_identifier, color)
Makes a block a static light.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
block_identifier
|
Block | BlockDescriptor | str
|
The block. |
required |
color
|
HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255
|
The light's color. |
required |
queue(directory=None)
Queues the addon object for processing and logs the event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
directory
|
str
|
The directory of the addon object. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
self |
'JsonFile[D]'
|
The instance of the current JsonFile. |
Atmosphere
anvil.api.pbr.atmosphere
AtmosphericSettings
Bases: JsonFile[_AtmosphereSettingsFile]
Atmospheric settings for Vibrant Visuals (PBR) rendering.
Allows customizing Rayleigh and Mie scattering, glare, blend stops, and sky colors.
Documentation reference
identifier
property
The file's identifier.
name
property
The identifier's name, without its namespace.
__export__()
Exports the addon object after potentially shortening its content and replacing backslashes. Logs the event and writes the object to a file.
__init__(name='default_atmospherics')
Initializes an AtmosphericSettings instance.
Raises:
| Type | Description |
|---|---|
ValueError
|
If PBR is not enabled in the config. |
__schema__()
classmethod
The JSON Schema (draft 2020-12) of this file: the schema of its _document_type, with
the file's type as title and where it is written under x-anvil-file.
Raises:
| Type | Description |
|---|---|
TypeError
|
When the class is an abstract file base, with no document type. |
horizon_blend_stops(min, start, mie_start, max)
How the atmosphere is divided up.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
min
|
float | list[tuple[float, float]]
|
The minimum horizon height. |
required |
start
|
float | list[tuple[float, float]]
|
The height relative to the horizon where the zenith contribution will take over. |
required |
mie_start
|
float | list[tuple[float, float]]
|
The height relative to the horizon where mie scattering begins. |
required |
max
|
float | list[tuple[float, float]]
|
The maximum horizon height. |
required |
moon_mie_strength(value)
How strong the moon's mie scattering term is.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
float | list[tuple[float, float]]
|
Moon Mie scattering strength. |
required |
queue(directory=None)
Queues the addon object for processing and logs the event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
directory
|
str
|
The directory of the addon object. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
self |
'JsonFile[D]'
|
The instance of the current JsonFile. |
rayleigh_strength(value)
How strong the atmosphere's rayleigh scattering term is.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
float | list[tuple[float, float]]
|
Rayleigh scattering strength. |
required |
sky_horizon_color(color)
The RGB color of the horizon region of the atmosphere. Supports RGB array or HEX string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
color
|
HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255 | list[tuple[float, HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255]]
|
Sky horizon color. |
required |
sky_zenith_color(color)
The RGB color of the zenith region of the atmosphere. Supports RGB array or HEX string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
color
|
HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255 | list[tuple[float, HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255]]
|
Sky zenith color. |
required |
sun_glare_shape(value)
How the lobe of the mie scattering is shaped.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
float | list[tuple[float, float]]
|
Sun glare shape factor. |
required |
sun_mie_strength(value)
How strong the sun's mie scattering term is.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
float | list[tuple[float, float]]
|
Sun Mie scattering strength. |
required |
Fog
anvil.api.pbr.fog
FogSettings
Bases: JsonFile[_FogSettingsFile]
Represents a Minecraft Fog resource pack definition.
Generates a .fog.json file in the pack's fogs/ directory. Fog settings define
both distance-based fog properties and volumetric (PBR/Ray Tracing) settings.
Settings are resolved in the game via the Active Fog Stack:
Command (highest precedence) -> Biomes -> Data Default -> Engine Default (lowest).
Documentation reference
Documentation reference
identifier
property
The file's identifier.
name
property
The identifier's name, without its namespace.
__export__()
Exports the addon object after potentially shortening its content and replacing backslashes. Logs the event and writes the object to a file.
__init__(name='fog', is_vanilla=False)
Initializes a Fog definition instance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The identifier and filename of the fog setting. Defaults to "fog". |
'fog'
|
is_vanilla
|
bool
|
True if referencing/overriding a vanilla fog definition
(under the |
False
|
__schema__()
classmethod
The JSON Schema (draft 2020-12) of this file: the schema of its _document_type, with
the file's type as title and where it is written under x-anvil-file.
Raises:
| Type | Description |
|---|---|
TypeError
|
When the class is an abstract file base, with no document type. |
add_distance_location(color, fog_start, fog_end, render_distance_type=RenderDistanceType.Render, camera_location=FogCameraLocation.Air)
Adds and configures distance-based fog settings for a specific camera location environment.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
color
|
HexRGB
|
Hex color code of the fog (e.g. |
required |
fog_start
|
float | int
|
Relative ratio or absolute block distance where fog begins to appear.
Maps to |
required |
fog_end
|
float | int
|
Relative ratio or absolute block distance where fog becomes fully opaque.
Maps to |
required |
render_distance_type
|
RenderDistanceType
|
Determines how start and end values are used.
- |
Render
|
camera_location
|
FogCameraLocation
|
The camera location environment (e.g., Air, Water, Weather, Lava, LavaResistance) matching the corresponding key in the JSON schema. Defaults to FogCameraLocation.Air. |
Air
|
Returns:
| Name | Type | Description |
|---|---|---|
_FogDistance |
_FogDistance
|
The configured distance settings object for method chaining. |
air_density(max_density, uniform=False, zero_density_height=0.0, max_density_height=0.0)
Sets the volumetric density parameters for air. Used for Ray Tracing / PBR rendering.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
max_density
|
float
|
Density multiplier disrupting light passing through air. Range: [0.0 (no fog), 1.0 (near opaque)]. |
required |
uniform
|
bool
|
If True, fog density is uniform at all heights. Defaults to False. |
False
|
zero_density_height
|
float
|
Y-level height in blocks where air fog density fades to 0.0.
Only active when |
0.0
|
max_density_height
|
float
|
Y-level height in blocks where air fog density starts at max_density.
Only active when |
0.0
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If PBR is not enabled in CONFIG. |
ValueError
|
If zero_density_height is less than max_density_height. |
henyey_greenstein_g(air_g=0.0, water_g=0.0)
Sets Henyey-Greenstein phase function asymmetry parameters for air and water. Supported in format_version 1.21.90+ and only applicable in Vibrant Visuals (PBR) packs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
air_g
|
float
|
Asymmetry factor for air scattering. Range [-1.0 (back-scattering), 1.0 (forward-scattering)]. Default is 0.75. |
0.0
|
water_g
|
float
|
Asymmetry factor for water scattering. Range [-1.0 (back-scattering), 1.0 (forward-scattering)]. Default is 0.6. |
0.0
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If PBR is not enabled in CONFIG. |
media_coefficients(water_scattering=None, water_absorption=None, air_scattering=None, air_absorption=None)
Sets media scattering and absorption RGB coefficients for water and air volumetric mediums.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
water_scattering
|
HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255
|
RGB scattering multipliers. |
None
|
water_absorption
|
HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255
|
RGB absorption multipliers. |
None
|
air_scattering
|
HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255
|
RGB scattering multipliers. |
None
|
air_absorption
|
HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255
|
RGB absorption multipliers. |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If PBR is not enabled in CONFIG. |
queue(directory=None)
Queues the addon object for processing and logs the event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
directory
|
str
|
The directory of the addon object. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
self |
'JsonFile[D]'
|
The instance of the current JsonFile. |
water_density(max_density, uniform=True, zero_density_height=0.0, max_density_height=0.0)
Sets the volumetric density parameters for water. Used for Ray Tracing / PBR rendering.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
max_density
|
float
|
Density multiplier disrupting light passing through water. Range: [0.0 (no fog), 1.0 (near opaque)]. |
required |
uniform
|
bool
|
If True, fog density is uniform at all heights. Defaults to True. |
True
|
zero_density_height
|
float
|
Y-level height in blocks where water fog density fades to 0.0.
Only active when |
0.0
|
max_density_height
|
float
|
Y-level height in blocks where water fog density starts at max_density.
Only active when |
0.0
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If PBR is not enabled in CONFIG. |
ValueError
|
If zero_density_height is less than max_density_height. |
Water
anvil.api.pbr.water
WaterSettings
Bases: JsonFile[_WaterSettingsFile]
Water effects customization settings for Vibrant Visuals (PBR) rendering.
Documentation reference
identifier
property
The file's identifier.
name
property
The identifier's name, without its namespace.
__export__()
Exports the addon object after potentially shortening its content and replacing backslashes. Logs the event and writes the object to a file.
__init__(name='default_water')
Initializes a WaterSettings instance.
__schema__()
classmethod
The JSON Schema (draft 2020-12) of this file: the schema of its _document_type, with
the file's type as title and where it is written under x-anvil-file.
Raises:
| Type | Description |
|---|---|
TypeError
|
When the class is an abstract file base, with no document type. |
caustics(enabled=None, frame_length=None, power=None, scale=None, texture=None)
Caustics make bodies of water more realistic by projecting light rays on underwater surfaces. These rays then scatter and dance as the surface of the water moves. This effect is enabled by default, but can be selectively disabled in given water configurations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
enabled
|
bool
|
Whether or not caustics are on or off. |
None
|
frame_length
|
float
|
Duration for each frame in the caustics texture animation (0.01 - 5.0). |
None
|
power
|
int
|
Controls brightness of the caustics effect (1 - 6). |
None
|
scale
|
float
|
Controls the size of the caustics texture repetition (0.1 - 5.0). |
None
|
texture
|
str
|
Resource location for a custom caustics texture; defaults to built-in texture if not provided. |
None
|
particle_concentrations(cdom=None, chlorophyll=None, suspended_sediment=None)
The composition of particles in a body of water determines its color and how light behaves as it travels through the water. We've boiled them down to three concentrations in mg/L. Use these values to simulate crystal clear lakes, deep oceans, or muddy rivers. Args: cdom (float | None): Concentration of colored dissolved organic matter (CDOM) in the water. chlorophyll (float | None): Concentration of chlorophyll in the water. suspended_sediment (float | None): Concentration of suspended sediment in the water.
queue(directory=None)
Queues the addon object for processing and logs the event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
directory
|
str
|
The directory of the addon object. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
self |
'JsonFile[D]'
|
The instance of the current JsonFile. |
waves(enabled=None, depth=None, direction_increment=None, frequency=None, frequency_scaling=None, mix=None, octaves=None, pull=None, sampleWidth=None, shape=None, speed=None, speed_scaling=None)
Waves are an optional effect that can be used to complement water surface animations to make your water appear more realistic. You can blend them with existing water texture animations, or replace them entirely. The waves in Vibrant Visuals are purely an image-based effect—waves don't actually move the vertices of the water surface, so the water surface geometry will remain unchanged. Args: enabled (bool, optional): Whether or not waves are on or off. depth (float, optional): Controls the amount of wave displacement. Valid range: 0.0 to 3.0. direction_increment (float, optional): Controls how much the heading changes between each octave. Valid range: 0.0 to 360.0. frequency (float, optional): Controls the size of individual waves; higher values create more tightly packed waves. Valid range: 0.01 to 3.0. frequency_scaling (float, optional): Controls how much frequencies change in subsequent octaves. Valid range: 0.0 to 2.0. mix (float, optional): Controls how much each octave will blend into the neighboring octave. Valid range: 0.0 to 1.0. octaves (int, optional): Determines how many layers of waves to simulate; high values result in more complex waves. Valid range: 1 to 30. pull (float, optional): Controls how much smaller waves are pulled into larger ones. Valid range: -1.0 to 1.0. sampleWidth (float, optional): Controls the resolution of the fractal effect; higher values result in smoother waves. Valid range: 0.01 to 1.0. shape (float, optional): Adjusts the shape of the wave. Valid range: 1.0 to 10.0. speed (float, optional): Controls the starting speed of the first waves. Valid range: 0.01 to 10.0. speed_scaling (float, optional): Controls how much faster/slower subsequent octaves move. Valid range: 0.0 to 2.0.
Color Grading
anvil.api.pbr.color_grading
ColorGradingSettings
Bases: JsonFile[_ColorGradingSettingsFile]
Color grading and tone mapping configuration settings for Vibrant Visuals (PBR) rendering.
Documentation reference
identifier
property
The file's identifier.
name
property
The identifier's name, without its namespace.
__export__()
Exports the addon object after potentially shortening its content and replacing backslashes. Logs the event and writes the object to a file.
__init__(name='default_color_grading')
Initializes a ColorGradingSettings instance.
Raises:
| Type | Description |
|---|---|
ValueError
|
If PBR is not enabled in the config. |
__schema__()
classmethod
The JSON Schema (draft 2020-12) of this file: the schema of its _document_type, with
the file's type as title and where it is written under x-anvil-file.
Raises:
| Type | Description |
|---|---|
TypeError
|
When the class is an abstract file base, with no document type. |
highlights(highlightsMin=None, contrast=None, gain=None, gamma=None, offset=None, saturation=None)
Sets color grading parameters for highlights.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
enabled
|
bool
|
Whether to enable highlight color grading. |
required |
highlightsMin
|
float
|
Multiplier for average luminance determining highlight threshold. Valid range: 1.0 to 4.0. |
None
|
contrast
|
tuple[float, float, float]
|
Highlight contrast multiplier per RGB channel. Valid range: 0.0 to 4.0. |
None
|
gain
|
tuple[float, float, float]
|
Highlight multiplicative gain per RGB channel. Valid range: 0.0 to 10.0. |
None
|
gamma
|
tuple[float, float, float]
|
Highlight exponential gamma correction per RGB channel. Valid range: 0.0 to 4.0. |
None
|
offset
|
tuple[float, float, float]
|
Highlight additive offset per RGB channel. Valid range: -1.0 to 1.0. |
None
|
saturation
|
tuple[float, float, float]
|
Highlight saturation intensity per RGB channel. Valid range: 0.0 to 10.0. |
None
|
midtones(contrast=None, gain=None, gamma=None, offset=None, saturation=None)
Sets color grading parameters for midtones (or globally if highlights/shadows are disabled).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
contrast
|
tuple[float, float, float]
|
Tonal range contrast multiplier per RGB channel. Valid range: 0.0 to 4.0. |
None
|
gain
|
tuple[float, float, float]
|
Multiplicative gain per RGB channel. Valid range: 0.0 to 10.0. |
None
|
gamma
|
tuple[float, float, float]
|
Exponential gamma correction per RGB channel. Valid range: 0.0 to 4.0. |
None
|
offset
|
tuple[float, float, float]
|
Additive offset per RGB channel. Valid range: -1.0 to 1.0. |
None
|
saturation
|
tuple[float, float, float]
|
Saturation intensity per RGB channel. Valid range: 0.0 to 10.0. |
None
|
queue(directory=None)
Queues the addon object for processing and logs the event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
directory
|
str
|
The directory of the addon object. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
self |
'JsonFile[D]'
|
The instance of the current JsonFile. |
shadows(shadowsMax=None, contrast=None, gain=None, gamma=None, offset=None, saturation=None)
Sets color grading parameters for shadows.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
enabled
|
bool
|
Whether to enable shadow color grading. |
required |
shadowsMax
|
float
|
Multiplier for average luminance determining shadow threshold. Valid range: 0.1 to 1.0. |
None
|
contrast
|
tuple[float, float, float]
|
Shadow contrast multiplier per RGB channel. Valid range: 0.0 to 4.0. |
None
|
gain
|
tuple[float, float, float]
|
Shadow multiplicative gain per RGB channel. Valid range: 0.0 to 10.0. |
None
|
gamma
|
tuple[float, float, float]
|
Shadow exponential gamma correction per RGB channel. Valid range: 0.0 to 4.0. |
None
|
offset
|
tuple[float, float, float]
|
Shadow additive offset per RGB channel. Valid range: -1.0 to 1.0. |
None
|
saturation
|
tuple[float, float, float]
|
Shadow saturation intensity per RGB channel. Valid range: 0.0 to 10.0. |
None
|
temperature_grade(temp_value=None, type=None)
Globally adjusts how warm or cool the scene is.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
temp_value
|
float
|
Overall image temperature in Kelvin. Default is 6500.0. Valid range: 1000.0 to 15000.0. |
None
|
type
|
Literal['white_balance', 'color_temperature']
|
Inverts scale logic. Default is "white_balance". |
None
|
tone_mapping(operator)
Remaps HDR colors to SDR-space for display.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
operator
|
Literal['reinhard', 'reinhard_luma', 'reinhard_luminance', 'hable', 'aces', 'generic']
|
The tone mapping operator. |
required |
Shadows
anvil.api.pbr.shadow
ShadowSettings
Bases: JsonFile[_ShadowSettingsFile]
Global shadow settings for Vibrant Visuals (PBR) rendering.
Documentation reference
identifier
property
The file's identifier.
name
property
The identifier's name, without its namespace.
__export__()
Exports the addon object after potentially shortening its content and replacing backslashes. Logs the event and writes the object to a file.
__init__()
Initializes a ShadowSettings instance.
Raises:
| Type | Description |
|---|---|
ValueError
|
If PBR is not enabled in the config. |
__schema__()
classmethod
The JSON Schema (draft 2020-12) of this file: the schema of its _document_type, with
the file's type as title and where it is written under x-anvil-file.
Raises:
| Type | Description |
|---|---|
TypeError
|
When the class is an abstract file base, with no document type. |
queue(directory=None)
Queues the addon object for processing and logs the event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
directory
|
str
|
The directory of the addon object. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
self |
'JsonFile[D]'
|
The instance of the current JsonFile. |
shadow_style(style, texel_size=16)
Sets the shadow style and resolution.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
style
|
Literal['blocky_shadows', 'soft_shadows']
|
The style of shadows to render. |
required |
texel_size
|
int
|
The resolution shadow texels snap to, usually the resolution of the pack's block textures. Defaults to 16. |
16
|
Cubemap
anvil.api.pbr.cubemap
CubeMapSettings
Bases: JsonFile[_CubeMapSettingsFile]
Cubemap settings for sky and indirect lighting in Vibrant Visuals (PBR) rendering.
Documentation reference
identifier
property
The file's identifier.
name
property
The identifier's name, without its namespace.
__export__()
Exports the addon object after potentially shortening its content and replacing backslashes. Logs the event and writes the object to a file.
__init__(identifier='minecraft:default_cubemap')
Initializes a CubeMapSettings instance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
identifier
|
str
|
Unique identifier for the cubemap. Defaults to "minecraft:default_cubemap". |
'minecraft:default_cubemap'
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If PBR requires PBR to be enabled in the config. |
__schema__()
classmethod
The JSON Schema (draft 2020-12) of this file: the schema of its _document_type, with
the file's type as title and where it is written under x-anvil-file.
Raises:
| Type | Description |
|---|---|
TypeError
|
When the class is an abstract file base, with no document type. |
queue(directory=None)
Queues the addon object for processing and logs the event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
directory
|
str
|
The directory of the addon object. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
self |
'JsonFile[D]'
|
The instance of the current JsonFile. |
set_lighting(ambient_light_illuminance=[(0.0, 5.625), (1.0, 5.625)], sky_light_contribution=1.0, directional_light_contribution=1.0, affected_by_atmospheric_scattering=False, affected_by_volumetric_scattering=False)
Set lighting parameters for the cubemap.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ambient_light_illuminance
|
list[tuple[float, float]]
|
Keyframed ambient illuminance (lux) over the day cycle. Each keyframe's time must be from 0.0 to 1.0 and each value from 0.0 to 100000.0. Defaults to a constant 5.625 lux across the day. |
[(0.0, 5.625), (1.0, 5.625)]
|
sky_light_contribution
|
float
|
How much the sky light contributes to the cubemap, in [0.0, 1.0]. Default 1.0. |
1.0
|
directional_light_contribution
|
float
|
How much directional light (sun/moon) contributes to the cubemap, in [0.0, 1.0]. Default 1.0. |
1.0
|
affected_by_atmospheric_scattering
|
bool
|
Whether the cubemap is affected by atmospheric scattering (horizon/sky effects). Use True for near-surface sky content. Default False. |
False
|
affected_by_volumetric_scattering
|
bool
|
Whether the cubemap is affected by volumetric scattering (fog/light shafts). Default False. |
False
|
Fallback
anvil.api.pbr.fallback
PBRFallback
Bases: JsonFile[_PBRFallbackFile]
PBR fallback settings acting as default values when texture sets are not provided.
Documentation reference
identifier
property
The file's identifier.
name
property
The identifier's name, without its namespace.
__export__()
Exports the addon object after potentially shortening its content and replacing backslashes. Logs the event and writes the object to a file.
__init__()
Initializes a PBRFallback instance.
Raises:
| Type | Description |
|---|---|
ValueError
|
If PBR is not enabled in the config. |
__schema__()
classmethod
The JSON Schema (draft 2020-12) of this file: the schema of its _document_type, with
the file's type as title and where it is written under x-anvil-file.
Raises:
| Type | Description |
|---|---|
TypeError
|
When the class is an abstract file base, with no document type. |
actors_fallback(MERS)
Sets the fallback MERS (Metalness, Emissive, Roughness, Subsurface) values for actors that do not have PBR textures.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
MERS
|
HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255
|
The MERS values as a color in any format, written as four whole numbers from 0 to 255. |
required |
block_fallback(MERS)
Sets the fallback MERS (Metalness, Emissive, Roughness, Subsurface) values for blocks that do not have PBR textures.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
MERS
|
HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255
|
The MERS values as a color in any format, written as four whole numbers from 0 to 255. |
required |
items_fallback(MERS)
Sets the fallback MERS (Metalness, Emissive, Roughness, Subsurface) values for items that do not have PBR textures.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
MERS
|
HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255
|
The MERS values as a color in any format, written as four whole numbers from 0 to 255. |
required |
particles_fallback(MERS)
Sets the fallback MERS (Metalness, Emissive, Roughness, Subsurface) values for particles that do not have PBR textures.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
MERS
|
HexRGB | HexRGBA | RGB | RGBA | RGB255 | RGBA255
|
The MERS values as a color in any format, written as four whole numbers from 0 to 255. |
required |
queue(directory=None)
Queues the addon object for processing and logs the event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
directory
|
str
|
The directory of the addon object. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
self |
'JsonFile[D]'
|
The instance of the current JsonFile. |