Lantern Console
User's Manual

Lantern is a retro game console powered by AI. You describe the game you want in plain English, and the AI writes the code for you. You don't need to know how to program — just know what you want to create.

How Your Game Runs

Every Lantern game has a simple rhythm: it sets up once when it starts, then thinks and draws 60 times per second. That's what makes everything feel smooth and responsive.

Screen Sizes

You can choose between three screen resolutions. The default "hires" mode is great for most games. Use "lores" for a chunkier pixel-art look, or "720p" for higher detail.

Lantern uses an SNES-style controller layout: a d-pad (up, down, left, right) and four action buttons (A, B, C, D). This works on keyboard, gamepads, and touchscreen.

The Controller

In single-player mode, both keyboard layouts work — you can use WASD or arrow keys interchangeably.

Mouse & Touch

Games can also use pointer input — clicks, taps, and hover position. Great for strategy games, drawing tools, or menus. The terms to know are ptr_click (just tapped), ptr_down (held down), and ptr_pos (where the cursor is).

Custom Controls

You can remap any button to a different key using key_remap. The on-screen labels update automatically to show players the right key.

The Lantern Console draws everything fresh each frame, 60 times per second. Things drawn later appear on top of things drawn earlier — like painting on a canvas, layer by layer.

What You Can Draw

The Color Palette

Lantern has a 256-color palette. Drawing functions use a palette index for color. The default palette uses PICO-8 colors for the first 16, shown below with their names. The full palette includes darker shades, pastels, grayscale ramps, skin tones, metallics, nature tones, neons, earth tones, fantasy hues, and a rainbow gradient — all ready to use by number.

Custom Colors

You can also change any palette color at runtime using pset_pal — just pick a slot (0–255) and set any RGB color you want. This means you're not locked into the defaults; you can create a completely custom palette for your game.

For sprites and images, you can use the tint option with RGBA values (0–1 each) to modulate colors directly — useful for flashing enemies red on hit, fading sprites, or creating color variations without changing the palette.

Word Wrapping & Text Layout

print supports automatic word wrapping — pass a pixel width as the last argument and text will break at word boundaries to fit.

Use text_layout to measure text without drawing it — it returns the wrapped lines and dimensions so you can size a box before rendering. Combined with font_height (which returns the current line height in pixels), this makes dialogue boxes and paginated text easy to build.

Camera & Clipping

The camera controls what part of the world is visible — essential for scrolling games.

clip(x, y, w, h) restricts all drawing to a rectangle — anything outside it is invisible. Useful for minimap windows, split-screen, or HUD panels. Call clip() with no arguments to clear the clip region and draw normally again.

Sprites are the images that make up your game — characters, enemies, items, backgrounds. You load them from PNG files, and the engine handles the rest.

What Sprites Can Do

• Sprite sheets — a single image containing multiple frames of animation, sliced automatically by the engine using load_image
• Scale up or down — make sprites bigger or smaller, or flip them horizontally/vertically
• Rotate — spin sprites around any pivot point
• Tint & transparency — recolor sprites or make them semi-transparent (great for ghosts, damage flashes, shadows)
• Sub-regions — draw just a piece of a larger image using draw_region

Tilemaps are how you build levels and game worlds. Instead of placing every pixel by hand, you create a grid and fill it with tiles from a tileset image — like arranging puzzle pieces on a board.

What You Can Build

• Platformer levels — ground, walls, platforms, hazards, all from a tileset
• Top-down worlds — RPG overworlds, dungeon rooms, maze games
• Parallax backgrounds — multiple tilemap layers scrolling at different speeds for depth
• Tile collision — the engine can check which tile is at any position, so characters interact with the world naturally

PostFX are full-screen visual effects applied on top of your game. They don't change gameplay — they change the mood. You can combine multiple effects, and they're all controlled through postfx.

Available Effects

Lantern has a full audio system — sound effects, multi-channel music with stem mixing, and a built-in chiptune synthesizer for instant retro sounds.

Sound Effects

Load any OGG or WAV file with load_sound and play it with play_sound. Sounds can play once or loop, and you control the volume. Stop them anytime with stop_sound.

Music with Stems

Music supports 5 separate channels (stems) that play in sync. You can fade individual channels in and out during gameplay — for example, adding drums when the action picks up, or muting everything but the bass when the player enters a cave.

Audio Atmosphere

The audio engine has built-in post-processing presets that change how everything sounds — like putting the whole game underwater, in a cave, or on an old radio. These transition smoothly.

Available Presets

You can also fine-tune with custom filters (lowpass, highpass, bandpass, notch) and reverb (room, hall, cave, plate, spring, shimmer).

The built-in Retro16 synthesizer generates chiptune sounds in real-time — no audio files needed. It uses a soundfont-based engine with 8-voice polyphony. Perfect for quick sound effects (bleeps, bloops, fanfares) and even full tracker-style songs.

Quick Sound Effects

Use synth_sfx to play an instant sound that stops on its own — pick an instrument, a note, how long it plays, and volume. Great for jump sounds, coin pickups, menu clicks, and hit effects.

Sustained Notes

Use synth_music_note for notes that play until you stop them — useful for building chords, ambient drones, or musical sequences.

Instruments

Lantern comes with 16 built-in instruments:

Tracker Songs (MTS Format)

The synth can play full songs written in MTS (Music Tracker Song) format — a compact text-based format where notes are arranged in patterns, like a spreadsheet of music. The AI can write these for you.

An MTS song has three parts:

• Song header — name, tempo (BPM), and speed
• Patterns — rows of notes using named instruments (like Piano, Kick, Lead) with volume and effects
• Sequence — the order patterns play in (you can repeat patterns to build full songs from short loops)

The engine includes built-in math helpers that the AI uses behind the scenes. Knowing what's available helps you describe what you want more precisely.

Randomness

There are two kinds of random numbers:

• Gameplay random (sync_rnd) — affects game logic like enemy spawning, loot drops, damage. These stay consistent in multiplayer.
• Visual random (vrnd) — for effects like particle direction, screen shake, sparkles. Doesn't affect gameplay.

Common Math Concepts

Games can save and load data that persists between play sessions using dset (save) and dget (load). This works for high scores, unlocked levels, player preferences, or anything else you want to remember.

• Save numbers, text, tables, or true/false values
• Data survives closing and reopening the game
• Each game has its own separate save data

Where Data Is Stored

Lantern has built-in online leaderboards. Players can submit_score and see how they rank against others with get_leaderboard. Scores are tied to their account — players sign in with their Discord account to submit and track scores.

What You Can Do

• Submit scores — the server only keeps each player's best score per board
• Multiple boards — have separate leaderboards for different things (e.g., "score", "speedrun", "kills")
• Attach metadata — store extra info with each score like which character they used or what level they reached
• Show personal best — check the current player's own rank with get_my_score

Lantern supports up to 4 players playing together online with rollback netcode — the same technology used in modern fighting games. Input is synchronized automatically.

How It Works

For multiplayer to work smoothly, the game must be deterministic — given the same inputs, it must produce the same result on every player's machine. The engine handles this automatically if you follow a few guidelines:

• Keep all important game data in the GameState table — this gets synced between players
• Keep visual-only stuff (particles, screen shake, animations) in a separate VisualState — this doesn't need to match
• The AI knows these rules and will organize your code correctly

What to Know

As your game grows, the AI will automatically split the code into separate files to keep things organized. Each file handles one part of the game — player logic, enemies, levels, UI, etc.

Typical Game Structure

You don't need to worry about this — the AI handles file organization. But if you want to look at the code, this is how it's structured. Files are linked together using require.

"Juice" is the magic that makes a game feel good. It's the screen shake when something explodes, the satisfying sound when you collect a coin, the way a character squashes when they land. None of it changes the game's rules — but it makes everything 10x more fun.

The Juice Techniques