Documentation

Open-source core

The MathPets language, compiler, deterministic runtime, model-file validator, and VS Code extension are developed in public. The hosted Studio is a separate product built on that core.

Project boundary

A reusable toolchain, without the website

The public repository contains everything needed to parse, compile, validate, and run a MathPets model in another host. It does not include this website, account integrations, hosted APIs, or private product data.

That boundary keeps the core useful on its own: model files remain portable, compiler behavior is testable outside the Studio, and hosts can build their own interfaces around the same deterministic runtime.

Read the friendly language guide here, or browse the public source on GitHub.

dependency direction

source.pet    │    ▼language / compiler    │    ▼model API    │    ▼engine / runtime    ▲    │host applications

Portable format

One model, four files

Executable rules live in source.pet. The three companions are ordinary YAML, so catalog copy, presentation, and parameter presets remain separate from simulation behavior. The validator checks the four files together and catches broken state, field, monitor, and parameter references before runtime.

my-model/  source.pet             executable model  definition.petmeta     title, description, topics, learning goal  styles.petstyle        colors, shapes, scales, transitions  presets.petpreset      named parameter configurations

Packages

What is in the core

packages/language

@mathpets/language

The grammar-backed parser, diagnostics, syntax tree, and JavaScript compiler.

Browse package ↗

packages/engine

@mathpets/engine

Deterministic worlds, geometry, random streams, lifecycle control, and indexed spatial queries.

Browse package ↗

packages/model-api

@mathpets/model-api

The small runtime-building API targeted by compiled MathPets models.

Browse package ↗

packages/model-files

@mathpets/model-files

YAML parsing and source-aware validation for metadata, styles, and presets.

Browse package ↗

packages/ide

MathPets for VS Code

Editing, live diagnostics, completion, hover help, compilation, and model preview.

Browse package ↗

Local workflow

Compile, validate, and package

The repository targets Node.js 20 or newer. One test command regenerates the parser, typechecks every package, builds the toolchain, and exercises compiler, editor, model-file, and runtime regressions.

Compiler output is standalone CommonJS. A host can load the resulting module, create the model, restart it, and advance deterministic ticks without importing the Studio.

core commands

npm installnpm test npm run compile:model -- examples/fire/source.pet \  --out /tmp/mathpets-fire.cjs npm run validate:model -- examples/firenpm run package:extension

Repository guides

Build with the core

Setup

Start here

Install the workspace, run the tests, compile Fire, and execute one deterministic tick.

Read on GitHub ↗

Syntax

Language reference

The complete source-language reference for worlds, patches, pets, links, actions, and lifecycle sections.

Read on GitHub ↗

YAML

Model file formats

The four-file model bundle, schemas, naming rules, and cross-file validation contract.

Read on GitHub ↗

Editor

VS Code integration

Build, package, install, and verify the extension or run it in an Extension Development Host.

Read on GitHub ↗