@mindcraft-lang/core

The core implementation of the Mindcraft programming language -- a tile-based visual language designed for creating behaviors in interactive worlds.

The Mindcraft Language

Mindcraft is a visual programming language where programs are built by arranging tiles -- typed, composable tokens -- into rules. Each rule has a WHEN side (conditions) and a DO side (actions), making behavior logic readable at a glance.

A Mindcraft program is called a brain. A brain contains pages of rules, and actors in a simulation each run their own brain instance. This makes it natural to express autonomous agent behaviors: "WHEN I see food, DO move toward it."

What makes it interesting

• Tile-based grammar -- Programs are sequences of typed tiles rather than text. Tiles include literals, variables, operators, sensors (read the world), actuators (act on the world), and control flow. The tile system defines its own grammar using composable call specs (bags, choices, sequences, optionals, conditionals) that control which tiles can appear where.

• Full compilation pipeline -- Tile sequences are parsed by a Pratt parser into an AST, type-checked with bidirectional type inference, compiled to bytecode, and executed on a stack-based VM with fiber-based concurrency.

• Extensible type system -- Host applications register custom types, sensors, and actuators. The language's type system, operator overloads, and implicit conversions all extend to cover app-specific types.

• Multi-target runtime -- The same TypeScript source compiles to Roblox (Luau), Node.js, and browser (ESM) targets. A single codebase runs identically across all three environments.

Core Package Layout

src/
  primitives/     Low-level utilities (FourCC) with zero dependencies
  platform/       Cross-platform abstractions (List, Dict, Stream, Error, StringUtils, etc.)
  util/           Higher-level utilities (EventEmitter, OpResult, BitSet, MTree)
  systems/        Service-level abstractions (Signal, Clock, Translator)
  brain/          The language implementation
    interfaces/   Type definitions and contracts (brain structures, tiles, type system, catalog)
    model/        Data model (Brain, Page, Rule, TileSet)
    compiler/     Pratt parser, AST types, type inference, bytecode compiler
    tiles/        Tile implementations (operators, sensors, actuators, control flow, variables, literals)
    runtime/      Stack-based VM, fiber scheduler, function registry, operator dispatch
    language-service/  Editor services (tile suggestions)

Layers follow a strict bottom-up dependency hierarchy: primitives -> platform -> util -> systems -> brain. This is enforced because the Luau target does not tolerate circular imports.

Integration

To use this package in your own app, see the Integration Guide.

The main app integration entry point is createMindcraftEnvironment():

import { createMindcraftEnvironment, coreModule } from "@mindcraft-lang/core";

const environment = createMindcraftEnvironment({
  modules: [coreModule(), createAppModule()],
});

const brain = environment.createBrain(brainDef, { context: actor });
brain.startup();
brain.think(now);

Sub-path imports (@mindcraft-lang/core/brain, @mindcraft-lang/core/brain/model, etc.) remain available for esoteric use cases (like Roblox) and internal consumption, but webapps should prefer the root-level createMindcraftEnvironment / coreModule api.

Getting Started

Prerequisites

• Node.js (latest LTS)
• npm

Install

From the monorepo root:

npm install

Build

From packages/core/:

npm run build          # All targets (Roblox, Node.js, ESM)
npm run build:node     # Node.js/CommonJS only
npm run build:esm      # ES Modules only
npm run build:rbx      # Roblox/Luau only
npm run watch:rbx      # Watch mode for Roblox development
npm run clean          # Remove build artifacts

Each target build has three steps: TypeScript compilation, platform file resolution (copies .node.ts or .rbx.ts implementations over the ambient .ts declarations), and post-processing.

Test

npm test

Tests use node:test and node:assert/strict, run via tsx. A pretest step builds the Node target first because spec files use package imports (@mindcraft-lang/core/brain/compiler, etc.) that resolve against dist/node/.

Development Guide

Ambient Type Declarations

Core publishes a checked-in ambient declaration file at ambient/mindcraft.core.d.ts. This file is the base type surface for user-authored Mindcraft TypeScript. It provides the small lib.d.ts-style runtime surface used by Mindcraft user code and declares the core "mindcraft" module types, including Context, BrainContext, EngineContext, Sensor, Actuator, MindcraftTypeMap, and the core host methods registered by coreModule().

Generate the file from packages/core/:

npm run generate:ambient

The command builds the Node target and @mindcraft-lang/ts-compiler, then writes ambient/mindcraft.core.d.ts from the runtime registry installed by coreModule(). Regenerate it whenever core changes the user-code type surface: registered core types, context fields, sensors, actuators, operators, arg-spec helper types, or the ambient generator itself.

The generated file should be checked in. Apps and command-line tooling consume it as a package asset via @mindcraft-lang/core/ambient/mindcraft.core.d.ts, and the sim exposes it to its workspace VFS as the readonly root file mindcraft.core.d.ts. Biome ignores ambient/ because the file intentionally contains no-default-lib declarations and TypeScript built-in shapes that do not follow source-code lint rules.

Platform Abstraction Pattern

Shared code must avoid Node-only or browser-only APIs. Several modules in platform/ use a three-file pattern:

• module.ts -- declare types only (ambient)
• module.node.ts -- JavaScript implementation
• module.rbx.ts -- Luau implementation

Build scripts copy the right platform file over the generic one per target.

Conventions

• Use List and Dict from platform/ instead of native Array and Map
• Use unknown instead of any (required for Roblox compatibility)
• Use Error from platform/error instead of the global Error class
• Use TypeUtils.isString() etc. instead of typeof x === "string"
• Avoid Luau reserved words as identifiers (and, end, not, repeat, then, nil, etc.)
• No globalThis in shared code (allowed in .node.ts files only)

Import Rules

| Layer | Can import from | |-------|----------------| | primitives/ | Nothing | | platform/ | primitives | | util/ | platform, primitives | | systems/ | util, platform, primitives | | brain/ | All lower layers |

Breaking these rules creates circular dependencies that fail the Roblox build.

Adding a Platform Abstraction

1. Create platform/module.ts with declare types
2. Create platform/module.node.ts with the JavaScript implementation
3. Create platform/module.rbx.ts with the Luau implementation
4. Add to platform mappings in all three post-build scripts
5. Export from platform/index.ts

Adding Tests

Tests are colocated as *.spec.ts files next to the code they test.

1. Create <module>.spec.ts beside the source file
2. Import from package exports (@mindcraft-lang/core/brain/compiler), not relative paths
3. Use describe/it from node:test and assert from node:assert/strict
4. npm test picks up new files automatically via the glob src/**/*.spec.ts

Package Exports

import { List } from "@mindcraft-lang/core/platform";
import { fourCC } from "@mindcraft-lang/core/primitives";
import * as brainModel from "@mindcraft-lang/core/brain/model";
import * as brainTiles from "@mindcraft-lang/core/brain/tiles";
import * as brainCompiler from "@mindcraft-lang/core/brain/compiler";
import * as brainRuntime from "@mindcraft-lang/core/brain/runtime";

Where to Start Reading

• Brain architecture -- brain/index.ts, then brain/interfaces/brain.ts for the IBrainDef contract
• Tile definitions -- brain/interfaces/tiles.ts for IBrainTileDef and call specs, brain/tiles/ for concrete implementations
• Parser/compiler -- brain/compiler/parser.ts (Pratt parser), brain/compiler/types.ts (AST), brain/compiler/rule-compiler.ts (bytecode emitter)
• Runtime -- brain/runtime/vm.ts (bytecode VM), brain/runtime/brain.ts (brain execution)
• Platform abstractions -- platform/index.ts for List/Dict, then stream.ts, error.ts, string.ts