Retrodev

<div align="center"><img src="doc/img/retrodev-logo.png" alt="Retrodev" width="400" /></div>

A development environment for retro 8-bit and 16-bit home computer software.

<div align="center"><a href="https://github.com/tlotb/retrodev/releases/latest"><img src="https://img.shields.io/badge/⬇_Download_Latest_Release-2ea44f?style=for-the-badge" alt="Download Latest Release" /></a></div>

---

Table of Contents

1. What is Retrodev?
2. Features at a Glance
3. Installing and Getting Started
4. Project Layout
5. Project Items
6. Files Panel
7. Building a Project
8. Emulators and Debugging
9. Contributing and Technical Information
10. Thanks and Greetings
11. Open Source Libraries and Licenses
12. License and Copyright

---

1. What is Retrodev?

Developing software for retro home computers has always meant assembling a fragile toolchain from scattered pieces: a batch file here, a graphics converter there, a separate palette tool, an assembler invoked from the command line, and a hex editor for sanity-checking the output. Every machine has its own quirks, its own file formats, its own assembler dialect. Keeping all those moving parts in sync is tedious and error-prone.

Retrodev replaces that mess with a single, self-contained application that acts as the glue between all your existing tools. It does not replace your image editor or your version control system — it sits alongside them and brings together everything you need for the build and conversion side of the workflow in one place:

• Graphics conversion — import any modern image and convert it to the native pixel and palette format of the target machine, with live preview.
• Tile and sprite extraction — slice a converted image into tiles or sprites ready to be referenced by your code.
• Tile map editor — paint multi-layer scrolling maps using extracted tiles, with parallax preview and aspect-ratio-correct display per system and mode.
• Palette solver — describe which graphics appear on screen at the same time and let Retrodev find a palette assignment that satisfies all constraints simultaneously.
• Integrated code editor — write Z80 assembly and AngelScript export scripts without leaving the application. The editor provides syntax highlighting, RASM directive and label auto-complete, code-lens timing annotations for Z80, and full Retrodev API auto-complete and hover documentation for AngelScript.
• Scripted export — write AngelScript export scripts for bitmaps, tile sets, sprites and maps that produce exactly the binary format your program expects, with full control over layout, headers and compression.
• Project-based workflow — everything lives in a .retrodev project file. Open it, build it, run it. No batch files.

<div align="center"><img src="doc/img/retrodev-overview.png" alt="Retrodev main window" width="800" /></div>

Supported target systems

| System | Status | |---|---| | Amstrad CPC / CPC+ | ✅ Full support | | ZX Spectrum | 🚧 Planned | | Commodore 64 | 🚧 Planned | | MSX | 🚧 Planned |

---

2. Features at a Glance

Graphics conversion and extraction

Retrodev converts modern RGBA images into native hardware formats. The conversion pipeline supports resize, colour correction, quantization and dithering — all applied in the order that matches how real hardware renders pixels.

For the complete documentation on graphics conversion, click here.

Dithering methods

Tile extraction: chop a converted image into a grid of tiles, deduplicate them, and produce a tile sheet the map editor and tile export scripts can reference.

For the complete documentation on tile extraction, click here.

Sprite extraction: extract individual sprite frames from a sheet, with configurable frame size and ordering.

For the complete documentation on sprite extraction, click here.

Palette solver

The palette solver takes a list of graphics participants — bitmaps, tile sets and sprite sheets — and finds the smallest set of hardware colours that satisfies all of them simultaneously, respecting screen zones (horizontal scanline bands that share a palette) and participant roles (always-on, level-specific, raster-zone).

For the complete documentation on the palette solver, click here.

Tile map editor

Paint multi-layer tile maps with configurable parallax scroll speeds, tile group stamps, viewable-area overlay and aspect-ratio-correct canvas preview per target system and screen mode.

For the complete documentation on the tile map editor, click here.

Integrated code editor

A full-featured text editor with Z80 assembler and AngelScript support: syntax highlighting, RASM directive completion, label and symbol auto-complete, code-lens timing annotations per instruction, and a directive reference built in.

The same editor is used for AngelScript export scripts, where it exposes the full Retrodev export API — IBitmapContext, ITilesetContext, ISpriteContext, IMapContext, IPaletteContext and all their methods — as built-in auto-complete symbols and hover documentation, so you write export scripts with the same comfort as assembly code.

For the complete documentation on the integrated code editor, click here.

Scripted export

Bitmap conversions, tile extractions, sprite extractions and maps each have an associated AngelScript export script that receives the fully converted data and writes it in any format you need. Scripts declare their parameters with // @param annotations and Retrodev builds the UI for them automatically.

For the complete documentation on scripted export, click here.

---

3. Installing and Getting Started

Download

The latest release is available on the GitHub Releases page.

Download the .zip archive for your platform and follow the installation instructions below.

Installation

Retrodev requires no installer. Unzip the release archive to any folder and run retrodev.exe. All dependencies are bundled.

retrodev-1.0.x/
├── retrodev.exe
├── sdk/              ← reusable macros and library code for your projects
└── examples/         ← ready-to-build example projects

Creating a new project

1. Launch Retrodev.
2. Choose File → New Project.
3. Pick a folder. Retrodev creates a single .retrodev project file there and opens it — nothing else is added. Your folder and its files are yours to organise however you like.

From here you can add files to the Files panel, create project items in the Project panel, and start building.

<div align="center"><img src="doc/img/new-project-dialog.png" alt="New Project dialog" width="800" /></div>

Opening an existing project

Choose File → Open Project and navigate to a .retrodev project file, or double-click a .retrodev file in Explorer. Recent projects appear in the File → Recent submenu.

---

4. Project Layout

When you open a project, Retrodev shows three sections in the Project panel. These are not filesystem folders — they are three distinct views into different parts of your workflow.

<div align="center"><img src="doc/img/project.-view.png" alt="Project panel" width="800" /></div>

SDK

The SDK section shows the contents of the sdk/ folder that ships alongside retrodev.exe. This is a read-only file view of the shared library: Z80 macros, reusable routines and AngelScript helpers that any project can draw from.

To use something from the SDK in your project, include it explicitly in your build configuration — the files are listed in the panel so it is just point-and-click. The paths are handled automatically; you just pick what you need.

The SDK folder is shared across all your projects. It never lives inside your project directory.

Project

The Project section is where all your build configuration lives. This is entirely virtual — nothing here corresponds directly to files on disk. It is the list of things Retrodev should do with your files:

• Bitmap conversions
• Tile extractions
• Sprite extractions
• Maps
• Build pipelines
• Palette definitions

Each item stores its parameters in the .retrodev project file. You add, configure, reorder and remove them here. The Project section is the backbone of the workflow.

Files

The Files section is a file view rooted at the folder where your .retrodev project file lives, showing that folder and all its subfolders. These are your actual input files — bitmaps, assembly sources, AngelScript export scripts, data files — and they can all be opened and edited directly from here:

| File type | Opens in | |---|---| | .png, .bmp, .jpg, .tga | Built-in image editor / viewer | | .asm, .z80 | Z80 assembly editor | | .as | AngelScript editor | | Anything else | Hex / data viewer |

Files in this section are the raw ingredients. The typical way to put them to work is to right-click a file, choose the conversion type from the context menu, and Retrodev creates the corresponding project item with that file already set as the source.

---

5. Project Items

Project items appear in the Project panel. You can organise them into virtual folders by drag-and-drop — for example, grouping all Amstrad CPC items under a CPC folder and all Spectrum items under a Spectrum folder. This organisation is cosmetic only; execution order is controlled by the dependency list inside each Build project item.

Bitmap conversi