Skip to main content

FAQ / Troubleshooting

This is a list of Frequently Asked Questions regarding Poiyomi Shaders. If you are having trouble with certain issues in Poiyomi Shaders, refer to this page.

Poiyomi Shaders

What is the Poiyomi Shaders Terms of Service?

A dedicated page is available which shows important information about the usage of the Shader. Please see Terms of Service for more details.

I'm trying to import a version that's in-between the versions the Unity Package specifies. How do I install them?

If you download a package with 2 revision numbers, that package contains all in-between versions as standard.

For example, if you import 7.3-9.0, it will include all 7.3/8.0/8.1/9.0 versions.

If an Avatar Base asks for a specific version, will it still work if I import a version that is slightly newer?

It is always recommended to use the latest version of the Shader. If an Avatar Base asks for something like 9.0.52 and you are importing 9.0.57, it is expected to still work perfectly fine as it's just a patch-version increase.

I am receiving Errors when attempting to use Poiyomi Shaders. What should I do?

If you are having issues with Poiyomi Shaders such as the Material Inspector not working properly, please follow these troubleshooting steps in the following order:

  1. Delete the _PoiyomiShaders Folder from your Assets entirely.
  2. Download the latest version of the Package if you haven't already.
  3. Import the Unity Package.

This should help solve most issues with the Shader not behaving as expected in Unity, including issues with double-importing the Shader from an Avatar that included the Shader when it wasn't supposed to.

If you are still running into issues, post some screenshots in the Discord and we'll be happy to help you out.

When I Upload an Avatar, I get a message saying "Unlocked Shaders were found and will not be included in the build."

This message indicates there was a problem with the Auto-Lock function. For context, your Materials must be locked in order to upload to VRChat in order to prevent unused features from being included.

If this function fails to work and you get that message, ensure there are no scripts interfering with the Upload. Some tools and certain optimizers can interfere with this, even though they're not supposed to.

  • Remove any third-party tools and Packages you suspect are interfering until the message no longer appears when uploading. If you find the culprit issue, we encourage you to inform the creator of said scripts/utilities that are interfering with the Auto-Lock so that it doesn't happen again.
Manual Lock-In

Try manually Locking your Materials before uploading. You can do this by Right-Click on your Avatar in the Hierarchy, followed by Thry -> Materials -> Lock All in the context menu. This function will Lock ALL Poiyomi Materials found on your Avatar.

How do I upgrade Poiyomi Shaders to a newer version?

To upgrade the shader, refer to the instructions found in Download & Install for the Method you used when you first installed the Shader.

Sometimes when updating your locked materials may get stuck in the locked state. This happens because the name of the shader changed. Avoid this by unlocking materials before updating. To Fix this, reselect the correct Poiyomi shader for the broken materials.

I'm trying to animate a property in the Material which kind of works, but it STOPS working when the Material gets Locked. What can I do?

You need to mark properties that you are animating by Right-Clicking on them and selecting Animated or Renamed, which are specific tags that ensure the property remains accessible when the Shader is locked. For more information, see the Documentation page Locking and Animation for further reading.

Keep in mind that properties marked as Renamed will only work when the Material is Locked. Make sure you Lock the Material prior to recording your animations!

Animation Tags

Where do AO Maps go in Poiyomi Shaders?

Place AO (Ambient Occlusion) Maps in the AO Maps Texture Slot, located in Shading -> Light Data.'

It is recommended to use a Lighting Type that supports AO Maps. Most of them (except for Flat) will work with AO Maps.

Where does Height Maps go in Poiyomi Shaders?

Height maps are generally used to change the shape of the surface of a material. Generally, if it's small displacements, You can often get the same detail by using a Normal Map (make sure your shading is set to something other than Flat, though!).

If you have a height map but not a normal map, you can convert it in Unity by setting the texture to a Normal map and selecting "Convert from Grayscale".

If you need the displacement, you can use it with Parallax Heightmapping, which creates a displacement-like effect. You can also use a shader that tessellates, which will add geometry to create the height detail.

Vertex Displacement takes a height map, but it's limited to the vertex density on the mesh, and often will not provide the desired results.

What is the difference between Roughness vs. Smoothness Maps?

Roughness and Smoothness have the same information, just flipped!

You can invert it in an image editor or use the invert checkboxes.

For v8+, Roughness goes in Reflections & Specular.

Open Packed Maps by clicking on the triangle and place the Roughness in the G Smoothness Map slot. It is important that you checkmark Invert so that it matches the Unity PBR Shading Pipeline. Refer to the Documentation Page for more information.

You will need to install the AudioLink Package into your Project. Read the Documentation Page for instructions here.

I am using a feature that is supposed to animate, but it doesn't show it's animating. Why is that?

In order to preview animations from Poiyomi Materials (such as Glitter or continuous Hue Shift) outside of Play Mode, you must toggle on this button/option in your Scene View:

Material Animations Toggle

Can I use Poiyomi Shaders in World Projects?

Yes! Make sure to select .poiyomi/Poiyomi Toon World as the shader so that it can receive and contribute to Global Illumination. This special shader variant includes all features in the Free version, with one minor difference; it exposes a category called Shading -> Baked Lighting that houses all the GI settings.

You may want to consider setting it to Realistic Shading from the Shading settings so that it can look it’s best with Baked Lighting.

I've un-tagged a property that I don't want to be animated, but it still animates regardless. Why does it still animate while in Play Mode?

You may have left the Material Unlocked. When a Material is Unlocked, all animated properties, regardless of it's animation tag, are still exposed in Play Mode.

To test your Animator against animated properties that are no longer tagged with A or RA, Lock your Material(s) prior to starting Play Mode.

Unity Editor

Why does Unity Editor constantly crash when editing the Shader?

You may be encountering the so-called "64 Crash" issue. This refers to a longtime Unity issue where if you reach or exceed 64 Texture Slots, the Editor will outright crash regardless if there's a texture or not in the slots.

This can happen when you have a large number of materials using Poiyomi while unlocked, with many different sections enabled.

To circumvent this issue, you can lock materials when not in use, as that will generate unique shaders for each material.

More information documented here.

Why does lighting change randomly while moving in a World?

Without setting an Anchor Override on the meshes, Unity can sample the world's lighting from unwanted spots. This can lead to undesired behavior with your Avatar's Lighting.

To fix this, we recommend assigning a Bone (such as the Chest) from your Armature into the Anchor Override on all Meshes.

ThryEditor will run this automatic fix to you if there's no Anchor Override set. A one-time "Bad Lighting Fix" message will appear when Uploading for the first time. We recommend you to keep it enabled when prompted.

Why can't I use Poiyomi Shaders on Quest?

You can only use the VRChat mobile shaders that come with the SDK on your Quest/Android Avatars!

Quest and Android hardware is underpowered and doesn't support features that Poiyomi Shaders need to work properly. Even if you managed to upload an avatar with unsupported shaders on it, the VRChat client will override them at runtime.


As of May 2024, we recommend VRChat SDK v3.5.0 or newer in order to use Poiyomi Shaders.

For the Unity Version, we currently actively support Unity 2022. To learn what specific version you should use, refer to the VRC Creators Documentation.

Other Resourceful Info

How can I test my Lighting in the Unity Editor, without having to Upload and test in the VRChat Client?

We recommend Haï Lightbox Viewer, a Utility that simulates your Avatar's Shading and Lighting Behavior in various different Scenes, all at once. This is an excellent tool that can give a visual representation of how your Shading and Lighting setup is expected to be shown as in the client.

You can download Haï Lightbox Viewer here.

Why does my Avatar get super bright in some Worlds?

This is generally because of additive lights which add up. If you want to set a max overall brightness for additive lights, hit the preset button at the top left and select maximum add intensity of 1. You can change the max value in the light data section.

Curated Tools

Here is a list of recommended plugins and tools that we use when building our Avatars, with or without Poiyomi Toon Shader:


  • Haï Lightbox Viewer: Test your Avatar’s lighting behavior in the Unity Editor. Highly Recommended for testing Poiyomi’s lighting behavior in various conditions! Download Haï Lightbox Viewer

  • Gesture Manager: A lightweight and powerful Emulator, allowing you to test your Avatar’s animations and toggles directly in the Editor. Download Gesture Manager

  • Thry’s VRC Avatar Performance Tools: Texture Memory calculator that measures the VRAM consumption of your Avatar’s Textures, exposing greater detail on how your Avatar impacts other users in VRChat. Download VRC Avatar Performance Tools

Other Awesome Tools: