Skip to content

Home

Jump to bottom
rurre edited this page Jan 7, 2020 · 13 revisions

Pumkin's Avatar Tools Documentation

Pumkin's Avatar Tools is a Unity editor script that provides a set of tools to automate and simplify certain avatar setup tasks within Unity. This Wiki goes over all the functionality of the tool, in detail.

If you need more help or want to offer suggestions or bug reports and for some reason don't want to post here, you can join my new Discord server and do that there. See you there!

Installation:

Grab the latest Unity Package from the releases page and run it. You will be prompted to import a few files. By default these files will be imported into a folder called 'PumkinsAvatarTools' in your root 'Assets' folder. It is recommended you don't move any files outside of the tools folder.

Usage:

To bring up the Tools window go to the top Menu Bar and select Tools > Pumkin > Avatar Tools.

If you have any issues with the tool you can try resetting it with Tools > Pumkin > Reset Tool Preferences.

In order to use any of the tools an Avatar has to be selected first. To select an avatar either drag it into the Selected Avatar object field, or select the avatar in your Unity scene and click the Select from Scene button.

When using the Select from Scene button, any child of the Avatar can be selected and the tool will automatically pick the root object and slot it into the Selected Avatar field, in this case our Avatar.

If you tick Use Scene Selection you can select an avatar by just clicking on the in the scene. Clicking in the hierarchy doesn't work yet, however.

There are 4 main sections to this tool:

Tools

This menu allows you to perform actions on your Selected Avatar.

  • Quick Setup Avatar - This button will allow you to quickly set up your avatar. You can configure what this does by clicking the settings button just to the right. Most of the things it does are available as separate buttons bellow as well. The current options are:

    • Auto Viewpoint - This will add an Avatar Descriptor, if missing, and set the viewpoint to eye level to your desired Z depth, if your avatar is humanoid.
    • Fill Visemes - This will add an Avatar Descriptor, if missing, and fill the visemes out for you.
    • Force TPose - This will put your avatar into a T-Pose, if it's humanoid.
    • Set Renderer Anchors - This will set the 'Anchor Override' on all your Skinned Mesh Renderers to a selected Transform by hierarchy path (default is Spine at Armature/Hips/Spine). This is useful if you have multiple skinned meshes and want them all to be lit uniformly. (Basically, use this if one of your mesh is darker than the others)

  • Fill Visemes - This will automatically select the Face Mesh and set Viseme Blendshape as your lipsync method, as well as fill in the Viseme fields with the ones VRChat expects, if they are present on your mesh. If not, Default will be selected instead as your lipsync method. These settings get applied to your Avatar Descriptor. If it is missing it will be added automatically.

  • Revert Blendshapes - This will revert the value of all the Blendshapes on all the SkinnedMeshRenderer components on your avatar and it's children to their prefab default. Useful for when your avatar has a default facial expression saved to prefab.

  • Zero Blendshapes - This will reset the value of all the Blendshapes on all the SkinnedMeshRenderer components on your Avatar and it's children to 0. Useful for when you want to reset the default facial expression of your Avatar.

  • Edit Viewpoint - This will allow you to move around the Viewpoint position of your avatar as if it was an object in the hierachy. When clicking Edit Viewpoint your Avatar's Viewposition ball with turn into an object you can move around, and a small window overlay will be added to your Scene View with the Accept and Cancel buttons. Move the Viewpoint position to where you want your eyes in VRChat to be, and click Apply to apply the changes. While the viewpoint position gets updated on the avatar descriptor in real time, clicking Cancel will revert the position to where it was before starting the edit. If the Viewpoint Position is at the default value of (0, 1.6, 0.2) when clicking Edit Viewpoint and your Avatar Rig is set to Humanoid, the Viewpoint will be centered in front of the origin of your Head Bone at the height of your Avatar's left eye, as selected in the Humanoid rig menu.

  • Reset Pose - This will reset all the Transform components of your Avatar to the values set in it's prefab.

  • Reset to T-Pose - This will force your avatar into a T-Pose if it's rig is set to humanoid.

  • Remove Empty GameObjects - This will remove and destroy all GameObjects that have no components or non-empty children on them from your avatar.

  • Edit Scale - This will allow you to uniformly scale your avatar. If you have an avatar descriptor on, it will also move your viewpoint for you.

  • Revert Scale - This will revert your scale back to prefab. If you've never messed with prefabs and don't know what it means, it will default the scale to 1. It will also move your viewpoint to compensate for the change.

  • Remove All x - This will remove all the components of type indicated on the button from your Avatar and all of it's children.

Note: If Dynamic Bones and Dynamic Bone Colliders are greyed out it means Dynamic Bones weren't detected in your project. To fix this you need to click 'Search for Dynamic Bones' in the Misc section if you have DBones in your project.

Copy Components

This menu allows you to copy components from one avatar to another. To use this an Avatar needs to be selected and put into the Copy from object field. The Select from Scene button under the Copy from can be used to fill the slot in the same manner as the button to Select an Avatar at the top of the window.

After that individual components can be selected to be copied with the Copy Selected button.

  • An ignore list is also provided at the bottom which lets you add GameObjects to be ignored by the copier. You can tick Include Children to include all the children of the objects in the list. For example:
    • If you add Neck to the list with Include Children unticked, only the neck is ignored.
    • If you add Neck to the list with Include Children ticked, the neck, the head, all the hair bones etc. are ignored.

Tick the box to the left of the component you want to select then expand the component by clicking the arrow to the left of it to reveal additional options.

  • Transforms - This allows you to copy the 'pose' from one Avatar to another. Values are copied by the name of the transform under the same parent, so the order of objects doesn't matter as long as the name of transform being copied to is the same as the one copied from and their parents have the same names.

    • Position - Copies the local position of all the transforms in the avatar, except the root avatar object.
    • Rotation - Copies the local rotation, and the local euler angles of all the transforms in the avatar, except the root avatar object.
    • Scale - Copies the local scale of all the transforms in the avatar, except the root avatar object.
    • Avatar Scale - Copies the scale of your main avatar object and moves the viewpoint to compensate, if an avatar descriptor is present.

  • Dynamic Bones - This allows you to copy over Dynamic Bones from one avatar to another. Components are copied by child name, similar to how Transforms are copied. As long as a child with the same name exists on both avatars and is on a parent with the same name, it will be transferred over. Dynamic Bones get copied over based on their Root. If multiple scripts affect the same Root transform only one will be copied over, and if a script doesn't have it's Root set it will be ignored. If a DynamicBones component with the same root already exists on the object being copied to a duplicate will not be created and instead it's settings updated.

    • Copy Settings - This will allow DynamicBone component settings to be copied over. With this ticked if a DynamicBone component is found on an object with the same root, it's settings will be updated with new ones from the Copy from avatar.
    • Copy Colliders - This will allow DynamicBonesCollider components to be copied over. If a collider with the exact same settings already exists on the object, a new one will not be created. If any of the settings is different, a new one will be created. If this behaviour isn't desirable consider checking the Remove Old Colliders option to remove all the DynamicBoneCollider components from your avatar prior to copying the new ones over.
    • Create Missing Bones - This will allow new DynamicBone components to be created if they're missing on the object being copied to but not on the one being copied from.
    • Remove Old Bones - This will remove all DynamicBone components prior to copying anything. This setting can be used alone without any others ticked to just remove all DynamicBone components, but in this case consider using the Remove All section buttons in the Tools menu instead.
    • Remove Old Colliders - This will remove all DynamicBoneCollider components from the avatar prior to copying anything. This setting can be used alone without any others ticked to just remove all DynamicBoneCollider components, but in this case consider using the Remove All section buttons in the Tools menu instead.

Note: If DynamicBones could not detected in your project the whole DynamicBones menu will greyed out and disabled. In this case the name of the menu will be appended with (Not Found). Check the Misc section for tips on how to fix this.

  • Avatar Descriptor - This will let you copy over the Avatar Descriptor and Pipeline Manager components and settings. If the components are missing they will be created automatically.

    • Settings - This will copy over the settings of your avatar descriptor including: the View Position, Lipsync setup, Default Animtion Set (Male/Female), and the Scale IPD setting.
    • Pipeline Id - This will copy over the Pipeline Id of your avatar into the Pipeline Manager component.
    • Animation Overrides - This will copy over the Animation Override controllers that are used for overriding gestures.

  • Skinned Mesh Renderers - This will allow you to copy over Skinned Mesh Renderer setups.

    • Settings - This will copy over: Quality, Update when Offscreen, Skinned Motion Vectors and Lighting Settings. Additionally the Root bone and Anchor Override transforms will be copied over and refernces changed to match the selected avatar. Bounds will also be recalculated.
    • Materials - This will copy over the material slots from one avatar to another. Useful when materials slots are empty or not filled correctly, but the expected materials and slots should be the same on both avatars.
    • BlendShape Values - This will copy over the BlendShape values from one avatar to another. This is commonly used for setting default facial expressions.

  • Mesh Renderers - This allows you to copy over MeshRenderers and MeshFilters between avatars as well as create GameObjects if they're missing.

    • Settings - This will copy over the settings of your Mesh Renderer and MeshFilter to the same components on the receiving avatar's object, but only if they exist.
    • Copy Missing - This will copy the Mesh Renderer and Mesh Filter components if they're missing on the receiving avatar's object and also copy the settings.
    • Copy GameObjects - This will copy the GameObjects that we attempt to copy components to if they're missing.

  • Particle Systems - This allows you to copy over Particle Systems between avatars as well as create GameObjects if they're missing.

    • Replace Old - This will replace the Particle System on the receiving object with a new one, if it exists.
    • Copy GameObjects - This will copy the GameObjects that we attempt to copy components to if they're missing.

  • Trail Renderers - This allows you to copy over Trail Renderers between avatars as well as create GameObjects if they're missing.

    • Settings - This will copy over the settings of your Trail Renderer to the same components on the receiving avatar's object, but only if they exist.
    • Copy Missing - This will copy the Trail Renderer components if they're missing on the receiving avatar's object and also copy the settings.
    • Copy GameObjects - This will copy the GameObjects that we attempt to copy components to if they're missing.

  • Audio Sources - This allows you to copy over Audio Sources between avatars as well as create GameObjects if they're missing.

    • Settings - This will copy over the settings of your Audio Sources to the same components on the receiving avatar's object, but only if they exist.
    • Copy Missing - This will copy the Audio Sources components if they're missing on the receiving avatar's object and also copy the settings.
    • Copy GameObjects - This will copy the GameObjects that we attempt to copy components to if they're missing.

  • Lights - This allows you to copy over Lights between avatars as well as create GameObjects if they're missing.

    • Settings - This will copy over the settings of your Lights to the same components on the receiving avatar's object, but only if they exist.
    • Copy Missing - This will copy the Light components if they're missing on the receiving avatar's object and also copy the settings.
    • Copy GameObjects - This will copy the GameObjects that we attempt to copy components to if they're missing.

  • Rigid Bodies - This allows you to copy over Rigid Bodies between avatars as well as create GameObjects if they're missing.

    • Settings - This will copy over the settings of your Rigid Bodies to the same components on the receiving avatar's object, but only if they exist.
    • Copy Missing - This will copy the Rigid Body components if they're missing on the receiving avatar's object and also copy the settings.
    • Copy GameObjects - This will copy the GameObjects that we attempt to copy components to if they're missing.

  • Colliders - This allows you to copy over Colliders from one avatar to another. Note that if a Collider with the same values already exists on the Avatar a duplicate will not be created. If any one setting in the inspector is different a new collider will be instead created. If this isn't the desired behaviour consider ticking 'Remove Old Colliders' before copying.

    • Box Colliders - This option will allow Box Colliders to be copied over.
    • Capsule Colliders - This option will allow Capsule Colliders to be copied over.
    • Sphere Colliders - This option will allow Sphere Colliders to be copied over.
    • Mesh Colliders - This option will allow Mesh Colliders to be copied over.
    • Remove Old Colliders - This will remove all Colliders for the selected Avatar and all of it's children. This setting can be used alone without any others ticked to just remove all Collider components, but in this case consider using the Remove All section buttons in the Tools menu instead.

  • Animators - This allows you to copy the Animator components. By default only Animators in children will be copied but you can override this behaviour by ticking Copy Main Animator.

    • Settings - This will copy over the settings of your Animator to the same components on the receiving avatar's objects, but only if they already exist.
    • Copy Missing - This will copy the Animator components if they're missing on the receiving avatar's object and also copy the settings.
    • Copy GameObjects - This will create the GameObjects that we attempt to copy components to if they're missing.
    • Copy Main Animator - This will copy over the main animator on your avatar. This isn't recommended unless you're copying to a different copy of the same avatar.

Avatar Info

This section displays a few quick stats of your avatar. Each element displays 2 values, one for enabled objects and one for total objects, shown in brackets. It also shows the stat rank for most components, as well as the total rank. Ranks are taken straight from the VRC sdk so they should be accurate, while numbers may be slightly different from ingame. When an Action from the Tools Menu or a Copy Components operation is preformed the stats should be automaticaly refreshed, but in case they aren't, the Refresh button can be used to generate the info again. The 'Copy Text' can be used to copy the stats text to your clipboard.

Currently Displayed:

  • Avatar Name - The name of your avatar object. Probably..
  • Skinned Mesh Renderers - The number of SkinnedMeshRenderer components on your Avatar.
  • Mesh Renderers - The number of Mesh Renderer components with associated Mesh Filter components that have their mesh set on your Avatar and all of it's children.
  • Triangles - The number of Triangles of all the meshes associated with your avatar.
  • Used Material Slots - The number of Material Slots with their materials set, on all the SkinnedMeshRenderer and MeshRenderer components on your Avatar and all of it's children.
  • Unique Materials - The number of Unique Materials in use between all the renderers on your Avatar and all of it's children.
  • Shaders - The number of Unique Shaders in use between all the Materials that are in use on all the renderers on your Avatar and all of it's children.
  • Dynamic Bone Transforms - The number of DynamicBone Transforms on your Avatar. This counts all the Transforms from the Root to all of it's children, minus the Excluded Transforms and all of their children.
  • Dynamic Bone Colliders - This counts the number of DynamicBoneCollider components on your Avatar and all of it's children.
  • Collider Affected Transforms - This counts the number of DynamicBone Transforms that have DynamicBoneColliders associated with them, and that can interact.
  • Particle Systems - This counts the number of Particle Systems on your Avatar and all of it's children.
  • Max Particles - This counts the Max Particle values from all the Particle Systems on your Avatar and all of it's children.
  • Overall Performance - This shows your avatar's total Performance Rank.

Thumbnails

This section allows you to create presets for your thumbnails to be used when uploading your avatar. This works in both edit and play mode, but it is recommended you do it in play mode, or reset your pose before uploading.

  • Hide Other Avatars when Uploading - This allows you to hide all the other avatars in your scene except the avatar you're uploading.

Presets Toolbar

  • Cameras - This menu allows you to setup and create camera presets.

    • Selected Camera - This is needed to do anything with camera presets. Your 'Main Camera' gets automatically selected in edit mode and VRCCam gets selected while uploading an avatar.

    • Use Camera Overlay - This allows you to overlay an image over your camera. It creates a GameObject called _PumkinsCameraOverlay which is used to display the image over your camera as a UI component.

      • This can be an image anywhere on your computer, even outside your project.
      • This will appear in front of your avatar so if the image has transparency (like a .png), it can be used to add watermarks and effects to your thumbnail.
      • If the image doesn't have transparency, it will cover your whole camera. This can be used to hide your avatar and just use an image for your thumbnail.
      • The image is stretched across your whole camera.
      • Tint Color - This can be used to color your selected image.

    • Use Camera Background - This allows you to change the background of your camera in 3 different ways.

      • Color - This will set your selected camera's clear flags to 'Solid Color' and set it's background color to the one you select.
      • Skybox - This will set your scene's skybox to the selected Material.
      • Image - This will set your scene's skybox to the selected Image. It creates a GameObject called _PumkinsCameraBackground which is used to display the image over your camera as a UI component.
        • This can be an image anywhere on your computer, even outside your project.
        • This will appear in front of your avatar so if the image has transparency (like a .png), it can be used to add watermarks and effects to your thumbnail.
        • If the image doesn't have transparency, it will cover your whole camera. This can be used to hide your avatar and just use an image for your thumbnail.
        • The image is stretched across your whole camera.
        • Tint Color - This can be used to color your selected image.

    • Align Camera to View - This will move your Selected Camera to your Scene View Camera's position. Meaning you can use your scene camera (moving around in scene view) to frame your thumbnail.

    • Center Camera on X - This allows you to move your camera, with the specified offsets, to whatever you selected in the settings menu that's toggled with the button to the right. The options are:

      • Viewpoint - Moves the camera to the viewpoint and applies the position and rotation offsets specified below.
      • Transform - Moves the camera to the selected GameObject transform, by path (default is Head at Armature/Hips/Spine/Chest/Neck/Head), and applies the position and rotation offsets specified below.
      • Avatar - Moves the camera to the origin of your avatar and applies the position and rotation offsets specified below. Useful if you really want to see your avatar's feet. Note that each mode has it's own position and rotation offset settings which can be changed manually or by using:
      • Set from Camera - This sets the position and rotation offsets from your currently selected camera to the settings of your currently selected mode.
      • Reset - This resets the position and rotation offsets for your currently selected mode.

    • Preset - This allows you to save and load all these selected camera settings.

      • Load Preset - This will load the preset that's currently selected in the drop down menu. It will move your camera and set it's overlay and background settings.
      • Edit Preset - This allows you to edit the preset that's selected in the drop down menu. It will apply the preset and open a popup window where you can change the existing settings of your preset. Simply close the window to save your changes.
      • Select in Assets - This will select the preset that's currently selected in the drop down menu in your Assets. By selecting the .asset file directly you can further edit the settings stored inside your inspector.
      • Create New Preset - This will create an .asset file and save your selected camera settings to it, including overlay and background settings.
        • This will open a popup window where you can specify the settings you want and pick a name to save the preset as.
      • Reset - This will reset your camera position and rotation.

  • Poses - This menu allows you to save and load your Avatar's pose

    • Try to Fix Pose Sinking - If your avatar sinks into the ground when loading a pose preset, try changing this setting.

    • Open Pose Editor - Opens the Pose Editor. Check the Pose Editor wiki page for more info.

    • Preset - This allows you to save and load your Avatar's current pose.

      • Load Preset - This will load the preset that's currently selected in the drop down menu. It will set your avatar's pose.
      • Edit Preset - This allows you to edit the preset that's selected in the drop down menu. It will set your avatar's pose and open a popup window where you can change the existing settings of your preset. Simply close the window to save your changes.
      • Select in Assets - This will select the preset that's currently selected in the drop down menu in your Assets. By selecting the .asset file directly you can further edit the settings stored inside your inspector.
      • Create New Preset - This will create an .asset file and save your current pose to it.
        • This will open a popup window where you can specify the settings you want and pick a name to save the preset as.
        • You need to select how you want your pose saved.
        • Selecting Human Pose will save it as humanoid muscle values. This will allow you to apply the pose to any humanoid avatar but it only affects only the bones set in the humanoid rig.
        • Selecting Transforms will save all transform positions and rotations. This will allow you to apply the pose to any avatar but only if the bone names are the same, however it allows to save all the bones.
      • Reset - This will reset your camera position and rotation.

  • Blendshapes - This menu allows you to save and load your avatar's facial expressions.

    • Blendshapes menu - This displays all your Skinned Mesh Renderers and sliders for all their blendshapes.

      • Revert Renderer - This will revert your Skinned Mesh Renderer's blendshapes to it's prefab values.
      • Reset Renderer - This will set all your Skinned Mesh Renderer's blendshapes to 0.

    • Preset - This allows you to save and load your avatar's current facial expression.

      • Load Preset - This will load the preset that's currently selected in the drop down menu. It will set your avatar's current facial expression.
      • Edit Preset - This allows you to edit the preset that's selected in the drop down menu. It will set your avatar's facial expressoin and open a popup window where you can change the existing settings of your preset. Simply close the window to save your changes.
      • Select in Assets - This will select the preset that's currently selected in the drop down menu in your Assets. By selecting the .asset file directly you can further edit the settings stored inside your inspector.
      • Create New Preset - This will create an .asset file and save your current facial expression to it.
        • This will open a popup window where you can specify the settings you want and pick a name to save the preset as.
        • You can choose to add and remove blendshapes and renderers to be saved in here. All the missing ones will be set to 0 when loading.
        • Renders use their hierarchy path as the name (so if you had a skinned mesh renderer on your Head the name would be Armature/Hips/Spine/Chest/Neck/Head by default)
        • Each Blendshape can have a list of Other Names. This allows you to indicate alternate names for each blendshape in case you want to use the same preset on avatars with different blendshape names.
          • When loading a preset, the main blendshape name is searched for, if not found each name from the other names list is searched for until one is found, then the slider value is applied.
      • Reset - This will revert your Skinned Mesh Renderers' blendshapes to prefab.

Misc

This section has a bunch of misc buttons.

  • Search for Dynamic Bones - This button currently only appears if DynamicBones aren't detected in your project. As of v0.7b you have to click this to perform the check manually. After adding the latest version of DynamicBones to your project and pressing the button, _DependencyChecker will check for DynamicBones again and a few things happen:
    • If DynamicBones are found, your project's global script defines will have either PUMKIN_DBONES or PUMKIN_OLD_DBONES added to them depending on if it's an old version or not.
    • If they're not found, your project's global script defines will be checked for the defines mentioned above. If found they will be removed.
    • Your project will recompile it's scripts due to the global script defines changing.

Whenever scripts are recompiled the DynamicBones check is automatically performed, but it can also be triggered by clicking the button. Once they're detected, the button disappears.

  • Open Github Page - Opens the main Github page for this project.
  • Open Help Page - Opens this Wiki page.
  • Join Discord Server - Opens a link to join the Pumkin's Avatar Tools Discord server. You can find more info when you join.
  • Buy me a Ko-Fi~ - Opens a donation page that you can use to support the project. It's totally optional but highly appreciated!

Contents:

Tools

Copy Components

Avatar Info

Thumbnails

Misc

Pose Editor

Clone this wiki locally