@blakron/cli

CLI tool for the Blakron game engine — a modern replacement for the legacy Egret CLI. Powered by esbuild for fast compilation, with a built-in EXML skin parser and code generator.

Migrating from Egret? See migration.md

Usage

@blakron/cli does not require a global install.

Creating a project

Use npx to scaffold a new project — no installation needed:

npx @blakron/cli create my-game
npx @blakron/cli create my-lib --template empty

In-project commands

Scaffolded projects include @blakron/cli as a devDependency and expose commands via npm scripts:

cd my-game
pnpm install
pnpm build    # build
pnpm dev      # dev server
pnpm clean    # clean output

You can also add it to an existing project manually:

pnpm add -D @blakron/cli

Commands

blakron create

Scaffold a new project from a template.

blakron create <name> [options]

| Option | Description | Default | | ----------------------- | -------------------------------------- | ------- | | --template <template> | Template: game | empty | game |

Templates:

| Template | Extends | Dependencies | Description | | -------- | ---------- | --------------------------------------------------- | -------------------------------------------------- | | game | Sprite | @blakron/core + @blakron/game + @blakron/ui | Full-featured project with resource loading, scene building, and Tween animation | | empty | Sprite | @blakron/core | Minimal project — pure Canvas rendering, no extra dependencies |

Lifecycle:

| Template | Entry class | Lifecycle | | -------- | --------------------- | ------------------------------------------------------------------------------------------------ | | game | Main extends Sprite | constructor → ADDED_TO_STAGE → onAddToStage → runGame → loadResource → createGameScene → startAnimation | | empty | Main extends Sprite | constructor → ADDED_TO_STAGE → onAddToStage |

blakron build

Compile and bundle the project.

blakron build [options]

| Option | Description | Default | | --------------- | -------------------------------------------------- | ------- | | -m, --minify | Bundle and minify output | false | | --sourcemap | Generate sourcemaps | false | | --watch | Watch mode — rebuild on file changes | false | | --analyze | Print bundle size analysis (esbuild metafile) | false |

blakron dev

Start a development server with auto-recompilation on file changes (manual browser refresh required).

blakron dev [options]

| Option | Description | Default | | -------------------- | ------------------ | ------- | | -p, --port <port> | Port to listen | 3000 | | --sourcemap | Generate sourcemaps | false |

blakron clean

Remove the build output directory.

blakron clean

Configuration

Create a blakron.config.ts in your project root:

export default {
	target: 'html5',
	entry: 'src/Main.ts',
	output: { dir: 'bin-debug' },
	stage: {
		width: 640,
		height: 1136,
		scaleMode: 'showAll',
		orientation: 'auto',
		frameRate: 60,
		background: '#000000',
	},
	// Optional: enable EXML skin compilation
	exml: {
		publishPolicy: 'gjs',                     // path | content | gjs | json
		themeFile: 'resource/default.thm.json',
	},
};

Options:

| Field | Type | Description | | -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | target | string | Build target — currently only 'html5' | | entry | string | Entry file path, default 'src/Main.ts' | | output.dir | string | Output directory, default 'bin-debug' | | stage.width | number | Stage width | | stage.height | number | Stage height | | stage.scaleMode | string | Scale mode: showAll / noScale / exactFit / noBorder / fixedHeight / fixedWidth / fixedNarrow / fixedWide | | stage.orientation | string | Orientation: auto / portrait / landscape | | stage.frameRate | number | Frame rate — must be a positive integer | | stage.background | string | Background color (e.g. '#000000') | | exml.publishPolicy | string | EXML output strategy: path / content / gjs / json | | exml.themeFile | string | Theme JSON file path |

EXML Skin Compiler

The CLI includes a complete EXML skin parsing and code generation pipeline (XML → SkinIR → ESM JavaScript). .exml files placed in the resource/ directory are compiled automatically during blakron build.

Features

• XML Parsing — lightweight parser with namespace, CDATA, and comment support
• AST / IR Generation — converts to an intermediate representation (SkinIR)
• Code Generation — outputs ESM factory functions
• Component Registry — built-in eui:* / egret:* namespace mapping to @blakron/ui / @blakron/core
• View States — parses <eui:State> and state-specific property overrides like label.up="Down"
• Percent Layout — auto-detects width="100%" and converts to percentWidth
• Data Binding — parses {expression} binding syntax and generates Binding.bindProperty calls

Compilation Pipeline

resource/skins/ButtonSkin.exml
        ↓ parseXML()
    XML Element Tree
        ↓ parseEXML()
       SkinIR
        ↓ generateCode()
    ButtonSkin.gjs.js (ESM factory)

Project Structure

A project created with the default template (game) has the following structure:

my-game/
├── blakron.config.ts          # Project config (includes exml options)
├── package.json               # Dependencies & scripts
├── tsconfig.json              # TypeScript config
├── resource/
│   ├── default.res.json       # Resource config
│   ├── default.thm.json       # Theme file: component → skin mapping
│   └── skins/                 # EXML skin directory (21 default skins)
│       ├── ButtonSkin.exml
│       ├── ...
│       └── ViewStackSkin.exml
└── src/
    ├── Main.ts                # Entry: class Main extends Sprite
    └── LoadingUI.ts           # Loading progress display

Quick Start

# Full-featured game project (default)
npx @blakron/cli create my-game
cd my-game && pnpm install
pnpm dev

# Minimal project
npx @blakron/cli create my-lib --template empty
cd my-lib && pnpm install
pnpm dev