Getting started

This walkthrough takes you from “no Banto installed” to “a real game I can host on banto.tv” in about five minutes. By the end you’ll know the shape of a Banto project and the handful of commands you’ll use every day.

What you’ll need

• Node.js 18 or newer — node --version should print something like v20.x.x.
• A terminal you’re comfortable with (PowerShell, Bash, zsh — any).
• VS Code (or a compatible fork). Banto ships an extension that gives you highlighting and inline error messages — it’s the fastest way to write .banto files.

1. Install the CLI

npm install -g @bantohq/cli

Verify it worked:

banto --help

You should see a list of subcommands (init, build, fmt, auth, publish, assets).

About the -g flag. Installing globally makes banto available from any directory. If you’d rather not, install it as a dev dependency in your project (npm install --save-dev @bantohq/cli) and use npx banto … instead.

2. Install the VS Code extension

Search “Banto DSL” in the Extensions view (or install it from the Marketplace / Open VSX if you’re on Cursor, Windsurf, or another fork). It gives you:

• Syntax highlighting for .banto files
• Inline diagnostics — the same type errors banto build reports, shown as you type
• Completions and hover docs for built-in components (cpnt.*), functions (func.* / client.*), and your assets (asst.*)
• Format Document support

Because the extension surfaces errors live, most mistakes never make it as far as a build.

3. Scaffold a project

Pick a directory you don’t mind creating, then:

banto init my-game
cd my-game

You should now have a folder that looks like this:

my-game/
├── globals.banto         # globals: data sources, custom components, shared state
├── start.banto           # the first state every game enters
├── styles.banto.css      # CSS classes you can reference from your views
├── banto.config.json     # publish settings (title, description, datasets)
└── .gitignore

That’s a complete “empty lobby” game: the host sees a room code, each player sees a “you’re in” message, and the host can kick players. No real game yet — but enough of a shell to start adding logic to.

Open start.banto and globals.banto in your editor. Don’t worry about every line yet — we’ll come back. Just notice the shape: top-level “blocks” with a name and a { … } body.

4. Build it

banto build

This compiles your project to a single game.json and typechecks it. A clean run prints something like:

Wrote ./game.json (487 bytes, 0 error(s), 0 warning(s)).

If there’s a mistake, you get the file, line, and a short explanation — fix it and build again. (With the extension installed you’ll usually have already seen the same error underlined in your editor.)

5. Publish it and play

Banto games run on banto.tv — that’s where you host and play them, so there’s no separate “run it locally” step. Publishing privately is how you preview your own work.

First, make sure "public": false in banto.config.json while you iterate, then:

banto publish

The first publish opens a browser to log you in (the same thing banto auth does), then uploads your game. Now:

1. Go to banto.tv and start your game as the host.
2. Join from a couple of phones or extra browser tabs using the room code.
3. Play a round.

Because you published with "public": false, only you (and anyone you send a direct link) can see it — perfect for playtesting.

Iterating. Edit a .banto file, run banto publish again, and refresh. Re-publishing updates the same game in place — same ID, no duplicate listing. Flip "public": true when you’re ready to list it in the public catalog.

6. Make your first change

Open start.banto and find the plyr default block. Change the welcome message:

plyr default {
    condition: true,
    child: cpnt.PlayerScreen({
        name: player.name,
        score: player.score,
        roomCode: var.roomCode,
        child: "Welcome — you made it in!"
    })
}

Save, run banto publish again, and refresh your game on banto.tv. The player screen shows your new copy.

You just learned the core idea of Banto: describe what each viewer should see, declaratively, in .banto files. The runtime takes care of getting it onto their screens.

7. Where to go next

You now know enough to wander.

• The Banto language — read this next. It explains everything you saw in the starter (var, host, plyr, cpnt, the child field) plus the parts you didn’t (state transitions, listeners, actions, custom components, custom assets).
• Recipes — once you have a feature in mind (“I want a text input”, “I want to advance to the next state when everyone has answered”), check here first.
• CLI reference — keep this handy. It documents every command, including banto assets for custom media and banto publish for shipping to banto.tv.

One part of the starter you’ll touch a lot:

• banto.config.json — your game’s identity on banto.tv. Title, description, default question/prompt set. Edit this before you banto publish.

Have fun. The DSL is small enough that you’ll have a feel for it within a few hours; ping the team if you get stuck on something the docs didn’t answer.