CPCtelera Reference Manual

If you want to create games for Amstrad CPC, you are at the right place.  Welcome to CPCtelera!

CPCtelera is a game development framework including a low-level game library for C and assembler programmers wanting to create games on Amstrad CPC.  You have an easy-to-use, optimized library with a lot of ready-to-use basic functionalities

• Draw different types of sprites, with and without transparency effects
• Draw solid colour boxes and speed up sprite trail erasing!
• Flip and blend sprites and apply different effects to them
• Reproduce audio and sound effects
• Create fade-in / fade-out effects with your sound FX and music!
• Mix-up sound effects with music, using the 3 audio channels for both at the same time!
• Draw strings and characters using ROM characters without using firmware.
• Change the complete hardware palette and individual palette colours
• Draw very fast tiles aligned with character lines in the screen.
• Change default screen video memory location
• Do hardware double buffering and scrolling effects.
• Synchronize with VSYNC
• Change Video Modes (0, 1, 2 and undocumented mode 3!)
• Measure performance of your game loop (and know how many free CPU cycles you still have for doing more things in your routines!)
• Scan the keyboard for pressed keys with the fastest keyboard scanning routine available!
• Disable and re-enable firmware operation at will
• Enable and disable lower and higher ROM access
• Easily manage and draw tilemaps in the screen
• Optimize array storage using bitarrays (arrays of 1-bit, 2-bit and 4-bit elements available!)
• Easily hook a user function to system interrupts to generate timers and events and automatically do frequency related tasks
• Locate parts of your code and data in specify memory places
• Generate custom-quality random number sequences

However, CPCtelera is much more than a low-level library.  CPCtelera comes with a complete build system for easing your project creation and management.  CPCtelera offers you

• Integrated set of compiling and generation tools (SDCC 3.5.5, iDSK 0.13, Hex2Bin 2.0, 2cdt)
• Easy and automated project creation and management
• Automatic generation of CDT and DSK files
• Program completely in C, completely in Assembler or mix both languages at will.  You won’t even have to touch a line of the build system!
• Automatic generation of obj/ folder with all the intermediate object files (Never mess up your src/ directory!)
• Automatic generation of binaries, assembler output, symbol files and everything you need for debugging your program.
• Automatic identification of your project source files in C and ASM (.c and .s).  Add new source files to your src/ directory and they will be automatically recognized an compiled!
• Automatic detection of src/ directory structure up to 1 level of subfolders without any modification!
• Automatically launch and run your programs into an emulator with a single command.
• Automatically load symbol files for debugging on launching your programs.
• Automatically convert binary files into source code arrays and link them into your project
• Automatically convert and use PNG, JPG, GIF images into sprites and tiles
• Automatically convert TMX tilemaps into C-arrays and use them in your games

Moreover, CPCtelera also comes with some authoring tools (in the folder cpctelera/tools/) for your game content as well as some command line tools for format conversions

• Create your musics with Arkos Tracker
• Create your sprites, tiles and maps with Retro Game Asset Studio!  (And export them directly to CPCtelera C Array!)
• Convert any binary file to C Array and include it in your project with cpct_bin2c
• Convert a big sprite in a C Array into tiles of your desired size with cpct_sp2tiles!
• Convert old sprites in assembler CPCRSLib format into C Arrays with cpct_rgas2c!
• Convert any kind of PC image or sprite sheet into C or assembler code and add it to your project with cpct_img2tileset and Img2CPC
• Generate and manage special kinds of DSK using DSKGen.

And, of course, CPCtelera comes with a complete API documentation and lots of well documented examples for you to quickly and easily learn it!

All these features included in a single bundle for you to download and use, free and under LGPL v3.0.  License.  You have all source code available for you to analyse, explore, improve and distribute!

We are incredibly grateful to these people, who sent us some economic support to continue with CPCtelera and other CPC-related projects.  Big most sincere thanks and respects to all of you,

We, as authors of CPCtelera, have started this journey to create a usable, free, convenient and up-to-date game engine.  There are lots of things to do and improve in order to achieve our goals.  If you want to help us, we are more than happy.  Any kind of help is always welcome, but we prefer any of these ways,

• Economic support: make a donation using Bitcoin or Paypal (Links are at the top of this file).  Big thanks for your support!
• Documentation: create videos, images, tutorials, better explanations...  And send us an email to cpct.nosp@m.elera@cheese.nosp@m.tea.com.  We will be happy to receive your links!  :)
• New library features: develop new functions and features and give us a Github pull request.  Please, do read pieces of CPCtelera code previously and try to meet our quality standards.
• Beta Testing and reporting: report your findings testing CPCtelera at any new platform or in new ways.  You may leave us a Github issue.
• New tools: creating new tools or adapting your tools to be included with CPCtelera is an awesome idea!

Any donation to our team will be used either in hardware / software to support this project, or as an aid for other Amstrad CPC related projects we manage (such us, for instance, #CPCRetroDev anual contest!)

CPCtelera works under Windows, Linux and OSX.  It has been tested in Windows XP, 7, 8 and 10, and in Ubuntu / Debian, Arch, Manjaro, Elementary OS and Raspbian Linux distributions.  It works either on Intel architectures or on ARM’s.

Once setup.sh completes without errors, CPCtelera will be ready to use.  To have a quick glance about what CPCtelera offers, you may enter examples/ folder and check all the examples included.  You can build any one of them just by typing make inside the example folder, then CDT and DSK files will be automatically generated.

For creating your own projects, CPCtelera includes the cpct_mkproject command line tool.  setup.sh configures your system’s $PATH variable so that you have direct access to cpct_mkproject anywhere on your system (you should close and open your terminal again after setup.sh finishes).  Creating a new project is as easy as typing this

cpct_mkproject [project_folder]

Once you have your own new project, you can enter its folder and you will have a Makefile and 2 important subfolders

• src/ is the folder containing source files.  At the start it only contains a main.c file, but you can create new files and folders (1 level of sub-folders) in it.  All .c and .s files below src/ will be automatically detected and compiled when you type in “make” at your project folder.
• cfg/ contains the building configuration of your project.  In the file build_config.mk you will be able to make changes to the way the project is built.  The 2 typical are changing the project name and its binary load address.  Open the file and you will see 2 variables for this purpose.  You can change them whenever you wanted.

The rest is up to you.  Navigate this reference manual, grasp code from examples and start your own projects.  All of us are waiting to see your new games!  :D

Just a few comments for those wanting to program in Assembly with CPCtelera.  Most of the assemblers available out there use MAXAM assembly syntax, and most assembly code out there is coded this way.  CPCtelera uses SDCC, which comes with ASZ80 integrated as assembler.  ASZ80 has its own syntax and directives which are different to MAXAM’s.  Take this into account when porting code to CPCtelera or when analyzing CPCtelera’s own code.

ASZ80 is developed by Alan R.  Baldwin, and hast a good and detailed documentation for ASZ80 assembly syntax online.  Check it to port your programs from MAXAM’s to CPCtelera.

CPCtelera lets you add assembly files to your projects by using the extension .s.  Any .s file that you include in the src/ folder of your project (or any first-level subfolder) will be automatically detected and compiled by the default Makefile.

Let’s have a quick look at some things that CPCtelera can do.

This is the setup.sh script in action

The ROM “characters” example running

Two screenshots of the “fade” example running

The sprites example, showing CPCtelera’s Logo on CPC Mode 1

Masked sprites example, with a character moving over a background

An example on measuring performance, drawing and moving a sprite in Mode 1

Example showing animations in mode 0