Draughts · how it hangs together

Draughts from above

What happens from the moment you tap the icon, what the one big loop does up to a hundred and twenty times a second (or not at all), who owns what, and which threads talk to which. Plain words. You can follow it with the code open next to you.

The whole thing in five sentences

The app is one program with one loop. Each time round, the loop reads your finger, asks the current screen "what do you look like now, and did anything change?", and only if something did, it paints the picture.

Everything that thinks (the rules, the board, the game, the screens, the layout) is plain code that knows nothing about the screen or the GPU. Everything that paints sits behind one renderer, src/app/render.goose, which the loop calls once a frame; everything that talks to the phone or the window sits behind the host, src/app/host.goose.

The computer opponent thinks on its own thread, so the screen never freezes while it ponders. They pass notes through two queues.

When nothing moves, the app sleeps. A ticking clock sets an alarm to wake it at the next second. That is why the battery lasts.

That is it. The rest is detail, and there is quite a lot of detail.

1. Waking up

All of this is in main() in src/app/draughts.goose, before the loop starts. It runs once. main() never calls the graphics library itself: it asks host for the platform and render for the pictures.

  1. Read the developer flags (--screen game, --fen …, --frames 30 and so on). On a phone there are none, so everything takes its normal value.flags::parse · src/app/flags.goose
  2. Ask the system for the storage folder, then read the players and the playing player's settings from it.host::storage (storage.c) · players::load
  3. Pick the language: the player's choice, else the first of the phone's languages that has a file, else English. Load the puzzles for the chosen draughts.host::locales · strings::pick, strings::use · puzzles::load
  4. Ask which platform this is (desktop, Android, iOS). Phones get a full-screen window, and on iOS home has no "close" button because iOS apps never close themselves.host::platform (launch.c)
  5. Open the window and the GPU. On Windows, first tell SDL to use Vulkan. This is the first time anything graphical happens.host::open → draughts_choose_gpu (display.c), gfx::open
  6. Make the Shell, the value that holds every screen and the game. Give it the player's settings, let the developer flags set up a game if they ask for one, then restore the saved game if there is one. A brand-new install opens on the "pick your badge" sheet.shell::new · shell::launch · dev::setup · shell::open → read_game, who::first_run
  7. Make the renderer. It makes all the painters at once: the flat-board drawer (it loads the season's photograph), the 3D-board drawer (empty for now; it gets ready a step at a time later), the UI drawer, and the text's state. Then the thinker (no thread yet).render::new → draw::new, draw3d::Drawer, widgets::new, text::Text · think::Thinker
Worth knowing. The computer's thread does not start here. It starts the first time the game actually asks for a move, so a game between two kids on one tablet never pays for the 6 MB search engine.

2. The loop, once round

while host::frame() { … }. One pass is one "frame". host::frame() shows the picture the last pass painted, then waits. If the last pass painted nothing, it waits for an event (a touch, a timer) for up to a second. So an idle app really is idle.

  1. Housekeeping for the window. Lost focus? Save the game now, because Android may kill a paused app without asking. Pause the clocks on phones. If the season changed two frames ago, load its photograph now.shell::write_game · shell::pause · render::reload
  2. Did the screen change? New size, rotated, a different notch or gesture bar, different display scale: any of these marks the frame "dirty". If the scale changed, bake the font again at the new size.host::screen_size · host::read_display (display.c) · gui::scale_of · render::upload_text
  3. Read the finger. Position, down, pressed, released, wheel; and typed letters if a name is being typed. Packed into a small gui::Input value and handed to the UI layer.host::input · gui::begin
  4. Back button or Escape. Go back a screen. On home's menu, Android's back puts the app in the background; Escape on the Mac ends the program.host::back · shell::back · host::leave
  5. Is the 3D board ready? If the player chose the 3D board, the renderer prepares it one step per frame so no frame stalls. Until it is ready the screen shows a still mark in its place. If the player went back to flat, the 3D board's memory is given back.shell::board3d · render::ready3d, render::shown3d · render::drop3d
  6. The screen declares itself. This is the heart. shell::frame calls the current screen (home, settings, the game, the puzzle list, a puzzle). The screen lays out its rectangles, declares its buttons, and handles the finger. A press that lands on a button belongs to the button; only otherwise does the board get it. Out comes a shell::Frame: what changed, where the board goes, how blurred the photograph is, and more (section 3).shell::frame → declare → home_screen / game_screen / settings_screen / picker_screen / puzzle_screen
  7. Pass notes to the computer. If the game now wants a move, put the question on the worker's queue. If an answer has arrived, give it to the game.think::frame
  8. Settings changed? The shell's frame says so (save). Write the player's file, switch language if needed, and schedule a new season photograph two frames later (so the tapped tile can light up first, before the 80 ms load).players::write · shell::wrote · season_in
  9. Paint, only if needed. If something changed or still moves: the board fills its draw lists, the loop packs everything the renderer needs into one render::Frame, and render::frame paints it all (section 4). Otherwise: nothing is drawn at all.shell::fill · render::Frame · render::frame
  10. Set the alarm. If a clock is running, or the computer's move is due, or a hint is on its way, set a timer to wake the loop exactly then.shell::wake_in → clock::until_next, game::due · host::wake_in (wake.c)

Developer tooling, the benchmarks (--bench), the idle measurement (--rest), scripted taps (--tap), and screenshots (--frames), lives in src/app/dev.goose. The loop calls it at a few fixed points (dev::before, dev::after_shell, dev::drawing, dev::drawn, dev::after), and with no flags given each call does nothing. On a real phone none of it runs.

3. What a screen hands back

The screens never reach out and change the app. Each frame they return what happened, and the loop decides what to do with it. Three pieces make that work.

The screen table

There are five screens: home, the game, settings, the puzzle list (the picker), and one puzzle. What sets them apart, where the shell runs none of their code, is one row each in a table, shell::KINDS. A row (shell::Kind) says whose board the screen shows, how blurred the photograph is behind it, where back goes, and which screens it slides to and from. The screens' own code is picked in one match (screen_frame). A new screen is a row in the table and an arm in the match.

The game's events

game::frame returns a game::Event: where to go (stay, home, settings), whether a game against the computer just ended and how, whether it was started over, and whether the lookout's eye was turned on or off. The shell reads it: it adapts the computer's level to how the child did, counts the game, and switches screens. No flag is set in one place and cleared in another.

The shell's frame

shell::frame returns a shell::Frame, filled anew every frame. The loop only reads it:

FieldMeans
changedAnything on screen changed, so paint.
screen, showsThe screen showing, and the one whose board shows (in a slide between home and settings, home's).
layout, overWhere the board is, and the pieces drawn over the UI.
blur, hole, tallHow blurred the photograph is, and the hole cut in the UI for the board passing through in a slide.
raised, view, place, fade, holdThe 3D board: on or off, its camera, where its picture goes and how opaque, and whether to keep the picture as drawn during a slide.
typing, keyboardA name is being typed: keep the keyboard up.
save, quitWrite the settings; home's way out was tapped.

Layouts as regions

Before a screen declares anything, a pure function works out where everything goes. It only measures: it draws nothing and changes nothing.

4. The renderer

render::Renderer holds every painter and everything they keep on the GPU. The loop hands it a render::Frame of plain values: the board as shell::fill left it, its layout, the pieces over the UI and the UI's quads (as slices), the 3D board's camera, the blur, the hole, the time, and the screen's size. render::frame then paints, always in the same order:

  1. Work that can't happen on the screen. Copy the UI's quads up, draw the 3D board's picture into its own texture if the 3D board is on, and copy up the pieces.widgets::prepare · draw3d::frame · draw::upload
  2. Open the screen's pass.gfx::begin_pass
  3. The background and the board. Flat: the photograph, the squares and the pieces. 3D: the photograph, then the 3D board's picture laid over it.draw::board · or draw::photo, draw3d::show
  4. The UI, then the pieces flying over it.widgets::frame · draw::overlay
  5. Close the pass. The next host::frame() shows it.gfx::end_pass

Pixels handed over from C

A few jobs are done in C: decoding the season's photograph, the cover a Mac window shows while you drag its edge. The C code never touches the GPU. It hands pixels over, and the renderer uploads them.

5. Who owns what

Think of it as floors in a house. Each floor may use the floors below it, never the ones above. Only the top floor touches the GPU.

touches the GPU (gfx / SDL)pure: no graphics, tested headlesshelpers anyone may use

The useful trick: the pure floors fill flat arrays (where each piece is, which squares glow, a list of UI rectangles) and the top floor just pours those arrays into the GPU. That is the whole contract between "thinking" and "painting": board::Piece, board::Marks, board::Layout, gui::Quad, view3d::Scene, and theme::Theme. That is why the tests can run a whole game with no window. model3d is the 3D board's half that needs no GPU, split from render3d so its sums are tested headless too.

The objects, as a family tree

Goose has structs, not classes. A struct holds data; functions in the same file work on it. "Owns" here means "is a field inside", so it is all one big value with no pointers between them.

// the thinking side, all in one value shell::Shell the whole app's state ├─ screen, from, since which screen, slide ├─ game::Game the game being played │ ├─ board::Board position, legal moves, │ │ │ undo, animation, draw lists │ │ └─ rules::Position a few u64 + side │ ├─ clock::Clock │ ├─ computer, level, skill │ └─ asking / reply the open question ├─ preview board::Board settings' small board ├─ next board::Board home's setup board ├─ puzzle puzzle::Play ├─ prefs settings::Settings ├─ players players::Players ├─ who who::Who badge / name sheet ├─ cam rig::Rig home's 3D board, dragged └─ out shell::Frame this frame's answer: ├─ layout board::Layout where the board is ├─ view view3d::View 3D camera this frame └─ over board::Overlay pieces over the UI
// the painting side, locals in main() rd render::Renderer ├─ d draw::Drawer flat board + photo │ └─ scene photograph, blurs, colors ├─ d3 draw3d::Drawer 3D board, kept image │ └─ render3d::… GPU side; sums in model3d ├─ w widgets::Widgets UI quads, font, badges, │ seasons' thumbnails └─ t text::Text the font's baked scale h host::Host insets, typed text dv dev::Dev the developer flags' state // in between g gui::Gui this frame's quads, input, press states thinker think::Thinker worker's id, last ask sent // how a frame uses them host::input ──▶ g ──▶ shell::frame(sh, g) │ returns ▼ sh.out (shell::Frame), g.quads │ packed into ▼ render::Frame ──▶ render::frame(rd) ──▶ GPU

6. Threads: who talks to whom

Almost everything happens on one thread, the main one. That keeps life simple: no locks, no "who changed this behind my back". There is exactly one helper thread of our own, plus a timer that SDL runs for us.

Threads: main loop, computer worker, SDL timer, and the system System / OS Android's Java side, iOS, the GPU driver. Not ours. Main thread the loop: input, screens, saving, all GPU calls Computer's worker started at the first ask, sleeps on its queue SDL timer only the wake-up alarm touch, back,pause / resume GPU shows thepicture (Vulkan/Metal) host::framewait / input shell::framescreens decide think::framepost / collect render::frameonly if dirty ai::step × 10 000 nodes, peek for newer ask host::wake_in(ms) Ask ▸ queue ◂ Thought event ends the wait loop sets the alarm
The worker and the main thread share nothing. The only things that cross are two small values: a game::Ask (position, skill, seed, an id) going in, and a think::Thought (the move, the same id) coming back. If you take a move back while the computer thinks, a newer Ask arrives, the worker notices within about 2 ms and drops the old search. An answer whose id is no longer open is ignored.
ThreadWho starts itWhat it doesHow it talks
mainSDL calls main()Everything: input, screens, layout, game logic, saving files, every GPU call.—
workerthink::frame, at the first askThe computer's move, a hint, or the lookout's traps. Owns its own search engine (6 MB table).qput / qpoll on Goose's typed queues
SDL timerSDL, on host::wake_inPushes one event at the right moment, so a sleeping loop wakes for the clock's next second or the computer's due move.an SDL event
systemAndroid / iOSTouch, lifecycle, the GPU driver's own threads. SDL turns them into events for the main thread.SDL events

7. One tap, followed all the way

You play against the computer. You tap your piece, then the square to move to. Here is the trip.

  1. The loop wakes on the touch. host::input reads it into a gui::Input, and gui::begin hands it to the UI layer.draughts.goose, the loop · host.goose
  2. shell::frame → game_screen → game::frame. The panels declare their buttons first (panel::game). Your finger is not on any of them, so the press goes to the board.shell.goose → game.goose → panel.goose
  3. board::press turns the point into a square (through the 3D camera's ray if the board is 3D), finds your piece among the legal moves and selects it. Its targets light up. The frame is dirty, so it gets painted.board.goose · view3d::pick for 3D
  4. Second tap, on a target. board::release picks the move, starts the move's animation, and plays it on the position using rules.board.goose → rules.goose
  5. The game notices the side to move changed, and that the computer plays it. It opens an "ask" with a fresh id. game::frame returns its Event (nothing to report: stay).game::frame, game::ask_for
  6. Same frame, think::frame sees a new open ask. If there is no worker yet, it starts one. It drops the Ask in the queue.think.goose
  7. The worker wakes, searches in slices of 10 000 positions, peeking between slices for a newer ask. Done: it posts a Thought.think's worker → ai::start_after, ai::step
  8. Meanwhile the main loop keeps painting your piece's slide. A frame later qpoll finds the Thought; game::answer stores it. The game does not play it at once: it waits a human-like time first, so the computer doesn't look like a machine gun.game::answer · game/pace.goose
  9. If nothing moves on screen, the loop sleeps, but first sets the alarm for when the move is due.shell::wake_in → game::due · host::wake_in
  10. The alarm fires. The board animates the computer's move. The loop paints until it stops moving, then sleeps again.board animation · shell::animating

8. House rules everyone keeps

RuleWhy
Nothing allocates in the loopMemory for a frame lives in fixed arrays sized at the start. No garbage, no hiccups.
Draw only on changeA still screen costs nothing. Battery is the main feature nobody sees.
Game state is a valueA position is a few numbers. Undo is a stack of them; saving is writing the value (about 15 KB) with a checksum.
Only render paintsmain() calls host and render, never the graphics library. The rest is tested headless, and a different renderer could replace render and its drawers without touching the rest.
Screens return, not reachA screen hands back a shell::Frame, the game a game::Event. Nobody sets a flag for someone else to clear.
No text in codeEvery word comes from strings/en.txt, et.txt, … by key.
Assets are baked inShaders, fonts, puzzles, photographs live inside the binary. No file loading on the phone except the player's own files.

9. Odd words you'll meet in the code

WordMeans
shellThe thing that holds all screens and switches between them. Not a terminal.
hostThe window, the clock, the finger, the keyboard, and the phone's own calls: everything the app asks of the platform.
FrameTwo of them. shell::Frame is what the screens hand back; render::Frame is what the loop hands the renderer.
declareA screen "declares" its buttons each frame, immediate-mode style: if the code calls button() this frame, the button exists this frame.
KindOne screen's row in the screen table: its board, its blur, where back goes.
EventWhat the game tells the shell after a frame: go somewhere, a game ended, started over.
dirtySomething changed; paint this frame.
raisedThe 3D board is on.
over / OverlayPieces drawn on top of the UI, like a piece flying into a panel when captured.
holeA cut-out in the UI where the board passes through during a slide between screens.
panelThe strips beside the board on the game screen: whose turn, clocks, buttons.
modeHow the panels sit: tall columns, short corner columns, portrait bars, or compact rows.
Out / PlayThe panels' two groups of places: the way out (back, the eye, the hint), and the play (clocks, turn, undo).
Page / FitWhere settings' parts go, and how its rows fit the width.
coverWhat a Mac window shows in the strip it gains while you drag its edge, before the app draws again.
rigThe 3D camera's swing and tilt when you drag the showcase board on home.
Ask / ThoughtA question to the computer, and its answer.
lookoutThe helper that warns a child about pieces the opponent could win.
season / themeThe background photograph and colours: winter, spring, summer, autumn, by date unless chosen.