The devcpc.conf file is the central configuration file for your DevCPC project. It controls compilation behavior, output formats, paths, and emulator settings.
Configuration File Location The configuration file must be located in your project root:
my-project/ ├── devcpc.conf ← Configuration file ├── ASM/ ├── bas/ └── ...
devcpc.conf is automatically created when you run devcpc new <project-name>.
Configuration Sections The configuration file is organized into logical sections:
1. Basic Configuration PROJECT_NAME (Required) The name of your project, used for generated DSK, CDT, and CPR files.
Usage:
DSK filename: ${PROJECT_NAME}.dsk
CDT filename: ${PROJECT_NAME}.cdt
CPR filename: ${PROJECT_NAME}.cpr
Map filename: ${PROJECT_NAME}.map
Use uppercase and avoid spaces. Use underscores instead: MY_GAME not my game.
BUILD_LEVEL (Required for 8BP Projects) Determines which 8BP features are included (0-4). See Build Levels for details.
Value Description MEMORY Value 0All functionalities 23599 1Maze games 24999 2Scrolling games 24799 3Pseudo-3D games 23999 4Basic features 25299
2. Source Code Paths
ASM_PATH - Assembly Source
Path to your main assembly file (not a directory). # For 8BP projects - points to main assembly file ASM_PATH = "asm/make_all_mygame.asm"
For non-8BP ASM projects , use these additional variables:ASM_PATH = "ASM" # Directory path SOURCE = "main" # Source filename (without .asm) TARGET = "program" # Output binary name LOADADDR = 0x1200 # Load address
Optional : Comment out if not using assembly code.
BASIC_PATH - BASIC Programs
Path to directory containing BASIC files. All .bas files are automatically added to the DSK. What it does:
Scans directory for *.bas files
Adds each file to DSK with its original name
Files appear in DSK catalog as LOADER.BAS, MENU.BAS, etc.
Optional : Comment out if not using BASIC.
RAW_PATH - Raw Binary Files
Path to directory containing raw binary files (no AMSDOS header). Use cases:
Custom data files
Pre-compiled binaries from other tools
Graphics or sound data
Optional : Comment out if not using raw files.
Configuration for C code compilation with SDCC. C_PATH = "C" C_SOURCE = "main.c" C_CODE_LOC = 20000
Variables:
C_PATH: Directory containing C sourceC_SOURCE: Main C file to compileC_CODE_LOC: Memory address where C code loads Memory constraint: C_CODE_LOC + compiled_size < 23999
Requires SDCC compiler installed. C code must not exceed address 23999 to avoid overwriting 8BP library.
3. Output Directories Control where build artifacts are stored.
# Intermediate build files (.bin, .lst, .map, .ihx) OBJ_DIR = "obj" # Final distributable files (.dsk, .cdt, .cpr) DIST_DIR = "dist" # Disk image filename DSK = "${ PROJECT_NAME }.dsk"
These directories are automatically created during build and removed with devcpc clean.
4. Tape Image (CDT) Configuration Generate cassette tape images alongside your DSK.
# Enable CDT generation CDT = "${ PROJECT_NAME }.cdt" # Files to include in tape (order matters!) CDT_FILES = "loader.bas 8BP0.bin main.bin"
Configuration
File Order
Supported Types
CDT - Filename for the tape imageCDT = "${ PROJECT_NAME }.cdt" # Uses project name # or CDT = "my_tape.cdt" # Custom name
CDT_FILES - Space-separated list of files to includeCDT_FILES = "loader.bas 8BP0.bin game.bin screen.scn"
The order in CDT_FILES is critical - files are loaded sequentially: # ✅ Correct: loader first, then data CDT_FILES = "loader.bas 8BP0.bin game.bin" # ❌ Wrong: will try to load binaries before loader CDT_FILES = "game.bin loader.bas 8BP0.bin"
Typical order:
BASIC loader (.bas)
8BP library (.bin)
Game code (.bin)
Additional data files
Extension Type Description CPC Load Command .basBASIC Tokenized BASIC RUN".binBinary Machine code with header LOAD"FILE.BIN".scnScreen 16KB screen at &C000 LOAD"FILE.SCN",&C000.txtRaw Data without header Direct read
Comment out CDT and CDT_FILES to disable tape generation.
5. Cartridge (CPR) Configuration Generate cartridge files for GX-4000 and CPC Plus.
# Enable CPR generation CPR = "${ PROJECT_NAME }.cpr" # File to auto-execute on boot (no 'run' command needed) CPR_EXECUTE = "loader.bas"
CPR = "${ PROJECT_NAME }.cpr" # Uses project name # or CPR = "my_cartridge.cpr" # Custom name
The cartridge is generated from your DSK image.
CPR_EXECUTE - Auto-Execute File
Specifies which file runs when the cartridge is inserted. # Just the filename - DevCPC adds run" automatically CPR_EXECUTE = "disc" # Default DSK program CPR_EXECUTE = "8BP0.BIN" # Direct binary CPR_EXECUTE = "loader.bas" # BASIC loader
Do not include run" in the value - DevCPC handles this automatically.# ✅ Correct CPR_EXECUTE = "loader.bas" # ❌ Wrong CPR_EXECUTE = 'run"loader.bas"'
Compatibility:
✅ GX-4000 (console)
✅ CPC 464+
✅ CPC 6128+
❌ CPC 464/664/6128 (no cartridge port)
Comment out CPR to disable cartridge generation.
6. Emulator Settings Configure RetroVirtualMachine for testing with devcpc run.
# Path to RetroVirtualMachine executable RVM_PATH = "/Applications/Retro Virtual Machine 2.app/Contents/MacOS/Retro Virtual Machine 2" # CPC model to emulate (464, 664, 6128) CPC_MODEL = 464 # File to auto-execute (DSK only) RUN_FILE = "8BP0.BIN" # Execution mode: "auto", "dsk", or "cdt" RUN_MODE = "auto"
RVM_PATH Examples
CPC_MODEL
RUN_MODE
RUN_FILE
Platform-specific paths: macOS: RVM_PATH = "/Applications/Retro Virtual Machine 2.app/Contents/MacOS/Retro Virtual Machine 2"
Linux: RVM_PATH = "/usr/local/bin/RetroVirtualMachine"
Windows (WSL): RVM_PATH = "/mnt/c/Program Files/RetroVirtualMachine/RetroVirtualMachine.exe"
Only v2.0 BETA-1 R7 (10/07/2019) supports the development features required by DevCPC.
Choose which Amstrad CPC to emulate: CPC_MODEL = 464 # CPC 464 (tape-based) CPC_MODEL = 664 # CPC 664 (disk-based) CPC_MODEL = 6128 # CPC 6128 (disk, more RAM)
Auto-detection for tape:
Models 664/6128 automatically use |TAPE command when loading CDT
Controls how the emulator loads your game: Mode Behavior Override autoUse CDT if configured, else DSK Default dskAlways mount DSK (disk) devcpc run --dskcdtAlways mount CDT (tape) devcpc run --cdt
# Automatically choose DSK or CDT RUN_MODE = "auto" # Always use disk RUN_MODE = "dsk" # Always use tape RUN_MODE = "cdt"
Command-line overrides: devcpc run --dsk # Force DSK regardless of RUN_MODE devcpc run --cdt # Force CDT regardless of RUN_MODE
DSK only: File to auto-execute after mounting disk.RUN_FILE = "8BP0.BIN" # Execute 8BP level 0 RUN_FILE = "loader.bas" # Execute BASIC loader RUN_FILE = "game.bin" # Execute game binary
Not used for CDT mode. Tape auto-executes the first file with RUN".
All emulator settings are optional . Comment them out if not using devcpc run.
7. Graphics Conversion Settings Automatically convert PNG images to CPC formats during build.
# CPC screen mode for conversions (0, 1, or 2) MODE = 0 # --- Sprites (PNG → ASM) --- SPRITES_PATH = "assets/sprites" SPRITES_OUT_FILE = "ASM/sprites.asm" SPRITES_TOLERANCE = 8 SPRITES_TRANSPARENT_INK = "" # --- Loading Screens (PNG → SCN) --- LOADER_SCREEN = "assets/screen"
MODE
Sprite Settings
Screen Settings
CPC screen mode affects resolution and colors: Mode Resolution Colors Pixels/Byte 0160×200 16 2 1320×200 4 4 2640×200 2 8
MODE = 0 # Standard for most games MODE = 1 # Higher resolution, fewer colors MODE = 2 # Monochrome, highest resolution
SPRITES_PATH SPRITES_PATH = "assets/sprites"
Directory containing PNG sprite files (searched recursively). SPRITES_OUT_FILE SPRITES_OUT_FILE = "ASM/sprites.asm"
Where to write the generated ASM sprite data. SPRITES_TOLERANCE SPRITES_TOLERANCE = 0 # Exact CPC colors only SPRITES_TOLERANCE = 8 # Recommended - small variance SPRITES_TOLERANCE = -1 # Auto - always find closest
RGB tolerance per channel when matching PNG colors to CPC palette. SPRITES_TRANSPARENT_INK (Optional)SPRITES_TRANSPARENT_INK = "" # No transparency SPRITES_TRANSPARENT_INK = "0" # Use INK 0 (black) SPRITES_TRANSPARENT_INK = "26" # Use INK 26 (white)
INK value (0-26) for transparent pixels (alpha=0 in PNG). LOADER_SCREEN LOADER_SCREEN = "assets/screen"
Directory containing PNG loading screens (searched recursively). Requirements:
Mode 0: 160×200 pixels, max 16 colors
Mode 1: 320×200 pixels, max 4 colors
Mode 2: 640×200 pixels, max 2 colors
Output:
.scn files generated in obj/.scn.info files with palette dataAutomatically added to DSK
Loading screens in BASIC: 10 MODE 0 20 LOAD"TITLE.SCN",&C000 30 ' Configure palette from .scn.info
Requires Pillow: Install with pip3 install Pillow to enable graphics conversion.
Complete Configuration Example Here’s a fully configured devcpc.conf for a scrolling platformer game:
# ============================================================================== # Platformer Game - DevCPC Configuration # ============================================================================== # Basic Settings PROJECT_NAME = "PLATFORMER" BUILD_LEVEL = 2 # Scrolling games - includes MAP2SP, UMA # Source Paths ASM_PATH = "asm/make_all_platformer.asm" BASIC_PATH = "bas" # Output Directories OBJ_DIR = "obj" DIST_DIR = "dist" DSK = "${ PROJECT_NAME }.dsk" # Generate both tape and cartridge versions CDT = "${ PROJECT_NAME }.cdt" CDT_FILES = "loader.bas 8BP2.bin level1.bin level2.bin" CPR = "${ PROJECT_NAME }.cpr" CPR_EXECUTE = "loader.bas" # Emulator Configuration RVM_PATH = "/Applications/Retro Virtual Machine 2.app/Contents/MacOS/Retro Virtual Machine 2" CPC_MODEL = 464 RUN_FILE = "8BP2.BIN" RUN_MODE = "auto" # Graphics Conversion MODE = 0 SPRITES_PATH = "assets/sprites" SPRITES_OUT_FILE = "ASM/sprites.asm" SPRITES_TOLERANCE = 8 LOADER_SCREEN = "assets/screen"
Validation Verify your configuration before building:
Checks performed:
✅ Required variables set (PROJECT_NAME, BUILD_LEVEL)
✅ Configured paths exist
✅ Required files present (e.g., ASM main file)
✅ Tools installed (Python, SDCC if needed)
Example output: ═══════════════════════════════════════ Validar Proyecto: PLATFORMER ═══════════════════════════════════════ → Validando configuración... ✓ PROJECT_NAME: PLATFORMER ✓ BUILD_LEVEL: 2 (Juegos con scroll) → Validando rutas... ✓ ASM_PATH: asm/make_all_platformer.asm ✓ BASIC_PATH: bas (2 archivo(s) .bas) → Validando herramientas... ✓ Python 3 instalado ✓ Pillow instalado ═══════════════════════════════════════ Resumen de Validación ═══════════════════════════════════════ ✓ Proyecto válido - Sin errores ni advertencias
Viewing Current Configuration Displays your current project settings:
═══════════════════════════════════════ Configuración del Proyecto ═══════════════════════════════════════ Proyecto: PLATFORMER Build Level: 2 Rutas configuradas: ✓ ASM: asm/make_all_platformer.asm ✓ BASIC: bas Directorios: Objetos: obj Salida: dist DSK: PLATFORMER.dsk CDT: PLATFORMER.cdt CPR: PLATFORMER.cpr Emulador: Modelo: 464 Modo: auto
Configuration Best Practices
Use Comments Document why you chose specific settings, especially BUILD_LEVEL. # Using level 2 because game needs # MAP2SP for tile streaming BUILD_LEVEL = 2
Comment Unused Options Keep optional settings commented until needed. Makes config cleaner. # Uncomment when adding C code: #C_PATH="C" #C_SOURCE="main.c"
Use Variables Leverage ${PROJECT_NAME} for consistency. DSK = "${ PROJECT_NAME }.dsk" CDT = "${ PROJECT_NAME }.cdt" CPR = "${ PROJECT_NAME }.cpr"
Version Control Commit devcpc.conf to your repository. Others can build with the same settings.
Common Configuration Patterns
PROJECT_NAME = "simple_game" BUILD_LEVEL = 4 ASM_PATH = "asm/make_all_simple.asm" BASIC_PATH = "bas" OBJ_DIR = "obj" DIST_DIR = "dist" DSK = "${ PROJECT_NAME }.dsk"
PROJECT_NAME = "mega_game" BUILD_LEVEL = 0 ASM_PATH = "asm/make_all_mega.asm" BASIC_PATH = "bas" OBJ_DIR = "obj" DIST_DIR = "dist" DSK = "${ PROJECT_NAME }.dsk" CDT = "${ PROJECT_NAME }.cdt" CDT_FILES = "loader.bas 8BP0.bin game.bin" CPR = "${ PROJECT_NAME }.cpr" CPR_EXECUTE = "loader.bas" MODE = 0 SPRITES_PATH = "assets/sprites" SPRITES_OUT_FILE = "ASM/sprites.asm" LOADER_SCREEN = "assets/screen"
PROJECT_NAME = "c_game" BUILD_LEVEL = 0 ASM_PATH = "asm/make_all_c_game.asm" BASIC_PATH = "bas" C_PATH = "C" C_SOURCE = "main.c" C_CODE_LOC = 20000 OBJ_DIR = "obj" DIST_DIR = "dist" DSK = "${ PROJECT_NAME }.dsk"
Next Steps
Build Levels Learn how to optimize memory with BUILD_LEVEL
Project Structure Understand where files are located
Quickstart Guide Start building your first project
Commands Reference Explore all available commands