Material

Description

This component creates a standard PBR material on an entity with geometry.

Properties

Property	Type	Default	Description
r	number	255	Red channel value of the material [0...255]
g	number	255	Green channel value of the material [0...255]
b	number	255	Blue channel value of the material [0...255]
textureSrc	string	""	The color map source, modulated by color (if set)
roughness	number	0.5	How rough the material appears [0...1]
roughnessMap	string	""	Green channel of this texture map resource the roughness, multiplied by the roughness number.
metalness	number	0.5	How metallic the material appears [0...1]
metalnessMap	string	""	Blue channel of this texture resource affects how metal the material appears.
normalScale	number	1	How much the normal map (if set) affects the material [0...1]
normalMap	string	""	Normal map source of the texture.
opacity	f32	1	Overall alpha/transparency of the material [0...1]
opacityMap	string	""	Alpha/transparency mapped via a texture resource.
emissiveIntensity	f32	0	Overall intensity of the emissive map [0...1]
emissiveMap	string	""	Emissive strength mapped as a texture resource. Modulated by emissive color and intensity.
emissiveR	number	0	Red channel emissive color of the material [0...255]
emissiveG	number	0	Green channel emissive color of the material [0...255]
emissiveB	number	0	Blue channel emissive color of the material [0...255]
side	string	"front"	Which sides of faces will be rendered. Choose from front, back, or double.
blending	string	"normal"	Blending to use when displaying objects with this material. Choose from 'no', 'normal', 'additive', 'subtractive', and 'multiply'.
wrap	string	'clamp'	Wrapping mode for textures. Choose from 'clamp', 'repeat', or 'mirroredRepeat'
repeatX	f32	1	How many times a texture is repeated across a material on the X axis.
repeatY	f32	1	How many times a texture is repeated across a material on the Y axis.
offsetX	f32	0	How much a texture is offset across a material on the X axis.
offsetY	f32	0	How much a texture is offset across a material on the Y axis.
depthTest	boolean	true	Whether to test depth when rendering this material
depthWrite	boolean	true	Whether rendering this material impacts the depth buffer
wireframe	boolean	false	Render geometry as wireframe.
forceTransparent	boolean	false	Whether to force the alpha channel to render as transparent.
textureFiltering	string	'smooth'	Texture filtering mode. Choose from 'smooth' or 'sharp'
mipmaps	boolean	true	Whether to generate mipmaps for textures

Functions

Get

Returns a read-only reference.

Example

ecs.Material.get(world, component.eid)

Set

Ensures the component exists on the entity, then assigns the (optional) data to the component.

Example

ecs.Material.set(world, component.eid, {
  r: 255,
  g: 0,
  b: 0
})

Mutate

Perform an update to the component within a callback function. Return true to indicate no changes made.

Example

ecs.Material.mutate(world, component.eid, (cursor) => {
  cursor.roughness = 0.8;
  cursor.wireframe = true;
  return false;
})

Remove

Removes the component from the entity.

Example

ecs.Material.remove(world, component.eid)

Has

Returns true if the component is present on the entity.

Example

ecs.Material.has(world, component.eid)

Reset

Adds, or resets the component to its default state.

Example

ecs.Material.reset(world, component.eid)

Advanced Functions

Cursor

Returns a mutable reference. Cursors are reused so only one cursor for each component can exist at a time.

Example

ecs.Material.cursor(world, component.eid)

Acquire

Same behavior as cursor, but commit must be called after the cursor is done being used.

Example

ecs.Material.acquire(world, component.eid)

Commit

Called after acquire. An optional third argument determines whether the cursor was mutated or not.

Example

ecs.Material.commit(world, component.eid)
ecs.Material.commit(world, component.eid, false)

Dirty

Mark the entity as having been mutated. Only needed in a specific case where systems are mutating data.

Example

ecs.Material.dirty(world, component.eid)