MaterialFile class final

A material saved in its own file (*.material.json), which 3-D shapes and models refer to by path: change it once and everything drawn with it changes.

Colours are 32-bit ARGB in sRGB, as a scene saves them. Maps are project paths; an empty one is not used. Every field has a default, so a file need only say what differs.

A variant names a parent material and keeps only what it changes (overrides, by JSON key); everything else comes from the parent. Read one through MaterialChain (or resolve) before drawing with it.

Constructors

MaterialFile({MaterialKind kind = MaterialKind.lit, int color = 0xFFFFFFFF, double metallic = 0, double roughness = 0.75, int emission = 0xFF000000, double emissionStrength = 1, MaterialAlpha alpha = MaterialAlpha.opaque, double opacity = 1, double alphaCutoff = 0.5, bool unlit = false, bool doubleSided = false, String colorMap = '', String metalRoughMap = '', String normalMap = '', String occlusionMap = '', String emissionMap = '', double normalScale = 1, double occlusionStrength = 1, double tilingX = 1, double tilingY = 1, double offsetX = 0, double offsetY = 0, double rotation = 0, MaterialUv uv = MaterialUv.natural, List<String> layers = const [], String parent = '', Set<String> overrides = const {}})

const

MaterialFile.fromJson(Map json)

Reads a saved material. Throws an UnsupportedFormatVersionException for one newer than this reads, a FormatException for one that is broken.

factory

MaterialFile.parse(String source)

Reads source, a material file's text.

factory

Properties

alpha → MaterialAlpha

How it treats what is behind it.

final

alphaCutoff → double

MaterialAlpha.cutout: the alpha (0-1) a pixel needs to be drawn.

final

color → int

The base colour (ARGB, sRGB); multiplies colorMap.

final

colorMap → String

The maps: colour, metal (blue) and rough (green), normal, occlusion, glow. Paths; empty for none.

final

doubleSided → bool

Both sides of each face drawn.

final

emission → int

The glow colour (ARGB, sRGB) and how strong it is.

final

emissionMap → String

The maps: colour, metal (blue) and rough (green), normal, occlusion, glow. Paths; empty for none.

final

emissionStrength → double

final

hashCode → int

The hash code for this object.

no setter, override

isVariant → bool

Whether it is a variant of another material.

no setter

kind → MaterialKind

final

layers → List<String>

MaterialKind.layered: the materials blended, by path, at most maxLayers: weighed by a mesh's vertex red, green, blue and alpha.

final

metallic → double

How metal (0-1) and how rough (0-1); multiply metalRoughMap.

final

metalRoughMap → String

The maps: colour, metal (blue) and rough (green), normal, occlusion, glow. Paths; empty for none.

final

normalMap → String

The maps: colour, metal (blue) and rough (green), normal, occlusion, glow. Paths; empty for none.

final

normalScale → double

How strongly normalMap bends the light.

final

occlusionMap → String

The maps: colour, metal (blue) and rough (green), normal, occlusion, glow. Paths; empty for none.

final

occlusionStrength → double

How much occlusionMap darkens (0-1).

final

offsetX → double

How far the maps are moved along the surface, in repeats.

final

offsetY → double

How far the maps are moved along the surface, in repeats.

final

opacity → double

MaterialAlpha.blend: how solid (0-1).

final

overrides → Set<String>

A variant's own keys (from keys); the rest come from parent. Ignored when there is no parent.

final

parent → String

The material this one is a variant of, by path; empty for none.

final

paths → List<String>

Every file it uses: its maps, the layers' files and its parent.

no setter

rotation → double

How far the maps are turned, in degrees.

final

roughness → double

How metal (0-1) and how rough (0-1); multiply metalRoughMap.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

tilingX → double

How many times the maps repeat across a surface — or, with MaterialUv.metres and MaterialUv.world, across a metre.

final

tilingY → double

How many times the maps repeat across a surface — or, with MaterialUv.metres and MaterialUv.world, across a metre.

final

unlit → bool

Drawn in its own colour, unlit by the scene.

final

uv → MaterialUv

final

Methods

copyWith({MaterialKind? kind, int? color, double? metallic, double? roughness, int? emission, double? emissionStrength, MaterialAlpha? alpha, double? opacity, double? alphaCutoff, bool? unlit, bool? doubleSided, String? colorMap, String? metalRoughMap, String? normalMap, String? occlusionMap, String? emissionMap, double? normalScale, double? occlusionStrength, double? tilingX, double? tilingY, double? offsetX, double? offsetY, double? rotation, MaterialUv? uv, List<String>? layers, String? parent, Set<String>? overrides}) → MaterialFile

encode() → String

The file's text: indented JSON with a newline at the end.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

resolve(MaterialFile base) → MaterialFile

This variant drawn over base, its parent already resolved: base with this file's overrides laid on top. Not a variant any more.

toJson() → Map<String, dynamic>

As saved: the version, then only what differs from the defaults — or, for a variant, its parent and every key it overrides.

toString() → String

A string representation of this object.

inherited

validate() → List<String>

What is wrong with it, for a person; empty when nothing is. Never throws.

withEdit(MaterialFile edited, {MaterialFile? shown}) → MaterialFile

edited keeping, as a variant, every key it changed as an override.

withoutOverride(String key) → MaterialFile

This variant without its own key: the parent's value shows again.

withValues(Map<String, Object?> values) → MaterialFile

This material with values (by key, from animatableKeys, shaped as a file saves them: color an ARGB number, tiling [x, y] — or one of a pair's numbers alone, tiling#0) laid on top: what an entity's overrides draw. A key it does not know, or a value of the wrong type, is left out.

Operators

operator ==(Object other) → bool

The equality operator.

override

Static Methods

isMaterialPath(String path) → bool

Whether path names a material file.

versionOf(Map json) → int

The format version json declares (1 when it declares none).

Constants

animatableKeys → const List<String>

The keys a game may change per entity as it runs — from code, the inspector or the Timeline — with withValues: colours and numbers, never maps, layers or switches.

ending → const String

How files of this format end.

formatVersion → const int

The version this writes, and the newest it reads.

keys → const List<String>

Every key a material saves, in the order it saves them: what a variant can override.

maxLayers → const int

The most layers a MaterialKind.layered material blends.