shift_along_ramp
Move pixels along a colour ramp to darken or lighten pixel art while keeping every colour on the existing palette. Negative steps shade; positive steps lighten; region and tolerance limit edits.
Instructions
Move pixels along a colour ramp, keeping every one of them on the palette.
This is the operation to use for "put this in shadow", "make the night variant" or
"deepen the shadow side". Each pixel is matched to its nearest ramp entry, moved
`steps` along the ramp, and clamped at the ends, so the result uses only colours
that were already on the ramp.
Prefer this over `adjust_brightness_contrast` for anything that should still look
like pixel art: that tool does colour arithmetic and lands almost every pixel
between palette entries.
Args:
ramp: The ramp, darkest first, as produced by `generate_ramp`. Order matters:
negative `steps` moves toward the front of this list.
steps: How far to move. Negative darkens (toward the front of `ramp`), positive
lightens. Pixels already at an end stay there rather than wrapping.
x, y, width, height: Restrict the change to a region. Defaults to the whole
canvas. Scope this when a sprite has several materials: one ramp applied to
everything flattens steel, brass and leather into the same colours.
tolerance: How far a pixel may be from a ramp entry and still be treated as
belonging to it, as a weighted RGB distance. Pixels further away than this
are left alone and counted in `pixels_skipped`, so shading one material does
not disturb its neighbours.
layer: Target layer (default: top layer).
frame: Target frame, 1-based.
Returns `pixels_written` and `pixels_skipped`. A high skip count usually means the
ramp does not match the artwork, not that the sprite was already correct.
`pixels_matched` counts the pixels that both matched the ramp and were written, so it
agrees with `pixels_written` rather than counting matches an active selection then
refused.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | Default: 0. | |
| y | No | Default: 0. | |
| ramp | Yes | ||
| frame | No | Default: 1. | |
| layer | No | ||
| steps | Yes | ||
| width | No | ||
| height | No | ||
| filename | Yes | ||
| tolerance | No | Default: 48.0. |