Skip to content

Effects

An effect is a JSON definition at data/<namespace>/vfx/<name>.json; its id is <namespace>:<name> and /reload loads it. Play one with /vfx play <id> (or /vfx playentity for entity effects). The full definition schema is on the Datapack format page; every effect below has its own page with its complete field list and a copy-pasteable example.

How to read an effect page

  • Every param is a float. Most "intensity-like" params are 0..1, where 0 = off.
  • Many built-ins animate their main param from the listed value down to 0 over the duration, so the effect fades out on its own. Override the param (command param-map / API) and it becomes a constant unless you animate it yourself (start/end, keyframes, expr).
  • A live keyframe with a negative time starts its segment at the current moment, pinning the value the param has right now - see Animating a param.
  • screen_layer (screen effects only): 0 = under the first-person hand and GUI, 1 = above the hand below the GUI (default), 2 = above everything.
  • order (screen effects only): the compositing order within one screen_layer. Lower runs earlier, default 0, and effects that do not set it keep the order they were started in. It is a float, so 10.5 slots an effect between two that sit at 10 and 11 without renumbering. It is an ordinary param - set it from the datapack, the command param-map, setParam or a keyframe like any other value; changing it live re-sorts from the next frame, which can pop if you animate it.

Shared fields

Every effect accepts fields that are not repeated in its own Fields table. A reader must check these too:

Definition fields (any effect). type (required), duration, easing, loop, persistent, fade_ticks, params, sound, sound_pos, volume, pitch — the complete list, types and defaults is on Datapack format. These control how long the effect runs, whether it loops or persists until stopped, how it fades, and its optional sound.

Screen effects additionally accept screen_layer (0/1/2, above) and order (the compositing order inside one layer, above). See Datapack format.

World overlays (block_tint, block_outline, light_beam, pulse_ring, guide_line, particles, block_chain) additionally accept:

  • positions — an array of [x, y, z] entries or entity anchors ({"entity": ..., "point": ..., "offset": ..., "dir": ..., "distance": ...}), documented on Datapack format.
  • region — a box [x0,y0,z0,x1,y1,z1] that expands to every block in it, an alternative to listing positions.
  • pos_x / pos_y / pos_z — params used as a single world position when neither positions nor region is present; they can be constant, animated or bound.

Entity effects (entity_tint, entity_outline, entity_displace) are targeted by /vfx playentity <effect> <selector> (up to 16 UUIDs) or by the entity_selector definition field, which lets a plain /vfx play find its own targets. See Datapack format.

Collections additionally accept effects (the child list) — see collection.

Effect groups

Screen post-processing

Fullscreen shader passes, one per effect. They accept screen_layer.

Adjacent pointwise screen effects - color_grade, screen_flash, vignette, invert, posterize, scanlines and film_grain - are fused with each masked effect's coverage consumer into one shader pass, so a run reads and writes the frame once instead of once per effect. Output is unchanged: every fused stage boundary is re-quantised to the RGBA8 the unfused chain wrote. blur-class effects (anything that samples neighbours, including bloom, vhs and motion_blur), afterimage/stop_motion and every unannotated effect cut the chain and render exactly as before. Fusion is on by default; disable it with -Dvfxweaver.fusion=false. The one-tap remaps (distortion, vortex, pixelate, noise_warp, slice_shift) are fused as well; disable them with -Dvfxweaver.fusion.remap=false.

Separately, a run of the heavy multi-tap passes - blur (both its passes), bloom, depth_of_field, vhs and digital_glitch - can render at half resolution: the run is wrapped in an exact downsample and upsample, and its passes run on a quarter of the pixels. A run only qualifies when it is heavy enough (the passes' taps must sum to at least 8, so vhs and digital_glitch - four taps each - join a scaled run only beside another scalable pass). Nothing else about the chain changes: pointwise and fused stages, mask consumers and mask coverage, the pre-effect image, the afterimage/stop_motion pair and every other effect render exactly as before. It is on by default; disable it with -Dvfxweaver.chainres=1.0 (-Dvfxweaver.chainres=0.5 is the default). Only those two values are accepted - anything else warns once and is treated as 0.5. The result inside a scaled pass is slightly softer, which is the point.

World overlays

World-space geometry drawn at positions (or entity anchors).

Entity effects

Targets are set by /vfx playentity <effect> <selector>, the Java API, or the entity_selector definition field. The client redraws the entity in a second pass over the original.

Audio

Generated sound, no post pass and no geometry. hum/noise/heartbeat accept positions/region (or entity anchors) for the voice position, like a world overlay; volume_duck is global and ignores them.

Camera and misc

Camera-space effects act on the camera transform; they do not accept screen_layer.

Collections

  • collection - play several child effects with per-child delays

Built-in effects

Built-ins ship as regular datapack JSON inside the mod jar (data/vfxweaver/vfx/*.json); they load and sync like custom definitions and can be overridden by a higher-priority pack. To tweak one, copy its JSON out of the jar into your own datapack under a new id.

  • Post-processing: chromatic_aberration, color_grade, distortion, dent, gradient_map, posterize, blur, pixelate, hue_isolation, vignette, screen_flash, motion_blur, bloom, film_grain, scanlines, halftone, ink, comic, accent_glow, depth_of_field, letterbox, invert, vortex, speed_lines, slice_shift, noise_warp, solarize, double_vision, eyelids, iris_wipe, digital_glitch, vhs, datamosh, torn_edge, spectral, hex_grid, shockwave, afterimage, stop_motion, surface_pattern, graph_demo, graph_logic_demo, dent_field_demo, tint_field_demo.
  • World overlays: block_tint, block_outline, light_beam, pulse_ring, guide_line, particles, block_chain.
  • Entity effects: entity_tint, entity_outline, entity_displace.
  • Audio: hum, noise, heartbeat, volume_duck.
  • Camera: camera_shake, camera_roll, fov_modifier, fog_modifier.

Built-in ids need their namespace (vfxweaver:<name>); there is no minecraft: fallback.

See also