FieldML cheatsheet

FieldML is a small, statically typed expression language with tools for making geometry. This cheatsheet lists its syntax and the types of the names in its prelude. For a guided introduction, try FieldML Examples.

Types are written the way they read: -> is right associative, so Float -> Float -> Vec2 is a function of two arguments. A type in argument position keeps its parentheses, as in ('a -> 'b) -> ['a] -> ['b].

Shape of a box

Top-level let bindings stack up, and the last expression is the box's result.

let width = 40.0
let height = 25.0

{ area = width * height, square = width == height }

Syntax

Operators

Listed loosest to tightest. Everything binds looser than function application, so print x * 10 is (print x) * 10.

Conventions

• Single-subject helpers take the subject last, so they read at the end of a pipe: 7 |> mod 4 is 3, 3.0 |> pow 2.0 is 9, [1] |> append [2] is [1, 2].
• Int and Float never mix silently. 10 + 1.0 is a type error; use toFloat.
• Only let f x = ... is recursive. A plain let x = ... refers to an outer x, so shadowing keeps working.
• Recursion is not tail-call optimised. Long loops should use range/tabulate with map/fold.
• Prefix - binds looser than application, so f -1.0 is a subtraction. Write f (-1.0).

Numbers

Angles are in radians. abs, sign, min, max and clamp keep whatever numeric type they are given; the trigonometric, exponential and rounding functions use Float. Integer division and modulo, conversions and Boolean negation have their own types below.

lerp from to amount and clamp low high value both end with the subject, so 0.5 |> lerp 0.0 10.0 is 5 and 5.0 |> clamp 0.0 1.0 is 1.

Lists

range start end stops before end; linspace start end count includes both ends. Together with tabulate they are how FieldML iterates, since there is no loop statement.

head, tail and nth fail at run time on a list that is too short. zip pairs the piped list first, so [1, 2] |> zip ["a", "b"] is [(1, "a"), (2, "b")].

range 0 6
  |> filter (fun i -> mod 2 i == 0)
  |> map (fun i -> toFloat i / 5.0)

Vectors

Vec2, Vec3 and Vec4 add and subtract component by component, multiply either component-wise or by a Float, divide by a Float, and read out through .x, .y, .z and .w. In dot, vlength, distance, normalize and mix the variable 'a stands for any one of the three widths; both sides have to agree, and mixing widths is a type error.

The arguments of vec2, vec3 and vec4 are numeric rather than strictly Float, so vec2 0 1 and vec2 0.0 1.0 are both fine. polar angle radius is where most generated geometry starts.

let spoke i count =
  polar (tau * toFloat i / toFloat count) 50.0

range 0 4 |> map (fun i -> spoke i 4) |> length

Lines

Path and style helpers all take the FLine last and return it, so they chain in a pipe. Coordinates are numeric, and moveTo3/lineTo3 are the three-dimensional forms.

Folding a list of points into fline is the idiom for generated geometry: the accumulator is the line, and each step adds one instruction.

linspace 0.0 tau 24
  |> map (fun a -> polar a 30.0)
  |> fold (fun line point -> line |> lineToV point) fline
  |> close
  |> stroked true

Output and animation

print, println, display, draw and the tap family all return what they were given, so they sit in the middle of a pipe without breaking it.

animate returns a value Field drives once per frame, passing the seconds since the box was launched, until the box is stopped. The function runs for its effects, so draw inside it; animateFor is the same with a stopping time.

JVM interop

Use hostTap when a Kotlin function is an effect in the middle of a pipe: it looks the function up in Field's source index, fills in defaults, and puts the piped value in the data argument. hostCall covers everything else. See The JVM bridge for the mechanism and FieldML Examples for worked versions.

hostCall name arguments target takes as many arguments as the method does: a tuple, or a list written out in place, is spread; a record is spread by name, and every Kotlin parameter you leave out of it gets its declared default; anything else is a single argument. hostNew is the same for constructors. hostCall0, hostCall1 and hostCall2 fix the argument count instead; hostCall1 never spreads, so use it to pass one list or one record as a single argument. A FieldML function passed where the JVM wants a functional interface (a Kotlin lambda parameter, Runnable, Comparator, or a suspend one such as eachFrame's) is converted on the way in.

The table gives the general types. In an actual call the type checker looks the member up, so thisBox |> hostGet "width" is an Int, a misspelled member name is a type error rather than a crash, and a result whose class is known keeps that class as its type. You get Host only when the lookup cannot tell: a generic erased to Object, a nullable Kotlin return, an array. Host unifies with every type; the hostAs… functions turn it into a specific one.

Source macros

Field's box-code macros (moduleHere, prop, println and the rest) rewrite Kotlin source before it is compiled. FieldML is not compiled as Kotlin, so it reaches them through two functions. hostMacroExpand runs a macro's expansion against this box, which is where a macro compiles its shaders, seeds its properties and installs its actions, and returns the rewritten source. hostMacro does the same and then calls the function the rewritten source would have called. See The JVM bridge for which macros this reaches and which it cannot.

The prop functions are built into FieldML instead. In Kotlin, prop<T>(name) declares a named property that boxes below inherit, and FieldML reads and writes that same property. A Kotlin box's speed and a FieldML box's prop "speed" are one property.

A macro's arguments are source text, one string per piece: hostMacroExpand "prop" ("<Double>", "(speed)") stands for the Kotlin prop<Double>(speed). hostMacro takes the same text and then the values to call with: hostMacro "println" "(x)" (7, "hello") expands println, then calls the function it expands to with line 7 and one value.

Reading a prop that no box up the graph has set is an error, usually because the box that sets it has not run yet. propOr takes a fallback instead. Writing with setProp is always local: it shadows an ancestor's value for this box and everything below it rather than changing theirs. setRootProp puts the slot on the document root, so every box shares the one value. once computes on the first read and stores the result, so the second read does not recompute.

For reactive properties, the read and write forms share the same slot as prop and setProp. Write setPropUp "speed" 3 in a supplier box, then propUp "speed" in a child: a missing read runs the supplier first. Use the Down forms when changed writes should rerun boxes that previously read the slot. A writer that needs both directions uses setPropUpDown.