Caffeine

Post-process

Reference Rendering Last updated: Lua 29 · Dryad 0

Per-entity post-process effects such as bloom, vignette, colour grading and fog, with presets and path-based field access.

All namespaces

Namespace: caffeine.postprocess

has#

Lua: caffeine.postprocess.has

text
has(entity) -> boolean

Checks whether the entity has a post-process component.

ParametersTypeDescription
entitynumberEntity id.

Returns: boolean. true if the entity has a post-process component.

Example

lua
if caffeine.postprocess.has(cam) then print('ok') end

add#

Lua: caffeine.postprocess.add

text
add(entity) -> boolean

Adds a post-process component to the entity if it does not have one.

ParametersTypeDescription
entitynumberEntity id.

Returns: boolean. false if the entity is not alive.

Example

lua
caffeine.postprocess.add(cam)

remove#

Lua: caffeine.postprocess.remove

text
remove(entity)

Removes the post-process component from the entity, if present.

ParametersTypeDescription
entitynumberEntity id.

Returns: none

Example

lua
caffeine.postprocess.remove(cam)

get#

Lua: caffeine.postprocess.get

text
get(entity) -> table

Returns a snapshot of the whole post-process state as a table.

ParametersTypeDescription
entitynumberEntity id.

Returns: table. A table of effect groups (for example bloom, vignette) with their fields, plus enabled, customEffectScript and the flat aliases exposure, vignetteIntensity, bloomIntensity. Empty if the entity has no component.

Example

lua
local s = caffeine.postprocess.get(cam)
print(s.bloom.intensity)

set#

Lua: caffeine.postprocess.set

text
set(entity, values) -> boolean

Merges a table of values into the post-process state.

ParametersTypeDescription
entitynumberEntity id.
valuestableTable shaped like the result of `get`; only the keys present are applied.

Returns: boolean. false if the entity has no component.

Example

lua
caffeine.postprocess.set(cam, { bloom = { intensity = 0.8 } })

getValue#

Lua: caffeine.postprocess.getValue

text
getValue(entity, path) -> number|boolean|nil

Reads one field by path.

ParametersTypeDescription
entitynumberEntity id.
pathstringField path such as "bloom.intensity".

Returns: number|boolean|nil. The field value, or nil if the entity or field is unknown.

Example

lua
print(caffeine.postprocess.getValue(cam, 'bloom.intensity'))

setValue#

Lua: caffeine.postprocess.setValue

text
setValue(entity, path, value) -> boolean

Writes one field by path.

ParametersTypeDescription
entitynumberEntity id.
pathstringField path such as "bloom.intensity".
valuenumber|booleanNew value.

Returns: boolean. true if the field was set.

Example

lua
caffeine.postprocess.setValue(cam, 'bloom.threshold', 1.0)

effects#

Lua: caffeine.postprocess.effects

text
effects() -> table

Lists the names of the available post-process effects.

Returns: table. List of effect names.

Example

lua
for _, name in ipairs(caffeine.postprocess.effects()) do print(name) end

fields#

Lua: caffeine.postprocess.fields

text
fields(effect) -> table

Lists the fields of one effect with their ranges and types.

ParametersTypeDescription
effectstringEffect name such as "bloom".

Returns: table. List of tables with name, min, max and type ("bool", "int" or "number").

Example

lua
for _, f in ipairs(caffeine.postprocess.fields('bloom')) do print(f.name, f.min, f.max) end

setEnabled#

Lua: caffeine.postprocess.setEnabled

text
setEnabled(entity, enabled)

Turns the whole post-process component on or off.

ParametersTypeDescription
entitynumberEntity id.
enabledbooleanMaster switch.

Returns: none

Example

lua
caffeine.postprocess.setEnabled(cam, false)

enableEffect#

Lua: caffeine.postprocess.enableEffect

text
enableEffect(entity, effect, enabled) -> boolean

Turns a single effect on or off.

ParametersTypeDescription
entitynumberEntity id.
effectstringEffect name such as "bloom".
enabledbooleanWhether the effect is on.

Returns: boolean. true if the effect exists.

Example

lua
caffeine.postprocess.enableEffect(cam, 'bloom', true)

isEffectEnabled#

Lua: caffeine.postprocess.isEffectEnabled

text
isEffectEnabled(entity, effect) -> boolean

Checks whether an effect is enabled.

ParametersTypeDescription
entitynumberEntity id.
effectstringEffect name such as "bloom".

Returns: boolean. true if the effect is on; false if off or unknown.

Example

lua
print(caffeine.postprocess.isEffectEnabled(cam, 'bloom'))

applyPreset#

Lua: caffeine.postprocess.applyPreset

text
applyPreset(entity, name) -> boolean

Applies a built-in post-process preset.

ParametersTypeDescription
entitynumberEntity id.
namestringOne of "cinematic", "horror", "arcade", "reset" (or "default").

Returns: boolean. false for an unknown preset or missing component.

Example

lua
caffeine.postprocess.applyPreset(cam, 'cinematic')

blend#

Lua: caffeine.postprocess.blend

text
blend(entity, from, to, t) -> boolean

Interpolates between two tables of values (each applied on top of the current state) and stores the result.

ParametersTypeDescription
entitynumberEntity id.
fromtableTable of values for the start state.
totableTable of values for the end state.
tnumberBlend factor, clamped to 0..1.

Returns: boolean. false if the entity has no component.

Example

lua
caffeine.postprocess.blend(cam, { bloom = { intensity = 0 } }, { bloom = { intensity = 1 } }, 0.5)

setExposure#

Lua: caffeine.postprocess.setExposure

text
setExposure(entity, exposure)

Sets colour-grading exposure and enables colour grading.

ParametersTypeDescription
entitynumberEntity id.
exposurenumberExposure value.

Returns: none

Example

lua
caffeine.postprocess.setExposure(cam, 1.2)

setColorGrading#

Lua: caffeine.postprocess.setColorGrading

text
setColorGrading(entity, contrast, saturation, temperature, tint)

Sets colour-grading values and enables colour grading.

ParametersTypeDescription
entitynumberEntity id.
contrastnumberContrast.
saturationnumberSaturation.
temperaturenumberColour temperature. Optional.
tintnumberTint. Optional.

Returns: none

Example

lua
caffeine.postprocess.setColorGrading(cam, 1.1, 0.9)

setBloom#

Lua: caffeine.postprocess.setBloom

text
setBloom(entity, intensity, threshold)

Sets bloom intensity and optionally the threshold.

ParametersTypeDescription
entitynumberEntity id.
intensitynumberBloom intensity; the effect is enabled when above 0.001.
thresholdnumberBrightness threshold. Optional.

Returns: none

Example

lua
caffeine.postprocess.setBloom(cam, 0.6, 1.0)

setVignette#

Lua: caffeine.postprocess.setVignette

text
setVignette(entity, intensity)

Sets vignette intensity.

ParametersTypeDescription
entitynumberEntity id.
intensitynumberIntensity; enabled when above 0.001.

Returns: none

Example

lua
caffeine.postprocess.setVignette(cam, 0.4)

setChromaticAberration#

Lua: caffeine.postprocess.setChromaticAberration

text
setChromaticAberration(entity, intensity)

Sets chromatic aberration intensity.

ParametersTypeDescription
entitynumberEntity id.
intensitynumberIntensity; enabled when above 0.001.

Returns: none

Example

lua
caffeine.postprocess.setChromaticAberration(cam, 0.2)

setGrain#

Lua: caffeine.postprocess.setGrain

text
setGrain(entity, intensity)

Sets film grain intensity.

ParametersTypeDescription
entitynumberEntity id.
intensitynumberIntensity; enabled when above 0.001.

Returns: none

Example

lua
caffeine.postprocess.setGrain(cam, 0.1)

setLensDistortion#

Lua: caffeine.postprocess.setLensDistortion

text
setLensDistortion(entity, intensity)

Sets lens distortion intensity.

ParametersTypeDescription
entitynumberEntity id.
intensitynumberIntensity; enabled when its absolute value is above 0.001.

Returns: none

Example

lua
caffeine.postprocess.setLensDistortion(cam, -0.1)

setMotionBlur#

Lua: caffeine.postprocess.setMotionBlur

text
setMotionBlur(entity, intensity)

Sets motion blur intensity.

ParametersTypeDescription
entitynumberEntity id.
intensitynumberIntensity; enabled when above 0.001.

Returns: none

Example

lua
caffeine.postprocess.setMotionBlur(cam, 0.5)

setDepthOfField#

Lua: caffeine.postprocess.setDepthOfField

text
setDepthOfField(entity, focusDistance, aperture)

Sets depth-of-field focus and aperture and enables the effect.

ParametersTypeDescription
entitynumberEntity id.
focusDistancenumberFocus distance.
aperturenumberAperture.

Returns: none

Example

lua
caffeine.postprocess.setDepthOfField(cam, 10, 2.8)

setFog#

Lua: caffeine.postprocess.setFog

text
setFog(entity, density, r, g, b)

Sets the deferred fog density and optionally its colour.

ParametersTypeDescription
entitynumberEntity id.
densitynumberFog density; enabled when above 0.001.
rnumberRed; the colour is applied only if r, g and b are all given. Optional.
gnumberGreen. Optional.
bnumberBlue. Optional.

Returns: none

Example

lua
caffeine.postprocess.setFog(cam, 0.02, 0.6, 0.7, 0.8)

setAmbientOcclusion#

Lua: caffeine.postprocess.setAmbientOcclusion

text
setAmbientOcclusion(entity, intensity, radius)

Sets ambient occlusion intensity and optionally the radius.

ParametersTypeDescription
entitynumberEntity id.
intensitynumberIntensity; enabled when above 0.001.
radiusnumberSampling radius. Optional.

Returns: none

Example

lua
caffeine.postprocess.setAmbientOcclusion(cam, 1.0, 0.5)

setAntiAliasing#

Lua: caffeine.postprocess.setAntiAliasing

text
setAntiAliasing(entity, mode)

Selects the anti-aliasing mode; "off" and "none" disable it.

ParametersTypeDescription
entitynumberEntity id.
modestring"fxaa", "off" or "none"; any other value selects the non-FXAA mode.

Returns: none

Example

lua
caffeine.postprocess.setAntiAliasing(cam, 'fxaa')

setAutoExposure#

Lua: caffeine.postprocess.setAutoExposure

text
setAutoExposure(entity, enabled, compensation)

Toggles auto exposure and optionally sets its compensation.

ParametersTypeDescription
entitynumberEntity id.
enabledbooleanTurns auto exposure on or off.
compensationnumberExposure compensation. Optional.

Returns: none

Example

lua
caffeine.postprocess.setAutoExposure(cam, true, 0.5)

setCustomScript#

Lua: caffeine.postprocess.setCustomScript

text
setCustomScript(entity, path)

Sets the custom effect script of the entity.

ParametersTypeDescription
entitynumberEntity id.
pathstringPath of the custom effect script.

Returns: none

Example

lua
caffeine.postprocess.setCustomScript(cam, 'scripts/fx.lua')

handle#

Lua: caffeine.postprocess.handle

text
handle(entity) -> table

Returns a per-entity handle, the same kind passed to onPostProcess, so calls need no entity id.

ParametersTypeDescription
entitynumberEntity id.

Returns: table. Table with entity, get, set, enable, isEnabled, snapshot, apply and preset, all bound to the entity.

Example

lua
local h = caffeine.postprocess.handle(cam)
h.set('bloom.intensity', 0.5)