Amiga ASM Development Workflow

Introduction

This repository provides and demonstrates an automation workflow for certain aspects of development in 68K assembly for the Commodore Amiga series of computers. It has been developed for use in a Linux environment using 'freely available' tools. FOSS tools are used as much as possible, but some components (e.g. vasm and vlink) are distributed under their own licenses.

The following features are provided and demonstrated:

Conversion of GIMP authored image assets (*.xcf) into .png, .iff and .raw (interleaved) formats
Generation of palette (COLORxx register) data for image assets in copper list format
Host compilation of assembler (vasm) and linker (vlink) tools included.
Building to a UAE emulated hard drive (dh0) folder
Building of a bootable AmigaDOS floppy disk format image (ADF) file.
A Unix Makefile to automate building on the host machine
A GitHub Actions (GHA)workflow for CI/CD automated building in the the cloud.

Limitations / TODO

Only RAW files with 'interleaved' bitplanes data are generated (no 'back-to-back' support)
Only images for low resolution (non-EHB) mode apps are supported.
No compression/packing support.
No special treatment for AGA
Bare bones 'no frills' bootable AmigaDOS ADFs. i.e. no loading messages etc.

Demo App

This repo contains source code for a simple Amiga demo using Bitplanes (playfield), Blitter objects (BOBs) and Sprites. This demo was made using samples of example code from the excellent book 'Bare-Metal Amiga Programming' by E. Th. van den Oosterkamp, and used under his permissive license terms.

The app was also developed in the equally excellent Amiga Assembly extension for Visual Studio Code (VSCode). VSCode is not required for this workflow but this repo structure matches the example project and aims to be compatible with its structure. e.g. the emulated hard drive uae\dh0 is the destination for the built binary.

Requirements

A host Linux environment is expected. This project has been developed under Debian based Linux x86_64 distros (e.g. Ubuntu) Other environments may need some modifications to run.

Some additional tools are required to be installed and made available in the PATH. These are automatically installed by the GHA workflow but will need to be installed manually to run on a local host machine.

GIMP

GIMP is required to convert GIMP native (*.xcf) indexed colour mode image asset files into an intermediary PNG format.

GIMP may already be installed on your Linux distro. If not it can be installed either through your distro package manager (e.g. Debian apt:)

sudo apt install gimp

or as a flatpak from FlatHub

ipng2iff

ipng2iff is used to create ILBM/IFF image files as used on the Amiga from PNG source files exported from GIMP.

ipng2iff has to be built from source. To do so requires you have a working RUST environment setup.

git clone https://github.com/m0ppers/ipng2iff.git
cd ipng2iff
cargo build -r

Once ipng2iff has built, you need to move it to somewhere where it can be found in your $PATH. e.g.

sudo cp target/release/ipng2iff /usr/local/bin

ilbmtoppm

ilbm2ppm is used to fetch metadata about IFF image files. It is part of the netpbm toolkit.

netpbm can be installed using your package manager. e.g. for Debian apt:

sudo apt install netpbm

amitools

amitools is used to create floppy disk (ADF) images using xdftool

To install amitools, first make sure you have a working python3 environment. Then amitools can be installed with these commands:

python3 -m pip install --upgrade pip setuptools wheel
python3 -m pip install amitools

GIMP Source Image Requirements

Your source (.xcf) GIMP files should be using indexed color mode, not 'RGB'. You can convert an RGB image into indexed using GIMP from the menu:

Menu->Image->Mode->Indexed...

A dialog will be presented allowing you choose the number of colours and whether you wish to use dithering etc.

Naming Conventions

Whilst not absolutely required, the workflow will work better if you stick to certain naming conventions for your image assets.

By default the copper list output of palette data will begin at colour palette index 0 (COLOR00/0xdff180) and proceed incrementally. This behaviour can be changed by using naming conventions for the source (.xcf) image files:

Dual Playfields

If you are developing a dual-playfield app, it's likely that for images destined for playfield 2 you will need the palette to start from the 'even bitplanes' palette of COLOR08/0xdff190 (See the HRM for more details)

This can be achieved by including the text 'pf2' somewhere in your image source filename.

Sprites

Sprites 0-7 operate in pairs and share a palette of 4 colours. As per the HRM

                 16  Unused   00  |
                 17  Color 1  01  |
                 18  Color 2  10  |-- Sprites 0 and 1
                 19  Color 3  11 _|
                 20  Unused   00  |
                 21  Color 1  01  |
                 22  Color 2  10  |-- Sprites 2 and 3
                 23  Color 3  11 _|
                 24  Unused   00  |
                 25  Color 1  01  |
                 26  Color 2  10  |-- Sprites 4 and 5
                 27  Color 3  11 _|
                 28  Unused   00  |
                 29  Color 1  01  |
                 30  Color 2  10  |-- Sprites 6 and 7
                 31  Color 3  11 _|

By including e.g. spr0 in your filename the copper list palette will be output starting at the appropriate colour index. Note, that for each sprite pair only one palette file is generated. In the case of multiple source files for the same sprite pair, the last one to be processed will be used as the source for palette data.

Makefile

The Makefile is invoked by the command:

make <TARGET>

Where <TARGET> is an optional specified component. If <TARGET> is not specified it will default to 'all' The various useful targets are described in the table below

Target	Description
`all`	Convert assets, build tools, assemble source `.s` files into `.o` object files and link program into `uae/dh0`.
`adf`	Everything in the `all` target PLUS generation of floppy disk image (ADF) file.
`assets`	Only converts image assets (and generates palette include files)
`tools`	Only builds the tools (`vasm` & `vlink`)

The Makefile also supports a set of 'clean-up' targets to remove files:

Target	Description
`clean`	Removes built target program and `.o` object files.
`clean_adf`	Removes the floppy disk image (ADF) file.
`clean_assets`	Removes converted image asset files (and generated palette include files)
`clean_tools`	Removes object and executable files for the tools (`vasm` & `vlink`)
`clean_all`	Removes all of the above

Image Asset Conversion Script

The image asset conversion script (convert_assets_to_raw.sh) is located in the scripts directory. It's used by the Makefile, but it can also be used standalone to do more selective conversions if required:

Passing -h (or --help) to the script shows usage information:

$ ./scripts/convert_assets_to_raw.sh -h
usage: convert_assets_to_raw.sh [options]

Options:
 
 -a,--asset-dir <dir name>
     Use dir <dir name> to find source assets and place output assets.
     Defaults to ./assets 
 -d,--delete-ints
     Delete intermediate files (PNGs & IFFs). 
 -i,--include-dir <dir name>
     Use target dir <dir name> for palette include files. <dir name> MUST exist.
     Defaults to same dir as --asset-dir 
 -n,--dry-run
     Show what would be done only. Do not actually [over]write or delete any output files. 
 -p,--png-iff
     Include generation of IFF files from PNGs. 
 -r,--iff-raw
     Include generation of RAW bitplane data files from IFFs. 
 -s,--inc-pal
     Include generation of palette ASM include code files from IFFs. 
 -x,--xcf-png
     Include generation of PNG files from XCFs.

GitHub Actions Workflow

This repository includes a GitHub Actions (GHA) workflow for automated build and ADF packaging in the cloud using a GHA hosted Ubuntu 24.04 (LTS) runner image. Successful build artifacts (ADFs) can be downloaded from the Actions tab

neildavis/amiga_asmdev_workflow