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 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.
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.
--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.goosewhile 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.
gui::Input value and handed to the UI layer.host::input · gui::beginshell::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_screensave). 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_inrender::Frame, and render::frame paints it all (section 4). Otherwise: nothing is drawn at all.shell::fill · render::Frame · render::frameDeveloper 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.
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.
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.
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.
shell::frame returns a shell::Frame, filled anew every frame. The loop only reads it:
| Field | Means |
|---|---|
| changed | Anything on screen changed, so paint. |
| screen, shows | The screen showing, and the one whose board shows (in a slide between home and settings, home's). |
| layout, over | Where the board is, and the pieces drawn over the UI. |
| blur, hole, tall | How blurred the photograph is, and the hole cut in the UI for the board passing through in a slide. |
| raised, view, place, fade, hold | The 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, keyboard | A name is being typed: keep the keyboard up. |
| save, quit | Write the settings; home's way out was tapped. |
Before a screen declares anything, a pure function works out where everything goes. It only measures: it draws nothing and changes nothing.
panel::layout_in (or panel::corners_in for the 3D board) gives a panel::Layout with a mode: LANDSCAPE (columns as tall as the board, beside it), CORNERS (short columns in the top corners), PORTRAIT (a bar above the board, the play below it), or COMPACT (a small window, one row each). The parts that change while you play are worked out each frame from it: panel::way_out gives an Out (where back, the eye and the hint go), and one function per shape, column_play (both column modes), compact_play, or portrait_play, gives a Play (the clocks, whose turn, undo). Then panel::game declares them all in one order, whatever the mode.settings::layout returns a settings::Page: the heading, the tabs, the glass panels, the preview board, and a settings::Fit (how wide the row names are, and whether the theme's tiles are slim). The rows and tiles take the Fit as an argument.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:
host::frame() shows it.gfx::end_passA 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.
background.c fills a draughts_pixels (photo.h) that points straight into the photograph's compressed blocks baked into the app, or into the decoded JPEG. The renderer's own C, photo.c, uploads them (draughts_photo) and gives them back (draughts_photo_done). No copy is made on the way.resize.c takes pixels the renderer reads back (draw::cover_with), and only where a cover shows at all (draughts_resize_covers: the Mac).text::bake) and the badges' animals (badges::atlas) come out as one byte per pixel, built in Goose; widgets uploads both.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.
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.
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.
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.
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.| Thread | Who starts it | What it does | How it talks |
|---|---|---|---|
| main | SDL calls main() | Everything: input, screens, layout, game logic, saving files, every GPU call. | — |
| worker | think::frame, at the first ask | The 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 timer | SDL, on host::wake_in | Pushes 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 |
| system | Android / iOS | Touch, lifecycle, the GPU driver's own threads. SDL turns them into events for the main thread. | SDL events |
You play against the computer. You tap your piece, then the square to move to. Here is the trip.
host::input reads it into a gui::Input, and gui::begin hands it to the UI layer.draughts.goose, the loop · host.gooseshell::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.gooseboard::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 3Dboard::release picks the move, starts the move's animation, and plays it on the position using rules.board.goose → rules.goosegame::frame returns its Event (nothing to report: stay).game::frame, game::ask_forthink::frame sees a new open ask. If there is no worker yet, it starts one. It drops the Ask in the queue.think.gooseqpoll 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| Rule | Why |
|---|---|
| Nothing allocates in the loop | Memory for a frame lives in fixed arrays sized at the start. No garbage, no hiccups. |
| Draw only on change | A still screen costs nothing. Battery is the main feature nobody sees. |
| Game state is a value | A position is a few numbers. Undo is a stack of them; saving is writing the value (about 15 KB) with a checksum. |
| Only render paints | main() 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 reach | A screen hands back a shell::Frame, the game a game::Event. Nobody sets a flag for someone else to clear. |
| No text in code | Every word comes from strings/en.txt, et.txt, … by key. |
| Assets are baked in | Shaders, fonts, puzzles, photographs live inside the binary. No file loading on the phone except the player's own files. |
| Word | Means |
|---|---|
| shell | The thing that holds all screens and switches between them. Not a terminal. |
| host | The window, the clock, the finger, the keyboard, and the phone's own calls: everything the app asks of the platform. |
| Frame | Two of them. shell::Frame is what the screens hand back; render::Frame is what the loop hands the renderer. |
| declare | A screen "declares" its buttons each frame, immediate-mode style: if the code calls button() this frame, the button exists this frame. |
| Kind | One screen's row in the screen table: its board, its blur, where back goes. |
| Event | What the game tells the shell after a frame: go somewhere, a game ended, started over. |
| dirty | Something changed; paint this frame. |
| raised | The 3D board is on. |
| over / Overlay | Pieces drawn on top of the UI, like a piece flying into a panel when captured. |
| hole | A cut-out in the UI where the board passes through during a slide between screens. |
| panel | The strips beside the board on the game screen: whose turn, clocks, buttons. |
| mode | How the panels sit: tall columns, short corner columns, portrait bars, or compact rows. |
| Out / Play | The panels' two groups of places: the way out (back, the eye, the hint), and the play (clocks, turn, undo). |
| Page / Fit | Where settings' parts go, and how its rows fit the width. |
| cover | What a Mac window shows in the strip it gains while you drag its edge, before the app draws again. |
| rig | The 3D camera's swing and tilt when you drag the showcase board on home. |
| Ask / Thought | A question to the computer, and its answer. |
| lookout | The helper that warns a child about pieces the opponent could win. |
| season / theme | The background photograph and colours: winter, spring, summer, autumn, by date unless chosen. |