CPCtelera Reference Manual

Astonishingly fast Amstrad CPC game engine for C and Assembler developers.

CPCtelera has been created by these Authors, and is distributed under LGPL v3 License (low-level library, examples, building system and scripts).

We give big thanks to all users, contributors and supporters, and all respects to our incredible Donors.


Summary
CPCtelera Reference Manual
Welcome to CPCtelera!If you want to create games for Amstrad CPC, you are at the right place.
DonorsWe are incredibly grateful to these people, who sent us some economic support to continue with CPCtelera and other CPC-related projects.
Supporting CPCteleraWe, as authors of CPCtelera, have started this journey to create a usable, free, convenient and up-to-date game engine.
Installing CPCteleraCPCtelera works under Windows, Linux and OSX.
Downloading CPCteleraYou can download CPCtelera from these sources
Software RequirementsIn order to install CPCtelera, your system will require previous software.
Installing CPCtelera in your systemThese are the steps to install CPCtelera in your system
TroubleshootingUsers have reported some occasional issues installing CPCtelera.
Starting with CPCteleraOnce setup.sh completes without errors, CPCtelera will be ready to use.
Advice for Assembly codersJust a few comments for those wanting to program in Assembly with CPCtelera.
ScreenshotsLet’s have a quick look at some things that CPCtelera can do.

Welcome to CPCtelera!

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!

Donors

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,

21/05/2015Lachlan Keown
10/06/2015Tim Riemann / Octoate
25/06/2015Ervin Pajor
13/07/2015Roald Strauss
23/09/2015Arnaud Bouche
24/11/2015Toni Ramirez
21/04/2016Oscar Martínez Gómez
26/05/2016Oliver Lenz

Supporting CPCtelera

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!)

Installing CPCtelera

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.

Summary
Downloading CPCteleraYou can download CPCtelera from these sources
Software RequirementsIn order to install CPCtelera, your system will require previous software.
Installing CPCtelera in your systemThese are the steps to install CPCtelera in your system
TroubleshootingUsers have reported some occasional issues installing CPCtelera.

Downloading CPCtelera

You can download CPCtelera from these sources

git clone https://github.com/lronaldo/cpctelera

Software Requirements

In order to install CPCtelera, your system will require previous software.  Check your system and install it before launching setup.sh.

Under Linux

Install these packages on your Linux distribution.  Although they are pretty standard, names may slightly vary on some distributions.

  • Commands: gcc, g++, make, bison, flex, mono (mono-complete)
  • Libraries: libboost-dev, libfreeimage-dev

Next are recommented packages.  They are not required for CPCtelera to work, but some included tool may require them (like cpct_winape script)

  • Commands: wget, unzip, wine

NOTE for ARM and Raspberry Pi users

On Raspbian and other ARM Linux OSes, the package texinfo is often required.  We recommend you to install it beforehand.  If your compilation fails, it may be due this package lacking in your system.

Under Windows

Under Windows Cygwin is required for CPCtelera to work.  You may download Cygwin 32 / 64 and install it along with these packages (you may launch cygwin’s setup.exe at any time to install them),

  • Commands: gcc-core, gcc-g++, make, bison, flex, wget, unzip, bc
  • Libraries: libboost-devel, libintl-devel

Additionally, Windows 8/10 may ask you to install .NET framework during examples building.  This is required to run Arkos Tracker and its command line tools.  Proceed to install it when prompted.

Under OSX

Under OSX XCode and Homebrew are required for installing CPCtelera.  Follow these steps,

1.Install XCode if you didn’t have it.
2.Install Homebrew if you didn’t have it.
3.Open a terminal and install XCode Command Line tools with this command,
xcode-select --install
4.Install required packages from homebrew with these commands,
brew install boost freeimage mono wine wget

Some things to take into account on OSX,

Installing CPCtelera in your system

These are the steps to install CPCtelera in your system

1.Install required Software Requirements
2.Download and unzip current stable version 1.4.2. of CPCtelera (read “some considerations” below)
3.Open a terminal an enter cpctelera/ folder.
cd cpctelera/
4.Launch setup.sh
./setup.sh
5.Once setup.sh finishes, close your terminal and open a new one for changes to be set.

CPCtelera is ready to be used in your system.

Some considerations

  • It is recommended to unzip CPCtelera to a folder inside your user’s $HOME path (typically /home/username/ or C:\cygwin\home\username\).
  • Once you run setup.sh, CPCtelera will be installed in the path you have previously unzipped it.  If you move the folder to a new location, you should run setup.sh again.
  • However, CPCTelera can be installed anywhere in your system, provided the path does not contain any spaces.
  • setup.sh checks software dependencies.  If some dependency is not met, you will receive an error message requesting you to install it and then launch setup.sh again.

Troubleshooting

Users have reported some occasional issues installing CPCtelera.  Please, have a look at this list if you have any problem,

  • Antivirus and scanning software.  This kind of software is causing random issues that cause Cygwin and CPCtelera not to operate properly.  Common problems include failing to compile and/or execute programs, privilege problems on executing programs and random crashes of Cygwin.  If you experience this problems, try disabling your antivirus or scanning software.  Once being sure that this is the reason for your problems, you may want to configure your software not to interfere with Cygwin.
  • Windows 8/10 privilege problems.  Under some unclarified circumstances, some users have privilege problems executing Cygwin sofware, and that affects CPCtelera.  In this cases, the most common workaround is launching Cygwin terminal with administrator privileges.
  • Windows 8/10 executable conflicts.  Some users experience compilation or execution problems due to other Windows being using other software installed outside cygwin.  This usually happens with MinWG (gcc, g++), SDCC and git, but may happen with other software aswell.  On some installations, Windows PATH variable gives priority to previously installed software.  So, when compiling with gcc, sdcc or using git, problems happen due to Windows version of the software being executed.  In this cases, please check Windows PATH variable and adjust it accordingly.
  • ’yywrap’ symbol not being defined.  Previous versions of CPCtelera may fail to build and have this issue reported in the tool_building.log.  This is due to changes outside of our control.  However, there is a simple fix for this problem.  Please, follow this steps:
1.Launch ./setup.sh (If launched previously, ask for clean reinstall ./setup.sh -cri)
2.Wait until it fails at ~47% and then edit this file: cpctelera-1.4/cpctelera/tools/sdcc-3.5.5/obj/support/sdbinutils/binutils/syslex.c
3.Comment out line 74 of syslex.c adding // at its start.  It should look like this: // #define yywrap yywrap
4.Launch ./setup.sh again

If you experience any diffenrent problem with Windows/Cygwin, please report to us so that we can include it in this list.

Starting with CPCtelera

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

Advice for Assembly coders

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.

Screenshots

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

We are incredibly grateful to these people, who sent us some economic support to continue with CPCtelera and other CPC-related projects.
Script for converting binary files to C arrays
Cuts up a big sprite into smaller tiles
This converts RGAS sprite definitions in CPCRSLib asm output format to CPCtelera’s C arrays.
Converts an image file with a set of tile or sprite images into a CPCtelera C-array tileset along with arrays for all tiles/sprites.
In order to install CPCtelera, your system will require previous software.
This script helps in the creation of new projects that use CPCtelera engine.
Close