Prepare for your first program.

Choose what you want to do

For Spectrum BASIC, start with the first BASIC lesson and the Spectrum setup guide. You do not need an assembler to type a BASIC program into the machine’s editor. Converting a saved BASIC listing into a tape image is a separate workflow.

For Spectrum assembly, follow the assembly route and its setup instructions. You can start there without completing BASIC or Foundations.

Find your system’s setup guide

These guides cover the initial four systems. Check the language and target configuration described in your lesson: a machine’s general setup page may focus on assembly.

The Amiga also has separate setup guides for AMOS and Blitz BASIC. Use the guide for the language you have chosen.

Understand where the work happens

The host is the computer you use to prepare your program. The target is the machine the program is written for. Writing and building on one computer to run on another is called cross-development.

1. Edit the source. Source files contain the instructions you write. Keep them in a project folder with any assets the lesson needs.
2. Build the target’s files. An assembler translates assembly source into machine code. Other tools may convert graphics, pack data or prepare a tape, disk or cartridge image. The lesson specifies which steps apply.
3. Load and run. Use an emulator configured for the target, or transfer the output to suitable original hardware. An emulator is a program that models the target machine on your host computer.
4. Observe and revise. Compare the result with the lesson, change the source and build again. Keep the source as well as the built output.

When you program inside the target’s own environment, the steps may look different. You might type and run BASIC there, then save to its emulated storage. Follow the chosen language’s instructions rather than applying an assembly command.

Host tools can make editing and building more convenient. They do not give the target extra memory, graphics facilities or processing time.

Know what each tool contributes

The 198x family develops tools used in this work: Asm198x for assembly, Build198x for preparing assets and media, and Emu198x for emulation. Each project’s documentation describes its installation and current capabilities.

You do not need to install every family tool. Use the assembler, emulator and converters named in your lesson’s setup guide. Match the assembler’s syntax settings and the emulator’s machine model to the example.

Some emulator configurations require system ROM files: the built-in software the original machine uses. The ROM guide explains the files and their sources. Check the requirements for your chosen configuration before trying to load the lesson’s program.

Check a small example before continuing

Use the first runnable example supplied by your lesson. An installed tool or a successful build is only part of the check.

• Confirm that the expected screen appears and the described controls respond.
• Make a small change suggested by the lesson, run it again and check the result.
• Save your source or listing, close it and reopen it. Check that you can load the built program or saved target files again too.

Once that works, continue the guided sequence. There is no need to design a complete game just to prove that your tools are ready.

When a step does not work

Find the first step whose result differs from the instructions. Check the filename, folder, tool version and target configuration. Copy the exact error message rather than paraphrasing it.

If the guide does not match what you see, report the page on GitHub or ask through Discord. Include your operating system, chosen language, tool versions and the step you reached. Setup instructions can be wrong or become outdated; a mismatch is something to investigate.

For a class or club, the teaching guide includes advice on preparing an activity and checking the available computers.