██▓ ███▄    █ ▄▄▄█████▓ █    ██  ██▓▄▄▄█████▓ ██▓ ▒█████   ███▄    █    ▓█████  ███▄    █   ▄████  ██▓ ███▄    █ ▓█████
▓██▒ ██ ▀█   █ ▓  ██▒ ▓▒ ██  ▓██▒▓██▒▓  ██▒ ▓▒▓██▒▒██▒  ██▒ ██ ▀█   █    ▓█   ▀  ██ ▀█   █  ██▒ ▀█▒▓██▒ ██ ▀█   █ ▓█   ▀
▒██▒▓██  ▀█ ██▒▒ ▓██░ ▒░▓██  ▒██░▒██▒▒ ▓██░ ▒░▒██▒▒██░  ██▒▓██  ▀█ ██▒   ▒███   ▓██  ▀█ ██▒▒██░▄▄▄░▒██▒▓██  ▀█ ██▒▒███
░██░▓██▒  ▐▌██▒░ ▓██▓ ░ ▓▓█  ░██░░██░░ ▓██▓ ░ ░██░▒██   ██░▓██▒  ▐▌██▒   ▒▓█  ▄ ▓██▒  ▐▌██▒░▓█  ██▓░██░▓██▒  ▐▌██▒▒▓█  ▄
░██░▒██░   ▓██░  ▒██▒ ░ ▒▒█████▓ ░██░  ▒██▒ ░ ░██░░ ████▓▒░▒██░   ▓██░   ░▒████▒▒██░   ▓██░░▒▓███▀▒░██░▒██░   ▓██░░▒████▒
░▓  ░ ▒░   ▒ ▒   ▒ ░░   ░▒▓▒ ▒ ▒ ░▓    ▒ ░░   ░▓  ░ ▒░▒░▒░ ░ ▒░   ▒ ▒    ░░ ▒░ ░░ ▒░   ▒ ▒  ░▒   ▒ ░▓  ░ ▒░   ▒ ▒ ░░ ▒░ ░
 ▒ ░░ ░░   ░ ▒░    ░    ░░▒░ ░ ░  ▒ ░    ░     ▒ ░  ░ ▒ ▒░ ░ ░░   ░ ▒░    ░ ░  ░░ ░░   ░ ▒░  ░   ░  ▒ ░░ ░░   ░ ▒░ ░ ░  ░
 ▒ ░   ░   ░ ░   ░       ░░░ ░ ░  ▒ ░  ░       ▒ ░░ ░ ░ ▒     ░   ░ ░       ░      ░   ░ ░ ░ ░   ░  ▒ ░   ░   ░ ░    ░
 ░           ░             ░      ░            ░      ░ ░           ░       ░  ░         ░       ░  ░           ░    ░  ░

Intuition Engine System Documentation

Complete Technical Reference & User Guide

(c) 2024 - 2026 Zayn Otley

https://github.com/intuitionamiga/IntuitionEngine

License: GPLv3 or later

https://www.youtube.com/@IntuitionAmiga/

See also: TUTORIAL.md - Step-by-step guide to building a complete demoscene intro with multiple CPU architectures.

Quick Links

| Document | Description | |----------|-------------| | DEVELOPERS.md | Build, test, toolchains, and contribution guide | | CHANGELOG.md | Release history | | sdk/README.md | SDK developer package with examples and build scripts | | sdk/docs/TUTORIAL.md | Step-by-step demoscene intro tutorial | | sdk/docs/IE64_ISA.md | IE64 instruction set reference | | sdk/docs/IE64_COOKBOOK.md | IE64 common patterns and recipes | | sdk/docs/ehbasic_ie64.md | EhBASIC language guide | | sdk/docs/iemon.md | Machine monitor (F9 debugger) reference | | sdk/docs/iescript.md | IEScript Lua automation reference | | sdk/docs/sdk-getting-started.md | SDK quick start | | sdk/docs/toolchains.md | Assembler toolchain reference | | sdk/docs/demo-matrix.md | Demo program coverage matrix | | sdk/docs/platform-compatibility.md | Platform support and build profiles | | sdk/docs/release-process.md | Release packaging guide | | sdk/docs/ie_emutos.md | EmuTOS integration guide (GEM desktop on IE) |

System Overview
- CPU Options
- Audio Capabilities
- Video System
- Quick Start
- 1.7 Machine Monitor
Architecture
- 2.1 Unified Memory
- 2.2 Hardware I/O
Memory Map & Hardware Registers
- 3.1 System Vector Table
- 3.2 Program Space
- 3.3 Video Registers
- 3.4 Timer Registers
- 3.5 Sound Registers (Legacy and Flexible)
- 3.6 PSG Registers
- 3.7 POKEY Registers
- 3.8 SID Registers
- 3.9 TED Registers
- 3.10 TED Video Chip Registers
- 3.11 AHX Module Player Registers
- 3.12 MOD Player Registers
- 3.13 Hardware I/O Memory Map by CPU
- 3.14 VGA Video Chip
- 3.15 ULA Video Chip (ZX Spectrum)
- 3.16 ANTIC Video Chip (Atari 8-bit)
- 3.17 GTIA Color Control (Atari 8-bit)
- 3.18 File I/O Device
- 3.19 Coprocessor Subsystem
- 3.20 Voodoo 3D Graphics
IE32 CPU Architecture
- 4.1 Register Set
- 4.2 Status Flags
- 4.3 Addressing Modes
- 4.4 Instruction Format
- 4.5 Instruction Set
- 4.6 Memory and I/O Integration
- 4.7 Interrupt Handling
- 4.8 Compatibility Notes
MOS 6502 CPU
- 5.1 Register Set
- 5.2 Status Flags
- 5.3 Addressing Modes
- 5.4 Instruction Set
- 5.5 Memory and I/O Integration
- 5.6 Interrupts and Vectors
- 5.7 Compatibility Notes
Zilog Z80 CPU
- 6.1 Register Set
- 6.2 Status Flags
- 6.3 Addressing Modes
- 6.4 Instruction Set
- 6.5 Memory and I/O Integration
- 6.6 Interrupts
- 6.7 Compatibility Notes
Motorola 68020 CPU with FPU
- 7.1 Register Set
- 7.2 Status Flags
- 7.3 Addressing Modes
- 7.4 Instruction Set
- 7.5 FPU (68881/68882) Features
- 7.6 Memory and I/O Integration
- 7.7 Interrupts and Exceptions
- 7.8 Compatibility Notes
Intel x86 CPU (32-bit)
- 8.1 Register Set
- 8.2 Status Flags
- 8.3 Addressing Modes
- 8.4 Instruction Set
- 8.5 Memory and I/O Integration
- 8.6 Interrupts
- 8.7 Compatibility Notes
IE64 CPU Architecture
- 9.1 Register Set
- 9.2 Instruction Format
- 9.3 Addressing Modes
- 9.4 Instruction Set
- 9.5 FPU Logic
- 9.6 Memory and I/O Integration
- 9.7 Interrupt Handling
- 9.8 Compatibility Notes
- 9.9 EhBASIC IE64
- 9.10 Memory Management Unit (MMU)
Assembly Language Reference
- 10.1 Basic Program Structure
- 10.2 Assembler Directives
- 10.3 Memory Access Patterns
- 10.4 Stack Usage
- 10.5 Interrupt Handlers
Sound System
- Custom Audio Chip Overview
- 11.1 Sound Channel Types
- 11.2 Modulation System
- 11.3 Global Effects
- 11.4 PSG Sound Chip (AY-3-8910/YM2149)
- 11.5 POKEY Sound Chip
- 11.6 SID Sound Chip
- 11.7 TED Sound Chip
- 11.8 AHX Sound Chip
- 11.9 MOD Player (ProTracker)
Video System
- 12.1 Display Modes
- 12.2 Framebuffer Organisation
- 12.3 Dirty Rectangle Tracking
- 12.4 Double Buffering and VBlank Synchronisation
- 12.5 Direct VRAM Access Mode
- 12.6 Copper List Executor
- 12.7 DMA Blitter
- 12.8 Raster Band Fill
- 12.9 Video Compositor
Developer's Guide
Implementation Details
Platform Support and Building
EmuTOS Mode
AROS Mode

1. System Overview

The Intuition Engine is a virtual machine that emulates a complete retro-style computer system. It is a modern 64-bit RISC reimagining of the Commodore, Atari, Sinclair and IBM 8/16/32-bit home computers, with IE64 as the default core and five additional CPU cores.

CPU Options

| CPU | Architecture | Registers | Features | |-----|--------------|-----------|----------| | IE32 | 32-bit RISC | 16 general-purpose (A-H, S-W, X-Z) | Fixed 8-byte instructions, simple and fast | | M68K | 32-bit CISC | 8 data (D0-D7), 8 address (A0-A7) | 95%+ instruction coverage, FPU support | | Z80 | 8-bit | AF, BC, DE, HL + alternates, IX, IY | Full instruction set, interrupt modes, x86-64 JIT with block chaining | | 6502 | 8-bit | A, X, Y | NMOS instruction set, zero page optimisation | | x86 | 32-bit | EAX-EDX, ESI, EDI, EBP, ESP | 8086 instructions + 32-bit registers, flat memory model | | IE64 | 64-bit RISC | 32 general-purpose (R0=zero, R31=SP) | ARM64/x86-64 JIT compiler, native FP32 FPU, compare-and-branch, no flags register, MMU with paged virtual memory and user/supervisor privilege levels, atomic memory operations (CAS/XCHG/FAA), TLS register |

Default core: IE64. Additional cores: IE32, M68K, x86, Z80, 6502.

Audio Capabilities

Custom Synthesizer:

10-channel synth engine (4 base + 3 SID2 + 3 SID3 for multi-SID playback)
5 legacy register blocks (square, triangle, sine, noise, sawtooth)
4 flexible channels with selectable waveforms (uniform register interface)
ADSR envelopes, PWM, frequency sweep, hard sync, ring modulation
Global filter (LP/HP/BP), overdrive, reverb
44.1kHz, 32-bit floating-point processing

Classic Sound Chips (register-mapped to custom synth):

AY/YM/PSG (AY-3-8910/YM2149) - Supports .ym, .ay, .vgm, .vgz, .vtx, .sndh, .pt3, .pt2, .pt1, .stc, .sqt, .asc, .ftc playback (VGM includes SN76489 conversion; tracker formats use Z80 emulation)
POKEY (Atari) - Supports .sap playback
SID (6581/8580) - Supports .sid playback
TED (Commodore Plus/4) - Supports .ted playback
Amiga AHX module playback
ProTracker MOD (.mod) - 4-channel Amiga module playback with A500/A1200 filter emulation
WAV PCM audio via SoundChip FLEX DAC mode

Video System

Resolutions: 640×480, 800×600, 1024×768, 1280×960 (default)
32-bit RGBA framebuffer with double buffering
Copper coprocessor for raster effects
DMA blitter for fast copy/fill/line operations
Dirty rectangle tracking for efficient updates
Engines/chips: IEVideoChip, VGA, ULA, TED video, ANTIC/GTIA, 3DFX Voodoo

Scripting

IEScript (Lua 5.1) automation engine for programmatic control of the entire emulator
11 API modules: cpu, mem, term, audio, video, repl, dbg, rec, coproc, media, sys
Frame-synchronised coroutine model, MP4+AAC recording via FFmpeg, interactive F8 REPL overlay
See iescript.md for the full reference

Quick Start

# Default: start EhBASIC on IE64
./bin/IntuitionEngine

# Run IE32 program
./bin/IntuitionEngine -ie32 program.iex

# Run M68K program
./bin/IntuitionEngine -m68k program.ie68

# Run x86 program
./bin/IntuitionEngine -x86 program.ie86

# Run IE64 program
./bin/IntuitionEngine -ie64 program.ie64

# Run EhBASIC interpreter
./bin/I

IntuitionEngine

Install / Use

README