Material3DFile 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

Material3DFile({Material3DKind kind = Material3DKind.lit, int color = 0xFFFFFFFF, double metallic = 0, double roughness = 0.75, int emission = 0xFF000000, double emissionStrength = 1, Material3DAlpha alpha = Material3DAlpha.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, Material3DUv uv = Material3DUv.natural, List<String> layers = const [], String parent = '', Set<String> overrides = const {}})
A material with every value given, or its default: a white, rough, solid, lit surface with no maps, and no parent.
const
Material3DFile.fromJson(Map json)
Reads a saved material. Throws an UnsupportedFormatVersionException for one newer than this reads, a FormatException for one that is broken.
factory
Material3DFile.parse(String source)
Reads source, a material file's text.
factory

Properties

alpha → Material3DAlpha
How it treats what is behind it.
final
alphaCutoff → double
Material3DAlpha.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).
final
emissionMap → String
The maps: colour, metal (blue) and rough (green), normal, occlusion, glow. Paths; empty for none.
final
emissionStrength → double
How strong emission glows.
final
hashCode → int
The hash code for this object.
no setteroverride
isVariant → bool
Whether it is a variant of another material.
no setter
kind → Material3DKind
Lit, or layered from other materials.
final
layers → List<String>
Material3DKind.layered: the materials blended, by path, at most maxLayers: weighed by a mesh's vertex red, green, blue and alpha. An empty path is a slot left empty — no layer on that channel.
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
Material3DAlpha.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 setterinherited
tilingX → double
How many times the maps repeat across a surface — or, with Material3DUv.metres and Material3DUv.world, across a metre.
final
tilingY → double
How many times the maps repeat across a surface — or, with Material3DUv.metres and Material3DUv.world, across a metre.
final
unlit → bool
Drawn in its own colour, unlit by the scene.
final
uv → Material3DUv
How the maps are laid over a surface.
final

Methods

copyWith({Material3DKind? kind, int? color, double? metallic, double? roughness, int? emission, double? emissionStrength, Material3DAlpha? 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, Material3DUv? uv, List<String>? layers, String? parent, Set<String>? overrides}) → Material3DFile
A copy with the values given replaced.
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(Material3DFile base) → Material3DFile
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(Material3DFile edited, {Material3DFile? shown}) → Material3DFile
edited keeping, as a variant, every key it changed as an override.
withoutOverride(String key) → Material3DFile
This variant without its own key: the parent's value shows again.
withValues(Map<String, Object?> values) → Material3DFile
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

isMaterial3DPath(String path) → bool
Whether path names a 3-D 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 Material3DKind.layered material blends.