Surface Light Preview

surface_light_preview

Renders a quick lighting preview from Surface height, normal, AO, roughness, and emission maps.

Reviewed

Guide available

The node name and summary are available in English. Port, parameter, and article details are currently shown in Japanese.

Input Ports

Name	Type	Description
サーフェース surface	Surface Required	光を当てて確認したいサーフェースです。
パレット palette	Palette	影段階やハイライト段階を指定色へ丸めるためのパレットです。

Output Ports

Name	Type	Description
画像 output	Image	光を当てた確認用画像です。

Parameters

Name	Type	Default	Range	Description / Options
光の向き angle	Angle	315	— / step 1	光がどの方向から来るかです。315度は左上からの光です。
光の高さ elevation	Angle	45	— / step 1	光源の縦方向の軌道角です。0は光の向き側の水平、90は真上、180は反対側の水平、270は下/裏側から照らします。
最低の明るさ ambient	Float	0.35	0–1 / step 0.01	光が当たりにくい面にも残す最低限の明るさです。
光の強さ intensity	Float	0.85	0–2 / step 0.01	直接当たる光の強さです。
高さの効き height_strength	Float	2	0–12 / step 0.1	高さマップから作る影やハイライトの強さです。
くぼみの暗さ shadow_strength	Float	0.6	0–1 / step 0.01	AOマップでくぼみや隙間をどれだけ暗くするかです。
落ち影の濃さ cast_shadow_strength	Float	0.45	0–1 / step 0.01	高い部分が低い部分へ落とす影の濃さです。0にすると落ち影は出ません。
落ち影の長さ cast_shadow_length	Float	16	0–128 / step 1	正の光の高さで落ち影がどこまで伸びるかです。正の低い高さほど、同じ長さでも影が長く見えます。
落ち影の精度 cast_shadow_steps	Int	16	1–128	影を落とす高さを何回調べるかです。大きいほど細かくなりますが重くなります。
ライティング設定 lighting_definition_mode	Enum	Custom	—	影色やハイライト色のルールを、このノードで直接持つか、保存済みの定義から呼び出すかです。このノードで設定`Custom` このノードに表示されている値を使います。定義を使う`Definition` 保存したサーフェースライティング定義を使います。定義を編集すると、それを参照するノードにも反映されます。
ライティング定義ID lighting_definition_id	Text	core:pixel_basic	—	このプレビューで使う保存済みサーフェースライティング定義です。
影色の作り方 tone_grade_mode	Enum	Off	—	影やハイライトを、暗く明るくするだけにするか、色味もずらすかです。明暗だけ`Off` ライト計算でできた明暗だけを使います。 OKLCH差分`OKLCH` 影やハイライトを、明るさ・鮮やかさ・色相の差分で色づけします。
影色の段階 tone_grade_steps_mode	Enum	Smooth	—	OKLCH差分のかかり方を、なめらかにするか段階でそろえるかです。なめらか`Smooth` 光や影の強さに合わせて、色をなめらかに変えます。段階化`Steps` 色の変化を少ない段階に丸めます。ドット絵の影色をそろえたい時に使います。
影色の強さ tone_grade_strength	Float	1	0–1 / step 0.01	影色・ハイライト色のずらし方をまとめて弱めます。0で色味の変化なし、1で指定どおりです。
影の段数 shadow_grade_steps	Int	2	1–16	段階化するときの影色の段数です。2なら影1・影2のように分かれます。
ハイライトの段数 highlight_grade_steps	Int	2	1–16	段階化するときのハイライト色の段数です。2なら弱いハイライト・強いハイライトに分かれます。
影色の詳細 shadow_tone_detail_mode	Enum	Shared	—	普通の影を1つの色ルールでまとめるか、影の段数に合わせて分けるかです。まとめて補正`Shared` 影の強さに関係なく、1つの影色ルールでまとめて補正します。影段階ごと`PerStage` 影の段数に合わせて、段階ごとの色ルールを使います。
影のOKLCH補正 shadow_oklch_adjust	OklchAdjust	[-12,0,8,0]	—	影になった場所の色の変え方です。明るさを下げたり、鮮やかさや色味を少しずらしたりできます。
落ち影の色 cast_shadow_tone_mode	Enum	SameAsShadow	—	落ち影の色を、普通の影と同じにするか、落ち影だけ別に調整するかです。影と同じ`SameAsShadow` 落ち影も普通の影と同じ色ルールで描きます。別に補正`Separate` 落ち影だけ別の色ルールで描きます。接地影や段差の影を少し濃くしたい時に使います。
落ち影の段数 cast_shadow_grade_steps	Int	2	1–16	落ち影を何段階の色に分けるかです。
落ち影のOKLCH補正 cast_shadow_oklch_adjust	OklchAdjust	[-18,-0.01,10,0]	—	落ち影だけに使う色の変え方です。接地影や物の後ろに落ちる影を、普通の影より少し濃くしたい時に使います。
ハイライトのOKLCH補正 highlight_oklch_adjust	OklchAdjust	[8,0,-4,0]	—	ハイライトになった場所の色の変え方です。明るくしたり、光が当たる色味へ少しずらしたりできます。
パレット段階化 palette_stage_mode	Enum	Off	—	ライト計算後にパレット色へどう丸めるかです。使わない`Off` ライト計算後の色をそのまま使います。近い色へ丸める`Nearest` ライト計算後の色を、接続したパレットの一番近い色へ丸めます。影/ハイライト段階`StageIndices` 影1・影2・ハイライト1・ハイライト2を、指定したパレット番号の色で塗ります。
パレット丸めの強さ palette_snap_strength	Float	1	0–1 / step 0.01	選ばれたパレット色へどれだけ寄せるかです。1で完全にパレット色になります。
影1の色番号 shadow_stage_1_index	Int	1	0–255	少し暗い影に使うパレット番号です。
影2の色番号 shadow_stage_2_index	Int	2	0–255	より暗い影に使うパレット番号です。
ハイライト1の色番号 highlight_stage_1_index	Int	3	0–255	少し明るいハイライトに使うパレット番号です。
ハイライト2の色番号 highlight_stage_2_index	Int	4	0–255	より強いハイライトに使うパレット番号です。
影1のしきい値 shadow_stage_1_threshold	Float	0.18	0–1 / step 0.01	どのくらい暗くなったら影1にするかです。
影2のしきい値 shadow_stage_2_threshold	Float	0.45	0–1 / step 0.01	どのくらい暗くなったら影2にするかです。
ハイライト1のしきい値 highlight_stage_1_threshold	Float	0.75	0–2 / step 0.01	どのくらい明るくなったらハイライト1にするかです。
ハイライト2のしきい値 highlight_stage_2_threshold	Float	1.05	0–2 / step 0.01	どのくらい強く光が当たったらハイライト2にするかです。
透明度を保つ palette_preserve_alpha	Bool	true	—	パレット色で塗り替えても、元の透明度をそのまま残します。
発光の強さ emission_strength	Float	1	0–4 / step 0.05	発光マップをどれだけ明るく足すかです。
光の色 light_color	Color	[1,0.9599999785423279,0.8799999952316284,1]	—	当てる光の色です。

Overview

The main lighting node in the 3D → pixel-art lane, lighting a Surface, the pixel-art G-buffer containing height, normals, AO, and other maps, into an image. Despite "Preview" in its name, it is not inspection-only: it can produce a finished image with stepped shadows, OKLCH color rules, and palette snapping.

If a normal map exists, the node uses it. Otherwise it derives approximate face directions from the height map. If an emission map exists, its color is added even in dark areas.

Usage tips

Start with only four controls: angle, where 315 = upper-left is the go-to direction; elevation; intensity; and ambient. Establish the basic light and dark first.
Basic pixel-art finishing path:
1. Set tone_grade_mode = OKLCH to apply color rules to shadows and highlights.
2. Set tone_grade_steps_mode = Steps for discrete stages; two shadow steps are standard.
3. Connect the project palette to palette and snap through palette_stage_mode.
When several assets share the same lighting rules, save and reference a lighting definition with lighting_definition_mode = Definition instead of configuring every node. Definitions live in user_data/definitions/lighting/ and can be shared between assets.
Cast shadows through cast_shadow_* determine contact. Lower elevation for longer shadows.

Common pitfalls

The result is flat: height_strength is too low. Raise it to about 2–6 relative to the Surface height range and inspect the result.
No cast shadow appears: cast_shadow_strength = 0, or the light is below the surface with elevation from 180–360. Height-map cast shadows are enabled only for upper lights from 0–180.
Palette stepping produces unexpected colors: StageIndices uses palette indices. Check the connected palette order against shadow_stage_*_index.
There are too many parameters: detailed controls remain hidden while tone_grade_mode = Off. Build basic lighting first, then move to OKLCH when needed.

Examples

Add a height map to Image to Surface, then change angle and confirm the shadow direction.
Add a lamp emission_map and adjust the glow with emission_strength.
Raise height_strength and inspect how strongly brick mortar falls into shadow.
On a brick or block Surface, raise cast_shadow_strength, lower elevation, and check that shadows extend from height changes.
With tone_grade_mode = OKLCH, add slightly to H in shadow_oklch_adjust and subtract slightly from H in highlight_oklch_adjust to apply consistent color rules to every shadow and highlight.
With tone_grade_steps_mode = Steps and shadow_grade_steps = 2, shadows become a small set of stages—shadow 1 and shadow 2—instead of a smooth gradient.
With shadow_tone_detail_mode = PerStage and shadow_grade_steps = 4, definition management shows correction fields for shadow 1 through shadow 4. Arrange them from light correction for weak shadows to deeper darkness for strong shadows.
With cast_shadow_tone_mode = Separate and cast_shadow_grade_steps = 3, cast shadows receive their own corrections from cast shadow 1 through cast shadow 3. Use this when contact shadows or block steps should be darker than ordinary shading.
Connect the project palette to palette, set palette_stage_mode = StageIndices, and lock shadow 1, shadow 2, highlight 1, and highlight 2 to palette indices.

Light direction and elevation

angle specifies the direction the light comes from in the image plane. It is an Angle parameter controlled with a cyclic knob in the inspector. 315 degrees means light from the upper left.

elevation is the vertical orbital angle representing light height. As an Angle parameter, it also uses a cyclic knob. 0 is the horizon on the light-direction side, 90 is directly overhead, 180 is the opposite horizon, and 270 lights from below or behind. With 光の向き fixed, moving elevation from 0→180 makes the sun rise, pass overhead, and set on the other side. Height-map cast shadows work with upper lights from 0〜180. For lower lights from 180〜360, height-map cast shadows are disabled to avoid unnatural projection.

shadow_strength darkens recesses using the AO map. cast_shadow_strength controls the actual shadow that higher height-map pixels cast onto lower pixels.

OKLCH adjustments

With tone_grade_mode = OKLCH, the node reads the amounts of shadow and highlight from the lighting calculation and shifts color in OKLCH.

With tone_grade_mode = Off, detailed OKLCH-adjustment parameters are hidden in the inspector. Values remain stored, so switching back to OKLCH restores the previous settings.

For example, shadow_oklch_adjust at L=-12, C=0, H=8 makes shadows slightly darker and rotates their hue. Applying one shadow-color rule everywhere makes a consistent look easier than matching shadow colors by hand on each node.

tone_grade_steps_mode = Steps rounds correction strength into a small number of stages. At shadow_grade_steps = 2, it divides into no shadow, shadow 1, and shadow 2. Use this to try pixel-art stepped shading through OKLCH alone before snapping fully to a palette.

With shadow_tone_detail_mode = PerStage, each shadow strength uses a separate correction. shadow_grade_steps = 1 uses only shadow 1; 4 uses shadow 1 through shadow 4. Definition management adds or removes fields to match the count. For fixed shadow rules, keep weak stages light and make stronger stages progressively darker.

Processing order is lighting, OKLCH adjustment, then palette stepping. You can therefore organize hue in OKLCH, then finish with palette_stage_mode = Nearest to snap to nearby project-palette colors.

By default, cast shadows use the same shadow_oklch_adjust as ordinary shadows to avoid unnecessarily increasing pixel-art colors and shadow rules. Switch to cast_shadow_tone_mode = Separate only when steps or contact need stronger depth. With Smooth, adjust all cast shadows through cast_shadow_oklch_adjust; with Steps, set corrections for cast shadow 1, cast shadow 2, and so on according to cast_shadow_grade_steps.

When tone_grade_steps_mode = Steps, highlight correction fields also follow highlight_grade_steps. Two stages provide weak and strong highlights; four stages can standardize finer light response in a palette-like way.

Palette stepping

StageIndices replaces shadow and highlight stages with palette indices instead of using the colors produced directly by the lighting calculation.

For example, define palette entry 1 as shadow 1, entry 2 as shadow 2, entry 3 as highlight 1, and entry 4 as highlight 2. The user palette, rather than the lighting calculation, then controls shading colors. With palette_snap_strength = 1, every final color belongs to the connected palette.

Lighting definitions use the same concept. Instead of changing colors on every node, first define how shadow and highlight stages map to palette indices across the work, then override individual nodes only when needed.

Likewise, lighting definitions can manage OKLCH shadow stages. Define project-wide rules for shadow 1, shadow 2, shadow 3, cast shadow 1, cast shadow 2, highlight 1, highlight 2, and so on, then override only exceptional nodes.

Related nodes

solid_render / model_render / image_to_surface — supply the input Surface
quick_shade — beginner version of this system contained in one node
surface_export — export the unlit Surface as engine textures
surface_edge_highlight — emphasize edge light separately

Back to Node List