A browser-based learning environment for the Lilka game console. Write a program, run it, take it away on the memory card — no installation required.
▶ Try it · Architecture · Lilka
The program must behave in the browser exactly like it does on hardware. Not "close enough" — pixel for pixel, frame for frame.
This isn't pedantry. The environment is meant for learning, and the costliest mistake here is a student writing a program that works in the browser but behaves differently on a real Lilka. That's why the emulator is ported from the firmware line by line, including quirks that look like bugs.
- Lua 5.4 with the firmware's lifecycle:
init/update(delta)/draw, 30 fps - 280×240 screen in RGB565 — primitives ported from
Arduino_GFX, no Canvas 2D - Fonts
u8g2_font_*_t_cyrillic, all nine, with Cyrillic letters - Images BMP and PNG, transforms, anchor point, transparent color
- File system
/sd,/spiffs,/tmppersisted between sessions — both firmware namespaces,fs.*and the oldersdcard.* - Sound via WebAudio, with the same notes as the firmware
- Buttons from keyboard or mouse, with
just_pressedsemantics matching hardware - Export to card — as an archive or written straight into a folder
- Editor with Lua syntax highlighting and autocompletion from 253 hints
- Run on a real Lilka over USB, plus a console for one-off commands
- English and Ukrainian interface, detected from the browser and switchable live
- Widgets
alertUI,keyboardUI(with a Ukrainian layout),progressUI
Lua API coverage: 118 of 181 functions; within scope — 118 of 119 (99%).
Missing: audio.play — playing audio files.
The rest of the gap is hardware namespaces that will never exist in a
browser: gpio, spi, wifi, mqtt, and others.
The best measure isn't the percentage — it's that real programs run without
edits. Bundled as examples: Asteroids, with four modules via require
and sixteen resources; Snake, with a high-score table via state; the
official examples/LUA/cat; and the community games "Dice" and "Repeat the
pattern".
Importing and exporting via GitHub. See Issues.
npm install
npm run dev # http://localhost:5173 — open in ChromeChrome is required because Lua runs in a Web Worker with SharedArrayBuffer,
which needs COOP/COEP headers. Locally these come from the Vite dev server;
in production, from coi-serviceworker. Firefox and Safari support them too,
but the environment hasn't been tested there yet.
All generated files are already in the repository — nothing to catch up on.
npm run check # 124 automated checks
npm run build # tsc --noEmit + vite build -> dist/
npm run test:e2e # Playwright: does the editor work in a real browsertest:e2e needs a browser the first time: npx playwright install chromium.
Other commands
npm run check:primitives # geometry
npm run check:fonts # fonts
npm run check:images # raster and transforms
npm run check:vfs # file system
npm run check:completions # autocompletion
npm run check:widgets # UI widgets
npm run check:runtime # Lua runtime
npm run proxy # local CORS proxy for http.execute (see above)
npm run gen:api # regenerate lilka-api.json from keira
npm run gen:fonts # regenerate fonts (pulls ~40 MB of source, cached)
npm run gen:fmath # sine tables
npm run gen:notes # note table
npm run gen:completions # editor hints from firmware annotations
npm run gen:icons # keyboard icons
npm run gen:coverage # API coverage report
npm run render:testcard # test-card PNG without a browserScripts ending in .mts run via node --experimental-strip-types, so
Node 22+ is required.
http.execute works in the browser, but the browser adds two rules a real
Lilka doesn't have:
- a page may only read responses from servers that allow it with a CORS
header (
Access-Control-Allow-Origin); - a page opened over
https://can't requesthttp://addresses.
Many APIs scripts use — Yahoo Finance, for example — don't send that header,
so the request ends with code -1, and a "Network request blocked" bar
appears under the device. The way around it is a small proxy on your own
computer: it makes the request itself and hands the answer back to the IDE.
-
Install Node.js 18 or newer.
-
Download
lilka-proxy.mjs— or take it from the bar's "How to start the proxy" link. It has no dependencies. -
Run it in a terminal from the download folder:
node lilka-proxy.mjs
From a clone of this repository:
npm run proxy. -
In the IDE, open Network in the toolbar (or use the bar under the device), enter
http://localhost:8787, press "Check", then "Use", and run the program. A green dot on the Network button means the proxy is on. -
When Chrome asks to let the site access apps or devices on this computer, allow it: from the browser's point of view the IDE is a site on the internet talking to your computer (Local Network Access). Without that permission the proxy looks unreachable even though it runs. If you dismissed the prompt, allow it by hand: the icon left of the address → Site settings → Local network access → Allow, then reload.
The setting lives in memory only, so after a page reload it has to be entered again.
What the proxy does, and doesn't:
- It listens on
127.0.0.1only — other computers can't reach it. - It answers only the IDE's own sites and
localhost. If the IDE is served from somewhere else (a fork), add it:node lilka-proxy.mjs --origin https://you.github.io. Otherwise any open tab could use the proxy to reach your local network. - It signs requests
Lilka/…, like the firmware, and doesn't follow redirects, like the firmware'sHTTPClient— the script sees the3xxcode. --port 9000changes the port.
.github/workflows/deploy.yml type-checks, runs npm run check, and only
then builds and publishes to GitHub Pages — broken code never reaches it.
VITE_BASE is filled in from the repository name automatically.
.github/workflows/ci.yml does the same plus npm run test:e2e and npm run build — on every pull request and every push to main. Without it a PR
could be merged without any automated check at all: deploy.yml doesn't
react to pull requests.
public/coi-serviceworker.js must stay a separate file outside the bundle,
served from its own origin — otherwise there's no SharedArrayBuffer, and
without it the runtime won't start.
In short: Lua runs in a Web Worker and writes pixels straight into a
SharedArrayBuffer; the main thread only presents them on a canvas. The
worker sets the pace — 30 fps at a flat 33 ms, like perfectDelta in the
firmware.
Details, diagrams, and the reasoning behind it all — in ARCHITECTURE.md. That's also where the catalog of deliberately reproduced hardware quirks lives.
Rules for working with the code (including via AI) — in CLAUDE.md (Ukrainian; it's the project's internal contributor/AI convention document).
The most useful thing right now is bringing real Lilka programs and
checking whether they run. Every such attempt so far has found something:
that's how a missing buzzer, an unknown notes table, and namespaces that
turned out to be userdata instead of tables were found.
If a program doesn't run — file an Issue. The cause could be the emulator (the most interesting case), the program itself, or a capability that's fundamentally unreachable in a browser — like networking or GPIO pins. Either way, it's worth digging into.
What to attach to the Issue:
- the program's code or a link to it
- the message from the environment's console, if there is one
- what should have happened and what happened instead
| What | From | License |
|---|---|---|
| Raster primitives | moononournation/Arduino_GFX |
BSD-3-Clause |
t_cyrillic font data |
olikraus/u8g2 |
BSD-2-Clause |
| Sine tables, pins, constants | lilka-dev/sdk, lilka-dev/keira |
MIT |
| Lua runtime | wasmoon |
MIT |
| COOP/COEP | coi-serviceworker |
MIT |
| Examples | Lilka community programs | with authors' permission |
Fonts and primitives weren't copied as files: they're generated by gen-*
scripts from the source. But the derived data lives in the repository, so
attribution is worth keeping.
GPL-2.0-or-later.