Troubleshooting

Common Issues and Solutions

---

Table of Contents

1. Installation Issues
2. Effect Not Visible
3. Visual Artifacts
4. Performance Issues
5. Pipeline-Specific Issues
6. Shader Errors
7. Editor Issues
8. FAQ

---

Installation Issues

Package won’t import

Symptoms:

• Import fails with errors
• Missing scripts after import

Solutions:

1. Check Unity version - CelShaderFX requires Unity 2021.3 or later
2. Close and reopen Unity - Sometimes Unity needs a restart
3. Delete Library folder - Force reimport:
4. • Close Unity
   • Delete Library folder in project root
   • Reopen Unity

Missing assembly references

Symptoms:

• The type or namespace ‘CelShaderFX’ could not be found

Solutions:

1. Check Assembly Definitions - Ensure your scripts reference the CelShaderFX assembly
2. Reimport package - Right-click CelShaderFX folder > Reimport

---

Compile errors after updating from v2.0.x to v2.1

Symptoms:

• After importing the v2.1 update over an existing v2.0.x install, the Console shows CS0266 errors such as:

(the same error may also mention KuwaharaVariant or XDoGThresholdMode)

```
Assets\CelShaderFX\Editor\CelShaderDefaultPresetGenerator.cs(...): error CS0266:
Cannot implicitly convert type 'CelShaderFX.CelShaderSettings.DitheringMode'
to 'CelShaderFX.DitheringSettings.DitheringMode'. An explicit conversion exists
(are you missing a cast?)
```

Cause:

CelShaderDefaultPresetGenerator.cs is an internal preset-authoring tool that shipped in v2.0.x but was removed from the v2.1 package. Unity’s importer never deletes files that are absent from an update, so the old copy stays in your project. v2.1 reorganized the effect settings into per-module groups, and the leftover v2.0.x tool references the old type locations - producing these errors. This does not affect the shader or your scenes; it is only the orphaned editor tool that fails to compile.

Solution:

1. In the Project window, open Assets/CelShaderFX/Editor/
2. Delete CelShaderDefaultPresetGenerator.cs (Unity removes its .meta automatically)
3. Let Unity recompile - the errors clear

This is an internal tool only; removing it has no effect on the effect, your presets, or anything at runtime.

Will I lose the ability to use presets? No. The ready-made presets ship as pre-built assets in CelShaderFX/Resources/DefaultPresets/ (browse them via Tools > CelShaderFX > Open Preset Browser) and remain in your project. Deleting the generator only removes the authoring tool, not the presets. If you ever delete or lose the preset assets themselves, restore them by reimporting CelShaderFX from the Package Manager (My Assets) - that brings back the full set; the generator is not needed for recovery.

Thorough alternative: to clear any other leftovers from the old version in one pass, back up any custom presets, delete the entire Assets/CelShaderFX folder, and reimport v2.1 from the Package Manager.

Effect Not Visible

Effect not showing at all

Checklist:

• Component/Volume added to camera or scene?
• Settings asset assigned?
• At least one effect enabled?
• Effect intensity > 0?
• Correct render pipeline setup?

Built-In Pipeline

Issue: No effect visible with CelPostProcessEffect

Solutions:

1. Check camera - Component must be on the active camera
2. Check settings - Ensure a CelShaderSettings asset is assigned
3. Check enable flags - At least one effect must be enabled:

settings.enableCelShading = true;
// or
settings.enableOutline = true;

Built-In Setup

URP

Issue: No effect visible in URP

Solutions:

1. Add Renderer Feature:
2. • Select your URP Renderer Asset
   • Click “Add Renderer Feature”
   • Add “Cel Render Feature”
3. Create Volume:
4. • Create GameObject with Volume component
   • Set Mode to “Global”
   • Add CelVolumeComponent override
5. Enable overrides:
6. • Check the box next to each parameter group
   • Enable specific effects

URP Setup

URP Setup

HDRP

Issue: No effect visible in HDRP

Solutions:

1. Register post-process:
2. • Edit > Project Settings > HDRP Default Settings
   • Custom Post Process Orders > After Post Process
   • Add “CelCustomPostProcess”
3. Create Volume:
4. • Same as URP setup

HDRP Registration

Effect only partial

Issue: Some effects work, others don’t

Solutions:

1. Check individual enable flags - Each effect has its own toggle
2. Check intensity values - 0 intensity = invisible
3. Check shader keywords - Some effects require specific shader variants

---

Visual Artifacts

Hatching “swimming” / jittering

Symptoms:

• Hatching lines move when camera moves
• Lines don’t stick to surfaces

Solutions:

1. Increase World Space Weight:

World Space Weight: 0.7
View Space Weight: 0.2
Screen Space Weight: 0.1

1. Enable Temporal Stability:
2. • Increase Temporal Stability parameter (0.8-1.0)
3. Use Blended Mode:
4. • Set Hatching Mode to “Blended”

Outline flickering

Symptoms:

• Outlines appear and disappear
• Inconsistent edge detection

Solutions:

1. Adjust thresholds:
2. • Lower Depth Threshold for more consistent depth edges
   • Adjust Normal Threshold for surface angle sensitivity
3. Check depth buffer:
4. • Ensure camera has depth texture enabled
   • In URP: Check “Depth Texture” in URP Asset
5. Distance fade:
6. • If flickering at distance, increase Distance Fade

Banding / color steps visible

Symptoms:

• Harsh visible steps between cel shading bands
• Not smooth enough transitions

Solutions:

1. Increase softness:

Cel Softness: 0.1 - 0.2 (instead of 0.05)

1. Increase band count:

Band Count: 6-8 (instead of 3-4)

1. Add dithering:
2. • Enable subtle dithering to break up bands

Z-fighting / depth issues

Symptoms:

• Outlines on wrong objects
• Effects applied incorrectly

Solutions:

1. Check near/far planes:
2. • Camera near plane not too small (> 0.1)
   • Far plane not too large
3. Adjust depth threshold:
4. • Increase Depth Threshold if too many false edges

---

Performance Issues

Low framerate

Symptoms:

• FPS drops significantly with effects enabled
• GPU usage very high

Solutions:

1. Reduce Kuwahara radius:

Radius: 2-3 (instead of 5+)

Radius	Relative Cost
2	1x
4	4x
6	9x

1. Use Basic Kuwahara variant:
2. • Basic is fastest
   • Anisotropic is slowest
3. Reduce hatching layers:

Layers: 2 (instead of 4)

1. Disable unused effects:
2. • Toggle off any effect you’re not using
3. Use quality presets:
4. • Mobile/Low preset for weaker hardware

Mobile performance

Solutions:

1. Disable Kuwahara - Too expensive for most mobile
2. Use simpler outline method - Sobel is fastest
3. Reduce texture sizes - Use smaller TAM textures
4. Lower resolution - Consider render scale < 1.0

Shader compilation stutters

Symptoms:

• Freezes when effects are first enabled
• Hitches during gameplay

Solutions:

1. Warm up shaders:

// In loading screen
Shader.WarmupAllShaders();

1. Use shader preloading:
2. • Add shaders to Graphics Settings > Preloaded Shaders

---

Pipeline-Specific Issues

URP: Depth texture not available

Symptoms:

• Outlines don’t work
• Depth-based effects fail

Solutions:

1. Enable depth texture:
2. • Select URP Asset
   • Check “Depth Texture” option

URP: Effect renders twice

Symptoms:

• Double effect intensity
• Performance worse than expected

Solutions:

1. Check for duplicate Volumes
2. Check Renderer Feature isn’t added twice
3. Ensure only one CelRenderFeature exists

HDRP: Effect not in correct order

Symptoms:

• Effect appears before/after other post-effects unexpectedly

Solutions:

1. Adjust injection point:
2. • HDRP Settings > Custom Post Process Orders
   • Move CelCustomPostProcess to desired position

Different appearance across pipelines

Symptoms:

• Effect looks different in URP vs Built-In

Solutions:

1. Check color space:
2. • All pipelines should use same color space (Linear recommended)
3. Check Volume settings:
4. • URP/HDRP use Volumes - ensure settings match
5. HDR differences:
6. • HDRP uses HDR - values may need adjustment

---

Shader Errors

“Shader not found”

Error:

CelModularController: Could not find cel shader!

Solutions:

1. Check shader path:
2. • Ensure shaders exist in CelShaderFX/Runtime/Shaders/
3. Reimport shaders:
4. • Right-click shader folder > Reimport
5. Check for correct pipeline:
6. • Built-In uses different shader than URP/HDRP

Shader compilation errors

Error:

Shader error in 'Hidden/CelShaderFX/...': ...

Solutions:

1. Check Unity version - Some features require newer Unity
2. Check render pipeline version - Ensure compatible URP/HDRP version
3. Check include paths - Shader includes must be correct

Pink/magenta materials

Symptoms:

• Screen turns pink
• Objects render pink

Solutions:

1. Shader not compiled:
2. • Reimport shaders
   • Check for compilation errors in Console
3. Wrong pipeline:
4. • Ensure correct shader variant for your pipeline

---

Editor Issues

Inspector not updating

Symptoms:

• Changes in Inspector don’t reflect in Scene view
• Need to toggle effect off/on

Solutions:

1. Force refresh:

// Call this after changing settings
effect.RefreshMaterial();

1. Check auto-apply:
2. • CelModularController: Ensure Auto Apply Changes is enabled

Preview window not working

Symptoms:

• Preview Window shows black/nothing
• Can’t see effect preview

Solutions:

1. Check camera:
2. • Preview needs an active camera in scene
3. Check effect setup:
4. • Effect must be properly configured first

Preset browser empty

Symptoms:

• No presets showing in Preset Browser

Solutions:

1. Check Resources folder:
2. • Presets should be in CelShaderFX/Resources/DefaultPresets/
3. Reimport presets:
4. • Right-click DefaultPresets folder > Reimport

---

FAQ

Q: Can I use multiple CelShaderFX components?

A: Generally no. Use one controller per camera. For different effects on different objects, use the Object Exclusion system.

Q: Does CelShaderFX work with VR?

A: Yes, but:

• Use Single Pass Instanced rendering for best performance
• Test Kuwahara radius carefully - VR requires high framerates
• Some effects may need per-eye adjustment

Q: Can I use CelShaderFX with other post-processing?

A: Yes. CelShaderFX works alongside:

• Unity Post Processing Stack v2
• URP Post Processing
• HDRP Post Processing
• Third-party effects

Order in the stack matters - adjust to get desired look.

Q: Why are my custom TAM textures not working?

A: Check:

1. Texture is horizontal strip (tones left to right)
2. Tone Count matches number of tones in texture
3. Invert Texture is set correctly (white lines = OFF, black lines = ON)
4. Texture import settings: No compression, Read/Write enabled

Q: How do I exclude UI from effects?

A: Options:

1. Use Screen Space - Overlay canvas (renders after post-process)
2. Use Object Exclusion layer
3. Render UI to separate camera

Q: Can I animate effect parameters?

A: Yes!

// In Update or Coroutine
settings.outlineThickness = Mathf.Sin(Time.time) * 2f + 1f;

// Or use Animation component
// Create animation clip targeting settings fields

Q: Effect looks different in build vs editor

A: Check:

1. Quality settings match
2. Shader stripping settings (don’t strip CelShaderFX keywords)
3. Build target specific issues (mobile vs desktop)

---

Still Having Issues?

If you’ve tried the solutions above and still have problems:

1. Check Console - Look for error messages
2. Verify setup - Re-follow Quick Start Guide
3. Test in new project - Rule out project-specific issues
4. Check Unity version - Ensure compatible version

Getting Help

• Documentation: Review User Manual
• Support: Contact via Asset Store
• Updates: Check for newer versions

---

Back to User Manual | Quick Start