feat: add shader stencil operations

[PenguinDOOM]

Summary

Adds a shared Unity Built-in Render Pipeline Stencil ABI to all Pure-Base product shaders:

• Adds seven Float-compatible public properties to Unlit, Toon, PBR, and Hybrid: _StencilRef, _StencilReadMask, _StencilWriteMask, _StencilComp, _StencilPass, _StencilFail, and _StencilZFail.
• Applies the full configurable Stencil state in ForwardBase.
• Makes ForwardAdd re-compare Ref/ReadMask/Comp after ForwardBase, with WriteMask 0 and fixed Keep operations so additional lights never mutate the buffer.
• Leaves ShadowCaster and Meta outside the camera Stencil policy.
• Adds exact Daily, release-runner, and cold-consumer contract coverage, including strict no-fallback D24S8 runtime observations.
• Documents ABI defaults, no-op compatibility, pass behavior, and post-ForwardBase comparison semantics in the public contract and English/Japanese technical documentation.

Closes #3.

Compatibility

The defaults preserve Unity's omitted Stencil behavior: Ref=0, masks 255, Comp=Always, and all operations Keep. Existing materials without serialized Stencil values continue to render without mutating the Stencil buffer. Rendering Mode Apply/Resync preserves user-provided Stencil overrides.

Validation

• Focused Stencil ABI/source/D24S8 contracts: 7/7 passed.
• Unity EditMode PureBase.Tests.Daily assembly: 56/56 passed.
• Release runner Pester harness: 2/2 passed.
• PureBase.Release.Consumer.Tests.csproj build: 0 errors.
• GitHub Actions Release validation: succeeded on 75c7cb2d0a843d701ac9e5481b379e9f18d2f1e1.

The hosted release run completed the audited package validation, cold consumer import contract, versioned ZIP export, repository-state assertion, and validation evidence upload.

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 134 complexity · 14 duplication

Metric	Results
Complexity	134
Duplication	14

View in Codacy

AI Reviewer: first review requested successfully. AI can make mistakes. Always validate suggestions.

_{TIP This summary will be updated as you push new changes.}

[codacy-production]

Pull Request Overview

This PR successfully implements a standardized Stencil ABI for product shaders in the Unity Built-in Render Pipeline, covering property definitions, pass-specific logic (ForwardBase vs ForwardAdd), and documentation. However, the automated analysis indicates the PR is not up to standards due to quality issues in the test suite.

The main point of concern is the file PureBaseRenderingModeRenderingTests.Stencil.cs. This file is flagged as a high-complexity, uncovered file that bundles multiple complex helper classes, exceeding recommended length limits. Furthermore, it contains a systemic pattern of omitting curly braces, which hinders maintainability. While the functional intent is achieved, refactoring the test infrastructure into dedicated fixtures is recommended to ensure long-term stability.

About this PR

• There is a systemic pattern across the new test files where curly braces are omitted for single-statement control structures (31 instances). While valid C#, this deviates from standard style guidelines and increases the risk of maintenance errors.

Test suggestions

• Verify Stencil property metadata including Float type, defaults, and drawer attributes across all products.
• Verify generated ShaderLab source code ensures ForwardBase contains the full stencil block and ForwardAdd contains the read-only block.
• Verify that ShadowCaster and Meta passes do not contain Stencil blocks in generated source.
• Verify runtime: Default Stencil state (Always/Keep) renders correctly regardless of the cleared buffer value.
• Verify runtime: ForwardBase 'Replace' operations correctly control subsequent 'Equal' readers.
• Verify runtime: Partial ReadMask and WriteMask bits are honored correctly in comparisons.
• Verify runtime: ForwardAdd correctly re-compares against values modified by ForwardBase without further mutating the buffer.

_{TIP Improve review quality by adding custom instructions
TIP How was this review? Give us feedback}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 75c7cb2d0a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR introduces a shared, configurable Unity Built-in Render Pipeline Stencil ABI across all Pure-Base product shaders, applying it consistently to forward passes while preserving legacy no-op defaults and documenting the contract. It also adds contract, consumer, and runtime validation coverage (including explicit D24S8 observations) to ensure the Stencil policy remains stable across releases.

Changes:

• Add seven shared public Stencil properties (_StencilRef, _StencilReadMask, _StencilWriteMask, _StencilComp, _StencilPass, _StencilFail, _StencilZFail) to Unlit/Toon/PBR/Hybrid and apply pass-bounded Stencil state in ForwardBase/ForwardAdd.
• Expand release-runner and consumer contract tests to assert Stencil ABI presence, ordering, defaults, and pass policy (including “ForwardAdd compare-only” behavior).
• Add Daily runtime/source contract coverage and update English/Japanese technical documentation and public shader contract docs.

Reviewed changes

Copilot reviewed 18 out of 20 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
Tests/Release/Run-PureBaseReleaseValidation.Tests.ps1	Adds runner-contract assertions for Stencil ABI/pass policy and wraps runner harness in a Pester Describe.
Tests/Release/Run-PureBaseReleaseValidation.ps1	Extends runner product contracts to require/forbid Stencil fragments per pass and adds Stencil properties to expected visible ABI.
Tests/Release/ConsumerProject/Assets/Editor/PureBaseConsumerReleaseTests.cs	Validates imported shader Stencil property metadata (type/attribute/default) and enforces visible property ordering.
Tests/Daily/Editor/PureBaseRenderingModeRenderingTests.Stencil.cs.meta	Adds Unity meta for the new Daily Stencil runtime test file.
Tests/Daily/Editor/PureBaseRenderingModeRenderingTests.Stencil.cs	Adds explicit D24S8 runtime observations verifying default no-op behavior, mask behavior, and ForwardAdd re-compare semantics.
Tests/Daily/Editor/PureBaseRenderingModeRenderingTests.SourceContracts.cs	Adds generated-source contracts to assert pass set/order, variant declarations, and per-pass Stencil render-state policy.
Tests/Daily/Editor/PureBaseRenderingModeContractTests.ProductContracts.cs	Extends product ABI tests to include Stencil properties, defaults, attribute contracts, and retention through Apply/Resync.
Tests/Daily/Editor/PureBaseD24S8StencilTarget.renderTexture.meta	Adds meta for the tracked RenderTexture fixture asset used by D24S8 observations.
Tests/Daily/Editor/PureBaseD24S8StencilTarget.renderTexture	Adds the tracked RenderTexture fixture asset configured for D24S8 without compatible-format fallback.
Shaders/PureBaseUnlit.scshader	Applies the Stencil policy to ForwardBase and ForwardAdd.
Shaders/PureBaseUnlit_properties.hlsl	Adds Stencil ABI properties to Unlit’s public property declarations.
Shaders/PureBaseToon.scshader	Applies the Stencil policy to ForwardBase and ForwardAdd.
Shaders/PureBaseToon_properties.hlsl	Adds Stencil ABI properties to Toon’s public property declarations.
Shaders/PureBasePBR.scshader	Applies the Stencil policy to ForwardBase and ForwardAdd.
Shaders/PureBasePBR_properties.hlsl	Adds Stencil ABI properties to PBR’s public property declarations.
Shaders/PureBaseHybrid.scshader	Applies the Stencil policy to ForwardBase and ForwardAdd.
Shaders/PureBaseHybrid_properties.hlsl	Adds Stencil ABI properties to Hybrid’s public property declarations.
Docs/technical-information.md	Documents the Stencil ABI defaults and per-pass policy in English technical docs.
Docs/technical-information.ja.md	Documents the Stencil ABI defaults and per-pass policy in Japanese technical docs.
Docs/pure-base-shader-contract.md	Updates the public contract: visible property order + Stencil pass policy and ABI tables.

Files not reviewed (2)

• Tests/Daily/Editor/PureBaseD24S8StencilTarget.renderTexture.meta: Generated file
• Tests/Daily/Editor/PureBaseRenderingModeRenderingTests.Stencil.cs.meta: Generated file

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.