Bataille Navale — the pen-and-paper classic, in C11 and GTK 3
A complete game, played by the program against itself. This animation is produced by the end-to-end test, not recorded by hand.
You command the Sup Galilée navy against a fleet of pirates on a 10 × 10 grid. Ten ships each, none of them touching another, and the first fleet sunk loses.
The project began in 2023 as a university assignment — a single 2 666-line C file. Version 2 is a ground-up rewrite that keeps the game and replaces everything underneath: a model / view / controller architecture, a game engine with no dependency, three measurable computer opponents, a test-suite, and a build and release pipeline.
- A real engine. The rules live in a dependency-free C11 library: no GTK, no
malloc, no global state. A whole match is one 800-byte structure. - Two interfaces, one model. A GTK 3 application and a terminal game drive the same engine — the proof that the model is really independent of its view.
- An opponent you can measure. Three levels whose strength is benchmarked over thousands of seeded games, and an AI that cannot cheat: it never receives the ship positions.
- Reproducible. Every game comes from a seed.
--seed 7replays the same match on Linux and macOS, bit for bit. - Tested where it matters. 54 unit cases, property tests over 2 250 full matches, sanitizers, static analysis, and a GUI test that plays a whole game through real widget clicks.
- One file to ship. Images, sounds and style sheet are compiled into the executable — and all of them are original, generated by a script in the repository.
| Choose a level | Fleets at the ready |
|---|---|
![]() |
![]() |
| In the thick of it | Victory |
![]() |
![]() |
| System | Command |
|---|---|
| Debian / Ubuntu | sudo apt install build-essential cmake pkg-config libgtk-3-dev libgstreamer1.0-dev |
| Fedora | sudo dnf install gcc cmake pkgconf-pkg-config gtk3-devel gstreamer1-devel |
| macOS | brew install cmake pkg-config gtk+3 gstreamer |
GStreamer is optional: without it the game builds without sound. GTK itself is only needed for the graphical interface (see Headless build).
git clone https://github.com/DmytroPalahin/battleship.git
cd battleship
make test # configure, compile and run the test-suite
make run # start the gamemake is only a shortcut for the CMake presets. The explicit form is:
cmake --preset release
cmake --build --preset release
ctest --preset release
./build/release/src/ui/battleshipRun make help for the other everyday commands (format, lint, asan, coverage,
report, package…).
The engine, the terminal game and the tests need nothing but a C11 compiler and CMake:
cmake --preset headless && cmake --build --preset headless && ctest --preset headless
./build/headless/src/cli/battleship-cli play| Rule | |
|---|---|
| Fleet | 1 × four cells, 2 × three cells, 3 × two cells, 4 × one cell |
| Placement | Ships never touch, not even by a corner. Fleets are drawn at random; redraw yours as often as you like before the first shot |
| Turn | Fire at an enemy cell. A hit earns another shot; a miss passes the turn |
| Flags | 🚩 marks a cell where no ship can be — worked out for you from the no-touch rule |
| End | The first fleet entirely sunk loses |
Controls. Click an enemy cell, or move with the arrow keys and press Space. F11 toggles full screen.
In a terminal. battleship-cli play offers the same game with typed coordinates (B7),
plus hint, shuffle and quit.
Each level adds one skill to the one below it.
| Level | What it knows how to do | Shots to sink a fleet |
|---|---|---|
| 😜 Facile (easy) | Fires at random, never twice at the same cell | 96.2 ± 4.1 |
| 😐 Moyen (medium) | Also skips every cell the rules prove to be empty | 65.8 ± 6.1 |
| 🤔 Difficile (hard) | Also finishes off wounded ships and hunts where a ship is most likely | 55.3 ± 6.8 |
Head-to-head, with the real "hit and shoot again" rule, hard beats medium in 87.5 % of matches, and medium beats easy in 9 999 matches out of 10 000.
These figures are not estimates. They come from the simulator shipped with the game, and you can reproduce them exactly:
$ battleship-cli simulate --games 10000 --seed 1
Shots needed to sink a random fleet (20 decks on 100 cells; lower is better)
level mean stddev min p50 p90 max
easy 96.19 4.10 69 97 100 100
medium 65.83 6.07 44 66 74 85
hard 55.27 6.80 28 56 64 79
Head-to-head: matches won by the row level against the column level (%)
easy medium hard
easy 49.6 0.0 0.0
medium 100.0 49.7 12.0
hard 100.0 87.5 50.0The hard level builds a probability map: for every ship still afloat it counts every position consistent with what the shots have revealed, and fires where the most positions overlap. The levels themselves were chosen from measurements of several candidate strategies — see ADR 0003.
flowchart TB
subgraph frontends["Interfaces"]
gui["<b>battleship</b><br/>GTK 3 · view + controller"]
cli["<b>battleship-cli</b><br/>terminal game · simulator"]
tests["<b>tests</b><br/>unit · property · end-to-end"]
end
core["<b>battleship_core</b><br/>game engine — C11, no dependency<br/>types → rng → board → ai → game"]
gui --> core
cli --> core
tests --> core
Dependencies point inwards: the engine knows nothing about how it is displayed. CI builds and tests it on a machine without GTK, so the rule cannot be broken by accident.
- Model —
include/battleship/,src/core/. Placement, shots, deductions, turn order, AI. Pure functions on plain structures. - View —
src/ui/view.c. Every widget, and no rule. It is driven in game vocabulary (bs_view_set_cell(…, BS_LOOK_HIT, …)) and reports gestures as intentions (cell_activated). NoGtkWidgetcrosses its interface; all styling is inassets/style.css. - Controller —
src/ui/controller.c. Asks the model to play, then re-synchronises the whole view from it. The view holds no game state, so it cannot go stale.
The full tour, with the state machine and a sequence diagram of a shot, is in docs/architecture.md; the reasoning behind each choice is in the decision records.
Project layout
.
├── include/battleship/ public API of the engine
├── src/
│ ├── core/ game engine (the model)
│ ├── cli/ terminal game and AI simulator
│ └── ui/ GTK application (view, controller, shell)
├── assets/ images, sounds, style sheet → compiled into the executable
├── tests/ unit, property and CLI tests
├── docs/
│ ├── architecture.md how it fits together
│ ├── adr/ architecture decision records
│ ├── report/ the project report (LaTeX, in French and in English)
│ └── screenshots/
├── tools/ asset generator
├── cmake/ build modules
├── packaging/ desktop entry, AppStream metadata, icon
└── .github/ CI/CD workflows, issue and PR templates
| Check | What it does | Where |
|---|---|---|
| Build matrix | GCC and Clang on Ubuntu, Apple Clang on macOS; Debug and Release | ci.yml → build |
| Warnings as errors | -Wall -Wextra -Wpedantic -Wconversion -Wshadow and friends |
every build |
| Unit and property tests | 54 cases; 2 250 matches with every invariant re-checked after each shot | ctest |
| Sanitizers | The whole suite under AddressSanitizer and UndefinedBehaviorSanitizer | ci.yml → sanitizers |
| Coverage | 98 % of the engine's lines; the job fails below 95 % | ci.yml → coverage |
| Static analysis | clang-tidy, cppcheck, CodeQL | ci.yml, codeql.yml |
| Documentation | The report (LaTeX) and the API reference (Doxygen) are rebuilt on change | docs.yml |
| Formatting | clang-format, checked on every push | ci.yml → format |
| Independence | Engine and CLI built and tested without GTK installed | ci.yml → headless |
| End-to-end | A full game played through the real widgets under Xvfb; any GTK warning is fatal; a screenshot is kept | ci.yml → build |
| Release | On a v* tag: packages, checksums, build provenance, report PDF |
release.yml |
Everything CI runs can be run locally with the same preset names: make test, make asan,
make coverage, make lint.
$ battleship --help
-l, --level=LEVEL Start at a level without showing the menu: easy, medium or hard
-s, --seed=N Seed of the first game, to replay it
-m, --mute Disable the sound effects
-V, --version Show the version and exit
$ battleship-cli --help
play play against the computer in the terminal
simulate benchmark the three AI levels against random fleetsSound goes to the system's default output. Set BATTLESHIP_AUDIO_SINK to the name of a
GStreamer sink (pulsesink, alsasink…) to send it elsewhere.
- 📐 Architecture — modules, state machine, sequence of a shot
- 🧭 Decision records — why it is built this way
- 📚 API reference —
make docsgenerates it from the public headers with Doxygen - 📄 Project report — the full write-up, in two editions built from the same LaTeX sources. Read the PDF in English or in French, the original.
- 📝 Changelog
| Version | Date | What it was |
|---|---|---|
| v1.0.0 | 2023 | The original assignment: one C file, GTK 3, three levels. By Dmytro Palahin and Ivanna Makam |
| v2.0.0 | 2026 | The rewrite described on this page |
| v2.1.0 | 2026 | Every image and sound redrawn: the whole repository is under one licence |
| v2.2.0 | 2026 | The project report in two editions, French and English |
The original code is preserved under the v1.0.0 tag. What changed, and which defects of the
first version the rewrite removed, is listed in the changelog.
- Two-player games over the network (the model is already interface-agnostic)
- Manual fleet placement by drag and drop
- Translations with gettext (every string already lives in one file)
- GTK 4 port
- Flatpak package
Issues and pull requests are welcome. CONTRIBUTING.md explains how to set up, what CI expects and how commits are written. Please also read the code of conduct.
![]() Dmytro Palahin Original game · v2 architecture and rewrite · maintainer |
Ivanna Makam Original game (2023): design, interface, report |
Written for the course Initiation aux interfaces graphiques taught by Sophie Toulouse at Sup Galilée (Université Sorbonne Paris Nord), whose model / view / controller method is the backbone of the architecture. See AUTHORS.md.
Code, artwork and sounds are released under the MIT License.
The images and sound effects are original: they are drawn and synthesised by
tools/generate-assets.sh (see assets/README.md).
The screenshots of the 2023 version show the third-party artwork that version used.






