The tutorial, chapter by chapter — Chipgrid

The app’s tutorial, in full, to read before a workshop or come back to later. In the app it opens by itself on the first visit, then from the TUTORIAL menu. You type everything yourself: glowing characters show where, and each step moves on when it is right. show me types the step for you.

1. What is 8-bit?

What is “8-bit”? A processor works on numbers of a fixed size. The home computers and consoles of the late ’70s and ’80s used 8-bit processors (MOS 6502, Zilog Z80): one byte at a time — values 0 to 255, written 00 to ff in hexadecimal (chapter 4) — at about 1 MHz, with 2 to 64 KB of memory. Less than one photo on your phone. Every sound and picture had to fit in that.
The machines. Atari 2600 (1977) · ZX Spectrum and Commodore 64 (1982) · Famicom/NES (1983 in Japan) · Sega Master System (1985) · Game Boy (1989). Each had its own sound chip with a handful of voices: that chip is the instrument we call “8-bit”. The Spectrum didn’t even have one — the processor clicked the speaker itself
A sound chip is not a synthesizer. The NES chip had exactly four voices: two pulse waves, a triangle and a noise generator. No recordings of real instruments, no reverb, a volume in 16 steps. Chipgrid emulates this chip, sample by sample.
Composers turned the limits into a style. Koji Kondo wrote Super Mario Bros. (1985) and Zelda (1986) for these four voices; Hirokazu Tanaka the eerie Metroid (1986). On the Commodore 64 (3 voices, but with a filter), Rob Hubbard and Martin Galway invented tricks that are still copied today.
The tricks — you’ll use all of them: an arpeggio fakes a chord · the duty changes the timbre · a pitch drop turns a tone into a drum or a laser · a fake echo: the melody again, quieter, on the second voice · channel juggling: the kick interrupts the bass
Pictures had the same limits. The NES drew 256×240 pixels from about 54 colours, only a few per area, and at most 8 sprites on a line (more and they flickered). Tricks: small mirrored sprites, palette cycling, scrolling, raster bars. In Chipgrid the screen starts black: everything on it is drawn by your code, as on those machines, where the program had to put every pixel there itself.
After the consoles: chiptune. The demoscene kept coding for these machines. Trackers (Soundtracker, Amiga, 1987) shaped how music is written in rows. Then the old hardware became an instrument: Nanoloop (1998) and LSDJ (2000) on the Game Boy, the Blip Festival in New York (2006–2012), Anamanaguchi, Chipzel, PICO-8 games…
How Chipgrid works. The grid is a program, a bit like the live-coding tool Orca: letters are operators; every tick (a 16th note) each one reads its neighbours and writes below. It drives the 4-voice chip and draws on the screen. The history is also in the Why 8-bit? tab. Ready? Your first sound.

2. First sound

This grid is a program. Every cell holds one character. The orange box is your cursor: move it with the arrow keys, or click (tap) a cell. Each step tells you what to type — the glowing cells show where. On a phone, use the key pad at the bottom.
Type a capital D in the glowing cell. D is a beat: it makes bangs.
Now type 8 just right of it — D’s input: “a bang every 8 ticks”. A tick is a sixteenth note, so 8 ticks = 2 beats. The green dot under D is where it writes.
Press Ctrl+Enter (or ▶). Every 8 ticks a red * appears under D: a bang. It lives for one tick.
Silence — a bang alone makes no sound. Type P in the glowing cell, right next to where the bang appears. P is a pulse voice: when a bang touches its left side, it plays.
Give P its inputs: octave 4, note C, duty 2, length 4 ticks. Type 4C24.
Listen: every bang plays a C, and P flashes when it fires. (Stopped? Ctrl+Enter (or ▶) again.)
Live coding: move onto the C and type E, G or A. You hear it on the next bang — no need to stop.
Faster: change the 8 after D into 4 (every beat) or 2.
Change the duty 2 into 1 or 0: a narrower pulse, a thinner, more nasal sound — the NES lead. (The Why 8-bit? tab draws the wave shapes.)
Last input: the length. Change the 4 into 1 for a blip — or g (= 16) for a long note.
Done! A one-note sequencer: D makes time, * carries it, P turns it into sound. Next: a melody.

3. A melody

Here is a beat 1D2 (every 2 ticks) playing a pulse P. Press Ctrl+Enter (or ▶).
A melody needs a list of notes. Type S — a sequence — in the glowing cell, right above P’s note input.
To the right of S type a row of notes: CEGEAGED — or your own, at least 4. Lowercase means sharp: c = C#.
S writes one of its notes below itself — straight into P’s note input. But which one? Its index (the purple dot on its left) is empty, so it always picks step 0: the first note.
Let’s count. Type 2C8 starting at the glowing cell. C is a clock: it counts 0, 1, 2 … 7, one step every 2 ticks, and writes the count below — right into S’s index.
Listen: the clock counts, the sequence picks, the voice plays. Clock → sequence → voice is the heart of every tracker.
Rewrite the notes while it plays: CDEFGABC, a tune you know, anything.
Change the clock’s 8 into 4: only the first 4 notes loop. Try 3 or 5 for odd loops.
Done! Next: how to write numbers bigger than 9 in a single cell.

4. Counting past 9

One cell, one character. So how do you write 12, or 16? After 9 the count goes on with letters: a = 10, b = 11 … z = 35. Ten digits + 26 letters = 36 symbols: base 36. 00112233445566778899a10b11c12d13e14f15g16h17i18j19k20l21m22n23o24p25q26r27s28t29u30v31w32x33y34z35
Let’s watch a counter. Type 1Cg: a clock that steps every tick and counts g = 16 values, 0 to 15.
Press Ctrl+Enter (or ▶) and watch the cell under C: 0 1 2 … 9, then a b c d e f, and back to 0. The step moves on when you see f (15).
That is hexadecimal. These 16 symbols, 0–f, are how the programmers of 8-bit machines wrote numbers. One hex digit holds exactly 4 bits (0000 to 1111, 16 values); two hex digits hold a byte: 00 to ff = 0 to 255. Base 36 starts exactly like hex and just carries on after f. (The Why 8-bit? tab has a byte you can flip bit by bit.)
Many chip settings were 4 bits, one hex digit: the NES volume (16 levels), the C64’s 16 colours, the 16 noise speeds. So in Chipgrid colour, background, noise pitch and the volume I reads all go 0–f. Write g there and it wraps round to 0, like a counter with only 16 positions.
Back to base 36: change the g into w (= 32). Now the clock counts past f.
Watch: … e f g h … up to v (31), then 0. The step moves on at v.
Sums too. A adds its left and right neighbours and writes the result below. Type 9A3.
Under A: c. 9 + 3 = 12, and 12 is written c. (Stopped? Ctrl+Enter (or ▶).)
Change the 3 into r (27): 9 + 27 = 36, one more than z. Like a car’s odometer, the count goes round to 0.
One trap: letters in a note input. There, C D E F G A B are notes and lowercase c d f g a are sharps — so c means C#, not 12. If a sum lands in a note input, keep it below 10, or expect a letter to be read as a note. Put the cursor on any value: the Cell tab tells you what it means.
Done! You can read every number on the grid now. Next: drums — on a chip that has no drum sounds.

5. Drums

Drum patterns have 16 steps. Start with a clock counting to 16: type 1Cg (in base 36, g = 16).
Below-right of the clock, a sequence of hits: * = hit, 0 = rest. Type S*000*000*000*000.
The NES had no drum sounds. A kick is the triangle voice with a fast pitch drop: type B3C2o (octave 3, C, 2 ticks, drop o = 24 semitones).
Press Ctrl+Enter (or ▶) if stopped. Four on the floor! When the step is a *, S writes a bang right next to B.
One clock for all the drums: type J under the clock’s output. J copies the cell above it to the cell below it.
Hi-hats on the offbeats: S00*000*000*000*0.
Hats are noise: N010 = pitch 0 (the highest hiss), 1 tick, mode 0.
The snare: another J, a pattern on beats 2 and 4, and a lower, longer noise N530. Three glowing spots.
Kick, hats, snare — a full beat from 2 voices. Hats and snare share the one noise channel: when they collide one wins (STEAL on the meters).
Edit the kick pattern: add a * on step 10 or 14. Every breakbeat lives in a row like this.
Make the snare metallic: change its last input 0 into 1. Mode 1 makes the noise loop after 93 steps — so short you hear a pitch.
Done! Next: chords and bass.

6. Chords & bass

Chords change slowly: a clock stepping once a bar (16 ticks), 4 values. Type gC4.
A beat every 4 ticks 1D4, and the chord roots SCAFG (C, A, F, G) right under the clock.
G is an arpeggio: a whole chord on one voice. Type G3, skip the note cell (S fills it), then 24: chord 2 = major, 4 ticks.
Play it. That shimmer is three notes flicking 50 times a second — the ear hears a chord. The Commodore 64 sound.
Change the chord type 2: 3 minor, 5 major 7, 1 power fifth.
Bass on the triangle: the same clock and roots, a beat every 2 ticks, two octaves down. Tip: “show me” fills it in if you’re in a hurry.
Chords + bass: two of the chip’s four voices, and a whole harmony.
Done! Next: movers — arrows that fly and play what they hit.

7. Movers

E is an emitter: every 8 ticks it launches a mover >. Type 8E.
Play, and watch the arrows fly — one cell per tick.
Put a voice in their path: P5C02. When an arrow hits it, it turns into a bang on P’s left.
Hear it? The distance between E and P is a delay.
A second lane, every 6 ticks, playing a G.
A third lane every 12 ticks (c = 12) with a hat.
8, 6 and 12 drift in and out of phase: polyrhythm. Try other numbers: 5, 7…
Experiment: type an x in a lane (the arrows explode earlier), or a v above a voice (it falls and plays it once). Done! Next: drawing with code.

8. Draw with code

The screen is black: nothing is drawn unless your code draws it. It is 32 × 24 big pixels (“blocks”). First the colours: V3 picks palette 3, the CGA PC’s.
X draws a pixel every tick: x g (16), y c (12), colour 4. Type Xgc4.
Press Ctrl+Enter (or ▶) if it isn’t running: a red block in the middle of the screen.
Make it move: type 1Cw right above X. The clock counts 0…31 (w = 32) into X’s x input. The drawing is kept, so the block leaves a line.
T dissolves the drawing a little every tick — random pixels go out: type T3 for trails. Try T1 (long) or T8 (short).
O draws a sprite: an 8×8 creature of random bits, mirrored. Inputs: x, y, seed (which creature), colour. A clock 4C8 on the seed makes it morph every beat.
In time with the music: Kwipes the screen when a bang touches it, like a sound. 1Dg bangs every 16 ticks: a fresh screen every bar.
Raster bars: H draws a horizontal bar (x, y, width, colour). A random 0Rn (0…23) feeds its y, so a bar appears at a random height every tick.
M scrolls everything: direction 2 (up), 1 pixel a tick. Type M21 — the bars rise. Hardware scrolling is how Super Mario moved its world.
Done! Pixels, bars and sprites take any value from the grid — the same values that play notes. More ideas — and more operators: W wave, L line, Q ring, Z mirror, I listen — in the Visuals examples (copper bars, radar, kaleidoscope…). Last chapter: the full song and recording.

9. Chance and scales

A fast beat on one note. Type 1D2, and the voice on its bang.
Press Ctrl+Enter (or ▶). Boring on purpose.
R writes a random number below it, here between 0 and 11 (b), right into the note. Type 0Rb.
All twelve notes, in any order: it sounds lost. Chance alone isn’t music. It needs a list of notes that go together: a scale.
Clean up: put the cursor on the R and press Delete.
Now R picks a position, 0 to 4, in a sequence holding C D E G A, the pentatonic scale. Type the three lines.
Random, and never wrong. Change the notes in the list, and you change the mood. Done! See also Dice drums in the examples.

10. Waves and motion

A clock jumps back to 0 at the end. W writes a wave that swings smoothly up and down. Here, 0 to 31 (v), into the x of a pixel.
Add a short trail: T4.
Press Ctrl+Enter (or ▶). It slows down at the edges, like a pendulum.
Its y is right next to its x, so no room above it. Y sends the value on its left to a cell further right and down: 1 right, 2 down lands on the y.
Two waves of different speeds on x and y: a Lissajous figure, as on old oscilloscopes. Change 3 and 4. Done!

11. Effects

Effects change what is already on the screen. First something to work on: a sprite, and a slow fade.
Press Ctrl+Enter (or ▶).
+ zooms everything a little, every tick. The sprite leaves copies of itself: feedback, as when you film a TV with its own camera.
Z2 mirrors the picture both ways: instant kaleidoscope.
% shifts all the colours along the palette. A clock on its input keeps them flowing.
= ripples the rows along a wave.
/ glitches. With amount 0 it waits for a bang: one burst on every bar. These effects all react to a bang touching them.
Watch for the burst.
Effects build on each other: delete one and see what it was doing. Done! See Tunnel and Kaleidoscope in the examples.

12. Words and your own sprites

" draws text: x, y, colour, then the letters, until an empty cell. _ is a space. Put your name instead if you like.
Press Ctrl+Enter (or ▶).
]2 just above makes it twice as big.
$ draws your own sprite: x, y, width, height, and the picture in the cells below it. Each digit is a colour, each empty cell is see-through.
Change a digit while it plays: the picture changes with it. The code is the drawing. Done! See Text scroller, Typewriter and City at night.

13. Gates and links

Until now, drawing operators drew on every tick. Time to draw on the beat. First a beat: type 1D8.
? is a gate. The operator on its right runs only when a bang touches the gate. The bang from D lands just left of it. Type ?Xgc7.
Add T4, so the block fades between two beats.
Press Ctrl+Enter (or ▶). The block blinks in time. ?V changes palette on a new section, ?! changes the tempo on cue, ?P plays a voice. A gate that turns red can do nothing there: movers, and operators with an input on their left, like C.
Now wires with no cable. @k sends what is on its left under the name k: here, the bang from 1D4.
Far away, &k receives it and writes it below itself. Type it in the glowing cells.
Put a voice right of where the bang arrives: P5C12.
Nothing joins them, and it plays. You can now lay out your code as you like. Links carry values too, not just bangs.
In multiplayer: a lowercase name like k is yours alone. An uppercase name like K is shared with the whole room: one player sends, and whoever wants it listens. Done! Next: tracks you can see.

14. Tracks and loops

Let’s build a track that never ends. ) turns a mover to its right. _ is a rail: movers ride over it and it comes back behind them. Type the top of the loop.
The sides: | is the same rail, for going up and down.
And the bottom, with two more turns. Four ) close the loop.
Now the train: type one > on the top rail, just after the first turn. It doesn’t move yet if the program is stopped.
Press Ctrl+Enter (or ▶) and watch it go round, with its tail behind it. No emitter, nothing used up: a loop 2 × (7 + 3) − 4 = 16 ticks long, exactly one bar.
A turn gives a bang to whatever touches it as the train goes round. Put a kick under the bottom-left turn: B2C2.
And a picture above the top-left turn: a gate and a ring, ?Qgc87.
T3 to fade it. You now have a sequencer you can see: the shape of the code is the rhythm.
Try it: type a second > on a rail for twice as many hits. ( turns left, for loops running the other way. : with a ^ or v on its right is a switch whose way out can change. Lost track of your arrows? reset puts them back where you typed them.
Rearrange it: drag across the whole loop to select it, then drag the selection (or use Ctrl + arrows): your code moves in one piece. If the grid looks too small, − 100% + at the top zooms it. Done! For more, see Routes and Code as art in the examples.

15. Switches

A lane of rails ending in a switch. : sends each arrow the way the cell on its right says: ^ up.
Above it, two rails and a voice. The arrow stops under the voice, and becomes a bang.
Press Ctrl+Enter (or ▶).
Build the other way: two rails down, and a bass.
Change the ^ into a v: the arrows go down instead.
Now let the music choose. A clock walks a list of directions, ^v, and sends it on the link r. &r writes it into the switch. It has nothing on its left, so the way up stays open.
One stream of arrows, two voices, taking turns.
Write a longer list, like ^^v^, and set the clock’s 2 to its length. Add a third way out to the right. Done! See Scene router and Effects board.

16. Fill the screen

So far, marks on black. ~ is a field: one line that paints the whole screen. Pattern 0 (plasma), speed 2, scale 3, colours from 1, over 8 colours. Type ~02318.
Press Ctrl+Enter (or ▶). Change the first 0 later for other patterns: 3 rings, 4 checkerboard, 7 tunnel.
A field stays on the back layer, so what you draw is always in front. ]3 makes what follows three times as big, which helps on a projector. Type it, then a sprite below it.
Now make something pulse. ; jumps to 15 (f) on a bang, then falls by 1 each tick. Its value feeds the radius of a ring: it jumps with the beat and shrinks back by itself.
Watch the ring breathe. Wire a swell into anything that takes a number: a size, a colour, a zoom.
T4 dissolves random pixels. Add a 1 after it and it fades through the palette instead, with no holes: T41.
Layers: [0 back, [1 middle, [2 front. Everything below a [ goes on that layer, and T, M or K only touch their own. So a sky stays still behind a ship that leaves a trail. See the example Depth. Done!

17. The picture plays

Until now the code made the picture. Now the other way round. Draw a bar on the screen: x 0, y 12 (c), 8 blocks wide, colour 1.
, is an eye: it looks at one block of the picture. Its x is the clock above it, sweeping across the screen.
Then its y, c, the same row as the bar. The 1 means: write a bang when you see something.
A voice right of where its bang appears: P5C02.
Press Ctrl+Enter (or ▶). You hear the bar: it plays while the eye passes over it, then silence.
Add a second, shorter bar further along. You have just written a rhythm by drawing it.
Without the 1, the eye writes the colour it sees, and that number can be a note: a row of colours becomes a melody. See Player piano and Rainbow tune in the examples. Done!

18. Making it a song

Here is a loop: chords, bass and drums. Press Ctrl+Enter (or ▶). It is nice, and after a minute you stop listening. A song needs things to change.
A break: -14 cuts all sound for 1 beat in every 4. The return on the downbeat is what makes you move.
Tempo on cue. Every 64 ticks 8D8 bangs the gate, and ?! reads a new speed: the clock is its tens digit, so 105, 115 or 125.
The picture follows the structure. On the same bang, ?V changes palette: a new section, a new colour.
Wait for the change, about 16 beats.
Real songs swap whole parts too: see Verse and chorus, where a slow clock changes the chords, and Two scenes. When you like it, the next chapter shows how to record it. Done!

19. Playing together

Chipgrid Multi puts up to 10 players on one big grid, on the same Wi-Fi. On one laptop, run bash start.sh in the multi folder. It prints an address: everyone opens it. Put ?stage at the end on the projector.
What is yours: your own 4-voice chip, your - silences, your lowercase links, your [ and ]. What is shared: one tempo, one palette, one picture. So a K wipes it for everyone. It is one program: an output can even overwrite someone else’s code.
Play to each other with uppercase links: one player sends a beat with @B, and whoever wants it reads &B. Nobody is forced to follow. See Room link and Room railway.
Good to know: the grid saves itself, so a crash loses little. For a new session, start with bash start.sh --new. If your Wi-Fi drops, reopen the page and you get your slot back. Done!

20. Screen & recording

This is the demo song — all four voices at once. Press Ctrl+Enter (or ▶). Put your cursor on anything: the Cell tab explains it.
The picture is code too. Right of the melody, J copies each note down to an X on the right edge (its y = the note), and M05 scrolls everything left: a piano roll. F1 flashes on the snare. Hover (or tap) any cell to see what it does.
Bottom left, V00 sets palette 0 and background 0. Change the palette into 2 (Game Boy): everything already drawn changes colour at once — the screen stores colour numbers.
And the background 0 into 3: the light green of a real Game Boy screen.
F1 under the snare flashes the screen. Change its colour 1 into 4.
Last thing: press ● REC, let it play, press it again — you get a video (.webm) of your piece, picture and sound. Tutorial complete! Explore the examples, or start from a new grid.