Syntax

Directives

A directive at the top of a file carries file metadata. Both @version and @id are optional; most files don't need them. Unknown directives are skipped so future files load fine.

@version 1

imagine title
  text: "Hello"

create title

@version is stored as Scene.formatVersion and @id as Scene.fileId. When present, the compiler writes them back.

Indentation and Comments

Nesting comes from leading spaces. The compiler writes two spaces per level, the recommended style, but the parser accepts any amount, so older files with three or eight spaces still parse. Tabs are consumed as whitespace but don't count toward nesting: don't use them for indentation.

# starts a comment. A line that starts with anything else, including //, is an unknown statement and is skipped rather than treated as a comment.

Declarations and Their Status

Declaration	What it becomes
`define`	A global or local define.
`imagine`	A blueprint, a reusable template.
`create`	An instance, or a create inside a blueprint.
`animate`	An animation in the current scope.
`effect`	An effect in the current scope.
`render`	A render configuration.
`for <count>`	Inside an `imagine`: repeats native vectors through ordered modifiers; retained and saved.
`for index from ...`	Legacy indexed loop. Parsed into the AST only; not compiled into the Scene.
`when`	Parsed into the AST only; not compiled into the Scene.

for index from 0 to 2
  create dot

This legacy indexed for is understood, but it isn't executed. The loop exists in the parser's tree, but the Scene builder doesn't instantiate its body, so this won't create three dots.

A replicator is the newer for form: a positive whole count, an optional seed:, and exactly one create. Write it inside an imagine block (a top-level for 12 is read as the legacy loop and fails to parse). The source create can use each.index, each.count, each.progress, and each.seed to vary per copy:

imagine dot
  shape: circle
  size: (20, 20)
  fill: "#ff9955"

imagine row
  for 12
    seed: 3
    create dot
      position: (each.index * 30, 0)

create row

The replicator stays on the row blueprint and draws its copies. See replication for ordered modifiers and supported source properties. Extra create lines inside one for are dropped, and for 0 discards the block; validation reports ignored input.

when time > 1
  opacity: 1

when behaves the same way: recognized, but not yet implemented.