Rosh

One script, many worlds. A plain-English language that runs on terminal, browser, and game engine.

print "hello world"

That's a complete programme. The same source targets a terminal, a browser, or a Phaser game — no rewriting.

Install

Requires Python 3.10+ and uv.

uv tool install rosh-lang

# With AI support (rosh create, REPL intent planner)
uv tool install "rosh-lang[ai]"

# Or install from GitHub for the latest pre-release
uv tool install git+https://github.com/rosh-studio/rosh-lang

Quick Start

No account needed.

echo 'print "hello world"' > hello.rosh
rosh hello.rosh                      # prints to terminal
rosh hello.rosh --target web --run   # opens in browser

Scaffold and run a game in three commands:

rosh new game my-game
rosh my-game.rosh --target phaser --run

That creates a working space shooter — score, lives, player, hazards, bullets, explosions, sound — and opens it in the browser. Edit my-game.rosh to make it your own.

Full docs at rosh.cloud/docs · Syntax reference

Language Reference

Keywords

into capture for get and look is currently a terminal/REPL feature. Browser, Phaser, Three.js, Scratch, and world target capture semantics are deferred until those targets have explicit get/look command-state paths.

Object Properties

Objects are created with create object <name> and configured with set:

Coordinates: 0.0–1.0 maps to percentage of the canvas. Values >1.0 are treated as pixels.

Events

Control Flow

# If/else/else-if (single end for chains)
if score > 10
  print "high score!"
else if score > 5
  print "getting close!"
else
  print "keep going"
end

# Natural comparisons also work
if phase is "playing"
  print "go!"
end

# Event handler block
when click
  set count to count + 1
end

# One-line reactive listener
on update set x to x + 0.01

# Conditional listener
on keydown when key == " " play laser

# User-defined functions
define fire_bullet
  set bullet._fire to 1
end
do fire_bullet

# Counted loop
repeat 5 as i
  print "Round {i}"
end

# List operations
add "Alice" to visitors
remove "Alice" from visitors
for each name in visitors
  print "Hello {name}"
end

Key-Hold State

The _keys dict tracks which keys are currently held. Use in if blocks inside when update:

when update
  if _keys.ArrowLeft == 1
    set player.x to player.x - 0.02
  end
end

Widgets

Widgets are reusable components composed with use:

use score x 0.5 text_color "#ffcc00" font_size "20px"
use player speed 0.03
use bullet count 3 vy -0.5
use timer total 30 running 1
use ball walls top-sides
use hazard count 5 vy 0.3 spawn_rate 0.8

Native .rosh widgets declare defaults in their header and read them through instance-owned config.* state:

# widget: label
# config: text=Hello x=0.5

create object display
set display.label to config.text
set display.x to config.x

use label as title text "Welcome home" binds title.config.text before the component runs. Named instances therefore receive independent config.

Available Widgets (22)

List widgets from the CLI:

rosh library list
rosh library info bullet

Targets

Add --run to auto-open the browser:

rosh game.rosh --target web --run
rosh game.rosh --target phaser --run

Example: Space Shooter

# Score and player (auto-movement + clamp)
use score
use lives count 3
use player speed 0.03 move x
sprite player "green spaceship"

# Bullet pool
use bullet count 3 vy -0.5 color "#ffff00"

# Enemy
create object enemy
set enemy.x to 0.45
set enemy.y to 0.1
set enemy.width to 0.08
set enemy.height to 0.06
sprite enemy "red alien"

# Sound
sound laser "laser shoot"
sound hit "explosion hit"

# Controls: space to shoot
on keydown when key == " " set bullet._x to player.x
on keydown when key == " " set bullet._y to player.y
on keydown when key == " " set bullet._fire to 1
on keydown when key == " " play laser

# Collision: bullet hits enemy
when collision bullet.* enemy
  set score.value to score.value + 1
  play hit
end

Run: rosh shooter.rosh --target web --run

Cloud & AI Features

These features require a rosh.cloud account. Local use (above) works without one.

1. Register

rosh register

Opens rosh.cloud/register in your browser. Create an account with email or GitHub. A verification link is sent to your email — click it to activate.

2. Log In

rosh login

Opens rosh.cloud/login in your browser. After logging in, create an API key from Settings > API Keys.

3. Configure

rosh config --key rosh_k1_your_key_here

Saves your rosh.cloud API key to ~/.rosh/config.json. You stay configured until you run rosh logout.

4. AI-Generate a Programme

rosh create "space invaders with power-ups"
rosh create "space invaders with power-ups" --target phaser --publish

Fetches the Rosh language reference from the API, builds a prompt, sends it to an AI engine, compiles to verify, and optionally publishes to rosh.cloud.

5. Publish

rosh publish my-game.rosh --target web --title "My Game"

Compiles locally via the API and uploads to rosh.cloud as a published programme.

AI Engine Configuration

Rosh has two AI-backed surfaces:

• rosh create "..." generates a new programme from a prompt.
• the optional REPL intent planner can turn broad live-session intent into strict Rosh when ordinary parsing and deterministic natural lowering cannot handle it.

Both surfaces keep Rosh code inspectable: AI output is compiled or parsed back into normal .rosh before it is accepted.

rosh create

rosh create needs a rosh.cloud API key for the language reference plus an AI engine for generation. Run rosh config --key ..., then configure an AI provider with environment variables:

Rosh also supports any OpenAI-compatible API endpoint:

export ROSH_AI_BASE_URL=https://your-provider.com/v1
export ROSH_AI_API_KEY=your_key
export ROSH_AI_MODEL=model-name

This covers providers like OpenRouter, Ollama, Together, Groq, and any other service that implements the OpenAI chat completions protocol.

REPL Intent Planner

The terminal REPL can optionally fall back to an AI intent planner for broad commands such as:

rosh> imagine a moonlit clearing with a campfire

The planner is deliberately above the parser/runtime:

1. strict Rosh runs first
2. deterministic natural phrases run next
3. only broad unknown input can call the planner
4. generated text must parse as normal Rosh before execution

It is off unless an AI provider, model, and API key are configured:

export ROSH_AI=1
export ROSH_AI_PROVIDER=anthropic
export ROSH_AI_MODEL=claude-sonnet-4-20250514
export ANTHROPIC_API_KEY=sk-ant-...

You can also set planner preferences inside a REPL session using ordinary Rosh state:

set _ai.enabled to true
set _ai.provider to anthropic
set _ai.model to claude-sonnet-4-20250514

Keep API keys in environment variables rather than .rosh files. The planner currently runs in the terminal REPL only. The portal's authenticated browser prompt command is a separate AI generation surface; the shared homepage world continues to use its deterministic command pipeline.

Trusted Native Components

Bundled and locally installed .py component factories are native extensions: loading one executes trusted Python with the permissions of the rosh process. Do not install or generate Python factories from untrusted input. Native .rosh components are the safe, inspectable default for AI planning and composition.

Interactive REPL

rosh
rosh -c 'create object player'
rosh -i examples/hello.rosh

The terminal REPL accepts a small amount of interactive sugar and lowers it into normal Rosh before execution. That keeps the language itself strict while making the shell more forgiving. Files and rosh -c use strict Rosh syntax; these natural phrases are for live REPL sessions.

Examples:

rosh> create a big red ball
rosh> make it blue
rosh> make it smaller
rosh> move it left
rosh> put the ball at 40 60
rosh> examine ball
rosh> push my-world

Current REPL-only conveniences include:

• natural create phrases like create a big red ball
• pronoun-based follow-ups like make it blue
• simple relative size edits like make it smaller / make it bigger
• simple movement phrases like move it left and put the ball at 40 60
• aliases like examine, inspect, x, ls, and remove
• typo suggestions for misspelled commands
• tab completion, history, and multiline blocks for when, define, and repeat
• optional AI intent planning for broad unknown commands when ROSH_AI, provider, model, and API key are configured
• push <slug> — publish everything built so far in the current session to rosh.cloud as a live, shareable world (creates it if the slug is new, updates it otherwise). Requires an API key: rosh config --key rosh_k1_..., or set ROSH_API_KEY. Get a key from rosh.cloud's Settings page after logging in. This is genuinely local-first: everything you build runs entirely in the terminal REPL until you explicitly push it.

VS Code

The repository includes the official Rosh VS Code extension in editor/vscode/. It provides syntax highlighting, folding, bracket matching, and snippets for current Rosh syntax.

Install it from a source checkout:

cd editor/vscode
./install.sh

Reload VS Code after installation.

Scaffold a Project

rosh new              # choose a template interactively
rosh new game         # creates my-game.rosh
rosh new game pong    # creates pong.rosh

Templates: hello (minimal), game (full space-shooter), app (interactive web app).

CLI Reference

rosh                              Start REPL
rosh <file.rosh>                  Run programme (terminal)
rosh <file.rosh> --target web      Render as HTML
rosh <file.rosh> --target phaser   Render as Phaser game
rosh <file.rosh> --target threejs  Render as Three.js 3D scene
rosh <file.rosh> --target scratch  Export as Scratch .sb3
rosh <file.rosh> --run            Auto-open browser
rosh new [template] [name]        Scaffold a starter programme
rosh library list                 List available widgets
rosh library info <name>          Show widget details
rosh register                     Open registration page
rosh login                        Open login page and API-key instructions
rosh logout                       Clear local API key
rosh config --key KEY             Save rosh.cloud API key
rosh create "description"         AI-generate a programme
rosh publish file.rosh            Upload to rosh.cloud
rosh --version                    Show version
rosh --help                       Show help

MCP Server

Rosh has a separate MCP server package for AI tools that can compile, publish, browse, and moderate programmes through the rosh.cloud API.

Install and run it with uvx:

ROSH_API_KEY=rosh_k1_your_key_here uvx rosh-mcp

Example MCP config:

{
  "mcpServers": {
    "rosh": {
      "command": "uvx",
      "args": ["rosh-mcp"],
      "env": {
        "ROSH_API_KEY": "rosh_k1_your_key_here"
      }
    }
  }
}

Canonical MCP package: github.com/rosh-studio/rosh-mcp

Project Structure

rosh-lang/
  src/rosh_lang/
    core/
      model.py        # Data model (32 statement types)
      parser.py       # Text -> Programme
      runtime.py      # Execute programmes, manage state
      widgets.py      # Widget loader and composition
    cli/
      cloud.py        # rosh.cloud commands
      scaffolder.py   # rosh new templates
      library_cli.py  # rosh library list/info (widget inspector)
      assets_cli.py   # rosh assets search (asset pipeline CLI)
    media/
      assets.py       # Asset file resolver (legacy path resolver)
      sprites.py      # Procedural pixel-art generator
      sounds.py       # Procedural sound generator
      sheets.py       # Spritesheet slicer
      asset_registry.py   # Semantic asset registry (find by name/alias/tag)
      asset_providers.py  # External provider connectors (mock, Sketchfab)
      asset_requests.py   # Unknown-object request queue loader
      asset_manifests/    # Bundled seed asset manifests (JSON)
    library/          # 22 bundled widgets
    targets/
      terminal.py     # Terminal target
      web.py          # Web target (HTML + CSS + JS)
      phaser.py       # Phaser 3 game target
      _js_runtime.py  # JS runtime (core + DOM)
      _js_runtime_phaser.py  # JS runtime (Phaser layer)
      _js_codegen.py  # AST -> JavaScript compiler
      threejs.py      # Three.js 3D target
      _js_runtime_threejs.py  # JS runtime (Three.js layer)
      scratch.py      # Scratch 3 .sb3 export target
    repl/             # Interactive shell kernel and natural command lowering
    intent/           # Optional AI-backed intent planning
    model.py          # Compatibility shim for rosh_lang.core.model
    parser.py         # Compatibility shim for rosh_lang.core.parser
    __main__.py       # CLI entry point + REPL
  examples/           # Example programmes
  tests/              # Test suite (1,289 tests)
  editor/vscode/      # Official VS Code language extension
  tools/              # Build tools (showcase generator)
  dist/               # Generated output (showcase.html)

Licence

MIT — Copyright 2026 Roger Dubar / Rosh Studio

Free to use, modify, and distribute for any purpose. "Rosh" is a trademark of Rosh Studio — forks are welcome, but the name isn't.