BBC Basic & Assembly Development Environment

A VS Code devcontainer setup for BBC Basic and 6502 assembly programming on Apple Silicon Macs.

Features

• 🐳 Docker-based development environment optimized for Apple Silicon
• 📝 VS Code integration with syntax highlighting for BBC Basic and assembly files
• 🔧 Pre-configured build tasks for running BBC Basic programs
• ⚙️ BeebAsm assembler for 6502 assembly development
• 📚 Example programs demonstrating core concepts in both BASIC and assembly
• 🖥️ Matrix Brandy interpreter for BBC Basic compatibility

Getting Started

Prerequisites

• Docker Desktop for Mac (with Apple Silicon support)
• VS Code with the Dev Containers extension

Quick Start

1. Open this project in VS Code
2. When prompted, click "Reopen in Container" or run "Dev Containers: Reopen in Container" from the command palette
3. Wait for the container to build and start
4. Open any .bas file in the examples/ directory
5. Press Ctrl+Shift+P and run "Tasks: Run Task" → "Run BBC Basic Program"

File Structure

.
├── .devcontainer/
│   ├── devcontainer.json    # Dev container configuration
│   └── Dockerfile          # Container image definition
├── .vscode/
│   ├── settings.json       # VS Code settings for BBC Basic
│   └── tasks.json         # Build tasks for running programs
├── examples/
│   ├── hello.bas               # Hello World BASIC example
│   ├── calculator.bas          # Simple calculator
│   ├── loops.bas               # Loop demonstrations
│   ├── graphics.bas            # Graphics and drawing examples
│   └── demo.6502               # Assembly: Advanced 3D spinning star globe demo
└── README.md

Running Programs

BBC Basic Programs

Method 1: VS Code Tasks

• Open a .bas file
• Press Ctrl+Shift+P → "Tasks: Run Task" → "Run BBC Basic Program"

Method 2: Terminal

# Run a BASIC program
brandy examples/hello.bas

# Check syntax only
brandy -check examples/calculator.bas

Assembly Programs

# Assemble a 6502 program
beebasm -i examples/demo.6502 -do demo.ssd -boot Code -v

# Alternative with verbose output
asm examples/demo.6502  # Using the 'asm' alias

The -do flag creates a DFS disk image that can be used with BBC Micro emulators.

BBC Basic Language Reference

Basic Commands

• PRINT - Output text or variables
• INPUT - Get user input
• CLS - Clear screen
• END - End program

Variables

• Numeric: A = 10
• String: NAME$ = "Hello"
• Arrays: DIM numbers(10)

Control Structures

REM Conditional
IF condition THEN statement ELSE statement

REM For loops
FOR I = 1 TO 10 STEP 2
  PRINT I
NEXT I

REM While loops
WHILE condition
  statements
ENDWHILE

REM Repeat loops
REPEAT
  statements
UNTIL condition

Graphics Commands

• MODE n - Set graphics mode
• MOVE x, y - Move graphics cursor
• DRAW x, y - Draw line to coordinates
• CIRCLE x, y, radius - Draw circle
• GCOL mode, color - Set graphics color

Examples

The examples/ directory contains demonstration programs for both BBC Basic and 6502 assembly:

BBC Basic Examples

1. hello.bas - Basic output and program structure
2. calculator.bas - Input, variables, and arithmetic
3. loops.bas - FOR, WHILE, and REPEAT loop examples
4. graphics.bas - Drawing shapes and using colors

Assembly Examples

demo.6502

Advanced 3D spinning star globe demonstration

This is a sophisticated BeebAsm demo that showcases advanced assembly programming techniques:

Features:

• Real-time 3D spinning star globe with 160 dots
• Interactive controls: Z/X keys to change rotation speed, Esc to quit
• Advanced graphics in MODE 2 (high resolution)
• Optimized raster-chasing techniques for smooth animation
• Custom multiplication tables for fast 8-bit math
• Sine wave calculations for 3D projection
• Sophisticated interrupt handling with VSync synchronization
• Debug raster visualization (enable with debugrasters = TRUE)

Development Tips

BBC Basic

• BBC Basic files use .bas extension
• Line numbers are optional but traditional
• Use REM for comments
• Variables ending with $ are strings
• Graphics coordinates start from bottom-left (0,0)

Assembly Programming

• Assembly files use .6502 extension (or .asm, .s)
• Use BeebAsm syntax (similar to BBC BASIC's built-in assembler)
• Start with ORG directive to set assembly address
• Use .label for local labels, label for global labels
• End with SAVE directive to specify output file and address range
• Comments start with ;

Troubleshooting

Container Issues

• Ensure Docker Desktop is running
• Try rebuilding the container: "Dev Containers: Rebuild Container"

Program Execution

• Check syntax with the "Check BBC Basic Syntax" task
• Ensure file encoding is UTF-8
• Line endings should be Unix-style (LF)

Resources

BBC Basic

• Matrix Brandy Documentation
• BBC Basic Reference Guide
• Original BBC Micro Manual

Assembly Programming

• BeebAsm Documentation
• 6502 Assembly Guide
• BBC Micro Hardware Reference
• Stardot Forums - BBC Micro community and resources