Quick Start Guide

This guide will walk you through creating your first Amstrad CPC project using DevCPC CLI.

Create Your First Project

Let’s create a new project called “my-game”:

devcpc new my-game

What Gets Created

The devcpc new command creates a complete project structure:

my-game/
├── devcpc.conf          # Project configuration
├── README.md            # Project documentation
├── .gitignore          # Git ignore rules
│
├── ASM/                # Assembly code (Z80/8BP)
├── bas/                # BASIC files
├── raw/                # Raw binary files
├── C/                  # C source files (optional)
│
├── assets/             # Project resources
│   ├── sprites/        # PNG sprites (converted to ASM)
│   └── screen/         # Loading screens (converted to SCN)
│
├── obj/                # Generated: intermediate files
└── dist/               # Generated: final DSK/CDT/CPR

The obj/ and dist/ directories are created during the build process.

Navigate to Your Project

cd my-game

Let’s explore what was created:

ls -la

You should see:

total 24
drwxr-xr-x  8 user  staff   256 Mar  5 10:30 .
drwxr-xr-x  5 user  staff   160 Mar  5 10:30 ..
-rw-r--r--  1 user  staff   233 Mar  5 10:30 .gitignore
drwxr-xr-x  2 user  staff    64 Mar  5 10:30 ASM
drwxr-xr-x  2 user  staff    64 Mar  5 10:30 assets
drwxr-xr-x  2 user  staff    64 Mar  5 10:30 bas
-rw-r--r--  1 user  staff  4579 Mar  5 10:30 devcpc.conf
-rw-r--r--  1 user  staff  2543 Mar  5 10:30 README.md

Configure Your Project

Open the devcpc.conf file to configure your project:

devcpc.conf

# Nombre del proyecto (usado para el DSK)
PROJECT_NAME="my-game"

# Nivel de compilación (0-4)
# 0 = Todas las funcionalidades (MEMORY 23599)
# 1 = Juegos de laberintos (MEMORY 24999)
# 2 = Juegos con scroll (MEMORY 24799)
# 3 = Juegos pseudo-3D (MEMORY 23999)
# 4 = Sin scroll/layout +500 bytes (MEMORY 25299)
BUILD_LEVEL=0

# Ruta al código ensamblador 8BP
ASM_PATH="asm/make_all_mygame.asm"

# Ruta a archivos BASIC
BASIC_PATH="bas"

# Rutas opcionales (comenta las que no uses)
#RAW_PATH="raw"
#C_PATH="C"

Understanding BUILD_LEVEL

The BUILD_LEVEL determines which 8BP library features are included:

Level	Description	MEMORY	Commands	Size
0	All features	23599	\|LAYOUT, \|COLAY, \|MAP2SP, \|UMA, \|3D	19120 bytes
1	Maze games	24999	\|LAYOUT, \|COLAY	17620 bytes
2	Scrolling games	24799	\|MAP2SP, \|UMA	17820 bytes
3	Pseudo-3D games	23999	\|3D	18620 bytes
4	Basic (no scroll/layout)	25299	Basic commands	17320 bytes

Use the highest BUILD_LEVEL possible for your game to have more BASIC memory available.

Add Your Code

Now let’s add some code to your project.

Assembly Code

Copy your assembly files to the ASM/ directory:

cp /path/to/your/make_all_mygame.asm ASM/
cp /path/to/your/*.asm ASM/

BASIC Files

Create a simple loader in bas/loader.bas:

bas/loader.bas

MODE 0
MEMORY 23599
LOAD"8BP0.BIN"
CALL &6B78
REM Your game starts here

Or copy your existing BASIC files:

cp /path/to/your/*.bas bas/

Build Your Project

Now compile everything:

devcpc build

Build Output

You’ll see output similar to this:

═══════════════════════════════════════
  Compilar Proyecto: my-game
═══════════════════════════════════════

ℹ Build Level: 0 (Todas las funcionalidades)
ℹ Memoria BASIC: MEMORY 23599

✓ Compilación exitosa
✓ Límite de gráficos respetado (< 42040)
✓ DSK creado
✓ 1 archivo(s) BASIC añadidos

Contenido del DSK:
0: 8BP0    .BIN  [ st: 0 extend: 0 data pages: 128 ]
1: LOADER  .BAS  [ st: 0 extend: 0 data pages: 3 ]

✓ Proyecto compilado exitosamente

What Was Generated

After building, check the generated files:

ls -la dist/

You should see:

total 360
drwxr-xr-x  3 user  staff      96 Mar  5 10:35 .
drwxr-xr-x  9 user  staff     288 Mar  5 10:35 ..
-rw-r--r--  1 user  staff  184320 Mar  5 10:35 my-game.dsk

And intermediate files:

ls -la obj/

total 400
drwxr-xr-x  5 user  staff    160 Mar  5 10:35 .
drwxr-xr-x  9 user  staff    288 Mar  5 10:35 ..
-rw-r--r--  1 user  staff  19120 Mar  5 10:35 8BP0.bin
-rw-r--r--  1 user  staff  45678 Mar  5 10:35 8BP0.lst
-rw-r--r--  1 user  staff   2341 Mar  5 10:35 my-game.map

Run in Emulator (Optional)

If you have RetroVirtualMachine installed, you can test your project:

Configure the emulator path

Edit devcpc.conf and set your emulator path:

devcpc.conf

# macOS example:
RVM_PATH="/Applications/Retro Virtual Machine 2.app/Contents/MacOS/Retro Virtual Machine 2"

# Linux example:
#RVM_PATH="/usr/local/bin/RetroVirtualMachine"

# Windows WSL example:
#RVM_PATH="/mnt/c/Program Files/RetroVirtualMachine/RetroVirtualMachine.exe"

# CPC model (464, 664, or 6128)
CPC_MODEL=464

# File to auto-run
RUN_FILE="8BP0.BIN"

Run your project

devcpc run

This will:

Close any previous emulator sessions
Launch RetroVirtualMachine
Load your DSK image
Auto-execute the specified file

Remember: Only RetroVirtualMachine v2.0 BETA-1 R7 (10/07/2019) is supported.

Project Structure Explained

Let’s understand each directory:

Source Directories

ASM/ - Assembly Code

Contains your Z80 assembly source files for 8BP projects.Key file: make_all_mygame.asm - Main assembly file that includes all others.Example:

; make_all_mygame.asm
include "graphics.asm"
include "music.asm"
include "game_logic.asm"

bas/ - BASIC Files

Contains BASIC programs that are automatically added to the DSK.Common uses:

loader.bas - Loads and initializes your game
menu.bas - Game menu
credits.bas - Credits screen

All .bas files in this directory are automatically included in the build.

raw/ - Raw Binary Files

Contains binary files added to the DSK without AMSDOS headers.Use for:

Custom data files
Pre-compiled binaries
Resource files

C/ - C Source Code

Optional: Contains C source files compiled with SDCC.Requires:

SDCC installed
C_PATH, C_SOURCE, and C_CODE_LOC configured

Example structure:

C/
├── main.c
├── 8BP_wrapper/
│   └── 8BP.h
└── mini_BASIC/
    └── minibasic.h

assets/ - Graphics Resources

Contains PNG images for automatic conversion.sprites/ - PNG sprites converted to ASM

Mode 0: 16 colors, 2 pixels/byte
Mode 1: 4 colors, 4 pixels/byte
Mode 2: 2 colors, 8 pixels/byte

screen/ - Full-screen PNGs converted to SCN

Mode 0: 160x200 pixels
Mode 1: 320x200 pixels
Mode 2: 640x200 pixels

Generated Directories

obj/ - Intermediate Files

Created during build. Contains:

*.bin - Compiled binary files
*.lst - Assembly listings
*.map - Memory maps
*.scn - Converted screen files
*.ihx - Intel HEX files (C)

This directory is cleaned with devcpc clean.

dist/ - Distribution Files

Created during build. Contains:

*.dsk - DSK disk image
*.cdt - CDT tape image (if configured)
*.cpr - CPR cartridge (if configured)

These are your final, runnable files.

Common Commands

Here are the essential commands you’ll use:

# Compile your project
devcpc build

Build Workflow

A typical development workflow looks like this:

Create project

devcpc new my-game
cd my-game

Configure settings

Edit devcpc.conf to set:

Project name
Build level
Source paths
Emulator settings (optional)

Add your code

Copy or create your:

Assembly files in ASM/
BASIC files in bas/
Graphics in assets/

Validate project

devcpc validate

This checks:

Configuration is correct
Required files exist
Paths are valid

Build

devcpc build

This:

Converts PNG graphics
Compiles assembly
Creates DSK/CDT/CPR
Adds all files

Test

devcpc run

Or load dist/my-game.dsk in your emulator.

Iterate

Make changes, then:

devcpc build && devcpc run

Example: Complete Build

Let’s create a complete example project from scratch:

# Create project
devcpc new space-shooter
cd space-shooter

# Create a simple BASIC loader
cat > bas/loader.bas << 'EOF'
10 MODE 0
20 MEMORY 23599
30 PRINT "Loading Space Shooter..."
40 LOAD"8BP0.BIN"
50 CALL &6B78
EOF

# Configure for 8BP scrolling game (BUILD_LEVEL 2)
# Edit devcpc.conf and set:
#   BUILD_LEVEL=2
#   ASM_PATH="asm/make_all_game.asm"
#   BASIC_PATH="bas"

# Add your assembly code to ASM/
# (Copy your make_all_game.asm and other .asm files)

# Build everything
devcpc build

# Check the output
ls -la dist/

Expected output:

═══════════════════════════════════════
  Compilar Proyecto: space-shooter
═══════════════════════════════════════

ℹ Build Level: 2 (Juegos con scroll)
ℹ Memoria BASIC: MEMORY 24799

✓ Compilación exitosa
✓ DSK creado
✓ 1 archivo(s) BASIC añadidos

Contenido del DSK:
0: 8BP2    .BIN  [ st: 0 extend: 0 data pages: 118 ]
1: LOADER  .BAS  [ st: 0 extend: 0 data pages: 3 ]

✓ Proyecto compilado exitosamente

Troubleshooting

Build fails with 'ASM_PATH not found'

Make sure ASM_PATH in devcpc.conf points to an existing file:

ASM_PATH="asm/make_all_mygame.asm"  # Must exist

Check the file exists:

ls -la ASM/make_all_mygame.asm

BASIC files not appearing in DSK

Verify BASIC_PATH is configured:

BASIC_PATH="bas"

And your .bas files are in that directory:

ls -la bas/*.bas

Graphics limit exceeded

Error: _END_GRAPH exceeds 42040Your graphics are too large. Either:

Reduce sprite size/count
Use a different MODE
Optimize your graphics

Emulator won't start

Check:

RVM_PATH is correct
RetroVirtualMachine v2.0 BETA-1 R7 is installed
File has execution permissions

Test manually:

"$RVM_PATH" --help

Next Steps

Commands Reference

Learn all available DevCPC commands

Configuration

Deep dive into devcpc.conf options

Graphics Conversion

Convert PNG images to CPC formats

8BP Library

Learn about the 8BP game library

Getting Started

Core Concepts

Guides

Advanced

Tools

Quick Start

Quick Start Guide

Create Your First Project

What Gets Created

Navigate to Your Project

Configure Your Project

Understanding BUILD_LEVEL

Add Your Code

Assembly Code

BASIC Files

Build Your Project

Build Output

What Was Generated

Run in Emulator (Optional)

Project Structure Explained

Source Directories

Generated Directories

Common Commands

Build Workflow

Example: Complete Build

Troubleshooting

Next Steps

Commands Reference

Configuration

Graphics Conversion

8BP Library

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

Advanced

Tools

​Quick Start Guide

​Create Your First Project

​What Gets Created

​Navigate to Your Project

​Configure Your Project

​Understanding BUILD_LEVEL

​Add Your Code

​Assembly Code

​BASIC Files

​Build Your Project

​Build Output

​What Was Generated

​Run in Emulator (Optional)

​Project Structure Explained

​Source Directories

​Generated Directories

​Common Commands

​Build Workflow

​Example: Complete Build

​Troubleshooting

​Next Steps

Commands Reference

Configuration

Graphics Conversion

8BP Library

Build docs developers (and LLMs) love

Quick Start Guide

Create Your First Project

What Gets Created

Navigate to Your Project

Configure Your Project

Understanding BUILD_LEVEL

Add Your Code

Assembly Code

BASIC Files

Build Your Project

Build Output

What Was Generated

Run in Emulator (Optional)

Project Structure Explained

Source Directories

Generated Directories

Common Commands

Build Workflow

Example: Complete Build

Troubleshooting

Next Steps