Avatar Material Swapping

So back in the dim and distant HighFidelity past, 31st October 2018, I wrote a forum post about a simple avatar material swapping app. Now we have forums again, I thought I’d bring the post back as the technique is still relevant and working on Vircadia.

Everything is available on Github as https://github.com/Madders/hifi-materialSwap, including instructions on how to use it which I’ve copied below from the readme.

NOTE: some of the links are out of date as they point back to hifi docs or the old marketplace, I’ll get round to updating them at some point, but everything code and technique wise still works great.


This is a fairly straight forward script / tablet app that is intended to be attached to an avatar in order to be able to swap materials between a set of preconfigured options.

When the script is running you get an additional button on the tablet / toolbar named “SKINS”. Clicking this will display the skin chooser as pictured below:

Then clicking on any of the options will update your avatar with the chosen materials.


You can see the script in action by settings your avatar to:



Assuming you know how to attach scripts to your avatar include the materialSwap.js in your avatars fst file. You also need to ensure you include the other source files in the same folder as the main script.

Material options are defined using the the materialOptions.json file. The example includes a number of very simple material options as displayed below:


    "id": "Green",

    "displayName": "Green",

    "description": "",

    "thumbnail": "",

    "materials": [


        "materialURL": "materialData",

        "materialName": "Material.003",

        "materialData": {

          "materialVersion": 1,

          "materials": {

            "model": "hifi_pbr",

            "albedoMap": "https://url.example.to.alternative.texture/nk4.png",






Basic definition of a materialOption is:

  • id - a unique identifier for the option

  • displayName - the name to display in the tablet app for the option

  • description (optional) - the description to display in the tablet app. If not supplied it simply doesn’t show the description block in the tablet app.

  • thumbnail (optional) - the image to display in the tablet app. If not supplied it simply doesn’t show the image block in the tablet app.

  • materials - a list of materials that will be replaced on the avatar when this option is selected. You can define any number of replacement materials for each option, so for example you could just replace the material on your avatar T-Shirt or re-define every material the avatar uses.

    • Materials use the format as defined on https://docs.highfidelity.com/api-reference/globals#Material

    • The most important property is martialName, which must match the name in the source model exactly.

    • Please note - the materials defined in the example are very basic, and are just defining the basic texture map. The kobold model may look slightly strange with this as there may be other material settings, such as normalMap etc, that should be defined for it to look correct.


Menithal for the scripting sample that I used for the core of the material switcher.

Assets used in the example:

  • Hifi Avatar from marketplace by Davwyn, Link

  • Original Kobold Model by uwusoft, Link

  • Sketchfab source, Link

Tablet Icon made by Smashicons from www.flaticon.com is licensed by CC 3.0 BY


[quote=“madders, post:1, topic:19”]
Hifi Avatar from marketplace by Davwyn, Link

is a dead link.

[quote=“madders, post:1, topic:19”]
Materials use the format as defined on https://docs.highfidelity.com/api-reference/globals#Material

should maybe be Entities - Vircadia API Docs ? I don’t see anything under Globals in there so did that change?

loading the avatar and script works fine and it looks nice. good example of on-the-fly editing of avatars :smiley: , I remember this from way back but never understood how it works but I think I do now .

EDIT: I did not read the disclaimer on top, sorry