Material Related Assets

In order to properly manipulate materials and colors in Cave, you'll need to acknowledge two main classes: ColorSampler and Material. Check them below.

Be aware that right now the engine does not support custom material shaders or pipelines, but it will provide you some basic functionalities such as changing colors and textures in realtime.

---

How to get a Material Instance?

The way you'll tipically get a Material class instance is by retrieving them from a MeshComponent, do NOT try to create your own instance from scratch, it will not work. Here is an example of how it's done:

# Getting the mesh component:
meshComponent = self.entity.get("Mesh")

# Getting the material:
material = meshComponent.getMaterial()

# If you want to change the material settings for a specific Entity, 
# you can duplicate it and reassign to the Component:
materialCopy = material.getCopy()
meshComponent.setMaterial(materialCopy)

# Now you'll be able to do local changes to the *materialCopy*:
materialCopy.albedo.set(1,0,0,1)

---

Documentation

Here is the full documentation:

cave.ColorSampler

You probably have noticed that when it comes to Material colors, Cave Engine allows you most of the times to choose if you want to use a Texture (an image) or a raw Color (with reg, green, blue and alpha values). To archieve that, Cave uses what we call ColorSampler. You'll find ways to change its color below.

Methods

# Returns true if the color sampler has a texture.
hasTexture() -> bool

# Will return the color sampler's color
getColor() -> Vector4
# Will return the color sampler's texture name (if there is a texture)
getTexture() -> string

In order to change the ColorSampler values, you can use one of those two setters, depending if you want to set it to a color or a texture.

# Use this one if you want to set it to a raw color:
set(r: float, g: float, b: float, a=1.0)

# Use this one if you want to set it to a texture:
set(textureName: str)

cave.Material

Variables

All the following variables returns ColorSampler class instances. Check the documentation above for more details on how to handle them.

albedo:     ColorSampler
roughness:  ColorSampler
metallic:   ColorSampler
normal:     ColorSampler
emission:   ColorSampler

Methods

If you need to duplicate a material (in order to do local changes to a specific Entity, for example), this is what you're looking for. It will duplicate the material and add it to the game data!

getCopy() -> cave.Material