Post-process
Per-entity post-process effects such as bloom, vignette, colour grading and fog, with presets and path-based field access.
Namespace: caffeine.postprocess
has#
Lua: caffeine.postprocess.has
has(entity) -> boolean
Checks whether the entity has a post-process component.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
Returns: boolean. true if the entity has a post-process component.
Example
if caffeine.postprocess.has(cam) then print('ok') end
add#
Lua: caffeine.postprocess.add
add(entity) -> boolean
Adds a post-process component to the entity if it does not have one.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
Returns: boolean. false if the entity is not alive.
Example
caffeine.postprocess.add(cam)
remove#
Lua: caffeine.postprocess.remove
remove(entity)
Removes the post-process component from the entity, if present.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
Returns: none
Example
caffeine.postprocess.remove(cam)
get#
Lua: caffeine.postprocess.get
get(entity) -> table
Returns a snapshot of the whole post-process state as a table.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity 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
local s = caffeine.postprocess.get(cam)
print(s.bloom.intensity)
set#
Lua: caffeine.postprocess.set
set(entity, values) -> boolean
Merges a table of values into the post-process state.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
values | table | Table shaped like the result of `get`; only the keys present are applied. |
Returns: boolean. false if the entity has no component.
Example
caffeine.postprocess.set(cam, { bloom = { intensity = 0.8 } })
getValue#
Lua: caffeine.postprocess.getValue
getValue(entity, path) -> number|boolean|nil
Reads one field by path.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
path | string | Field path such as "bloom.intensity". |
Returns: number|boolean|nil. The field value, or nil if the entity or field is unknown.
Example
print(caffeine.postprocess.getValue(cam, 'bloom.intensity'))
setValue#
Lua: caffeine.postprocess.setValue
setValue(entity, path, value) -> boolean
Writes one field by path.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
path | string | Field path such as "bloom.intensity". |
value | number|boolean | New value. |
Returns: boolean. true if the field was set.
Example
caffeine.postprocess.setValue(cam, 'bloom.threshold', 1.0)
effects#
Lua: caffeine.postprocess.effects
effects() -> table
Lists the names of the available post-process effects.
Returns: table. List of effect names.
Example
for _, name in ipairs(caffeine.postprocess.effects()) do print(name) end
fields#
Lua: caffeine.postprocess.fields
fields(effect) -> table
Lists the fields of one effect with their ranges and types.
| Parameters | Type | Description |
|---|---|---|
effect | string | Effect name such as "bloom". |
Returns: table. List of tables with name, min, max and type ("bool", "int" or "number").
Example
for _, f in ipairs(caffeine.postprocess.fields('bloom')) do print(f.name, f.min, f.max) end
setEnabled#
Lua: caffeine.postprocess.setEnabled
setEnabled(entity, enabled)
Turns the whole post-process component on or off.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
enabled | boolean | Master switch. |
Returns: none
Example
caffeine.postprocess.setEnabled(cam, false)
enableEffect#
Lua: caffeine.postprocess.enableEffect
enableEffect(entity, effect, enabled) -> boolean
Turns a single effect on or off.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
effect | string | Effect name such as "bloom". |
enabled | boolean | Whether the effect is on. |
Returns: boolean. true if the effect exists.
Example
caffeine.postprocess.enableEffect(cam, 'bloom', true)
isEffectEnabled#
Lua: caffeine.postprocess.isEffectEnabled
isEffectEnabled(entity, effect) -> boolean
Checks whether an effect is enabled.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
effect | string | Effect name such as "bloom". |
Returns: boolean. true if the effect is on; false if off or unknown.
Example
print(caffeine.postprocess.isEffectEnabled(cam, 'bloom'))
applyPreset#
Lua: caffeine.postprocess.applyPreset
applyPreset(entity, name) -> boolean
Applies a built-in post-process preset.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
name | string | One of "cinematic", "horror", "arcade", "reset" (or "default"). |
Returns: boolean. false for an unknown preset or missing component.
Example
caffeine.postprocess.applyPreset(cam, 'cinematic')
blend#
Lua: caffeine.postprocess.blend
blend(entity, from, to, t) -> boolean
Interpolates between two tables of values (each applied on top of the current state) and stores the result.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
from | table | Table of values for the start state. |
to | table | Table of values for the end state. |
t | number | Blend factor, clamped to 0..1. |
Returns: boolean. false if the entity has no component.
Example
caffeine.postprocess.blend(cam, { bloom = { intensity = 0 } }, { bloom = { intensity = 1 } }, 0.5)
setExposure#
Lua: caffeine.postprocess.setExposure
setExposure(entity, exposure)
Sets colour-grading exposure and enables colour grading.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
exposure | number | Exposure value. |
Returns: none
Example
caffeine.postprocess.setExposure(cam, 1.2)
setColorGrading#
Lua: caffeine.postprocess.setColorGrading
setColorGrading(entity, contrast, saturation, temperature, tint)
Sets colour-grading values and enables colour grading.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
contrast | number | Contrast. |
saturation | number | Saturation. |
temperature | number | Colour temperature. Optional. |
tint | number | Tint. Optional. |
Returns: none
Example
caffeine.postprocess.setColorGrading(cam, 1.1, 0.9)
setBloom#
Lua: caffeine.postprocess.setBloom
setBloom(entity, intensity, threshold)
Sets bloom intensity and optionally the threshold.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
intensity | number | Bloom intensity; the effect is enabled when above 0.001. |
threshold | number | Brightness threshold. Optional. |
Returns: none
Example
caffeine.postprocess.setBloom(cam, 0.6, 1.0)
setVignette#
Lua: caffeine.postprocess.setVignette
setVignette(entity, intensity)
Sets vignette intensity.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
intensity | number | Intensity; enabled when above 0.001. |
Returns: none
Example
caffeine.postprocess.setVignette(cam, 0.4)
setChromaticAberration#
Lua: caffeine.postprocess.setChromaticAberration
setChromaticAberration(entity, intensity)
Sets chromatic aberration intensity.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
intensity | number | Intensity; enabled when above 0.001. |
Returns: none
Example
caffeine.postprocess.setChromaticAberration(cam, 0.2)
setGrain#
Lua: caffeine.postprocess.setGrain
setGrain(entity, intensity)
Sets film grain intensity.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
intensity | number | Intensity; enabled when above 0.001. |
Returns: none
Example
caffeine.postprocess.setGrain(cam, 0.1)
setLensDistortion#
Lua: caffeine.postprocess.setLensDistortion
setLensDistortion(entity, intensity)
Sets lens distortion intensity.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
intensity | number | Intensity; enabled when its absolute value is above 0.001. |
Returns: none
Example
caffeine.postprocess.setLensDistortion(cam, -0.1)
setMotionBlur#
Lua: caffeine.postprocess.setMotionBlur
setMotionBlur(entity, intensity)
Sets motion blur intensity.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
intensity | number | Intensity; enabled when above 0.001. |
Returns: none
Example
caffeine.postprocess.setMotionBlur(cam, 0.5)
setDepthOfField#
Lua: caffeine.postprocess.setDepthOfField
setDepthOfField(entity, focusDistance, aperture)
Sets depth-of-field focus and aperture and enables the effect.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
focusDistance | number | Focus distance. |
aperture | number | Aperture. |
Returns: none
Example
caffeine.postprocess.setDepthOfField(cam, 10, 2.8)
setFog#
Lua: caffeine.postprocess.setFog
setFog(entity, density, r, g, b)
Sets the deferred fog density and optionally its colour.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
density | number | Fog density; enabled when above 0.001. |
r | number | Red; the colour is applied only if r, g and b are all given. Optional. |
g | number | Green. Optional. |
b | number | Blue. Optional. |
Returns: none
Example
caffeine.postprocess.setFog(cam, 0.02, 0.6, 0.7, 0.8)
setAmbientOcclusion#
Lua: caffeine.postprocess.setAmbientOcclusion
setAmbientOcclusion(entity, intensity, radius)
Sets ambient occlusion intensity and optionally the radius.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
intensity | number | Intensity; enabled when above 0.001. |
radius | number | Sampling radius. Optional. |
Returns: none
Example
caffeine.postprocess.setAmbientOcclusion(cam, 1.0, 0.5)
setAntiAliasing#
Lua: caffeine.postprocess.setAntiAliasing
setAntiAliasing(entity, mode)
Selects the anti-aliasing mode; "off" and "none" disable it.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
mode | string | "fxaa", "off" or "none"; any other value selects the non-FXAA mode. |
Returns: none
Example
caffeine.postprocess.setAntiAliasing(cam, 'fxaa')
setAutoExposure#
Lua: caffeine.postprocess.setAutoExposure
setAutoExposure(entity, enabled, compensation)
Toggles auto exposure and optionally sets its compensation.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
enabled | boolean | Turns auto exposure on or off. |
compensation | number | Exposure compensation. Optional. |
Returns: none
Example
caffeine.postprocess.setAutoExposure(cam, true, 0.5)
setCustomScript#
Lua: caffeine.postprocess.setCustomScript
setCustomScript(entity, path)
Sets the custom effect script of the entity.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
path | string | Path of the custom effect script. |
Returns: none
Example
caffeine.postprocess.setCustomScript(cam, 'scripts/fx.lua')
handle#
Lua: caffeine.postprocess.handle
handle(entity) -> table
Returns a per-entity handle, the same kind passed to onPostProcess, so calls need no entity id.
| Parameters | Type | Description |
|---|---|---|
entity | number | Entity id. |
Returns: table. Table with entity, get, set, enable, isEnabled, snapshot, apply and preset, all bound to the entity.
Example
local h = caffeine.postprocess.handle(cam)
h.set('bloom.intensity', 0.5)