The secret life of Material Entities

The secret life of Material Entities.

Material entities in Vircadia are quite powerful but still, not very often used, I think in part it is because of some of it’s quirks, like the fact that you can not (yet) apply the same material entity to more than one object, but really I think the main reason is that it just seems so complicated and nerdy.
It really isn’t, complicated that is, it is a bit nerdy though, with all those property names and stuff but luckily you don’t have to remember all that stuff, I will provide some examples you can use and modify to your liking.

What are material Entities?

  • Material entities can be used to apply materials to models, avatars or shapes by making the material entity a child of the object.

  • For models and avatars, you can select which submesh and/or material slots you want to override.

  • You can override the material as a whole, replacing the original. or only override selected properties and keep the others as original by setting a property to fallthrough.

  • Material entities have a priority property, many material entities can be applied to the same mesh, but only the one with the highest priority will show, unless fallthrough is used in which case that property will “fall through” to the next highest material property.
    The properties of the material is JSON formated text and supplyed in the MaterialURL field, this can be either a link to external file or “MaterialData” in wich case it will look in the “MaterialData” field for the JSON formatted data.

  • The material data can contain multiple named materials that you can access by appending the name in the MaterialURL field, if the data only contains one material this can be omitted.

Why would you use material entities?

  • Applying custom shaders to avatars and entities (and shapes but here userdata can be used instead).

  • Quickly test different materials, no need to export a model 10 times to get it looking just right. Just live edit the material in-world.

  • Special effects using 3d projected mode or UV offset animation.

  • Changing some properties of a material on a model, like making glass double sided and transparent, or making part of a model render unlit.

  • Linked materials, in the sense that many objects can reference the same JSON file so changes to that file will show on all the objects.

  • Setting material properties that are usually not possible in models, like setting emission higher than 1 to get a bloom effect.

  • Simply putting materials on shapes.

How do I use material entities?

To make a material entity you can click create->material, if you don’t put anything in the Material URL field yo get an empty material with the material URL set to MaterialData, But it’s blank so now you have to know which properties to type in there :thinking:

You can look here: Entities - Vircadia API Docs to see the available properties, but honestly it’s just easier to load an existing material and modify it’s properties from there, here’s a material entity with the most basic properties already filled out:
http://silverfish-freestuff.s3.amazonaws.com/Materials/Examples/basicMaterialEntity.json
That should be a good starting point.
I usually prefer putting the data in the material data field of the entity instead of in an external file, but if you like to have it all in one central file or you use the same material on a lot of objects it may be better reference an external JSON file.

Note: importing JSON files.

JSON files are used somewhat ubiquitous in Vircadia for all sorts of stuff so you sort of have to know what is in it to know how to use it but for the most part, they represent an entity, or a collection of entities with all of their properties and relative relations, like this sippy Bird:
https://silverfish-freestuff.s3.eu-north-1.amazonaws.com/Misc/SippyBird/SippyBird_Green.json
that will load a fbx mode with animation and two materials in 3D projected mode parented to specific bone.
To load a JSON like this you can:

  1. Simply drag the link onto the interface window.

  2. use the create menu to load from url or file:

  3. use the main menu->edit:
    import_menuI

  4. Load it via script, If you know how to do that you probably find this guide really basic :SMILE

To use the material you need to parent it to a shape or model, first select the material entity, hold shift and select the target entity and then press ctrl+P, the material entity will change from a little ball into an material icon
material_icon

Now, it you select the material entity again and select the material tab in the create menu you can edit the properties of the material and how it applies to the target, importantly, you need to select which submeshes and/or materials you want to override.

Note: Parenting in VR mode.

To parent an entity in VR mode you open the list view in the create menu and enable multi select mode:

Now you can select first the material, then the target entity and in the edit menu, select:
Parent Entities to the last Selected

Well, this is all getting awfully long so let me just leave you with a few more examples, That’s how I usually figure stuff out so maybe it works for you too:

Note: this may not all be correct.

I did not properly test or fact-check all of my claims in this post so if you find an error or outright lie :cry: , let me know or, even better, update the information yourself

Happy Materializing…

4 Likes