# CPC Color Flood making-of

## How the game was created

I have another project mathematically and performance-wise difficult.

I wanted to create something simpler to exercise writing in C for the CPC.

I had already wrote such a game on a desktop application, so I wrote this for the CPC.

## Technology used

* A laptop running Ubuntu Linux and cpc-dev-tool-chain with SDCC.
* C, C and more C.  Also one assembly routine to count the number of bits set in a given byte.
* According to sloccount: 919 lines of ANSI C, 22 lines of assembly.
* Portable C, clean code (more below).

## Problems and solutions found.

Problem: how to debug on my laptop ? Solution: Have the same source code compile to the CPC and to a Linux-based PC.

Problem: sometimes when source code is incorrect, SDCC is sometimes confused about where the error actually is (beyond what is normal confusion due to C rules).

## Learned lessions

* SDCC is solid enough to code in C.  It understand C syntax and rules, produces good code (often excellent).

* Exercising decision-making: data structure, etc.

* Complete the firmware section the cpc-dev-tool-chain.

* Art and design is a work in itself.

* Assert is powerful.

## More ?

### Educational: open-source

Code is meant to be released as open-source on github, most certainly with MIT license.

### Educational: uses one of the recommended C toolchains

Game is built upon cpc-dev-tool-chain and should build easily on your PC, produce CDT, DSK etc without manual step.  Just type code, compile and run.

Disclosure: I wrote cpc-dev-tool-chain and am grateful to Francisco Gallego (lronaldo) for taking is as a starting point to develop CPCTelera.

### Educational: fully written in portable C code, project structure segregates platform-specific areas

Game is fully written in portable C.  The project can be equally compiled for the CPC or a modern platform.

No platform mix mess! There's not even a platform-related #ifdef. (Actually, there used to be one that I ditched today with a simple refactoring as it was not necessary.)

This works by writing only portable code in main project, then segregating a few ad-hoc platform-specific functions into platform-specific subdirectories.  Some low-level, some high-level, as needed by the simple project.  The result is clean, lean, fast, and educational.

The original motivation is clean code and ease of debug.  I actually ran it and debugged it on my local 64-bit OS with modern tools.  Note that current modern-platform runtime is not intended to be pretty-looking, only to work enough to be used for a debug session, and for that printf and scanf are the base.  One could port it to SDL or whatever.  When compiled on CPC, printf and the like are not called, firmware and write to screen memory instead. Again, educational value.

Makefile and project structure is very simple and pragmatic.  Only there are still one or two hacks.  I'm considering improving the build system by introducing clean out-of-source build (for example https://stackoverflow.com/questions/39015453/building-c-program-out-of-source-tree-with-gnu-make ).

Also, by default make builds on both platforms, so any time you mix non-portable code in portable area, you get an immediate compilation failure and fix your code to keep the pattern. (This happened to me when preparing the screenshots  :laugh: ) Again, educational value.

### Educational: clean, minimal, readable C source code.

The C source code is very educational.

* It is written very cleanly yet with parsimony as suited for a retro platform.
* Code uses relevant data structures and types (C struct, signed/unsigned).
* Code uses relevant C patterns, structured programming, function parameters, etc.
* Respect the DRY principle (don't repeat yourself): nearly no magic variables or implicit relationships.  Values that depend on other values are nearly always resolved at compile time, allowing static arrays that just fit and won't overflow.
* Relevant variable usage: local scope, static, const, a few global variables when that makes sense.
* Relevant usage of assert() to spot bugs early and save debugging time (and it did!).
* C preprocessor macros (#define mymacro(args) code...) are used when it makes sense due to C limitations with respect to compile-time computation, or to have high-performance generated ASM yet keeping a hihly readable C source code.
* Anyone can study generated ASM to see that clean C code can produce excellent ASM code (short and to-the-point, high-performance).


Additionally, graphics handling is very simple and conforms to above patterns.

Assert power! When the runtime finds bugs for you.


### Educational: not totally trivial game mechanics

At each move, the program performs some kind of area fill, like CPC BASIC 1.1 fill command.

This needs either recursivity or dedicated data structure.  Recursivity yields simplest source code and works flawlessly.

Again, source code reability is favored, and yet runtime performance is excellent.

Future steps

* One-player mode against AI? Would make the game more fun, not change educational value a lot.
* Fancy graphics? Would not enhance educational value.
* Music? Would an 8-bit port of "Sail by Awolnation" on a calm board game enhance educational value? ;-)
* A totally different project with 3D landscape graphics (would not enhance educational value of this project).
