Byte Engine Docs

BEMX graphs

Look up the BEMX value types, every node kind with its inputs and defaults, the surface it ends in, and the fields of a .bemx file.

BEMX, the Byte Engine material expression, describes how a material computes its surface. A graph is a set of nodes, each of which produces one value from the values of the nodes it reads, and ends in one surface node that hands a metallic-roughness surface to the renderer. Every material reaches the renderer as a BEMX graph: .bema materials name a .bemx file, MaterialX documents are converted to one, and glTF and FBX materials are imported as one. To write a graph, follow Author assets.

The node set follows the MaterialX standard library: each node kind is spelled as the MaterialX category it follows, and its inputs have the MaterialX names and defaults. Unlike MaterialX, a graph has no node definitions, nested graphs, or overloads per type.

Value types

TypeComponentsAlso written as
float1
vector22
vector33color3
vector44color4

A colour and a vector of the same width are the same type. BEMX has no integer or Boolean type; MaterialX values of those types convert to float.

Graph rules

  • A node reads only nodes of the same graph, and no node reads its own value, directly or through other nodes.
  • Every input carries the type its node accepts. Where an input accepts either T or float, a float applies to every component of a value of type T.
  • A node whose inputs set its type, such as add, produces the wider of its inputs.
  • Nothing reads the surface node, because it produces no value.
  • Geometric values are in world space.

A graph that breaks a rule fails to load and names the node at fault.

Values and geometry

KindInputs and fieldsProduces
constantvalue: a number, or an array of two to four numbersThe type of value
parameterparameter: the name of a material parameter. type: its typetype
positionNonevector3: the position of the shaded point
normalNonevector3: the unit geometric normal
tangentNonevector3: the unit tangent, along increasing texture coordinate u
bitangentNonevector3: the unit bitangent, along increasing texture coordinate v
viewdirectionNonevector3: the unit direction from the viewer toward the shaded point
texcoordindex: the coordinate set, default 0vector2
imagetexture: the name of a material texture parameter. type: how many channels to keep, default vector4. texcoord: a vector2, default coordinate set 0type: the first channels of the texel

The material stage carries texture coordinate set 0 only, and samples every image at those coordinates. A graph that reads another set, or samples an image at coordinates computed from them, fails to bake.

Math

The inputs of these nodes have type T, or accept T or float, and the node produces T.

KindInputs, with defaultsProduces
addin1, in2 = 0in1 + in2
subtractin1, in2 = 0in1 - in2
multiplyin1, in2 = 1in1 × in2
dividein1, in2 = 1in1 ÷ in2
moduloin1, in2 = 1The remainder of in1 ÷ in2, with the sign of in2
powerin1, in2 = 1in1 raised to in2
min, maxin1, in2 = 0The smaller or larger operand
atan2in1, in2 = 1The arc tangent of in1 ÷ in2, in the quadrant both signs select
absval, floor, ceil, round, sign, sqrt, exp, ln, sin, cos, tan, asin, acosinThe function of each component. sign gives 1, −1, or 0, and ln is the natural logarithm
normalizeinin scaled to unit length
clampin, low = 0, high = 1in limited to the range from low to high
smoothstepin, low = 0, high = 1A smooth step from 0 at low to 1 at high
mixbg, fg, mix = 0The linear blend from bg at a mix of 0 to fg at 1
remapin, inlow = 0, inhigh = 1, outlow = 0, outhigh = 1in moved from the input range onto the output range
invertin, amount = 1amount - in
KindInputsProduces
dotproductin1, in2, of one typefloat
crossproductin1, in2, both vector3vector3
magnitudeinfloat: the length of in

Channels

KindInputs and fieldsProduces
extractin. index: the channel, default 0float
swizzlein. channels: one to four letters from xyzw or rgba, or 0 and 1 for constant channelsOne channel per letter
combinein1 to in4, at least two components in allThe components of every input, first to last
convertin. type: the target typeA float fills every component; a narrower value gains components of 1; a wider value loses its last components

Colour

KindInputs and fieldsProduces
luminancein, a vector3 or vector4. lumacoeffs: three weights, default 0.2722287, 0.6740818, 0.0535895The weighted sum of the colour channels in each colour channel. Alpha passes through
premultin, a vector4The colour channels multiplied by alpha
unpremultin, a vector4The colour channels divided by alpha, which is kept above 0.000001

Conditions

KindInputs, with defaultsProduces
ifgreatervalue1 = 1, value2 = 0, in1 = 0, in2 = 0in1 when value1 is greater than value2, otherwise in2
ifgreatereqAs for ifgreaterin1 when value1 is greater than or equal to value2, otherwise in2
ifequalAs for ifgreaterin1 when value1 equals value2, otherwise in2
switchwhich = 0, in1 to in10, numbered without gapsThe input at position which rounded to the nearest whole number, counting from 0

value1 and value2 are float. in1 and in2 share one type, or one of them is a float.

Normal maps

KindInputs, with defaultsProduces
normalmapin, a vector3 texel in the 0 to 1 range. scale = 1vector3: the world-space normal the tangent-space texel encodes

Only the first two channels of the texel are read. Each maps from the 0 to 1 range to the −1 to 1 range, the third component is rebuilt so the normal has unit length, and scale then scales the first two. A normal map stored with two channels decodes the same as one stored with three.

Surface

Every graph ends in one surface node. An input left out takes its default.

InputTypeDefault
base_colorvector30.8, 0.8, 0.8
opacityfloat1
metalnessfloat, 0 to 10
roughnessfloat, 0 to 10.5
normalvector3, in world spaceThe geometric normal
emissionvector30, 0, 0
occlusionfloat, 0 to 1, multiplying indirect diffuse light1

How the renderer shades these inputs is in Rendering.

Parameters

A graph names the values and textures it reads from its material instead of holding them. A parameter node reads a value parameter and an image node samples a texture parameter. The material that uses the graph declares each of them with a value of the matching type:

BEMX.bema data_type
parameter of type floatfloat
parameter of type vector3vec3f
parameter of type vector4vec4f
imageTexture2D

A graph that reads a parameter its material doesn't declare with that type fails to bake. The material's .bema file, not the graph, says whether a value parameter is static or dynamic.

.bemx files

A .bemx file holds one graph in JSON5:

FieldValue
nodesRequired. An array of node objects, in any order.
surfaceThe name of the surface node. Required when the graph holds more than one surface node.

Each node object has these fields:

FieldValue
nameRequired. A name unique in the file, which other nodes connect to it with.
nodeRequired. The node kind.
Each inputThe name of the node that drives it, or a constant: a number, or an array of two to four numbers.
Each other field the kind listsThe value the tables above give it.

A field the node kind doesn't list, a connection to a name the file doesn't hold, and a numbered input that follows a missing one each fail to load. The schema bemx.schema.json in the engine's assets/schemas directory describes the same fields.

On this page