Skip to main content
Version: 11.0

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.

Complex Information Ahead!

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:

  1. Module Definition (.asset) - YAML file defining module metadata and template references
  2. 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.

tip

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​

PrefixType
VRLM_Module Definition (asset)
VRLT_Single Template (poiTemplate)
VRLTC_Template Collection (poiTemplateCollection)

Key Fields​

FieldDescription
IdUnique identifier for the module. Must be unique across the whole project, since dependencies and conflicts use it
Name, Version, Author, DescriptionShown 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
IconOptional texture shown at the start of that row. Without one, a puzzle piece is shown
ModuleDependenciesIds of modules that must also be installed
IncompatibleWithIds of modules that can't be installed alongside this one
AllowDuplicatesWhether the same module can appear more than once. See Duplicate Module Support
TemplatesReferences to template sections with keyword mappings
QueueSet 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​

SectionKeywordHolds
PropertiesOne UI sectionShader properties, which make up the inspector UI
Variables<PASS>_PROPERTY_VARIABLES_EXPOSEDNumeric declarations such as float _MyThing;
FunctionsFRAGMENT_<PASS>_FUNCTIONSYour function definitions
Function CallsA hook pointThe call that runs your function

Top-Level Shader Structure​

These keywords define the overall shader structure and pass ordering:

KeywordDescription
SHADER_TAGSShader-level tags and properties
DEPTH_NORMALS_PASSDepth normals pass injection
GRAB_PASSGrab pass for screen effects
DEPTH_ONLY_PASSDepth only (early Z) pass
EARLY_OUTLINE_PASSEarly outline pass (before base)
BASE_PASSMain forward base pass
ADD_PASSAdditive lighting pass
SELF_GRAB_PASSSelf grab pass
BASE_PASS_TWOSecond base pass (two-pass shaders)
ADD_PASS_TWOSecond additive pass
OUTLINE_PASSOutline rendering pass. The lil Fur passes are injected here too
SHADOW_PASSShadow casting pass
META_PASSLightmapping/GI meta pass
MOTION_VECTORS_PASSMotion 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:

KeywordAppears As
MAIN_PROPERTIESColor & Normals
2NDPASS_PROPERTIES2nd Pass (Two Pass shaders only)
OUTLINE_PROPERTIESOutlines
LIGHTING_PROPERTIESShading
SPECIALFX_PROPERTIESSpecial FX
RAYMARCHING_PROPERTIESRaymarching
VERTEX_PROPERTIESVertex Options
GRABPASS_PROPERTIESGrab Pass (Grab Pass shaders only)
GLOBAL_PROPERTIESGlobal Modifiers & Data -> Global Data and Masks
UV_PROPERTIESGlobal Modifiers & Data -> UVs
POSTPROCESSING_PROPERTIESGlobal Modifiers & Data -> Post Processing
MODIFIER_PROPERTIESGlobal Modifiers & Data
EXTRAS_PROPERTIES(No header, added as-is)
THIRDPARTY_PROPERTIESThird Party
RENDERING_PROPERTIESRendering

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:

KeywordDescription
PRAGMA_DIRECTIVESShader pragma statements
REQUIREMENTSShader requirements/features
SHADER_KEYWORDSShader feature keywords
MACROS_AND_DEFINESPreprocessor macros and defines
INCLUDESInclude file directives

Pass-Specific Pragma & Keywords​

Each pass type has its own keyword and pragma injection points:

PassKeywordsPragma Programs
BaseBASE_PASS_KEYWORDSBASE_PASS_PRAGMA_PROGRAMS
AddADD_PASS_KEYWORDSADD_PASS_PRAGMA_PROGRAMS
ShadowSHADOW_PASS_KEYWORDSSHADOW_PASS_PRAGMA_PROGRAMS
MetaMETA_PASS_KEYWORDSMETA_PASS_PRAGMA_PROGRAMS
OutlineOUTLINE_PASS_KEYWORDSOUTLINE_PASS_PRAGMA_PROGRAMS
Depth (Depth Only and Depth Normals)DEPTH_PASS_KEYWORDSDEPTH_PASS_PRAGMA_PROGRAMS
LilFurLILFUR_PASS_KEYWORDSLILFUR_PASS_PRAGMA_PROGRAMS
Base TwoBASE_PASS_TWO_KEYWORDSBASE_PASS_TWO_PRAGMA_PROGRAMS
Add TwoADD_PASS_TWO_KEYWORDSADD_PASS_TWO_PRAGMA_PROGRAMS
Self GrabSELF_GRAB_PASS_KEYWORDS-
Motion Vectors (URP only)MOTION_VECTORS_PASS_KEYWORDSMOTION_VECTORS_PASS_PRAGMA_PROGRAMS

Stencil Injection Points​

KeywordPass
BASE_PASS_STENCILBase pass stencil settings
ADD_PASS_STENCILAdd pass stencil settings
SHADOW_PASS_STENCILShadow pass stencil settings
META_PASS_STENCILMeta pass stencil settings
DEPTH_PASS_STENCILDepth only and depth normals stencil settings
MOTION_VECTORS_PASS_STENCILMotion vectors stencil settings (URP only)
BASETWO_PASS_STENCILBase two pass stencil
ADDTWO_PASS_STENCILAdd 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_EXPOSED holds numeric uniforms: floats, vectors and colors. In URP it sits inside the UnityPerMaterial cbuffer.
  • <PASS>_PROPERTY_VARIABLES holds Texture2D and sampler declarations, which must stay outside that cbuffer.
PassNumbers, Vectors & ColorsTextures & Samplers
BaseBASE_PROPERTY_VARIABLES_EXPOSEDBASE_PROPERTY_VARIABLES
AddADD_PROPERTY_VARIABLES_EXPOSEDADD_PROPERTY_VARIABLES
ShadowSHADOW_PROPERTY_VARIABLES_EXPOSEDSHADOW_PROPERTY_VARIABLES
MetaMETA_PROPERTY_VARIABLES_EXPOSEDMETA_PROPERTY_VARIABLES
OutlineOUTLINE_PROPERTY_VARIABLES_EXPOSEDOUTLINE_PROPERTY_VARIABLES
DepthDEPTH_PROPERTY_VARIABLES_EXPOSEDDEPTH_PROPERTY_VARIABLES
LilFurLILFUR_PROPERTY_VARIABLES_EXPOSEDLILFUR_PROPERTY_VARIABLES
Base TwoBASETWO_PROPERTY_VARIABLES_EXPOSEDBASETWO_PROPERTY_VARIABLES
Add TwoADDTWO_PROPERTY_VARIABLES_EXPOSEDADDTWO_PROPERTY_VARIABLES
Self GrabSELF_GRAB_PROPERTY_VARIABLES_EXPOSEDSELF_GRAB_PROPERTY_VARIABLES
Motion Vectors (URP only)MOTION_VECTORS_PROPERTY_VARIABLES_EXPOSEDMOTION_VECTORS_PROPERTY_VARIABLES

Vertex Shader Keywords​

Vertex program injection points (per pass - replace BASE with pass name):

KeywordStage
VERTEX_BASE_DATA_STRUCTURESVertex data structure definitions
VERTEX_BASE_FUNCTIONS_EARLYEarly vertex function definitions
VERTEX_BASE_FUNCTIONSMain vertex function definitions
VERTEX_BASE_FUNCTIONS_LATELate vertex function definitions
VERTEX_BASE_PROGRAMMain vertex program code

Vertex Modification Keywords​

These keywords are used within the vertex program for modifying vertex data:

KeywordTimingDescription
VERTEX_INPUT_MODSVery earlyModify input vertex data
VERTEX_MODS_EARLYEarlyEarly vertex modifications
VERTEX_MODSMainPrimary vertex modifications
VERTEX_MODS_LATELateLate vertex modifications
VERTEX_MODS_PENETRATIONPost-offsetTPS/DPS penetration systems
VERTEX_MODS_PRE_CLIPPOSBefore clipBefore clip position calculation
VERTEX_MODS_POST_CLIPPOSAfter clipAfter clip position calculation
VERTEX_MODS_LILFURFur-specificLilFur vertex modifications
VERTEX_MODS_FINALFinalFinal vertex modifications
vertexOutDataData structAdditional vertex output data

Geometry & Tessellation Keywords​

KeywordDescription
HULLDOMAIN_BASE_PROGRAMHull/Domain shader for base pass
HULLDOMAIN_ADD_PROGRAMHull/Domain shader for add pass
HULLDOMAIN_SHADOW_PROGRAMHull/Domain shader for shadow pass
HULLDOMAIN_META_PROGRAMHull/Domain shader for meta pass
HULLDOMAIN_DEPTH_NORMALS_PROGRAMHull/Domain shader for depth normals
HULLDOMAIN_DEPTH_ONLY_PROGRAMHull/Domain shader for depth only
HULLDOMAIN_LILFUR_PROGRAMHull/Domain shader for LilFur
HULLDOMAIN_MOTION_VECTORS_PROGRAMHull/Domain shader for motion vectors (URP only)
GEOMETRY_BASE_PROGRAMGeometry shader for base pass
GEOMETRY_ADD_PROGRAMGeometry shader for add pass
GEOMETRY_SHADOW_PROGRAMGeometry shader for shadow pass
GEOMETRY_META_PROGRAMGeometry shader for meta pass
GEOMETRY_DEPTH_NORMALS_PROGRAMGeometry shader for depth normals
GEOMETRY_DEPTH_ONLY_PROGRAMGeometry shader for depth only (early Z)
GEOMETRY_LILFUR_PROGRAMGeometry shader for LilFur
GEOMETRY_MOTION_VECTORS_PROGRAMGeometry shader for motion vectors (URP only)

Fragment Shader Keywords​

Fragment program injection points (per pass - replace BASE with pass name):

KeywordStage
FRAGMENT_BASE_DATA_STRUCTURESFragment data structure definitions
FRAGMENT_BASE_FUNCTIONS_EARLYEarly fragment function definitions
FRAGMENT_BASE_FUNCTIONSMain fragment function definitions
FRAGMENT_BASE_FUNCTIONS_LATELate fragment function definitions
FRAGMENT_BASE_PROGRAMMain 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.

KeywordRunsPasses
FRAGMENT_BASE_DECLARATIONSStructs are declared here. Don't target thisAll
FRAGMENT_BASE_INIT_EARLYBefore mesh data is filled inAll
FRAGMENT_BASE_INITMesh, light and camera data gets filled inAll
FRAGMENT_BASE_INIT_LATEAfter setup, before any colorAll
FRAGMENT_BASE_COLOR_EARLYBefore the main textureAll
FRAGMENT_BASE_COLORMain texture and decals. The usual choiceAll
FRAGMENT_BASE_COLOR_LATEAfter all color workAll
FRAGMENT_BASE_LIGHTING_EARLYBefore the lighting modelAll except Depth, Motion Vectors and Self Grab
FRAGMENT_BASE_LIGHTINGAlongside the lighting modelAll except Depth, Motion Vectors and Self Grab
FRAGMENT_BASE_LIGHTING_LATEAfter the lighting modelAll except Depth, Motion Vectors and Self Grab
FRAGMENT_BASE_LIGHTING_ADDAdding light on top, such as rim lights and glowsBase, Add, Meta, Outline and LilFur
FRAGMENT_BASE_EMISSION_EARLYEarly emissionAll except Depth, Motion Vectors and Self Grab
FRAGMENT_BASE_EMISSIONMain emission calculationsAll except Depth, Motion Vectors and Self Grab
FRAGMENT_BASE_EMISSION_LATELate emission effectsAll except Depth, Motion Vectors and Self Grab
FRAGMENT_BASE_RETURNLast change before alpha cutoutAll
FRAGMENT_BASE_ALPHA_LATEAfter clippingBase, 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​

KeywordDescription
POI_MESH_PROPERTIESPoiMesh struct properties
POI_CAM_PROPERTIESPoiCam struct properties
POI_LIGHT_PROPERTIESPoiLight struct properties
MESH_DATA_INITMesh data initialization
MESH_DATA_POST_INITPost mesh initialization
MAIN_TEXTURE_SAMPLEMain texture sampling
FRAGMENT_NORMAL_CALCULATIONNormal calculation
CAMERA_DATA_INITCamera data initialization

Feature-Specific Keywords​

Some modules expose their own injection points:

KeywordModuleDescription
MAIN_COLOR_MODMainBase color modification
TANGENT_NORMAL_INJECTIONMainNormal map injection
BASE_LIGHTDATA_MODLight DataLight data modification
BASE_AFTER_ATTENUATIONLight DataAfter attenuation calculation
BASE_REALISTIC_MODShadingRealistic shading modifications
MOCHIE_METALLIC_SMOOTHNESS_MODMetallicsMetallic/smoothness mods
POI_EMISSION0_MODSEmissionEmission 0 modifications
LILFUR_TWO_PASS_PROPSLilFurFur 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:

QueueUsed For
NegativeBefore core setup
0Core infrastructure, such as data structures and init
1–99Features that must run before the bulk
100Default. Most features
101–999Features 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:

StructUseful Fields
PoiFragData poiFragDatabaseColor, finalColor, alpha, emission, smoothness, metallic
PoiMesh poiMeshuv[11], normals[2], worldPos, localPos, vertexColor, isFrontFace, tangent[2]
PoiLight poiLightfinalLightAdd, direction, directColor, indirectColor, lightMap, nDotL, attenuation
PoiCam poiCamCamera position and vectors
PoiMods poiModsglobalEmission 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:

AttributePurpose
[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.

warning

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);
#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​

info

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:

  1. Add Poi Raymarching Data to your ModuleDependencies.

  2. 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
  3. Add your enable property to the //ifex lines 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:

NameDescription
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.bindTangentThe bind pose at this fragment

Best Practices​

  1. Always wrap code in feature guards - Use #ifdef and //ifex to exclude unused code
  2. Use texture property guards - Only declare textures when they might be used
  3. Follow naming conventions - Consistent prefixes help organization
  4. Declare variables in correct sections - Match passes where they're used
  5. Use appropriate queue values - Lower values execute first
  6. Test with optimizer enabled - Ensure guards work correctly
  7. Provide documentation links - Use button_help for tutorials
  8. Prefix every property - Start property names with your module's name (_MyModule…) so they can't collide with another module's
  9. 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​

IndexChannelIndexChannel
01R83R
11G93G
21B103B
31A113A
42R124R
52G134G
62B144B
72A154A

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:

ValueTypeDescription
0UV0Primary UVs
1UV1Secondary UVs (lightmap)
2UV2Tertiary UVs
3UV3Quaternary UVs
4PanosphereSpherical projection
5World PosWorld position XZ
6Polar UVPolar coordinates
7Distorted UVPost-distortion UVs
8Local PosObject-space position
9MatcapView-space matcap UVs
10Screen SpaceScreen-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​

  1. 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
  2. Properties not showing in material

    • Check //ifex conditions match property values
    • Verify m_start_ and m_end_ markers are properly paired
    • Ensure reference_property points to a valid toggle
  3. Shader compilation errors

    • Check for missing #endif or //endex closures
    • Verify variable declarations are in the correct pass sections
    • Ensure texture samplers are properly guarded with PROP_ checks
  4. Optimizer stripping needed code

    • Use isNotAnimated() checks for animated properties
    • Verify //ifex conditions correctly reflect property states
    • Check that shader features use shader_feature_local for optimization
  5. 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_BASE for 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:

  1. Go to Poi -> Modular Shaders Generator
  2. Check the checkbox next to the shader(s) you want to auto-rebuild
  3. 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 in ModularShader/Editor/Poi_FeatureModules/Toon/:
    • Poi_VertexColors: The minimal shape. Four sections, a color hook, and nothing else
    • Poi_Backlight: A lighting module using finalLightAdd, with textures and a shader keyword
    • AL_Modules/Poi_ALDecals: A large one, with sub-sections, masks and blend modes