Docs menu: Source files and DixScript Documentation home
On this page File sections The @DATA section QuickFuncs Interpolated strings Enums Colors Importing the standard library Errors and validation

Source files and DixScript

File sections, QuickFuncs, enums, interpolated strings and color literals.

An MSX source file is a DixScript file with a handful of sections that the MSX parser knows about. DixScript evaluates the whole file before MSX reads it, so function calls, enum values and interpolated strings are already plain values when the scene is built.

File sections

Section Holds
@CONFIG File metadata. Every example starts with @CONFIG( version -> "1.0.0" )
@QUICKFUNCS Functions that return values or whole objects
@ENUMS Named integer constants such as blend modes
@IMPORTS Functions and enums loaded from another file
@DATA The scene

The @DATA section

Inside @DATA the parser reads these keys.

Key Form Meaning
scene object Canvas size and background, see Canvas and viewbox
viewbox object Optional visible region
defs:: array Gradients, shaders and audio
elements:: array The drawable tree, in paint order
animations:: array Keyframe tracks, see Keyframe animation
duration number Timeline length in seconds
loop_mode string once, loop or ping_pong

defs::, elements:: and animations:: introduce an array. Each entry is an object, written one after another with no separating comma.

@DATA(
  scene = { width = 300, height = 200, background = #101820 }
  elements::
    { type = "circle", cx = 90,  cy = 100, r = 40, style = { fill = #4a9eff } }
    { type = "circle", cx = 210, cy = 100, r = 40, style = { fill = #f5a623 } }
)

An object is a list of key = value fields. Fields are separated by a comma or by whitespace. Comments start with //.

QuickFuncs

A QuickFunc is a function declared in @QUICKFUNCS and called wherever a value or an array entry is expected. It is the main tool for removing repetition. The parametric example defines two functions and calls each one several times.

parametric rendered
examples/parametric.msx · 39 lines · open in playground · all samples
Source
@CONFIG( version -> "1.0.0" )
@QUICKFUNCS(
  ~badge<object>(x, y, label, color) {
    return {
      type = "group"
      elements = [
        { type = "rect", x = x, y = y, width = 100, height = 32, rx = 16,
          style = { fill = color, stroke = "none", stroke_width = 0, opacity = 1.0 } },
        { type = "text", x = x + 50, y = y + 21, content = label,
          style = { fill = #ffffff, font_size = 13, text_anchor = "middle",
                    font_weight = "bold", stroke = "none", stroke_width = 0, opacity = 1.0 } }
      ]
    }
  }
  ~dot<object>(cx, cy, r, color) {
    return {
      type = "circle"
      cx = cx  cy = cy  r = r
      style = { fill = color, stroke = #1a1a2e, stroke_width = 2.0, opacity = 0.9 }
    }
  }
)
@DATA(
  scene = { width = 700, height = 420, background = #f4f5f7 }
  elements::
    badge(20,  20, "primary", #007bff)
    badge(140, 20, "success", #28a745)
    badge(260, 20, "warning", #ffc107)
    badge(380, 20, "danger",  #dc3545)
    badge(500, 20, "dark",    #343a40)
    dot(80,  200, 55, #e94560)
    dot(210, 200, 45, #533483)
    dot(330, 200, 60, #0f3460)
    dot(460, 200, 40, #4a9eff)
    dot(580, 200, 50, #22c55e)
    { type = "text", x = 350, y = 390, content = "MSX Parametric Components",
      style = { fill = #333333, font_size = 16, text_anchor = "middle",
                stroke = "none", stroke_width = 0, opacity = 1.0 } }
)

A QuickFunc declaration has the form ~name<return type>(arguments) { return value }. Arguments are used by name inside the returned object, and the body can compute with them, as in x = x + 50. A call that returns an object can stand directly in an elements:: list.

Interpolated strings

A string written as $"..." evaluates the expressions inside braces and builds the string. It is the way to compute path data from parameters. This path, taken from std/shapes.msx, draws a check mark whose size follows half.

d = $"M {cx - half * 0.7} {cy} L {cx - half * 0.1} {cy + half * 0.7} L {cx + half * 0.8} {cy - half * 0.6}"

Enums

Fields that take a closed set of values, such as blend_mode, fill_rule and stroke_linecap, accept either a DixScript enum value or a plain string. Both forms mean the same thing.

blend_mode<enum> = BlendMode.Multiply
blend_mode = "multiply"

The constants live in std/enums.msx. That file notes that importing enums from another file uses a different grammar from importing functions, and recommends copying the @ENUMS block into the scene file when a cross-file enum does not resolve. Plain strings work in every case.

Warning A string that is not a recognized value does not raise an error. stroke_linecap = "rounded" is read as butt, and an unknown loop_mode is read as once. Check spelling against the value lists on each page.

Colors

A color can be written as an unquoted hex literal such as #e94560 or as a quoted string such as "#e94560". The accepted forms are listed in Style and paint.

Warning A color string that cannot be parsed becomes "no paint" without an error. A fill of "#e9456" draws nothing.

Importing the standard library

The std/ directory ships four files. Each is a normal DixScript file, so a function can also be copied into a scene.

File Provides
std/colors.msx Twenty color functions: white, black, six slate shades, crimson, violet, navy, azure, emerald, amber, lavender, success, warning, danger, info and primary
std/effects.msx Layer effect presets: soft_blur, heavy_blur, soft_shadow, long_shadow, pressed_inset, neon_glow and highlight_rim
std/shapes.msx Components: badge, card, icon_check, dot and divider
std/enums.msx The enum constants described above

The header of each file documents its import form.

@IMPORTS( Colors from "std/colors.msx" )
// then
fill = Colors.crimson()

Errors and validation

A missing required field or an unknown element type stops the parse with a message that names the path, for example elements[2]: unknown element type 'rectangle'. msx validate runs the parse and the schema check without producing any output, and its exit code reports the result.