feat: triplanar projected materials

[Dlizzio]

single planar projection (vanilla):

triplanar projection:

Summary by CodeRabbit

• New Features
  • Triplanar texture mapping with stochastic sampling and gradient-guided mip-bias for improved detail and sharper blends.
• Improvements
  • Reduced projection stretching and seams across complex geometry.
  • More consistent albedo, normal detail, and per-pixel lighting for cleaner, more stable shaded surfaces.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new Triplanar shader utility (package/Shaders/Common/Triplanar.hlsli) exposing weight computation, projection sampling, stochastic sampling, gradient/mip-bias helpers, and integrates these APIs into package/Shaders/Lighting.hlsl to replace projected-UV texture lookups with world-space triplanar sampling.

Changes

Cohort / File(s)	Summary
Triplanar Shader Utility package/Shaders/Common/Triplanar.hlsli	New header (TRIPLANAR_HLSLI) defining Triplanar::GetWeights, Triplanar::Sample, Triplanar::ComputeGradients, Triplanar::SampleStochastic, and Triplanar::SampleStochasticBias for world-space triplanar projections, stochastic selection, and gradient/mip-bias handling.
Lighting Integration package/Shaders/Lighting.hlsl	Adds include "Common/Triplanar.hlsli"; computes tri face/geo normals and triWeights; replaces projected-UV sampling paths (noise, baseColor, normals, detail) with Triplanar::Sample / SampleStochastic / SampleStochasticBias calls using projWorldPos and triWeights.

Sequence Diagram(s)

sequenceDiagram
  participant VS as Vertex/Input
  participant Lighting as Lighting.hlsl
  participant Triplanar as Triplanar.hlsli
  participant Tex as Texture Samplers
  VS->>Lighting: provide WorldPosition, Normal, UVs
  Lighting->>Triplanar: Triplanar::GetWeights(vertexNormal, faceNormal, sharpness)
  Lighting->>Triplanar: Triplanar::ComputeGradients(worldPos, scale)
  Lighting->>Triplanar: Triplanar::SampleStochastic/ SampleStochasticBias(tex, samp, worldPos, weights, scale, [bias], noise)
  Triplanar->>Tex: sample projections (YZ, XZ, XY) using gradients / bias
  Tex-->>Triplanar: sampled texels
  Triplanar-->>Lighting: blended triplanar result
  Lighting->>Lighting: integrate into proj noise, baseColor, normals, detail

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• fix(snow): use world space vectors #1618: Edits projection coordinate handling in Lighting.hlsl (world-space projection conversion), overlapping projection logic changes.
• fix: fix bright character lighting #1448: Modifies character projection noise usage in Lighting.hlsl; related to replacing direct noise sampling with triplanar sampling.

Suggested reviewers

• jiayev
• alandtse
• doodlum

Poem

🐰 I hop through worldspace on three-fold ground,
I blend every axis so seams aren't found,
With weights and noise, and gradients I steer,
I bias and sample — textures appear clear,
Happy hops, triplanar cheer! 🎨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: triplanar projected materials' directly describes the main change: adding triplanar shading functionality to projected materials via a new Triplanar.hlsli header and integration into Lighting.hlsl.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

No actionable suggestions for changed features.

[github-actions]

✅ A pre-release build is available for this PR:
Download

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (1)

package/Shaders/Lighting.hlsl (1)

1981-1985: ⚠️ Potential issue | 🟠 Major

Hard axis selection still causes seams and pays full triplanar cost.

Line 1983 uses a per-face normal, and Line 1984 reduces it to a one-hot axis. That will still snap adjacent triangles between projections on curved meshes, and every Triplanar::Sample* in this block still fetches all three planes and just zeros two of them out. Either restore blended weights, or switch this path to a dominant-axis sampler that fetches only the selected plane.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@package/Shaders/Lighting.hlsl` around lines 1981 - 1985, The current code
computes triGeoNormal and then reduces to a one-hot axis which still causes
seams and keeps full triplanar sampling cost because Triplanar::Sample fetches
all three planes; fix by either (A) restoring smooth blended weights from
Triplanar::GetWeights(triGeoNormal) and pass those blended triWeights into
Triplanar::Sample so adjacent triangles interpolate smoothly, or (B) implement
and call a dominant-axis sampler (e.g., Triplanar::SampleDominant or
Triplanar::SamplePlane) from this path that takes the selected axis (derived
from triGeoNormal) and only samples that one plane to avoid the cost of fetching
all three; update the call site currently using ProjNoise =
Triplanar::Sample(...) to use the blended triWeights or the new dominant sampler
accordingly.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@package/Shaders/Lighting.hlsl`:
- Around line 2008-2012: The projected normal/detail sampling must be reoriented
per-axis before blending: replace the raw Triplanar::Sample calls used for
normals in the block (where diffuseNormalScale, projNormal, detailNormalScale,
projDetailNormal, finalProjNormal are computed) with a dedicated
triplanar-normal helper that performs per-axis swizzle and sign correction
(e.g., a new Triplanar::SampleNormal or ReorientProjectedNormal routine in
package/Shaders/Common/Triplanar.hlsli); call that helper for
TexProjNormalSampler/SampProjNormalSampler and
TexProjDetail/SampProjDetailSampler (using projWorldPos, triWeights and
respective scales), then TransformNormal the reoriented results and blend them
exactly as before to produce finalProjNormal. Ensure the helper handles
tangent-space axis rotation/sign for X/Y/Z projections so lighting on side faces
isn’t flipped.

---

Duplicate comments:
In `@package/Shaders/Lighting.hlsl`:
- Around line 1981-1985: The current code computes triGeoNormal and then reduces
to a one-hot axis which still causes seams and keeps full triplanar sampling
cost because Triplanar::Sample fetches all three planes; fix by either (A)
restoring smooth blended weights from Triplanar::GetWeights(triGeoNormal) and
pass those blended triWeights into Triplanar::Sample so adjacent triangles
interpolate smoothly, or (B) implement and call a dominant-axis sampler (e.g.,
Triplanar::SampleDominant or Triplanar::SamplePlane) from this path that takes
the selected axis (derived from triGeoNormal) and only samples that one plane to
avoid the cost of fetching all three; update the call site currently using
ProjNoise = Triplanar::Sample(...) to use the blended triWeights or the new
dominant sampler accordingly.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 327c2166-ee1a-457e-b7ca-a4e1db634de5

📥 Commits

Reviewing files that changed from the base of the PR and between 2c91bad and efa454e.

📒 Files selected for processing (2)

• package/Shaders/Common/Triplanar.hlsli
• package/Shaders/Lighting.hlsl

🚧 Files skipped from review as they are similar to previous changes (1)

• package/Shaders/Common/Triplanar.hlsli

[coderabbitai]

🧹 Nitpick comments (1)

package/Shaders/Common/Triplanar.hlsli (1)

32-59: Consider extracting duplicate branching logic between SampleStochastic and SampleStochasticBias.

Both functions share the same branching structure for plane selection. If maintenance becomes a concern, you could factor out the common logic. However, given the simplicity and the performance-critical nature of shaders, keeping them separate is also reasonable.

♻️ Optional: Factor out common plane selection

+	// Internal helper for stochastic plane selection
+	float4 SampleGradInternal(Texture2D<float4> tex, SamplerState samp, float3 worldPos, float3 weights, float scale, float3 dPdx, float3 dPdy, float noise)
+	{
+		if (noise < weights.x)
+			return tex.SampleGrad(samp, worldPos.yz * scale, dPdx.yz, dPdy.yz);
+		if (noise < weights.x + weights.y)
+			return tex.SampleGrad(samp, worldPos.xz * scale, dPdx.xz, dPdy.xz);
+		return tex.SampleGrad(samp, worldPos.xy * scale, dPdx.xy, dPdy.xy);
+	}

 	float4 SampleStochastic(Texture2D<float4> tex, SamplerState samp, float3 worldPos, float3 weights, float scale, float noise)
 	{
 		float3 dPdx, dPdy;
 		ComputeGradients(worldPos, scale, dPdx, dPdy);
-
-		if (noise < weights.x)
-			return tex.SampleGrad(samp, worldPos.yz * scale, dPdx.yz, dPdy.yz);
-		if (noise < weights.x + weights.y)
-			return tex.SampleGrad(samp, worldPos.xz * scale, dPdx.xz, dPdy.xz);
-		return tex.SampleGrad(samp, worldPos.xy * scale, dPdx.xy, dPdy.xy);
+		return SampleGradInternal(tex, samp, worldPos, weights, scale, dPdx, dPdy, noise);
 	}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@package/Shaders/Common/Triplanar.hlsli` around lines 32 - 59, Both
SampleStochastic and SampleStochasticBias duplicate the same plane-selection
branching after ComputeGradients; extract that common logic into a small inline
helper (e.g., SampleTriplanarPlanes or SelectAndSamplePlane) that takes the
texture, sampler, scaled UVs or worldPos, the per-axis gradient components
(dPdx, dPdy) and weights, then returns the appropriate tex.SampleGrad result;
call ComputeGradients only in the callers
(SampleStochastic/SampleStochasticBias) and pass the possibly bias-scaled
dPdx/dPdy into the helper to remove duplication while preserving performance.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@package/Shaders/Common/Triplanar.hlsli`:
- Around line 32-59: Both SampleStochastic and SampleStochasticBias duplicate
the same plane-selection branching after ComputeGradients; extract that common
logic into a small inline helper (e.g., SampleTriplanarPlanes or
SelectAndSamplePlane) that takes the texture, sampler, scaled UVs or worldPos,
the per-axis gradient components (dPdx, dPdy) and weights, then returns the
appropriate tex.SampleGrad result; call ComputeGradients only in the callers
(SampleStochastic/SampleStochasticBias) and pass the possibly bias-scaled
dPdx/dPdy into the helper to remove duplication while preserving performance.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5a7184de-3d3a-4fe0-b5a7-3a9a1490e53f

📥 Commits

Reviewing files that changed from the base of the PR and between efa454e and fc0edcf.

📒 Files selected for processing (2)

• package/Shaders/Common/Triplanar.hlsli
• package/Shaders/Lighting.hlsl