Modular Shader System
Poiyomi Shaders is put together using the Modular Shader System, which allows for modular architecture on each individual features. This is a comprehensive guide to creating shader modules for the Poiyomi Shaders framework.
This page contains complex information! Therefore, this is intended to be read by Advanced Shader Developers only.
Quick Start
The fastest way to make a module is Poi -> Create New Module. Name it, pick where its settings appear and where its code runs, then click Create. You get a folder containing the two files described below.
Then open any Poiyomi material, expand Third Party, and click Install on your module. That material's shader rebuilds and your settings appear in its inspector. The shader's name doesn't change. Other Poiyomi shaders pick the module up the first time you select a material that uses them. To take it out again, use Remove in the menu on your module's section.
The rest of this page explains what the Wizard sets up for you. For how installing, updating and removing works from the user's side, see Third Party.
Overview
The Poiyomi Shader system uses a modular architecture where individual features are defined as separate modules. Each module consists of two main files:
- Module Definition (
.asset) - YAML file defining module metadata and template references - Template Collection (
.poiTemplateCollection) - Contains the actual shader code templates
The template collection is a plain text file. On import, every #T# section in it becomes its own sub-asset, named after its header. The module definition then points each section at one or more injection keywords.
Don't hand-edit the fileID references in the .asset file. Create the module with the wizard, or assign templates in the module's inspector, and let Unity write them.
File Structure
Poi_FeatureModules/
├── Poi_YourModule/
│ ├── VRLM_PoiYourModule.asset # Module definition
│ ├── VRLM_PoiYourModule.asset.meta
│ ├── VRLTC_PoiYourModule.poiTemplateCollection # Shader code
│ └── VRLTC_PoiYourModule.poiTemplateCollection.meta
Poiyomi's own modules live in Poi_FeatureModules/. A Third Party module can live anywhere in the project, as long as it's outside the Poiyomi folder. See What is a Third Party Module for why.
Naming Convention
| Prefix | Type |
|---|---|
VRLM_ | Module Definition (asset) |
VRLT_ | Single Template (poiTemplate) |
VRLTC_ | Template Collection (poiTemplateCollection) |
Key Fields
| Field | Description |
|---|---|
Id | Unique identifier for the module. Must be unique across the whole project, since dependencies and conflicts use it |
Name, Version, Author, Description | Shown on the module's row in Third Party before it's installed. Bump Version with each release, so the Update button can show which version people are moving to |
Icon | Optional texture shown at the start of that row. Without one, a puzzle piece is shown |
ModuleDependencies | Ids of modules that must also be installed |
IncompatibleWith | Ids of modules that can't be installed alongside this one |
AllowDuplicates | Whether the same module can appear more than once. See Duplicate Module Support |
Templates | References to template sections with keyword mappings |
Queue | Set on each template entry. Priority order (lower = earlier in shader). See Ordering |
Dependencies and conflicts are checked before install. A module with an unmet dependency can't be installed, and its row in Third Party shows why.
Template Collection (.poiTemplateCollection)
Templates contain shader code organized into named sections. Each section is marked with #T#SectionName.
Template Structure
#T#YourModuleProperties
//ifex _EnableYourModule==0
[HideInInspector] m_start_yourModule (" Your Module--{reference_property:_EnableYourModule}", Float) = 0
[HideInInspector][ThryToggle(POI_YOUR_MODULE)]_EnableYourModule ("Enable", Float) = 0
_YourProperty ("Property Name", Range(0, 1)) = 0.5
[HideInInspector] m_end_yourModule ("", Float) = 0
//endex
#T#YourModuleKeywords
//ifex _EnableYourModule==0
#pragma shader_feature_local POI_YOUR_MODULE
//endex
#T#YourModuleVariables
//ifex _EnableYourModule==0
#ifdef POI_YOUR_MODULE
float _YourProperty;
#endif
//endex
#T#YourModuleFunction
//ifex _EnableYourModule==0
#ifdef POI_YOUR_MODULE
void ApplyYourModule(inout PoiFragData poiFragData, in PoiMesh poiMesh)
{
// Your shader logic here
}
#endif
//endex
#T#YourModuleFunctionCall
//ifex _EnableYourModule==0
#ifdef POI_YOUR_MODULE
ApplyYourModule(poiFragData, poiMesh);
#endif
//endex
Common Keywords (Injection Points)
Keywords define where code is injected into the shader pipeline. Keywords are marked with #K# in templates. For example, #K#FRAGMENT_BASE_COLOR in a pass program is where everything targeting FRAGMENT_BASE_COLOR gets pasted.
Keywords are per pass. BASE is the main forward pass. The others are ADD (extra realtime lights), META (lightmap baking), SHADOW (shadow caster), OUTLINE, LILFUR (fur), DEPTH (depth only and depth normals), and MOTION_VECTORS (URP only). Two-pass and grab pass shaders also have BASETWO/ADDTWO and SELF_GRAB versions of some keywords, listed in the tables below. Target every pass you want your effect to appear in.
Targeting a keyword that a pass doesn't have is harmless. Injection is a plain text match, so that template is skipped silently instead of causing an error. The flip side is that a misspelled keyword doesn't cause an error either; that code just never shows up in the shader.
The Four Keywords a Typical Module Needs
| Section | Keyword | Holds |
|---|---|---|
| Properties | One UI section | Shader properties, which make up the inspector UI |
| Variables | <PASS>_PROPERTY_VARIABLES_EXPOSED | Numeric declarations such as float _MyThing; |
| Functions | FRAGMENT_<PASS>_FUNCTIONS | Your function definitions |
| Function Calls | A hook point | The call that runs your function |
Top-Level Shader Structure
These keywords define the overall shader structure and pass ordering:
| Keyword | Description |
|---|---|
SHADER_TAGS | Shader-level tags and properties |
DEPTH_NORMALS_PASS | Depth normals pass injection |
GRAB_PASS | Grab pass for screen effects |
DEPTH_ONLY_PASS | Depth only (early Z) pass |
EARLY_OUTLINE_PASS | Early outline pass (before base) |
BASE_PASS | Main forward base pass |
ADD_PASS | Additive lighting pass |
SELF_GRAB_PASS | Self grab pass |
BASE_PASS_TWO | Second base pass (two-pass shaders) |
ADD_PASS_TWO | Second additive pass |
OUTLINE_PASS | Outline rendering pass. The lil Fur passes are injected here too |
SHADOW_PASS | Shadow casting pass |
META_PASS | Lightmapping/GI meta pass |
MOTION_VECTORS_PASS | Motion vectors pass (URP only) |
Property Categories
These keywords decide where your settings appear in the inspector. Third Party modules should default to THIRDPARTY_PROPERTIES. Every module is offered for install in the Third Party section either way; one that puts its settings somewhere else says where on its row.
In inspector order:
| Keyword | Appears As |
|---|---|
MAIN_PROPERTIES | Color & Normals |
2NDPASS_PROPERTIES | 2nd Pass (Two Pass shaders only) |
OUTLINE_PROPERTIES | Outlines |
LIGHTING_PROPERTIES | Shading |
SPECIALFX_PROPERTIES | Special FX |
RAYMARCHING_PROPERTIES | Raymarching |
VERTEX_PROPERTIES | Vertex Options |
GRABPASS_PROPERTIES | Grab Pass (Grab Pass shaders only) |
GLOBAL_PROPERTIES | Global Modifiers & Data -> Global Data and Masks |
UV_PROPERTIES | Global Modifiers & Data -> UVs |
POSTPROCESSING_PROPERTIES | Global Modifiers & Data -> Post Processing |
MODIFIER_PROPERTIES | Global Modifiers & Data |
EXTRAS_PROPERTIES | (No header, added as-is) |
THIRDPARTY_PROPERTIES | Third Party |
RENDERING_PROPERTIES | Rendering |
TOP_PROPERTIES also exists, above every section. It's where the lock button lives, so it isn't a normal home for a module.
The source of truth for this list is Poi_UIBoilerPlate/VRLTC_PoiPropertySkeleton.poiTemplateCollection. The Create New Module wizard reads that file directly, so its dropdown always matches the shader, even when new sections are added.
Generic Pass Keywords
These keywords are available in VRLT_PoiGenericPass.poiTemplate for all passes:
| Keyword | Description |
|---|---|
PRAGMA_DIRECTIVES | Shader pragma statements |
REQUIREMENTS | Shader requirements/features |
SHADER_KEYWORDS | Shader feature keywords |
MACROS_AND_DEFINES | Preprocessor macros and defines |
INCLUDES | Include file directives |
Pass-Specific Pragma & Keywords
Each pass type has its own keyword and pragma injection points:
| Pass | Keywords | Pragma Programs |
|---|---|---|
| Base | BASE_PASS_KEYWORDS | BASE_PASS_PRAGMA_PROGRAMS |
| Add | ADD_PASS_KEYWORDS | ADD_PASS_PRAGMA_PROGRAMS |
| Shadow | SHADOW_PASS_KEYWORDS | SHADOW_PASS_PRAGMA_PROGRAMS |
| Meta | META_PASS_KEYWORDS | META_PASS_PRAGMA_PROGRAMS |
| Outline | OUTLINE_PASS_KEYWORDS | OUTLINE_PASS_PRAGMA_PROGRAMS |
| Depth (Depth Only and Depth Normals) | DEPTH_PASS_KEYWORDS | DEPTH_PASS_PRAGMA_PROGRAMS |
| LilFur | LILFUR_PASS_KEYWORDS | LILFUR_PASS_PRAGMA_PROGRAMS |
| Base Two | BASE_PASS_TWO_KEYWORDS | BASE_PASS_TWO_PRAGMA_PROGRAMS |
| Add Two | ADD_PASS_TWO_KEYWORDS | ADD_PASS_TWO_PRAGMA_PROGRAMS |
| Self Grab | SELF_GRAB_PASS_KEYWORDS | - |
| Motion Vectors (URP only) | MOTION_VECTORS_PASS_KEYWORDS | MOTION_VECTORS_PASS_PRAGMA_PROGRAMS |
Stencil Injection Points
| Keyword | Pass |
|---|---|
BASE_PASS_STENCIL | Base pass stencil settings |
ADD_PASS_STENCIL | Add pass stencil settings |
SHADOW_PASS_STENCIL | Shadow pass stencil settings |
META_PASS_STENCIL | Meta pass stencil settings |
DEPTH_PASS_STENCIL | Depth only and depth normals stencil settings |
MOTION_VECTORS_PASS_STENCIL | Motion vectors stencil settings (URP only) |
BASETWO_PASS_STENCIL | Base two pass stencil |
ADDTWO_PASS_STENCIL | Add two pass stencil |
Variable Declarations
Variables must be declared in every pass that uses them. Each pass has two keywords for this:
<PASS>_PROPERTY_VARIABLES_EXPOSEDholds numeric uniforms: floats, vectors and colors. In URP it sits inside theUnityPerMaterialcbuffer.<PASS>_PROPERTY_VARIABLESholdsTexture2Dand sampler declarations, which must stay outside that cbuffer.
| Pass | Numbers, Vectors & Colors | Textures & Samplers |
|---|---|---|
| Base | BASE_PROPERTY_VARIABLES_EXPOSED | BASE_PROPERTY_VARIABLES |
| Add | ADD_PROPERTY_VARIABLES_EXPOSED | ADD_PROPERTY_VARIABLES |
| Shadow | SHADOW_PROPERTY_VARIABLES_EXPOSED | SHADOW_PROPERTY_VARIABLES |
| Meta | META_PROPERTY_VARIABLES_EXPOSED | META_PROPERTY_VARIABLES |
| Outline | OUTLINE_PROPERTY_VARIABLES_EXPOSED | OUTLINE_PROPERTY_VARIABLES |
| Depth | DEPTH_PROPERTY_VARIABLES_EXPOSED | DEPTH_PROPERTY_VARIABLES |
| LilFur | LILFUR_PROPERTY_VARIABLES_EXPOSED | LILFUR_PROPERTY_VARIABLES |
| Base Two | BASETWO_PROPERTY_VARIABLES_EXPOSED | BASETWO_PROPERTY_VARIABLES |
| Add Two | ADDTWO_PROPERTY_VARIABLES_EXPOSED | ADDTWO_PROPERTY_VARIABLES |
| Self Grab | SELF_GRAB_PROPERTY_VARIABLES_EXPOSED | SELF_GRAB_PROPERTY_VARIABLES |
| Motion Vectors (URP only) | MOTION_VECTORS_PROPERTY_VARIABLES_EXPOSED | MOTION_VECTORS_PROPERTY_VARIABLES |
Vertex Shader Keywords
Vertex program injection points (per pass - replace BASE with pass name):
| Keyword | Stage |
|---|---|
VERTEX_BASE_DATA_STRUCTURES | Vertex data structure definitions |
VERTEX_BASE_FUNCTIONS_EARLY | Early vertex function definitions |
VERTEX_BASE_FUNCTIONS | Main vertex function definitions |
VERTEX_BASE_FUNCTIONS_LATE | Late vertex function definitions |
VERTEX_BASE_PROGRAM | Main vertex program code |
Vertex Modification Keywords
These keywords are used within the vertex program for modifying vertex data:
| Keyword | Timing | Description |
|---|---|---|
VERTEX_INPUT_MODS | Very early | Modify input vertex data |
VERTEX_MODS_EARLY | Early | Early vertex modifications |
VERTEX_MODS | Main | Primary vertex modifications |
VERTEX_MODS_LATE | Late | Late vertex modifications |
VERTEX_MODS_PENETRATION | Post-offset | TPS/DPS penetration systems |
VERTEX_MODS_PRE_CLIPPOS | Before clip | Before clip position calculation |
VERTEX_MODS_POST_CLIPPOS | After clip | After clip position calculation |
VERTEX_MODS_LILFUR | Fur-specific | LilFur vertex modifications |
VERTEX_MODS_FINAL | Final | Final vertex modifications |
vertexOutData | Data struct | Additional vertex output data |
Geometry & Tessellation Keywords
| Keyword | Description |
|---|---|
HULLDOMAIN_BASE_PROGRAM | Hull/Domain shader for base pass |
HULLDOMAIN_ADD_PROGRAM | Hull/Domain shader for add pass |
HULLDOMAIN_SHADOW_PROGRAM | Hull/Domain shader for shadow pass |
HULLDOMAIN_META_PROGRAM | Hull/Domain shader for meta pass |
HULLDOMAIN_DEPTH_NORMALS_PROGRAM | Hull/Domain shader for depth normals |
HULLDOMAIN_DEPTH_ONLY_PROGRAM | Hull/Domain shader for depth only |
HULLDOMAIN_LILFUR_PROGRAM | Hull/Domain shader for LilFur |
HULLDOMAIN_MOTION_VECTORS_PROGRAM | Hull/Domain shader for motion vectors (URP only) |
GEOMETRY_BASE_PROGRAM | Geometry shader for base pass |
GEOMETRY_ADD_PROGRAM | Geometry shader for add pass |
GEOMETRY_SHADOW_PROGRAM | Geometry shader for shadow pass |
GEOMETRY_META_PROGRAM | Geometry shader for meta pass |
GEOMETRY_DEPTH_NORMALS_PROGRAM | Geometry shader for depth normals |
GEOMETRY_DEPTH_ONLY_PROGRAM | Geometry shader for depth only (early Z) |
GEOMETRY_LILFUR_PROGRAM | Geometry shader for LilFur |
GEOMETRY_MOTION_VECTORS_PROGRAM | Geometry shader for motion vectors (URP only) |
Fragment Shader Keywords
Fragment program injection points (per pass - replace BASE with pass name):
| Keyword | Stage |
|---|---|
FRAGMENT_BASE_DATA_STRUCTURES | Fragment data structure definitions |
FRAGMENT_BASE_FUNCTIONS_EARLY | Early fragment function definitions |
FRAGMENT_BASE_FUNCTIONS | Main fragment function definitions |
FRAGMENT_BASE_FUNCTIONS_LATE | Late fragment function definitions |
FRAGMENT_BASE_PROGRAM | Main fragment program |
Fragment Execution Pipeline
These are the hook points where your code runs, in execution order within the fragment program. All of them sit in the same function body, so the same variables are in scope at every one.
| Keyword | Runs | Passes |
|---|---|---|
FRAGMENT_BASE_DECLARATIONS | Structs are declared here. Don't target this | All |
FRAGMENT_BASE_INIT_EARLY | Before mesh data is filled in | All |
FRAGMENT_BASE_INIT | Mesh, light and camera data gets filled in | All |
FRAGMENT_BASE_INIT_LATE | After setup, before any color | All |
FRAGMENT_BASE_COLOR_EARLY | Before the main texture | All |
FRAGMENT_BASE_COLOR | Main texture and decals. The usual choice | All |
FRAGMENT_BASE_COLOR_LATE | After all color work | All |
FRAGMENT_BASE_LIGHTING_EARLY | Before the lighting model | All except Depth, Motion Vectors and Self Grab |
FRAGMENT_BASE_LIGHTING | Alongside the lighting model | All except Depth, Motion Vectors and Self Grab |
FRAGMENT_BASE_LIGHTING_LATE | After the lighting model | All except Depth, Motion Vectors and Self Grab |
FRAGMENT_BASE_LIGHTING_ADD | Adding light on top, such as rim lights and glows | Base, Add, Meta, Outline and LilFur |
FRAGMENT_BASE_EMISSION_EARLY | Early emission | All except Depth, Motion Vectors and Self Grab |
FRAGMENT_BASE_EMISSION | Main emission calculations | All except Depth, Motion Vectors and Self Grab |
FRAGMENT_BASE_EMISSION_LATE | Late emission effects | All except Depth, Motion Vectors and Self Grab |
FRAGMENT_BASE_RETURN | Last change before alpha cutout | All |
FRAGMENT_BASE_ALPHA_LATE | After clipping | Base, Add, Outline, LilFur and Self Grab |
The same pattern applies to other passes: FRAGMENT_ADD_*, FRAGMENT_OUTLINE_*, FRAGMENT_LILFUR_*, etc. The Passes column shows which passes have each hook.
Data Initialization Keywords
| Keyword | Description |
|---|---|
POI_MESH_PROPERTIES | PoiMesh struct properties |
POI_CAM_PROPERTIES | PoiCam struct properties |
POI_LIGHT_PROPERTIES | PoiLight struct properties |
MESH_DATA_INIT | Mesh data initialization |
MESH_DATA_POST_INIT | Post mesh initialization |
MAIN_TEXTURE_SAMPLE | Main texture sampling |
FRAGMENT_NORMAL_CALCULATION | Normal calculation |
CAMERA_DATA_INIT | Camera data initialization |
Feature-Specific Keywords
Some modules expose their own injection points:
| Keyword | Module | Description |
|---|---|---|
MAIN_COLOR_MOD | Main | Base color modification |
TANGENT_NORMAL_INJECTION | Main | Normal map injection |
BASE_LIGHTDATA_MOD | Light Data | Light data modification |
BASE_AFTER_ATTENUATION | Light Data | After attenuation calculation |
BASE_REALISTIC_MOD | Shading | Realistic shading modifications |
MOCHIE_METALLIC_SMOOTHNESS_MOD | Metallics | Metallic/smoothness mods |
POI_EMISSION0_MODS | Emission | Emission 0 modifications |
LILFUR_TWO_PASS_PROPS | LilFur | Fur two-pass properties |
Reflections & Specular Smoothness Modifiers
Code injected at MOCHIE_METALLIC_SMOOTHNESS_MOD should access the current Reflections & Specular instance through POI_BRDF_MOD_DATA, for example POI_BRDF_MOD_DATA.smoothness. The alias only exists around that hook, and it follows the current instance when Reflections & Specular is duplicated. Don't hardcode the first instance's mochieBRDFData identifier in injected modifiers.
Ordering
Each template entry has a Queue (default 100). Within a keyword, everything targeting it is sorted by Queue in ascending order, so lower runs earlier. There's no "run after module X" setting; it's one flat number.
Ties keep module order, and user modules are processed after Poiyomi's own. So at the default Queue of 100, your code runs after Poiyomi's, which is usually what you want.
These bands are used throughout the shader. They're a convention, not a rule:
| Queue | Used For |
|---|---|
| Negative | Before core setup |
0 | Core infrastructure, such as data structures and init |
1–99 | Features that must run before the bulk |
100 | Default. Most features |
101–999 | Features that must run after the bulk |
1000+ | Last |
Poi -> Tools -> Modular Shader -> Module Order Listing lists every module targeting a given keyword, with editable queues.
Core Data Structures
Five structs are declared before any hook point and filled in during INIT, so they're in scope at every fragment hook:
| Struct | Useful Fields |
|---|---|
PoiFragData poiFragData | baseColor, finalColor, alpha, emission, smoothness, metallic |
PoiMesh poiMesh | uv[11], normals[2], worldPos, localPos, vertexColor, isFrontFace, tangent[2] |
PoiLight poiLight | finalLightAdd, direction, directColor, indirectColor, lightMap, nDotL, attenuation |
PoiCam poiCam | Camera position and vectors |
PoiMods poiMods | globalEmission and other cross-module modifiers |
Note that baseColor, finalColor and emission are half3, not half4. Alpha is kept separately.
PoiFragData
Fragment output data for color, lighting, and material properties.
struct PoiFragData {
half3 baseColor; // Albedo color before lighting
half3 finalColor; // Final color after all effects
half alpha; // Transparency
half3 emission; // Emissive color
// PBR Properties
half smoothness; // Primary smoothness (0-1)
half smoothness2; // Secondary smoothness for layered materials
half metallic; // Metallic value (0-1)
half specularMask; // Mask for specular highlights
half reflectionMask; // Mask for reflections
half toggleVertexLights; // Enable/disable vertex lights contribution
};
PoiMesh
Mesh geometry, UVs, and vertex data.
struct PoiMesh {
// Normals
float3 normals[2]; // [0] = vertex normal, [1] = fragment/normal-mapped
float3 objNormal; // Object-space normal
float3 tangentSpaceNormal; // Normal in tangent space
float3 binormal[2]; // Binormal vectors
float3 tangent[2]; // Tangent vectors
// Position
float3 worldPos; // World-space position
float3 localPos; // Object-space position
float3 objectPosition; // Object pivot position in world space
// Face
float isFrontFace; // 1.0 = front face, 0.0 = back face
// Vertex Data
float4 vertexColor; // Vertex color RGBA
float4 lightmapUV; // Lightmap UVs
// UV Channels (11 total)
// [0-3] = UV0-UV3
// [4] = Panosphere UV
// [5] = World position XZ
// [6] = Polar UV
// [7] = Distorted UV
// [8] = Local position
// [9] = Matcap UV
// [10] = Screen space UV
float2 uv[11];
// Parallax
float2 parallaxUV; // UV offset from parallax
float2 dx; // Screen-space derivatives X
float2 dy; // Screen-space derivatives Y
uint isRightHand; // Handedness for normal mapping
};
PoiCam
Camera and view information.
struct PoiCam {
float3 viewDir; // View direction (pixel to camera)
float3 forwardDir; // Camera forward direction
float3 worldPos; // Camera world position
float distanceToVert; // Distance from camera to vertex
// Screen Space
float4 clipPos; // Clip-space position
float4 screenSpacePosition; // Screen-space position
float4 posScreenSpace; // Normalized screen position
float2 posScreenPixels; // Screen position in pixels
float2 screenUV; // Screen UVs (0-1)
// Reflections
float3 reflectionDir; // Reflection direction
float3 vertexReflectionDir; // Vertex-based reflection direction
float3 tangentViewDir; // View direction in tangent space
float vDotN; // View dot normal
float4 worldDirection; // World-space direction
};
PoiLight
Lighting calculations and light source data.
struct PoiLight {
// Light Direction & Color
float3 direction; // Light direction
float3 directColor; // Direct light color
float3 indirectColor; // Indirect/ambient light color
float3 halfDir; // Half vector (view + light)
// Attenuation
float attenuation; // Light attenuation
float attenuationStrength; // Attenuation intensity
float occlusion; // Ambient occlusion
float shadowMask; // Shadow mask value
float detailShadow; // Detail shadow value
// Dot Products
float nDotL; // Normal dot light direction
float nDotV; // Normal dot view direction
float nDotH; // Normal dot half vector
float nDotVCentered; // Centered nDotV
float vertexNDotL; // Vertex-based nDotL
float vertexNDotV; // Vertex-based nDotV
float vertexNDotH; // Vertex-based nDotH
float lDotv; // Light dot view
float lDotH; // Light dot half
float nDotLSaturated; // Clamped nDotL (0-1)
float nDotLNormalized; // Normalized nDotL (0-1 range)
// Light Maps
float lightMap; // Light map value
float lightMapNoAttenuation;// Light map without attenuation
float3 rampedLightMap; // Toon ramp applied light map
// Final Lighting
float3 finalLighting; // Combined final lighting
float3 finalLightAdd; // Additive light contribution
// LTCGI
float3 LTCGISpecular; // LTCGI specular contribution
float3 LTCGIDiffuse; // LTCGI diffuse contribution
// Luminance
float directLuminance; // Direct light luminance
float indirectLuminance; // Indirect light luminance
float finalLuminance; // Final combined luminance
// Add Pass Only
#ifdef POI_PASS_ADD
float additiveShadow; // Shadow for additive pass
#endif
// Vertex Lights (4 non-important lights)
#if defined(VERTEXLIGHT_ON)
float4 vDotNL; // Per-light nDotL
float4 vertexVDotNL; // Vertex-based per-light nDotL
float3 vColor[4]; // Light colors
float4 vCorrectedDotNL; // Corrected per-light nDotL
float4 vAttenuation; // Per-light attenuation
float4 vSaturatedDotNL; // Clamped per-light nDotL
float3 vPosition[4]; // Light positions
float3 vDirection[4]; // Light directions
float3 vFinalLighting; // Combined vertex lighting
float3 vHalfDir[4]; // Per-light half vectors
half4 vDotNH; // Per-light nDotH
half4 vertexVDotNH; // Vertex-based per-light nDotH
half4 vDotLH; // Per-light lDotH
#endif
};
PoiMods
Global modifiers, masks, and AudioLink data.
struct PoiMods {
float4 Mask; // Legacy mask (deprecated, use globalMask)
// AudioLink
float audioLink[5]; // [0]=Bass, [1]=LowMid, [2]=HighMid, [3]=Treble, [4]=Volume
float audioLinkAvailable; // 1.0 if AudioLink is present
float audioLinkVersion; // AudioLink version number
float4 audioLinkTexture; // Raw AudioLink texture sample
float ALTime[8]; // AudioLink chronotensity time values
// Detail Masks
float2 detailMask; // Detail texture masks
float2 backFaceDetailIntensity; // Detail intensity for back faces
// Global Systems
float globalEmission; // Global emission multiplier
float4 globalColorTheme[12];// Theme colors (4 user + 4 ColorChord + 4 AL Theme)
float globalMask[16]; // 16 global mask channels (4 textures × 4 RGBA)
};
PoiVertexLights
Individual vertex light data (used in vertex lighting calculations).
struct PoiVertexLights {
float3 direction; // Light direction
float3 color; // Light color
float attenuation; // Light attenuation
};
Preprocessor Directives
//ifex Blocks
Conditionally exclude code based on material properties:
//ifex _EnableFeature==0
// Code only included if _EnableFeature != 0
//endex
Texture Property Guards
Optimize by only including texture sampling when texture is assigned:
#if defined(PROP_YOURTEXTURE) || !defined(OPTIMIZER_ENABLED)
Texture2D _YourTexture;
#endif
Keyword Guards
Wrap code in shader feature checks:
#ifdef POI_YOUR_MODULE
// Module code
#endif
Duplicate Module Support
For modules that can have multiple instances (like Emission 0, 1, 2...):
AllowDuplicates: 1
ForceDuplicateLogic: 1
Use placeholders in templates:
__mIDx__- Replaced with instance index (0, 1, 2...)__mID__- Replaced with module ID string<ms_include_in_first>{ }- Only in first instance<ms_include_in_not_first>{ }- Only in subsequent instances<ms_include_in_last>{ }- Only in last instance
Example: Multiple Backlight Instances
Custom modular shaders can include PoiBacklight more than once. For example, one instance with low Directivity and View Direction Strength for a front highlight, plus another for silhouette backlighting. The current default shaders include two independently enabled sections, Backlight 1 and Backlight 2. Both are disabled by default, so existing materials look the same until the second one is turned on.
The generator keeps the first instance's existing property names and keyword. Additional instances use the standard __1, __2, etc. suffixes, for example _BacklightDirectivity__1, _BacklightColorTex__1 and POI_BACKLIGHT__1. Colors, textures, directionality, shadow reception, backface masking and enable toggles are all independent. Each instance adds to finalLightAdd using the existing Backlight formula.
Global mask storage is shared on purpose. Mask writes and reads follow module order, so instances targeting the same mask can affect each other.
Each enabled instance repeats the Backlight lighting calculation in each relevant pass, plus one texture sample per shaded fragment when a texture is used. Each additional instance also adds a local shader keyword, which doubles the possible Backlight combinations before variant stripping. Disabled instances are excluded by their keyword, and the material optimizer can strip them using their own enable property. No extra render pass is added.
ThryEditor Property Attributes
Common UI attributes for material properties:
| Attribute | Purpose |
|---|---|
[HideInInspector] | Hide from default inspector |
[ThryHideInInspector] | Same as [HideInInspector] but allows third-party utilities (such as VRCFury or Modular Avatar) to access it |
[ThryToggle(KEYWORD)] | Toggle that enables shader keyword |
[ThryToggleUI(true)] | Toggle without keyword |
[ThryWideEnum(...)] | Wide dropdown with named options |
[sRGBWarning] | Warn if texture is sRGB when it shouldn't be |
[sRGBWarning(true)] | Warn if texture is Linear when it shouldn't be |
[Gradient] | Gradient texture picker |
[Vector2] | 2D vector input |
[VectorLabel(X, Y)] | Labeled vector components |
[IntRange] | Only for Int props, makes a clamped range slider determined by Range(X, Y) |
[Curve] | Animation curve texture |
[MultiSlider] | Sets the Vector to clamp between a min and max value |
[Ramp4(normalized)] | Use a vector curve ramp |
[DoNotAnimate] | Explicitly block the property from being tagged as Animated |
[ThryHDR] | HDR color picker for ordinary tint colors, without Unity's HDR flag. See HDR Tint Colors |
HDR Tint Colors
Use [ThryHDR] for ordinary tint colors. It turns on the HDR color picker in Thry's inspectors without setting Unity's HDR shader property flag:
[ThryHDR] _MyTint ("Tint", Color) = (1, 1, 1, 1)
Adding this drawer to an existing ordinary Color property keeps its saved values, alpha, and gamma-to-linear conversion. Values above 1 are allowed and use that same conversion. Keep any existing brightness or intensity multipliers, since the drawer doesn't change any shader math.
Use Unity's [HDR] when a new property needs linear HDR values, such as an emission color.
DO NOT remove existing [HDR] or [Gamma] attributes to switch to the tint picker. That would reinterpret existing materials and animation values.
In 11.0 and newer, existing HDR properties keep their original flags, except Theme Colors 0–3. Those deliberately switch from [HDR] to [ThryHDR] to match ordinary tints, so saved non-white theme colors can render differently in Linear color space. Their stored values aren't migrated. Older shader versions, and other shaders that use ThryEditor, are unchanged.
UI Organization
// Foldout sections
[HideInInspector] m_start_sectionName (" Section Title--{reference_property:_EnableProperty}", Float) = 0
// ... properties ...
[HideInInspector] m_end_sectionName ("", Float) = 0
// Subsections
[HideInInspector] s_start_subsection ("Subsection--{reference_property:_EnableSub}", Float) = 0
// ... properties ...
[HideInInspector] s_end_subsection ("", Float) = 0
// Nested Subsections
[HideInInspector] ss_start_nestedsubsection ("Nested Subsection--{reference_property_EnableNestedSub}", Float) = 0
// ... properties ...
[HideInInspector] ss_end_nestedsubsection ("", Float) = 0
Conditional Visibility
_Property ("Name--{condition_showS:_OtherProperty==1}", Float) = 0
UI-only Attributes
These Attriibutes are used soley for helpful and decorative elements, which can help out in UI organization.
[Helpbox(1, 2, 1)] _MessageBox ("This is a UI message.", Int) = 0 // Creates a message box with a message and an Icon
[PoiPrefabSpawner(GUID)] _PrefabSpawner ("Add Prefab to Scene", Float) = 0 // Adds the specific Prefab's GUID directly into the active Scene
[Space(7)] // Creates spacing between the properties above and below this line by 7 pixels
[ThrySeperator(2, 2, 2)] // Draws a horizontal line between the properties above and below this line (useful in Nested Subsections)
// Thry Decal Positioning Tool
[ThryDecalPositioning(_Texture, _UV, _Position, _Rotation, _Scale, _SideOffset)]
// ... properties ...
// Multi-Float Buttons (only used for UV Tile Discard)
[ThryMultiFloatButtons(u0v0, u1v0, u2v0, u3v0, _UDIMDiscardRow0_1, _UDIMDiscardRow0_2, _UDIMDiscardRow0_3)] _UDIMDiscardRow0_0("Row 0", Float) = 0
Helper Functions
Common utility functions available in modules:
// UV helpers
float2 poiUV(float2 uv, float4 st); // Apply scale/offset
float2 POI2D_SAMPLER_PAN(tex, sampler, uv, pan); // Sample with panning
// Color operations
float3 poiThemeColor(PoiMods mods, float3 color, float themeIndex);
float3 hueShift(float3 color, float shift, int colorSpace, int mode);
float calculateluminance(float3 color);
// Masking
float maskBlend(float base, float mask, int blendType);
void applyToGlobalMask(inout PoiMods mods, int index, int blendType, float value);
// Math helpers
float inverseLerp(float a, float b, float value);
float remap(float value, float inMin, float inMax, float outMin, float outMax);
float poiMax(float3 color);
float poiEdgeLinear(float value, float border, float blur);
AudioLink Integration
#ifdef POI_AUDIOLINK
if (poiMods.audioLinkAvailable)
{
float bassValue = poiMods.audioLink[0]; // Bass
float lowMidValue = poiMods.audioLink[1]; // Low Mid
float highMidValue = poiMods.audioLink[2]; // High Mid
float trebleValue = poiMods.audioLink[3]; // Treble
float volumeValue = poiMods.audioLink[4]; // Volume
}
#endif
Shared Raymarching Data
The Raymarching Data module only exists in Poiyomi Pro. A Third Party module that depends on it fails to generate in the Toon shaders. See the Third Party Limitations.
Anything that raymarches through the mesh needs the same two baked inputs: an SDF volume of the mesh, and its bind pose stored in the mesh UVs. Both come from one bake, so they live in their own module, Poi_FeatureModules/Pro/Poi_Raymarching. It owns the SDF Volume & Bind Data section under Raymarching, the Bake SDF + Bind Data button, and these properties: _SDFTexture, _SDFPixelSize, _SDFLowerCorner, _SDFSize, _MinThickness, _BindDataMode, the three bind UV slots, and _WorldRecale.
To use it from your own raymarching module:
-
Add
Poi Raymarching Datato yourModuleDependencies. -
Request the data from your keywords template, so shaders without your feature carry none of it:
#ifdef MY_RAYMARCHING_KEYWORD#define POI_RAYMARCHING_DATA#endif -
Add your enable property to the
//ifexlines in that module's templates, so the optimizer can still strip the data from locked materials that use no raymarching feature at all.
You then get the following, guarded by POI_RAYMARCHING_DATA:
| Name | Description |
|---|---|
PoiGetModelThickness(startPos, marchDir) | Distance from a point inside the mesh to where the ray exits, marched through the baked SDF |
PoiUseBindData(poiMesh) | Whether to march in bind space. Forced on, or automatic when the mesh carries bind data |
poiMesh.bindPosition, poiMesh.bindNormal, poiMesh.bindTangent | The bind pose at this fragment |
Best Practices
- Always wrap code in feature guards - Use
#ifdefand//ifexto exclude unused code - Use texture property guards - Only declare textures when they might be used
- Follow naming conventions - Consistent prefixes help organization
- Declare variables in correct sections - Match passes where they're used
- Use appropriate queue values - Lower values execute first
- Test with optimizer enabled - Ensure guards work correctly
- Provide documentation links - Use
button_helpfor tutorials - Prefix every property - Start property names with your module's name (
_MyModule…) so they can't collide with another module's - Put numbers in
_EXPOSED- Floats, vectors and colors go in<PASS>_PROPERTY_VARIABLES_EXPOSED, textures and samplers in<PASS>_PROPERTY_VARIABLES. See Variable Declarations
Example: Simple Color Tint Module
#T#ColorTintProperties
//ifex _EnableColorTint==0
[HideInInspector] m_start_colorTint (" Color Tint--{reference_property:_EnableColorTint}", Float) = 0
[HideInInspector][ThryToggle(POI_COLOR_TINT)]_EnableColorTint ("Enable", Float) = 0
_TintColor ("Tint Color--{reference_property:_TintColorThemeIndex}", Color) = (1, 1, 1, 1)
[HideInInspector][ThryWideEnum(Off, 0, Theme Color 0, 1, Theme Color 1, 2, Theme Color 2, 3, Theme Color 3, 4)] _TintColorThemeIndex ("", Int) = 0
_TintStrength ("Strength", Range(0, 1)) = 1
[HideInInspector] m_end_colorTint ("", Float) = 0
//endex
#T#ColorTintKeywords
//ifex _EnableColorTint==0
#pragma shader_feature_local POI_COLOR_TINT
//endex
#T#ColorTintVariables
//ifex _EnableColorTint==0
#ifdef POI_COLOR_TINT
float4 _TintColor;
float _TintColorThemeIndex;
float _TintStrength;
#endif
//endex
#T#ColorTintFunction
//ifex _EnableColorTint==0
#ifdef POI_COLOR_TINT
void ApplyColorTint(inout PoiFragData poiFragData, in PoiMods poiMods)
{
float3 tint = poiThemeColor(poiMods, _TintColor.rgb, _TintColorThemeIndex);
poiFragData.baseColor.rgb = lerp(poiFragData.baseColor.rgb, poiFragData.baseColor.rgb * tint, _TintStrength);
}
#endif
//endex
#T#ColorTintFunctionCall
//ifex _EnableColorTint==0
#ifdef POI_COLOR_TINT
ApplyColorTint(poiFragData, poiMods);
#endif
//endex
Global Masks System
The shader provides 16 global mask channels (4 textures × 4 RGBA channels) that can be shared between modules.
Mask Indices
| Index | Channel | Index | Channel |
|---|---|---|---|
| 0 | 1R | 8 | 3R |
| 1 | 1G | 9 | 3G |
| 2 | 1B | 10 | 3B |
| 3 | 1A | 11 | 3A |
| 4 | 2R | 12 | 4R |
| 5 | 2G | 13 | 4G |
| 6 | 2B | 14 | 4B |
| 7 | 2A | 15 | 4A |
Using Global Masks
// Reading a global mask (0-indexed)
float mask = poiMods.globalMask[_YourGlobalMaskIndex - 1];
// Writing to a global mask with blending
if (_YourApplyGlobalMaskIndex > 0)
{
applyToGlobalMask(poiMods, _YourApplyGlobalMaskIndex - 1, _YourBlendType, value);
}
// Blend types: Add=7, Subtract=1, Multiply=2, Divide=3, Min=4, Max=5, Average=6, Replace=0
Global Mask Property Pattern
[ThryWideEnum(Off, 0, 1R, 1, 1G, 2, 1B, 3, 1A, 4, 2R, 5, 2G, 6, 2B, 7, 2A, 8, 3R, 9, 3G, 10, 3B, 11, 3A, 12, 4R, 13, 4G, 14, 4B, 15, 4A, 16)] _YourGlobalMask ("Global Mask--{reference_property:_YourGlobalMaskBlendType}", Int) = 0
[HideInInspector][ThryWideEnum(Add, 7, Subtract, 1, Multiply, 2, Divide, 3, Min, 4, Max, 5, Average, 6, Replace, 0)] _YourGlobalMaskBlendType ("Blending", Int) = 2
Vertex Shader Examples
For modules that modify vertices, use the vertex keywords documented in Vertex Modification Keywords above.
Vertex Modification Example
#T#YourVertexFunction
//ifex _YourVertexFeature==0
#ifdef YOUR_VERTEX_KEYWORD
// Access vertex data via 'v' (appdata) and output via 'o' (VertexOut)
v.vertex.xyz += v.normal * _YourOffset;
o.normal = UnityObjectToWorldNormal(v.normal);
#endif
//endex
UV Types
The shader supports multiple UV coordinate sources:
| Value | Type | Description |
|---|---|---|
| 0 | UV0 | Primary UVs |
| 1 | UV1 | Secondary UVs (lightmap) |
| 2 | UV2 | Tertiary UVs |
| 3 | UV3 | Quaternary UVs |
| 4 | Panosphere | Spherical projection |
| 5 | World Pos | World position XZ |
| 6 | Polar UV | Polar coordinates |
| 7 | Distorted UV | Post-distortion UVs |
| 8 | Local Pos | Object-space position |
| 9 | Matcap | View-space matcap UVs |
| 10 | Screen Space | Screen-space UVs |
String Builders (Duplicate Modules)
For accumulating values across duplicate module instances:
// Define a string builder (first instance creates, others append)
<ms_stringbuilder::MY_ACCUMULATED_VALUE>initial_value
// In subsequent instances, append to the builder
<ms_stringbuilder::MY_ACCUMULATED_VALUE>|| additional_value
// Use the accumulated value
#if <ms_stringwriter::MY_ACCUMULATED_VALUE>
// Code using the combined condition
#endif
Example from Emission module:
<ms_include_in_first>
{
<ms_stringbuilder::_ANY_EMISSION_KEYWORD>defined(_EMISSION)
}
<ms_include_in_not_first>
{
<ms_stringbuilder::_ANY_EMISSION_KEYWORD>|| defined(POI_EMISSION___mID__)
}
Animation Optimization
Use isNotAnimated() to skip code when properties aren't animated:
//ifex isNotAnimated(_YourProperty) && _YourProperty==0
// This code is excluded if _YourProperty is 0 AND not animated
//endex
This allows the optimizer to remove code paths that will never be used at runtime.
VRChat-Specific Functions
// Mirror detection
float VRCMirrorMode(); // Returns >0 if in VRC mirror
bool IsInMirror(); // Generic mirror detection
// Camera detection (VRC only)
float VRCCameraMode(); // Returns >0 if in VRC camera
// Usage
if (VRCMirrorMode() > 0)
{
// In mirror rendering
}
Troubleshooting
Common Issues
-
Module not appearing in shader
- Verify the module is added to the appropriate ModuleCollection
- Check that the GUID references in the .asset file are correct
- Ensure Unity has reimported the meta files
- For a Third Party module, make sure it's outside the Poiyomi folder, and that it has been installed from the Third Party section of a material
- Check your keywords for typos, since a misspelled keyword is skipped without an error
-
Properties not showing in material
- Check
//ifexconditions match property values - Verify
m_start_andm_end_markers are properly paired - Ensure
reference_propertypoints to a valid toggle
- Check
-
Shader compilation errors
- Check for missing
#endifor//endexclosures - Verify variable declarations are in the correct pass sections
- Ensure texture samplers are properly guarded with
PROP_checks
- Check for missing
-
Optimizer stripping needed code
- Use
isNotAnimated()checks for animated properties - Verify
//ifexconditions correctly reflect property states - Check that shader features use
shader_feature_localfor optimization
- Use
-
Code running in wrong passes
- Verify keywords match the intended passes (BASE, ADD, SHADOW, etc.)
- Check queue values don't conflict with other modules
- Use pass-specific defines like
POI_PASS_BASEfor conditional code
Debugging Tips
- Use the Debug module to visualize values
- Turn on the DEBUG section (
_DEBUGEnabled) to access debug output - Check the generated shader code in the Shaders folder after generation
- Test with optimizer both enabled and disabled
Development Workflow
Auto-Rebuild Shaders
When developing modules, enable automatic shader rebuilding to see changes immediately:
- Go to
Poi -> Modular Shaders Generator - Check the checkbox next to the shader(s) you want to auto-rebuild
- The shader will now regenerate whenever you modify module files
The generator window shows all available shader variants with their source module definitions. You can also manually trigger rebuilds by clicking Generate Shaders.
For a module installed from Third Party, editing any of its files makes Third Party show an Update row marked "new changes". Click it to rebuild with your edits. See The Development Loop.
Shader Output Destinations
Each shader has configurable output settings:
- Destination - Output folder for generated shader files
- Shader Name Match - Filter which shaders get generated (StartsWith, Always, etc.)
- Version Override - Custom version number for the generated shader
Adding Modules to Shaders
There are two ways a module ends up in a shader:
- Third Party modules are installed from the Third Party section of any Poiyomi material. No collection asset needs editing. See Third Party.
- Core modules are included via Module Collections. Add your module reference to the appropriate collection asset (e.g.,
ModuleCollectionPro.asset) or create a custom shader definition that includes your module.
Shipping a Module
Export both files as a .unitypackage, plus your icon if you set one. Nothing else is needed: no folder requirements and no manifest. Importing it anywhere in a project makes it appear in the Third Party section of every Poiyomi material, ready to install.
To ship an update, export the same files again. When someone imports the newer version, Third Party shows an Update button that rebuilds with it. Bump Version so the button can show which version they're moving to.
See Shipping A Custom Module for what to leave out of the export, and why the .meta files matter.
Additional Resources
- ThryEditor Attributes
- Third Party
- Existing modules in
Poi_FeatureModules/serve as excellent references. These are small, complete examples inModularShader/Editor/Poi_FeatureModules/Toon/:Poi_VertexColors: The minimal shape. Four sections, a color hook, and nothing elsePoi_Backlight: A lighting module usingfinalLightAdd, with textures and a shader keywordAL_Modules/Poi_ALDecals: A large one, with sub-sections, masks and blend modes