sys-64738.com

A website that serves as a Commodore 64 emulator, where the web content is provided as a C64 program that the emulator loads.

Overview

This project creates a web-based C64 emulator where you can:

• Load and run C64 programs (.prg, .d64, .t64, .crt files)
• Modify the C64 program files to change the web content
• Provide an authentic retro computing experience in the browser

Features

• Full C64 emulation in the browser
• Load programs from local files or URLs
• Clean, retro-styled UI
• Responsive design

Setup

Note: While JSC64 can work when opening the HTML file directly, it's recommended to use a local web server for best results, especially when loading programs.

Option 1: Direct (Simple Testing)

You can open index.html directly in your browser, though some features may be limited.

Option 2: Using Python (Recommended)

python3 -m http.server 8000

Then open http://localhost:8000 in your browser.

Option 3: Using Node.js http-server

npx http-server -p 8000

Option 4: Using PHP

php -S localhost:8000

After starting a server (or opening directly):

1. Navigate to the page in your browser
2. Wait for "Emulator ready" message
3. Click "Load Program" to load a C64 program file (.prg format)
4. The emulator will start and run your program

Loading Programs

From Local File

Click the "Load Program" button and select a C64 program file from your computer.

From URL (Programmatic)

You can load a program programmatically using the browser console:

loadProgramFromUrl('https://example.com/path/to/program.prg', 'My Program');

PRG Decompiler (BASIC + 6502)

To analyze/diff compiled PRGs, use:

python3 tools/prg_decompile.py programs/main.prg
python3 tools/prg_decompile.py programs/main.prg --mode basic
python3 tools/prg_decompile.py programs/main.prg --mode disasm --start 0x1000 --length 256
python3 tools/prg_decompile.py programs/main.prg --mode acme > /tmp/out.asm

File Structure

• index.html - Main HTML file with emulator container
• styles.css - Styling for the retro-themed UI
• app.js - JavaScript code for emulator integration and program loading
• src/ - Source code files
  • src/*.bas - BASIC source (compiled with petcat)
  • src/*.asm - 6502 assembly source (compiled with acme)
• programs/ - Compiled PRG files (generated by CI/CD)
  • programs/main.prg - Compiled program (auto-loaded on startup)
  • programs/programs.d64 - Disk image containing all compiled PRGs (auto-attached in VICE.js)
• lib/ - Local JavaScript libraries (jQuery and JSC64 with all dependencies)
  • lib/assets/ - C64 ROM files (kernal, basic, and character ROMs)
• compile.sh - Local compilation script
• .github/workflows/compile.yml - CI/CD workflow for automatic compilation

All dependencies are stored locally - no CDN required! The C64 ROM files are included in lib/assets/.

Creating Your C64 Program

Method 1: Write BASIC Source Code (Recommended)

1. Edit the BASIC source file in src/main.bas

2. Write your C64 BASIC program in plain text format:

   10 print "WELCOME TO SYS-64738.COM"
   20 for i=1 to 1000:next
   30 goto 10

   Important: Use lowercase keywords (print, for, goto, next, etc.). The petcat compiler expects lowercase keywords for proper tokenization.

3. The program will be automatically compiled to programs/main.prg in CI/CD

4. The compiled PRG will be auto-loaded when the emulator starts

Compiling Locally

To compile the BASIC source locally:

# Install VICE (includes petcat compiler)
# On macOS:
brew install vice

# On Linux:
sudo apt-get install vice

# Run the compiler
./compile.sh

This will compile src/main.bas to programs/main.prg.

Method 1b: Write 6502 Assembly Source (ASM)

1. Add one or more *.asm files under src/
2. CI/CD compiles each src/<name>.asm into programs/<name>.prg using acme
3. In dev.html, you can also assemble and run ASM in the browser (ASM tab). That mode produces a PRG that auto-runs via a tiny BASIC SYS stub.

Method 2: Use Existing PRG Files

1. Place your .prg files in the programs/ directory
2. Load them manually using the "Load Program" button
3. Or name it main.prg to have it auto-load on startup

The program you create will be what users see and interact with when they visit your website.

Emulator

Default emulator is VICE.js (an Emscripten build of VICE) with a JSC64 fallback path kept in place.

• VICE.js (default): ships locally at lib/vice/x64.js and is booted by app.js.

• JSC64 (fallback): loaded dynamically by app.js when selected.

• GitHub: https://github.com/reggino/jsc64

• Demo: https://reggino.github.io/jsc64/

• API: Uses jsc64.loadPrg(url) method to load programs

Switching backends

• Use VICE.js (default): open the site normally.
• Force JSC64: open with ?emu=jsc64 (example: debug.html?emu=jsc64).
• Force VICE.js: open with ?emu=vice.

The selection is remembered in localStorage (sys64738.emu).

Alternative Emulators

If you need to switch to a different emulator:

1. ty64 - Lightweight, native JavaScript (no jQuery)

   • Documentation: https://ty64.krissz.hu/documentation/en/

2. EmulatorJS - More complex setup, supports many systems

   • Requires server headers and data directory
   • Documentation: https://emulatorjs.org/

To switch emulators, update the script tags in index.html and modify the initialization code in app.js.

Notes

• Make sure your C64 programs are compatible with the emulator
• Some programs may require specific C64 configurations
• Test your programs thoroughly before deploying

License

Check the licenses of the emulator libraries you use.