E@SY

E@SY is a small beginner-friendly programming language for learning scripting, compiler design, and simple game-language ideas. Source files use .easy; compiled bytecode files use .easyc.

E@SY is experimental alpha software. Syntax and project files may change before v1.0.

The internal Python package is named easylang because E@SY is not a valid Python import name. User-facing text should use E@SY.

Current Compiler Path

E@SY no longer uses a C backend. The compiler now writes E@SY bytecode:

.easy source
  -> lexer
  -> parser
  -> AST
  -> type checker
  -> bytecode compiler
  -> .easyc bytecode
  -> bytecode VM

The tree-walking interpreter is still available for quick script runs.

Game blocks compile into the same .easyc bytecode. When you execute game bytecode, E@SY starts an experimental Python window runtime that calls init(), update(dt), and draw() from the VM.

Quick Start

Run a script directly:

python -m easylang run examples/hello.easy

Compile to bytecode:

python -m easylang compile examples/hello.easy

Run compiled bytecode:

python -m easylang exec examples/hello.easyc

The packaged GUI and installer register .easy and .easyc file associations automatically where supported. To repair them manually from a terminal:

python -m easylang register-file-types

Disassemble bytecode:

python -m easylang dis examples/hello.easyc

Open the GUI:

python -m easylang gui

If you are using the packaged Windows release, run the same commands with easy.exe instead of python -m easylang.

Projects

Create a starter project:

python -m easylang new MyGame --template sprite

Compile the configured project entry:

python -m easylang compile MyGame

Package a bytecode release folder:

python -m easylang dist MyGame
python -m easylang dist MyGame --zip

Example easyconfig.json:

{
  "name": "MyGame",
  "entry": "main.easy",
  "output": "dist/MyGame.easyc",
  "assets": "assets",
  "build": "build"
}

Relative paths are resolved from the folder containing easyconfig.json.

GUI Compiler

Launch:

python -m easylang gui

The GUI is a wrapper over the same compiler functions as the CLI. It can:

• create and open projects
• edit .easy files
• open .easyc files through the bytecode runtime after validation
• run scripts with the interpreter
• compile .easy to .easyc
• run compiled bytecode
• preview bytecode JSON
• run doctor/setup/examples/release checks
• package a bytecode release

Useful Commands

python -m easylang doctor
python -m easylang setup-check
python -m easylang templates
python -m easylang examples-check
python -m easylang release-check
python -m unittest discover tests

File Types

• .easy: E@SY source code, UTF-8 text, text/vnd.easylang.source; charset=utf-8
• .easyc: compiled E@SY bytecode/package, JSON with magic "EASYBC", application/vnd.easylang.bytecode+json

The media type requests have been submitted and are pending IANA registration.

See docs/file-types.md for details, and docs/iana-media-type-registration.md for the IANA-style media type registration specification.

Language Features

Current script features include:

• comments with //
• numbers, strings, booleans, and null
• let and const
• arithmetic, comparisons, and boolean operators
• if, else, while, and for
• functions and return values
• arrays and structs
• imports
• built-ins such as print, input, len, range, str, num, type, and small save/load helpers

Project Structure

easylang/
  lexer.py          tokenizes source
  parser.py         builds the AST
  ast_nodes.py      dataclass AST definitions
  type_checker.py   checks names and types
  interpreter.py    tree-walking interpreter
  compiler.py       AST -> bytecode compiler
  bytecode.py       bytecode model and JSON serialization
  vm.py             stack-based bytecode virtual machine
  game_runtime.py   bytecode game loop, drawing, input, and assets
  disassembler.py   readable bytecode output
  gui_app.py        CustomTkinter GUI wrapper
examples/
tests/
docs/

Extending E@SY

To add syntax, usually edit:

1. easylang/token.py
2. easylang/ast_nodes.py
3. easylang/parser.py
4. easylang/type_checker.py
5. easylang/interpreter.py
6. easylang/compiler.py
7. easylang/vm.py
8. tests

To add a built-in function, edit easylang/stdlib.py. If the built-in needs special bytecode behavior, also update easylang/compiler.py and easylang/vm.py.

Roadmap

• improve the bytecode game runtime
• add richer bytecode debugging tools
• improve GUI bytecode debugging tools
• add richer beginner docs and tutorials
• consider native targets later from the bytecode layer