Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
D

d4rkAvatarOptimizer

> 编程语言
Open source

d4rkpl4y3r's VRChat Avatar 3.0 optimizer

589 stars0 likes2 views
WebsiteGitHub

About

d4rkpl4y3r's VRChat Avatar 3.0 optimizer

d4rkAvatarOptimizer

d4rkpl4y3r's VRChat avatar 3.0 optimizer that aims to reduce skinned mesh & material count.

How to Use

  1. Add the d4rkAvatarOptimizer component to your avatar. This can be on any transform.
  2. Upload the avatar to VRChat. The optimizations will be applied before upload automatically with the default settings.

Alternatively you can click the "Create Optimized Copy" button to create a new avatar with optimized materials and meshes. That way you can test the optimized version in editor to validate it works properly before uploading it. If everything works correctly you can then upload that optimized copy.
This button is the old workflow and I recommend against using it as it can't work properly with nondestructive tooling such as VRCFury or ModularAvatar.

Installation

To install the optimizer with VCC you need to add the url https://d4rkc0d3r.github.io/vpm-repos/main.json as a custom repository.

  1. Click here
  2. Allow the redirect to open with VCC
  3. VCC should now be open with a dialog asking you to add the repository
  4. Click I understand, Add Repository in the popup after reading its contents

After that you can add and update the optimizer like any other packages in your VCC projects.

Settings Recommendation

  • Your avatar is over 150k triangles or a lot of materials
    • Use the "Standard" preset
    • Shader and NaNimation toggles should be avoided as merging too many meshes could cause performance regressions
  • Your avatar is under 150k triangles and a moderate amount of materials
    • Use the "Shader Toggles" preset
    • If your shaders are supported shaders like Poiyomi
      • Disable NaNimation toggles
      • Check if your avatar doesn't show anything unwanted with shaders blocked
        In-game, open the action menu (the round one) -> Options -> Avatar -> Fallback Shaders
    • If anything in-game looks off, fall back to the "Standard" preset

If you want to look into more detail there is an extra document here: For Advanced Users
Also read the preset & individual option documentation below.

Presets

Standard

This preset only uses optimizations that don't affect the behavior of the avatar (some exceptions apply)

  • Removes unused components, blend shapes & bones from skinned meshes
  • Bakes non animated blend shapes into the mesh
  • Merges all skinned meshes that are always animated in the same way
  • Merges material slots that use the same material
    • Slots affected by material swap animations are not merged
  • Merges toggles in the FX Layer into a direct blend tree
  • Merges blend shapes that are always animated in the same ratio to each other

Shader Toggles

This preset uses all the above & some new optimizations.
For this mode you should keep shaders unlocked as it can allow for more merging.

  • Merges meshes even if they are animated/toggled differently by injecting logic into the shaders
  • Merged materials with the same shader even if their properties differ
  • Applies a generalized version of "lock in" to the new shaders
    Due to the added shader logic this preset will slightly increase the GPU cost of the avatar as a trade off for less draw calls.

Expect the following behavior changes (reduced due to NaNimation toggles):

  • World effects that rely on projectors/shader replacement don't understand shader toggles and will show like the merged meshes are always visible
    • Some examples of this are wire frame shaders and screen space ambient occlusion
  • With blocked shaders all merged meshes that now rely on shader toggles are always visible
    • Make sure DPS/TPS penetrators don't show up! The optimizer tries to detect and exclude them from shader toggles. If it fails you need to exclude them manually

Aggressive

Some of the settings used here compromise quality of the avatar heavily when animations/shaders are blocked.
It has some more experimental & some behavior changing ones. Testing that your avatar still works as intended is very needed in this mode. If it doesn't work correctly switch to a lower optimization preset.

Why my Shader Pink?

Shaders can do a lot of weird things, therefore the optimizer is bound to fail on some of them. Here is a couple things you could try:

  • Use different shaders, for example:
    • Poiyomi Toon
    • Silent Crosstone
    • ACLS
  • Use the "Standard" preset which causes the optimizer to not touch the shaders at all.
  • Use the "Exclusions" foldout to manually only exclude meshes from optimization that are broken.

If you are a shader author you can read the Guidelines for Shader Authors document to make your shaders compatible with the optimizer.

Make a Bug Report

To make a bug report you need to find the generated assets in the trash bin folder. You can get them by clicking the settings button on the optimizer component and then clicking the button with the open folder icon.
Now your explorer should open with the trash bin folder open and a _TrashBin.zip file selected. This file contains the generated animation controllers, materials, shaders and the log file of the optimization.
Now you can make a bug report on the issue tracker by describing your issue and attaching the _TrashBin.zip file.

UI Options Documentation

There are also some settings to tweak the optimization. You can read about their effects in more detail here:

Apply on Upload

Automatically applies the optimizer to the avatar before uploading it to VRChat. This is non destructive, the avatar in your scene will stay as it is.

Write Properties as Static Values

This is very similar to what some shaders call locking in or baking. If you use this option you should disable the locking in or baking feature of your shader.
One exception to this is for materials that use the "Rename Animated" feature. These materials should stay locked in.

When enabled the optimizer will replace the uniform parameter definitions with a static value on all materials.
For example uniform float4 _Color; will get changed to static float4 _Color = float4(1, 0, 1, 1);
This enables the shader compiler to do more constant folding and thus making the shader run faster.
Unfortunately the shader compiler is allowed to ignore NaNs while doing that so if a shader is not made with that in mind this might cause some issues.

Merge Skinned Meshes

The optimizer tries to merge different skinned meshes together.
This usually means meshes which always get animated in the same way will get merged.
Skinned meshes that are on different layers (eg UIMenu) from each other will not get merged.
Skinned meshes that are disabled and have no animation to turn them on will get deleted.

Use Shader Toggles

Merges meshes even if their material properties get animated differently or if they get toggled separately from each other.
This will add logic to the shaders to ensure everything works correctly. Some shaders might not work correctly with this option enabled.
Can't merge meshes that have any tessellation or surface shaders.

Forces on Write Properties as Static Values if enabled.

Shader Toggles will not work with blocked shaders or projectors.

NaNimation Toggles

Merges meshes even if they get toggled separately from each other.
This will add an extra bone per original mesh that gets added to each vertex with a very low weight. This bones scale will be animated to NaN to toggle the mesh off.

Unlike the Use Shader Toggles option this does not require the shaders to be changed.
It also doesn't have the problems of projectors and blocked shaders not understanding the toggles.

Might cause some issues with name plate & chat box position. If they are inside your head / way too far above your head you should disable this option.

It can't merge meshes that use a WD ON workflow when they are off by default unless the toggles are simple enough that they can get optimized by Optimize FX Layer.

Allow 3 Bone Skinning

Allows NaNimation Toggles to be used on meshes that use 4 bone weights on some vertices reducing the skinning quality to only 3 effective bone weights.

You can see which meshes use 4 bone weights in the debug info section under Mesh Bone Weight Stats. Any mesh that shows index 3 being used will be affected by reduced skinning quality if it has toggle animations.

Keep Default Enabled State

Stops meshes that are enabled by default from getting merged with meshes that are disabled by default and vice versa.

This is useful to not look weird with blocked animations in case of NaNimation toggles. With this disabled and animations blocked all merged meshes will be visible.

Merge Static Meshes as Skinned

Automatically converts static meshes to skinned meshes so that they can be merged with other meshes and have their materials merged as well. This only happens if the static mesh has materials that can be merged with materials from the skinned mesh it tries to get merged into.
Does not convert meshes on the UIMenu layer since they are mostly used for computation.

Allow Mesh Data Duplication

Allows multiple Skinned Mesh Renderers that reference the same mesh asset to be optimized independently. This can duplicate mesh data in the uploaded avatar and increase download and VRAM size.

When disabled, all Skinned Mesh Renderers sharing a mesh with more vertices than the global Shared Mesh Vertex Count Exclusion Threshold are automatically excluded from optimization. Their children are not excluded. The threshold defaults to 1024 vertices and can be changed in the Avatar Optimizer global settings.

Merge Different Property Materials

Merges materials with the same shader where properties can have different values. If they do have different values the values will get written to a constant buffer. Material IDs get written to uv.z and used to access the correct value from that cbuffer.

If your shader has a "lock in" or "bake" feature, make sure to not use it with this optimizer if you have "Write Properties as Static Values" enabled. Locked in shaders will have different actual shaders for each material, so they can't be combined. "Write Properties as Static Values" will take over the job of locking in the shaders.

Can't merge materials if:

  • Shader is surface shader or has tessellation
  • A property that differs is used in shader lab code (eg ZWrite [_ZWrite])
  • Materials have different Keywords set
  • Material slot is affected by a material swap animation

Forces on "Write Properties as Static Values" if enabled.

Merge Same Dimension Textures

Merges materials if they use different textures if their width, height & compression format match. Creates a Texture2DArray from the original textures.

Can't merge materials if:

  • Shader declares Texture2D or sampler2D properties with a custom macro.
    eg #define CUSTOM_TEX2D(name) Texture2D name
  • The textures use crunch compression.

Merge MainTex

If disabled, the optimizer will not merge materials that have different textures assigned to the _MainTex property.
If you care about your avatar looking ok with disabled shaders you should disable this option.

Merge Same Ratio Blend Shapes

This option tries to merge blend shapes that always get animated in the same ratio.
For example you have two animations. The first animates A to 100, B to 50 and C to 100. The second animates A to 50, B to 25 and D to 100. In this case the optimizer would merge A and B in a 2:1 ratio as they are always animated in that ratio.

Optimize FX Layer

Deletes all layers in the FX Layer that are considered useless:

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

C#vrchatvrchat-avatarsvrchat-tool

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言