Color Types

How to define color values

Color values can passed as properties of different components, like Materials, Text or different properties of UI entities. Color values can either be of type Color3 or Color4.

Color3 contains three properties, red, green, and blue. Color4 has those same three plus alpha, for transparency values.

Set a color

You can make a color by using the Color3.create() or the Color4.create() functions.

// Red color
const red3 = Color3.create(1, 0, 0)
const red4 = Color4.create(1, 0, 0, 1)

You can also create certain predetermined colors that are part of the Color3 and Color4 namespaces.

const red = Color3.Red()
const blue = Color3.Blue()
const black = Color3.Black()

💡 Tip: Write Color3. or Color4. and Visual Studio should suggest all the possible values in an intelligent dropdown.

You can otherwise pick a random color using the following function:

const randomColor = Color3.Random()

If you prefer to describe a color in hexadecimal, use Color3.fromHexString().

const red = Color3.fromHexString('FD350A')
const blue = Color3.fromHexString('0A0CFD')

Any object value that includes numeric values for r, g, and b can be interpreted as a Color3 value. Likewise, any object that includes those properties plus an a value can be interpreted as a Color4 value. This allows you to also use the following syntax:

// Red color
const red3 = { r: 1, g: 0, b: 0 }
const red4 = { r: 1, g: 0, b: 0, a: 1 }

The following example uses a color property as part of a TextShape component, to set the text color.

const myEntity = engine.addEntity()

Transform.create(myEntity, {
  position: Vector3.create(4, 1, 4),
})

TextShape.create(myEntity, {
  text: 'this text is RED',
  textColor: Color4.create(1, 0, 0, 1),
})

📔 Note: Color3 and Color4 must be imported via

import { Color3, Color4 } from "@dcl/sdk/math"

See Imports for how to handle these easily.

Transparency

Use the alpha property of Color4 to make a color translucid.

If alpha is 1, the color will be completely opaque, if it's 0 it will be completely invisible. Anything in between results in a partially transparent tone.

// Completely opaque
const opaque = Color4.create(1, 1, 1, 1)

// Half way
const half = Color4.create(1, 1, 1, 0.5)

// Almost invisible
const half = Color4.create(1, 1, 1, 0.1)

Lerp

Use the Color3.lerp() or the Color4.lerp() function to define a color that's somewhere between two other colors. These functions work similar to the Vector3.lerp() function.

Both Color3.lerp() or the Color4.lerp() take the following arguments:

• left: The first color to use as reference

• right: The second color to use as reference

• amount: A number from 0 to 1 to define how much of the left color to use in the mix. The closer to 0, the closer to the left color.

const orange = Color3.lerp(Color3.Red(), Color3.Yellow(), 0.3)

You can use a system to gradually change the amount parameter, to create a smooth transition.

// Systems
var pulseState: number = 0
const color1 = Color4.Red()
const color2 = Color4.Yellow()

export function PulseSystem(dt: number) {
  pulseState += dt
  const entitiesWithMaterial = engine.getEntitiesWith(Material)

  // iterate over the entities of the group
  for (const [entity] of entitiesWithMaterial) {
    const material = Material.getMutable(entity)
    material.albedoColor = Color4.lerp(color1, color2, Math.sin(pulseState))
  }
}

engine.addSystem(PulseSystem)