Region rendering

Region effects have their own mesh. Three options control it: placement (where the stack draws), backdrop (whether filters process the map under the Region or a flat shape) and rotate (whether the effect turns with an attached token). Leave the Region's Visibility at its usual layer-only setting: the effect stays visible during play while the editor highlight disappears. Locking, selection and sidebar filters do not hide the effect. Hidden turns it off for everyone, including GMs. Only Regions included in the viewed Level render.

Placement

Placement applies to the Region's complete filter stack. Pass it separately from the filter specs.

`placement`	Where the stack draws
`"interface"`	Default. The existing interface overlay above scene content, outside primary scene lighting and fog composition.
`"ground"`	Below tiles, drawings and tokens at the same elevation.
`"aboveTiles"`	Above tiles and drawings, below tokens at the same elevation.
`"aboveTokens"`	Above tiles, drawings and tokens at the same elevation.

The three scene placements share RegionFX and ambientFX's sort layers (100, 650 and 800). Neither module is required. These placements participate in primary scene lighting and fog composition; they can look different from "interface".

Elevation sorts first. A higher-elevation tile can cover an "aboveTokens" effect. The effect uses the Region's animated bottom elevation when finite. Without a finite bottom, it uses the lowest finite floor of its assigned Levels (all scene Levels if none are assigned), falling back to the primary background's elevation, then Foundry's background default. Placement does not change Level membership.

Stacks at the same elevation and placement use a stable Region-ID order, independent of selection and redraw. There is no separate Draw Order option. They sort at 0 within their primary sort layer, alongside ambientFX particles and before RegionFX effects with their default positive effect order; no finer order relative to other modules is promised.

Backdrop: effects on the map

By default a Region's filters work on a flat white copy of the Region's shape. That suits effects which paint their own colours (flood, fog, fire, smoke). Effects that only change what is already there (Old Film, Adjustment, Pixelate, CRT, Twist and other distortions) then just tint a white area.

With backdrop: true, leanFX copies what is already drawn under the Region right before the stack draws and fills the Region's shape with it. The filters then age, grade or distort the map itself:

await leanFX.addUpdateFiltersOnSelected([{
  filterType: "oldfilm", filterId: "oldfilm",
  sepia: 0.6, noise: 0.2, scratch: 0.8, scratchDensity: 0.5, scratchWidth: 1.2,
  vignetting: 0.3, vignettingAlpha: 0.2, vignettingBlur: 0.2,
  animated: {
    seed: {animType: "randomNumber", val1: 0, val2: 1},
    vignetting: {animType: "syncCosOscillation", loopDuration: 2000, val1: 0.2, val2: 0.4}
  }
}], {placement: "aboveTiles", backdrop: true});

What the copy contains follows the placement: with "ground" the map, with "aboveTiles" also tiles and drawings at or below the Region's elevation (tokens on it draw over the effect), with "aboveTokens" those tokens too. Scenery at a higher elevation stays on top. Scene lighting and fog apply afterwards, as they do to the map. Other Region effects drawn before the stack (RegionFX or another leanFX Region with a lower placement) are part of the copy. Holes stay untouched. Filters that pull pixels from beyond the shape's edge (twist, shockwave, blurs) see transparency there, so the plain map shows through at the edge.

The backdrop needs a scene placement: backdrop: true together with "interface" is rejected, whether you pass both or one is already saved. To return to the interface overlay, pass {placement: "interface", backdrop: false}.

Moving and token-attached Regions

The effect follows a Region wherever it is drawn: when you drag it, change its shape, or when it is attached to a token that moves. While the token animates, core moves the Region's shape with it and leanFX copies what is under the shape on every frame, so the backdrop stays in place without restarting filters or animations.

Rotate: effects that turn with their token

Filters always run in screen orientation, so on their own Old Film's scratches, a shadow's direction or a ray pattern stay fixed while an attached token turns. With rotate: true, the effect's pattern turns with the token's rotation (also during core's auto-rotate while moving); with false (the default) it keeps its map orientation while the Region's shape turns.

const region = canvas.regions.controlled[0];
await leanFX.setRegionRendering(region, {rotate: true});

The map under a backdrop stays where it is either way; only the effect's pattern turns. The reference is rotation 0, the same on every client and after a reload. Token emanations (the circle around a token) don't turn their shape, but their pattern does. rotate has no effect on Regions that aren't attached to a token. A turned stack costs one extra texture and draw, and its edges are slightly softer because the image is resampled once more.

Save filters and placement together

Select a Region on the Regions layer, then run:

const region = canvas.regions.controlled[0];
await leanFX.addUpdateFilters(region, [{
  filterType: "flood", filterId: "water",
  color: 0x0020bb, billowy: 0.43, tintIntensity: 0.72,
  glint: 0.31, scale: 70,
  animated: {time: {animType: "move", speed: 0.0006}}
}], {placement: "aboveTiles"});

addFilters, addUpdateFilters and updateFilters accept this optional third argument, {placement, backdrop, rotate}. Their selection helpers accept it as the second argument. Options are Region-only: other target types reject them, even {}. Unknown keys, placement values and non-boolean backdrop/rotate reject before saving. A combined operation saves filters and rendering atomically; if either is invalid, neither changes.

Given options merge into the saved ones; omitted options keep their saved value. Regions without saved settings use {placement: "interface", backdrop: false, rotate: false}, so existing macros and effects keep their rendering behavior. getFilters() and filter-operation return values remain arrays of specs.

Change only rendering

const region = canvas.regions.controlled[0];
await leanFX.setRegionRendering(region, {placement: "ground"});
console.log(leanFX.getRegionRendering(region)); // {placement: "ground", backdrop: false, rotate: false}

setRegionRendering uses the same GM, permissions and document queue as filter changes. It returns saved, resolved options and works before any filters are added. Changing only rendering keeps the existing mesh, filter instances, textures and animation timelines.

Deleting filters or automatic one-shot expiry preserves rendering settings. Reset explicitly with {placement: "interface", backdrop: false, rotate: false}. Clear-all still repairs unreadable effect envelopes; repairing an envelope discards its unreadable rendering settings too. Any explicit option through setRegionRendering can repair malformed rendering metadata (starting again from the defaults) without deleting filters.

Local preview

const region = canvas.regions.controlled[0];
const preview = leanFX.preview(region, [{
  filterType: "flood", filterId: "try-water", color: 0x0020bb
}], {placement: "aboveTiles"});
// ... inspect the result ...
preview.clear();

Preview options save nothing and affect only your client. Options you pass override the saved ones until the preview ends; an impossible combination with the saved ones (a backdrop on the interface) throws at once. With options omitted (or {}), the preview follows current saved settings. Clearing or expiring the preview restores the latest saved stack and settings, including changes made while previewing.

inspect(region).regionRendering reports {placement, backdrop, rotate, elevation, visible, backdropCaptured, turned} for the current mesh, or null without one. backdropCaptured says whether the last frame copied a backdrop (null without backdrop or before the first frame); turned is the token rotation in degrees the last frame turned the pattern by. Interface placement reports elevation 0 as a placeholder; it does not sort with scene elevations. getRegionRendering() reports saved options, excluding previews. regionPlacements lists the four accepted values.

Placement and filter order

zOrder orders filter processing inside the stack. It does not move effects above or below tokens. Use separate Regions when you need different placements.

Placement changes where the overlay draws; backdrop decides what the filters process. Without it, Adjustment on a Region changes its white overlay rather than grading the map under it. "ground" does not add RegionFX's special clipping to opaque map pixels; Region geometry remains the source, with filters' usual padding and spill.

Primary placement controls draw order, not wall occlusion, token detection, roof cutouts or a depth-masked material. Check those scene-specific interactions in the intended world.

Home