I. The Light Before the Word
Before the first pyramid, before the first word was carved into stone, there was only Ra’s light — endless, indifferent, spilling over sand and river alike, asking nothing and giving no direction. Light without a path is just light. Someone, something, had to move it.
Thoth kept the words. Every incantation ever spoken, every spell ever written in the sacred script, lived in his keeping — and no two were ever quite the same. A farmer’s charm for rain was not a priest’s rite for the dead, was not a king’s decree carved to outlast his own bones. Thoth cared nothing for which words a person chose to speak. He only kept them, infinite and unjudging, waiting for a voice.
And between the two — between the light that meant nothing until it moved, and the words that meant nothing until they were carried — there was Khepri.
He was small. He owned no light of his own, and spoke no incantation that was his. He simply rolled — a plain, dark shell against a rising sun, pushing forward whatever the morning gave him to push, asking no tribute, keeping no secrets, caring not at all whether what he carried belonged to a king or a farmer. Each dawn was the same to him: something arrived that needed carrying, and he carried it.
II. What a Beetle Is For
That’s also, more or less, what a game engine is for.
A little while back I wrote about the ship that became sunlight — the engine underneath, the part that actually knows how pixels get on screen, what happens when two things collide, what a tile map even is. I said then that sunlight wasn’t the end of it, that it had already become the rendering backend for something else I was building on top, and that I’d leave what that something else turned out to be for later. This is later.
Scarab turned out to be almost nothing, on purpose.
Not nothing in the sense of unfinished — nothing in the sense that it doesn’t own a single line of game logic anywhere inside it. It’s a thin C++17 shell around sunlight: it opens the window, loads whatever Lua you hand it, and calls straight into a handful of functions that script defines — an on_update called every frame, an on_load_stage when a stage begins, and so on. Everything that makes one game different from another — the ship, the aliens, how a level unfolds, what happens when you die — lives entirely in that Lua, calling back into a few hundred small verbs Scarab exposes: acquire a sprite, load a map, play a sound, start a timer. You could point it at a vertical shooter one day and a puzzle game the next, and it would never know the difference, because it isn’t supposed to.
The smallest possible game Scarab will actually run looks like this, in full:
-- main.lua — the entire "game"
function on_load_stage(stageId)
return true -- Scarab has no opinion on what a stage means; Lua claims it
end
function on_update(dt)
draw_text("Hello, Khepri", 10, 10, 20)
end
sp_wait(1) -- queue at least one command, or the beetle refuses to roll at all
That’s it. No class to subclass, no engine object to instantiate, no build step of its own — one file, two callbacks C++ will call back into, and a scatter of verbs like draw_text standing in for the whole rest of the engine underneath. A whole game, script and every asset it needs, can travel as a single sealed .zip — Scarab reads out of one exactly the way it reads out of a loose folder on disk, no difference at all from the inside. One incantation, whole, ready to be handed to anything that knows how to carry it.
That’s Khepri’s whole trick, really. He never asked what he was rolling. He just rolled it.
III. Not a God’s Throne Room
Every pantheon has a jealous god somewhere — one who guards his own light behind ritual and tribute, who’ll carry your incantation only if it’s written in his own priesthood’s tongue, and who charges for the privilege of being carried at all. He’s not evil, exactly. He’s just decided that what he offers is worth owning, and that ownership means someone else has to ask permission.
Scarab doesn’t ask permission for anything, and it doesn’t sell what it doesn’t have to sell. It’s released under the zlib license — about as close to “take it, use it, sell your own game built on it, just don’t pretend you wrote the engine yourself” as a license gets. There’s no tier where the real features live behind a paywall, because there’s nothing in here worth locking away in the first place: no game logic, no assets, nothing proprietary. What you get is a beetle, not a god’s throne room.
The clearest place this actually shows up is the newest thing I’ve built into it: a way to encrypt a game’s own files, so a Lua script and its assets can be bundled up tight enough that a casual look won’t just hand them over.
The whole workflow is three commands, from a source tree to a sealed, encrypted archive only your own build can open:
# 1. Generate a key of your own (32 random bytes, hex-encoded) and
# build scarab with it baked in
python3 -c "import secrets; print(secrets.token_hex(32))"
cmake -B build -S . -DSCARAB_CONTENT_KEY=<the 64 hex characters just generated>
cmake --build build -j 4
# 2. Point --pack at a game's own source directory
echo '{ "source_dir": "/path/to/my_game_source", "output": "/path/to/my_game.zip" }' > pack-config.json
./build/scarab --pack pack-config.json
# 3. Run it back - only this exact build, with this exact key, can open it
./build/scarab /path/to/my_game.zip
Nothing exotic underneath: a 256-bit key handed to CMake at build time, a small JSON file telling the packer which folder to seal and where to write the result, and the same executable used both to seal it and to open it again. Anyone who builds their own private copy this way — with a key of their own choosing, kept somewhere only they can see it — gets a bundle nobody else’s build can read.
The tempting version of this feature — the one a jealous god would build — bakes in one secret key for everybody, ships it quietly in every public download, and lets you assume you’re protected. Scarab does the opposite on purpose: the key every public download actually ships with is worked out fresh for each release, from a private formula, different every time — and still, every one of those downloads prints out loud, every single time you run it, that this particular key was never meant to be private, and that anyone willing to spend five minutes with a disassembler can pull it straight out of the binary. If you want the real thing, you build your own copy with your own key, kept where only you can see it. Nothing hidden, nothing implied. The idol lies by omission; Khepri just tells you what he is.
IV. Two Priesthoods
None of this works if Scarab tries to own everything itself, which is why it doesn’t even try. sunlight is its own project now, with its own repository, its own releases, its own author’s-worth-of-decisions that Scarab has no say in — and that separation isn’t a limitation, it’s the whole point. When something breaks at the seam between them, neither side can just reach over and fix the other’s code. What actually happens is closer to two priesthoods comparing notes: a precise account of exactly what’s wrong, checked line by line against the real source before a word of it is sent, handed across, and answered with a real fix and a real test — not a favor, an actual collaboration between two things that owe each other nothing.
A multi-file bitmap font — the kind that’s a text file plus a separate image, rather than one neat file — refused to load through Scarab at all, and for a long time nobody could say why beyond “it just doesn’t.” Every resource Scarab loads — a texture, a sound, a script, that same font — is meant to go through one shared reading point sunlight maintains, precisely so a loose folder of files and a single sealed .zip get treated exactly the same way underneath. The whole project is just a folder with one small manifest at its root:
// project.json
{ "main_script": "src/main.lua" }
# Run it straight from the loose folder...
./scarab project.json
# ...or seal the exact same folder into one file and run that instead
./scarab --pack pack-config.json
./scarab my_game.zip
main_script resolves relative to project.json‘s own location, not wherever scarab happens to be run from — so the folder above works untouched whether it’s sitting loose on disk or packed whole into my_game.zip. Neither main_script nor a single line of the game’s own Lua needs to know or care which of the two it’s actually running from; that’s the shared reading point’s whole job, not something each resource load has to handle for itself.
Tracing the bug all the way down showed the image half of the font quietly slipping past that shared point instead of through it — asked for by a path that had grown a stray ./ in front of it, which the reader underneath rejected without a word. No error, no warning, just a fallback font appearing where the right one should have been, and nothing in the logs to say a substitution had even happened. That got fixed, verified, shipped.
And then it broke again, in a way the first fix couldn’t have caught: the font’s own text half — the part that isn’t an image at all — turned out to have never been wired into that shared reading point in the first place. It had simply never been asked to matter, because on every machine anyone had tested it on, the real file happened to be sitting right there on disk regardless, quietly answering a question nobody knew they were still asking wrong. It only broke once a game shipped as one sealed bundle with nothing loose left lying around to rescue it — which is, not coincidentally, exactly the situation Scarab exists to make normal. Fixed the same way as the first: found for real, described precisely, handed across, verified independently by both sides before anyone called it done.
Twice, the failure was the same shape — something silently standing in for what should have been there, saying nothing about it. Khepri doesn’t do that. When he can’t carry something, he stops, and he says why.
V. Another Dawn
Ra didn’t stop making light because Khepri rolled it once. Tomorrow, there’ll be another dawn, another stretch of sand needing exactly the same small labor as today’s — and Khepri will be there again, not because the work was left unfinished, but because that’s simply what the work is. It was never going to be a monument. It was always going to be a practice.
Scarab’s first real version shipped with just enough to actually run a game — a window, a way to load Lua, the bare minimum a story needs before it can move at all. Every feature since has been added because some actual game needed it, never because a roadmap said so. As of v0.1.13, that list looks like this:
- Sprites — texture-backed, animated, pooled by handle
- Collision — shape-based detection between sprites
- Tile maps — Tiled (
.tmx) map loading and per-layer rendering - Camera — scrolling/following a target across a map
- Sound — one-shot effects and streamed background songs
- Timers — background-thread scheduled callbacks back into Lua
- Input — keyboard, mouse, and multiple gamepads
- Text — TrueType and multi-file bitmap fonts
- JSON — reading arbitrary config/data files from Lua
- A scripting/sequencing layer — queuing stage transitions and scripted waits without hand-rolled state machines
- Content encryption — sealing a whole game’s Lua and assets into one encrypted
.zip, openable only by the build it was sealed for - A packaging tool (
--pack) — turning a loose source folder into that sealed.zipwith one command
None of that was there on day one, and none of it is the last of it either.
Sometime back, I ended a story about a transforming ship by saying more forms were coming, without saying what they’d be. This was one of them. It won’t be the last.
Enjoy.
[]’s
PopolonY2k
Scarab GitHub project link
https://github.com/popolony2k/scarab
