Getting started

Omibit is a fantasy console. You write Lua, the machine runs it at 60 frames per second on a 128x128 screen with 16 fixed colors, and the result is a cartridge: a PNG file you can keep, send, or share as a link.

This page takes you from nothing to a shared cart. No install, no account.

Open the console

Open the omibit site and press Make a cart. The editor runs in your browser. Work is autosaved to your browser storage as you go — your last cart is silently restored the next time you open the editor.

You can also open any omibit cart PNG with the editor's import button, or drop one straight onto the player to play it. Press Play all carts to try the lobby before writing anything.

The editor tabs

The editor has five tabs, one per cart section:

• code — the Lua source. Syntax highlighting, error line numbers, and

Tab-to-indent are built in.

• sprites — the sprite sheet. 128 sprites of 8x8 pixels, painted one

pixel at a time with the 16 console colors.

• map — a 128x64 grid of cells. Each cell holds a sprite number (or 0

for empty); map() draws it in one call.

• sfx — 64 sound effect slots. Each slot is a list of up to 31 notes

you can edit and audition in place.

• music — 64 patterns that sequence sfx slots onto four channels.

Above the tabs: run plays the cart in place. Esc comes back to the editor. Cmd/Ctrl+Enter runs from any tab. On the right: export png, export html, and share.

Hello, omibit

Make sure you are on the code tab, clear what is there, and paste:

-- hello, omibit
t = 0

function _update()
  t = t + 1
end

function _draw()
  cls(0)
  print("hello, omibit", 34, 58, 10)
  print("frame " .. t, 40, 70, 13)
end

Press run. Every frame the machine calls _update() then _draw(). cls(0) wipes the screen to black, print draws text at pixel coordinates, and the third number is a palette index — 10 is sky blue, 13 is silver.

The full list of functions is in the API reference (this site's docs section, docs/API.md in the repo). It is short; the whole API is one table.

Make it yours

Change the code to take input. The six buttons are btn(0) through btn(5), mapped to the arrow keys, Z, and X:

-- a dot you can steer
x, y = 60, 60

function _update()
  if btn(0) then x = x - 1 end
  if btn(1) then x = x + 1 end
  if btn(2) then y = y - 1 end
  if btn(3) then y = y + 1 end
end

function _draw()
  cls(0)
  circfill(x, y, 3, 3)
  print("dpad moves the dot", 24, 120, 13)
end

btn(i) is true the whole time the button is held. btnp(i) is true only on the frame it goes down — that is the one to use for menu selections and single shots.

Press run again. You are playing a cart you wrote.

Run, fix, run again

If your code has an error, the run pane shows the message with a line number. Fix it, press Cmd/Ctrl+Enter. The edit-to-run loop is meant to be under two seconds — small changes, run often.

Sprites, map, sfx, and music edits carry too: there is no save step between edit and run — change a sprite, press Cmd/Ctrl+Enter, and the next run uses it.

Share it

Four ways out of the editor:

• export png saves a cartridge — a real 160x205 PNG with your cart

inside. The label on top is drawn from your cart. The file opens in any image viewer, and drops back into any omibit editor.

• share uploads the cart to the console's cache and gives you a cart

page of the form /cart/<hash>: a public home for the cart with the game playable inline, a remix tree, comments, and its verified replay board. You can give the cart a name in the share dialog; the link is copied for you. Anyone with the link plays it in the browser, no account needed. The hash is the cart: the site is a cache, not the source of truth — the file still works if the site disappears.

• export html bundles the cart with the whole player into one HTML

file that runs offline from a double-click.

• export source saves a lossless .o8proj archive with editable modules,

authoring records and original asset files. Reopen it with import source. Keep this archive to collaborate or continue editing; a PNG/HTML cartridge does not preserve the original multi-file project.

The player shows the frame count and the running state hash — the same hash the command line tools produce, because it is the same core running everywhere.

Where next

• Build a real game: the first game guide walks through a platformer,

controls to coins, one step at a time.

• Share pages, replays, the daily, and jams: the community guide.
• Sound and music: the audio guide.
• What the machine will and will not let you do: the limits guide — the

constraints are the point.