Language reference

Hyle describes lattice simulations using properties, presets, models, behaviors, phases and visuals. This reference covers the implemented Hyle 0.2 authoring syntax. Short snippets illustrate individual declarations; the first simulation is a complete program that is checked by the compiler test suite.

Project Shape

A Hyle 0.2 project is a set of .hyle source files that compile into one simulation. It must contain exactly one source file named main.hyle.

File boundaries are organizational. A project may be a monolith:

main.hyle

Or split across any directory structure:

materials/water.hyle
materials/fire.hyle
rules/flow.hyle
rules/combustion.hyle
display/defaults.hyle
main.hyle

Both shapes are semantically equivalent after project assembly. main.hyle is the required entrypoint name, not a separate module or namespace.

Assembly is deterministic:

1. main.hyle is processed first.
2. Remaining source files are processed in lexical path order.
3. Declarations are merged by the mandatory declaration categories described in File Shape, preserving that file order inside a category.

There must be exactly one world declaration across the assembled project. All other declaration categories may be distributed across files. In particular, phases retain their assembled source order, so scheduling does not depend on filesystem enumeration.

Local declarations belong to one assembled project scope. File paths do not create semantic namespaces, and they do not need imports to refer to each other.

File Shape

Declarations must appear in this order:

1. Imports.
2. Properties.
3. Presets.
4. Models.
5. World, neighborhoods, and inputs.
6. Behaviors.
7. Phases.
8. Visuals and visual bindings.

This order is mandatory in every .hyle file. Project assembly does not make an out-of-order declaration valid; it only merges already valid source files into one project scope.

Reference topics

• Properties, presets and models: fields, types and initial values.
• World construction: starting cells, objects and procedural recipes.
• Worlds and neighborhoods: dimensions, offsets and inputs.
• Behaviors and phases: reads, writes, operations and scheduling.
• Visuals: derived colors and model bindings.
• Reusable artifacts: importing exact published parts through Studio.

The grammar is maintained in core/grammars/hyle.pest. File paths organize source; they do not create language namespaces. The editor resolves selected published parts from exact @author/Name#revision imports before compilation. No atlas.toml dependency table or lockfile is required. Physics aliases and file-scoped modules remain unsupported.