Getting started

By the end of this page you will have compiled a .knip file into a .sb3 and watched it run in TurboWarp.

Requirements

• Node.js 20 or newer — node --version to check.
• A text editor. VS Code is recommended, because Katnip ships an extension for it.
• Somewhere to run the result: TurboWarp (fastest, no account) or scratch.mit.edu.

Install

npm install -g @katnip-org/compiler

That puts a katnip command on your path:

katnip help

Note

Prefer not to install globally? npx @katnip-org/compiler help works too — substitute npx @katnip-org/compiler for katnip everywhere below.

Building from source instead

If you cloned the repository:

pnpm install
pnpm build
node packages/compiler/build/cli.js help

Your first file

Make a file called hello.knip:

sprite Cat {
    events.onFlag() {
        looks.say("Hello from Katnip!", 2);
        motion.forward(50);
        motion.turn(90);
    }
}

Three things to notice:

• Everything that runs lives inside a sprite. A bare statement at the top of the file is a declaration, not an action.
• events.onFlag() { ... } is the green-flag hat block. Inside a sprite, it becomes a script.
• looks.say and motion.forward are standard-library procedures that map onto Scratch blocks one-for-one.

Check it

Before building, type-check:

katnip check hello.knip

No semantic errors found.

Now break it on purpose — change the 2 to "two":

Semantic Error: Argument 2 of 'say' expects 'num', got 'str'
  at line 3, column 39
    |
  3 |         looks.say("Hello from Katnip!", "two");
    |                                         ^^^^^

That is the entire pitch for Katnip in one screenshot. Change it back.

Build it

katnip build hello.knip

Wrote hello.sb3

Drag hello.sb3 onto turbowarp.org and click the green flag. The cat says hello and takes a step.

Tip

build runs the whole pipeline, so it type-checks too. check is just the fast path when you only want the errors.

Set up the editor

The VS Code extension gives you live diagnostics as you type, syntax highlighting, and a build command.

code --install-extension Katnip-org.katnip-vscode

Reload the window, open a .knip file, and errors underline as you type. Ctrl+Shift+P → Katnip: Build .sb3 compiles the file you are looking at.

Full details, including the debounce and on-save settings, are in VS Code extension.

What next

• Your first projects — build a square, then a game.
• Program structure — what can go where in a .knip file.
• How the compiler works — what happens between .knip and .sb3.