# raylib examples

Both Ohio Engines now run **Tung Tung Sahur: Run**, a moonlit endless runner
using the supplied transparent 1774 × 887 sprite sheet. The game loop, gravity,
double jump, bat attacks, collision checks, coins, score, lives, pause, and
restart are written in Brainrot. Both engines share
[`sahur_game.brainrot`](sahur_game.brainrot) and
[`sahur_rules.brainrot`](sahur_rules.brainrot).

## `ohio_engine.brainrot` — hand-written binding

Uses `#cooked <raylib>` and the scalar `rl_*` wrappers in `rayrot/raylib.c`.

```bash
make play
```

## `ohio_engine_gen.brainrot` — generated binding

Uses `#cooked <raylibgen>` and real `gang Color`, `gang Rectangle`, and
`gang Vector2` values through the generated native ABI. It runs the same game
until you close the window; the old 30-frame demo is replaced.

```bash
make rayrot-gen             # generates, compiles, and checks ABI layout
make play-gen
```

The API input is pinned to **raylib 6.0** to match the installed headers and
library. [`raylib_api.source.json`](../../rayrot/raylib_api.source.json)
records the upstream source and the repair of one malformed description.
Generated bindings remain build artifacts and are never committed.

## Controls

| Input | Action |
| --- | --- |
| Enter / Space | Start; start another run after game over |
| Space / Up | Jump; press again in midair to double jump |
| X / J | Swing the bat; break crates and hit flying drones |
| P | Pause / resume |
| R | Restart after game over |
| Escape / close button | Quit |

Cactus must be jumped over. You have three lives and a short invulnerability
period after a hit. Coins and smashed obstacles add to the score. Speed
increases as the score grows. Native personal best lasts for the current
process; the browser arcade stores it locally.

## Requirements

raylib remains **optional**. `make`, `make test`, and `make valgrind` neither
build the graphics modules nor require raylib. `make play` / `make play-gen`
require raylib and a real display. Check it with:

```bash
pkg-config --exists raylib
pkg-config --modversion raylib
```

On macOS install `bison`, `flex`, `openssl@3`, `pkg-config`, and `raylib` with
Homebrew. The Makefile finds the keg-only Bison and Flex automatically. See
[`docs/rayrot.md`](../../docs/rayrot.md#installing-raylib) for the canonical
Ubuntu, macOS, Windows, and source-build instructions. Ubuntu does not have an
official `libraylib-dev` package; use the documented PPA or source build.

## The native modules

`#cooked <raylib>` loads Brainrot's `rayrot/raylib.so` wrapper rather than the
system `libraylib.so`. The generated engine loads its generated prelude and
`raylibgen_native.so`. Do not import both sets of `rl_*` exports together.

Both engines also load the small **`sahurassets`** module. The generator cannot
return a `Texture2D`, so this module owns up to 16 textures and exposes integer
handles under distinct `sa_*` names. `sa_draw_texture` crops and scales a
source rectangle; `sa_clear_textures` frees every texture before window close.
A failed load or full table returns `-1`; invalid handles draw nothing. Cleared
handles may be reused, so do not keep using them. No changes to language
keywords or to the native ABI are needed.

Run from the **repository root** so asset paths resolve:

```bash
make rayrot sahur-assets
BRAINROT_PATH=rayrot ./brainrot examples/raylib/ohio_engine.brainrot

make rayrot-gen sahur-assets
BRAINROT_PATH=rayrot/generated:rayrot ./brainrot examples/raylib/ohio_engine_gen.brainrot
```

The sprite sheet is used directly; its labels are excluded by source rectangles.
The scrolling scenery is derived from the supplied title art. Asset provenance
and the generation prompt are in
[`games/sahur/assets/README.md`](../../games/sahur/assets/README.md).

## Browser arcade and original examples

```bash
make play-web
```

Open **http://localhost:8765/games/sahur/**. It includes a separate Canvas
runner, touch controls, original WAV sound effects, fullscreen, a sprite lab,
and an examples panel that runs the actual local Brainrot interpreter.
Its **Solana Dots chart defense** mode adds real OpenMarket candles to the
browser background. The native Ohio Engines keep the original runner. See the
[OpenMarket setup](../../games/sahur/README.md#openmarket-charts) for server
credentials, transport status, and the separate optional Pump.fun pool source.
Build the interpreter with `make` to enable example execution. The local server
accepts only the shipped example names; it does not accept arbitrary programs.

The combined browser arcade needs Node and installs its JavaScript dependencies
with `make play-web`, then serves the bundled client. The runner needs no raylib.
A static build can play the runner; native example execution requires the local
Brainrot binary. The Python helper in `games/sahur/serve.py` also exercises the
original-example API in the regression tests; use the Node server to play the
combined wallet arcade.

Verified wallet profiles and run history use the server-side Neon connection.
The optional Solana leaderboard requires deploying its program. Setup and
Railway instructions are in [`games/sahur/README.md`](../../games/sahur/README.md).

## Verification

```bash
make test                  # includes pure rules and optional windowed smoke tests
make valgrind              # every language fixture, including sahur_rules
make test-sahur             # browser physics / combat / pause / restart
make format-check
make cppcheck
```

`tests/test_sahur_native.py` drives both shipped game loops through start,
double jump, pause, resume, and clean exit. It also checks failed texture loads,
capacity, handle recycling, and repeated cleanup. It skips if raylib or a display
is unavailable. Native `cap` results are landed in variables before conditions.
Graphics examples stay in a subdirectory so the top-level wasm/native examples
check does not launch windows. The binding and ownership reference remains
[`docs/rayrot.md`](../../docs/rayrot.md).