# NacatamalOn

> NacatamalOn is a 2D and 3D game engine for the web, written in TypeScript, built for the look of the consoles from SNES to GameCube. It draws with WebGPU where there is one and WebGL2 where there is not. Scenes and components are plain functions, and state comes from hooks: there are no classes to extend.

Everything below in one file, to read before writing code: [llms-full.txt](https://nacatamalon.com/llms-full.txt)

## Start a project

```bash
npm create nacatamalon@latest my-game -- --template vite-ts --install
```

- `--template vite-ts` or `--template vite-js`; `pnpm create nacatamalon`, `yarn create nacatamalon` and `bun create nacatamalon` work too.
- It asks nothing when an AI or a script runs it. `--install` installs the dependencies; then `npm run dev`, which keeps running, so start it in the background.
- The project carries an `AGENTS.md` (where things go, how to split, naming) and the engine's own guide at `node_modules/nacatamalon/llms.txt`: read both before writing code.
- The engine's guide, the same file, for version dev: [llms.txt](https://nacatamalon.com/engine/dev/llms.txt).
- In a project that already exists: `npm install nacatamalon`.

## Docs

- [Up and running in ten minutes](https://nacatamalon.com/en/docs/start): the fast track for people who already code.
- [The lifecycle of a scene](https://nacatamalon.com/en/docs/scene-lifecycle): Everything that happens to a scene from the moment it starts until it leaves, in the exact order the engine does it.
- [What the engine hands a shader](https://nacatamalon.com/en/docs/shader-inputs): Every name a material or a screen effect can read, for sprites, models and the whole screen, on both graphics backends.
- [Hooks](https://nacatamalon.com/en/docs/essentials/hooks): every hook, by topic, with its signature and an example.
- [Creators](https://nacatamalon.com/en/docs/essentials/creators): every `create*` function, by topic, with its signature and an example.
- [API reference](https://nacatamalon.com/en/docs/reference): everything a game can import, generated from the engine's code.
- [Your first plugin](https://nacatamalon.com/en/docs/plugins): A typewriter that writes a text letter by letter, from the plugin template to the .zip any game can use. Start one with `npm create nacatamalon@latest my-plugin -- --template plugin`; the project's `PLUGIN_GUIDE.md` and `AGENTS.md` hold the rules.

## Tutorial: a Breakout in nine chapters

- [The screen](https://nacatamalon.com/en/learn/the-screen): Boot the engine and stare at a coloured rectangle. Less boring than it sounds.
- [The paddle](https://nacatamalon.com/en/learn/the-paddle): Your first object on screen, and why the coordinates run the opposite way to the ones you learned at school.
- [Make it move](https://nacatamalon.com/en/learn/make-it-move): The game loop, and the one number that separates a game that works from one that runs twice as fast on your friend's laptop.
- [Take control](https://nacatamalon.com/en/learn/take-control): Keyboard input, and the one-line detail that stops the paddle escaping off the edge.
- [The ball](https://nacatamalon.com/en/learn/the-ball): Velocity on two axes, bouncing, and why the angle you leave at depends on where you hit it.
- [The wall](https://nacatamalon.com/en/learn/the-wall): Forty bricks from a loop inside a loop, and the moment the game stops fitting in one file.
- [Break them](https://nacatamalon.com/en/learn/break-them): Removing an object from the game, and why the engine waits until the end of the frame to do it.
- [Score and lives](https://nacatamalon.com/en/learn/score-and-lives): Text on screen with a bitmap font, and the two lines that turn this into a match you can win or lose.
- [Make it 1997](https://nacatamalon.com/en/learn/make-it-1997): One line of code that runs a filter over the whole screen and turns your rectangles into a 16-bit console.

## Examples

- [How to do X](https://nacatamalon.com/llms/examples.md): every example of the catalogue by topic, each with an id. Fetch one by its id for its explanation and its whole code.