diff --git a/README.md b/README.md new file mode 100644 index 0000000..3a59e40 --- /dev/null +++ b/README.md @@ -0,0 +1,206 @@ +# PETProject + +**A Commodore 64–native IDE for BASIC and 6502 assembly.** + +PETProject is a full-featured integrated development environment that runs +directly on a stock Commodore 64 with a 1541 disk drive. Write, edit, assemble, +disassemble, and renumber code without ever leaving your C64 β€” no cross-assembler, +no modern PC, no special hardware required. + +> πŸ•ΉοΈ **Download a ready-to-run disk image:** + +[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.txt) +![Platform: Commodore 64](https://img.shields.io/badge/platform-Commodore%2064-blue.svg) +![Assembler: cc65](https://img.shields.io/badge/built%20with-cc65-orange.svg) + +--- + +## Table of Contents + +- [Features](#features) +- [Quick Start](#quick-start) +- [Keyboard Reference](#keyboard-reference) +- [Modules](#modules) +- [Building From Source](#building-from-source) +- [Source Layout](#source-layout) +- [Documentation](#documentation) +- [Tips](#tips) +- [License & Credits](#license--credits) + +--- + +## Features + +- πŸ–ŠοΈ **Full-screen PETSCII editor** backed by gap-buffer storage (up to ~24 KB of source) +- 🌈 **Syntax highlighting** for both BASIC 2.0 and 6502 assembly +- βš™οΈ **Built-in two-pass assembler** β€” turn your source into runnable machine language +- πŸ” **Built-in disassembler** with full illegal-opcode support; runs automatically when you open an ML file +- πŸ”’ **Line renumbering** that also fixes `GOTO`/`GOSUB` targets +- πŸ’Ύ **Disk utility** β€” browse the directory, load files, delete, rename, format, and send raw drive commands +- πŸ”Ž **Search & replace** with toggleable case sensitivity +- ⌨️ **Keyword completion** β€” press `TAB` to cycle through completions +- πŸ“œ **BASIC scripting engine** with extended keywords to automate the IDE *(REU required)* +- 🧰 **Many quality-of-life touches** that make coding on a real C64 pleasant +- πŸ“¦ **Fully self-contained** β€” runs perfectly on a stock C64; an REU is optional and used only by the scripting subsystem + +--- + +## Quick Start + +1. Grab the disk image (`petproject.d64`) from the + [download page](https://gopherbrokesoftware.com/petproject), or + [build it yourself](#building-from-source). +2. Insert it into drive 8 (in [VICE](https://vice-emu.sourceforge.io/) or on real hardware). +3. Load and run: + + ```basic + LOAD"*",8 + RUN + ``` + + *(Or use your emulator's autostart feature.)* + +That's it β€” you're in the editor. Press `F8` to open the module picker, or start +typing to write some BASIC. + +> πŸ’‘ **Tip:** Your experience will be much smoother with a fastloader cartridge. + +--- + +## Keyboard Reference + +| Key | Action | +| --- | --- | +| `F1` | Settings β€” colors, data-drive number, cursor blink | +| `F2` | Page Up | +| `F3` | Load a file (BASIC, assembly, or compiled ML) | +| `F4` | Page Down | +| `F5` | Save the current file | +| `F6` | Load a SEQ (plain text / source) file | +| `F7` | Quit to BASIC | +| `F8` | Open the module picker (see [Modules](#modules)) | +| `CTRL+F` | Find / replace | +| `CTRL+L` | Force a full screen redraw | +| `CTRL+N` | New file (clears the buffer) | +| `CTRL+R` | Run Script (shortcut for `F8 β†’ Run Script`) | +| `TAB` | Cycle keyword completions | +| Cursor keys | Navigate | +| `INST/DEL` | Delete the character left of the cursor | + +> ℹ️ The **program disk must stay in drive 8**; the data drive is configurable in +> Settings (`F1`). If you try to do something destructive (new file, load, quit) +> with unsaved changes, the IDE prompts you to save first. During long-running +> tasks it flashes the top-left character so you know it's working, not frozen. + +--- + +## Modules + +Reach these from the module picker (`F8`): + +| Module | Purpose | +| --- | --- | +| **Assemble** (MODASM) | Two-pass 6502 assembler β€” compiles the current buffer to ML | +| **Disassemble** (MODDIS) | 6502 disassembler; runs automatically when loading an ML file | +| **Renumber** (MODREN) | Renumbers BASIC lines and updates `GOTO`/`GOSUB` targets | +| **Disk Utility** (MODDSK) | Directory browser, delete, rename, format, raw commands | +| **Run Script** (MODSCT/MODSCR/MODSCRH) | Run BASIC automation scripts with extended keywords *(REU required)* | + +Search & replace (MODSFR) is available directly via `CTRL+F`. + +--- + +## Building From Source + +**Requirements:** the [cc65](https://cc65.github.io/) toolchain (`ca65` + `ld65`, +v2.19 or newer) and Python 3. + +```bash +# Build the editor, all modules, and the .d64 disk image +bash make_petproject.sh +``` + +To build only the modules: + +```bash +bash build_modules.sh +``` + +To (re)create the disk image manually: + +```bash +python3 make_disk.py --build-dir build --name petproject --id pp petproject.d64 +``` + +> ⚠️ `make_petproject.sh` ends with an optional line that launches VICE +> (`x64sc`). Edit or comment out that path to match your setup. See the script's +> comments for the full `ca65`/`ld65` invocations, which you can override with the +> `CA65` and `LD65` environment variables. + +--- + +## Source Layout + +**Editor core** + +| File | Description | +| --- | --- | +| `editor.asm` | Main editor: entry point, main loop, rendering, input | +| `colorize.asm` | Syntax colorizer (included by `editor.asm`) | +| `loadsave.asm` | File I/O (included by `editor.asm`) | +| `modules.asm` | Module-loader framework (included by `editor.asm`) | +| `petproject.cfg` | Linker config for the editor PRG | + +**Modules** + +| File | Loads at | Description | +| --- | --- | --- | +| `modasm.asm` | `$A000` | Assembler | +| `moddis.asm` | `$A000` | Disassembler | +| `modren.asm` | `$C000` | Renumber | +| `moddsk.asm` | `$C000` | Disk utility | +| `modsfr.asm` | `$C000` | Search / replace | +| `moddet.asm` | β€” | Detokenizer (hidden; runs on BASIC load) | +| `modtok.asm` | β€” | Tokenizer (hidden; runs on BASIC save) | +| `modsct.asm` | β€” | Script tokenizer (hidden; runs on Run Script) | +| `modscr.asm` | `$A000` | Script runner stub | +| `modscrh.asm` | `$C000` | Script handler (stays resident during scripts) | + +**Linker configs:** `module.cfg` (default `$C000`), `modasm.cfg` (`$A000`), +`moddis.cfg`, `modsfr.cfg`, `modscr.cfg`, `modsct.cfg`. + +**Build tooling:** `make_petproject.sh` (full build), `build_modules.sh` +(modules only), `make_disk.py` (creates the `.d64` image). + +**Reference:** `Resources/basic.asm` and `Resources/kernal.asm` are annotated +ROM disassemblies kept for reference. + +--- + +## Documentation + +In-depth manuals live in the [`docs/`](docs/) directory: + +- [Editor manual](docs/editor_manual.md) +- [Assembler manual](docs/assembler_manual.md) +- [Renumber manual](docs/renumber_manual.md) +- [Script runner manual](docs/script-runner-manual.md) + +Security policy: [`SECURITY.md`](SECURITY.md). + +--- + +## Tips + +- Use a **fastloader cartridge** for a much snappier experience. +- Keep the **program disk in drive 8**; point Settings (`F1`) at a separate data + drive if you have one. +- The scripting engine needs an **REU** for script tokenization and IDE snapshots. + +--- + +## License & Credits + +Released under the **MIT License** β€” see [`LICENSE.txt`](LICENSE.txt). + +PETProject was designed and built by **Thomas Knox / Gopher Broke Software**.