# 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

```bash
npm install -g @bantohq/cli
```

Verify it worked:

```bash
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](https://marketplace.visualstudio.com/) / [Open VSX](https://open-vsx.org/)
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:

```bash
banto init my-game
cd my-game
```

You should now have a folder that looks like this:

```text
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

```bash
banto build
```

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

```text
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](https://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:

```bash
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](https://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:

```banto
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](./language-guide.md)** — 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](./recipes.md)** — 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](./cli.md)** — 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.