Code Monkey home page Code Monkey logo

coco3java's Introduction

Yet Another Color Computer 3 Emulator

GitHub Workflow Status Coverage Status Dependency Status License: MIT

Table of Contents

  1. What Is It?
  2. License
  3. Compiling
  4. Running
    1. Specifying a System ROM
    2. Trace Mode
  5. Cassette Tapes
    1. Reading
    2. Writing
  6. Disk Drives
    1. Loading a Disk Image
    2. Saving a Disk Image
  7. Configuration File
  8. Keyboard
    1. Emulated Keyboard
    2. Pass-through Keyboard
  9. Current Status

What Is It?

This project is a Color Computer 3 emulator written in Java. Note that I cannot distribute ROM files with the emulator, as they are copyright their respective owners.

The Color Computer 3 is the third incarnation of the Tandy Radio Shack Color Computer line (TRS-80). The CoCo 3 offered several improvements over the original CoCo 1 and CoCo 2, most notably the introduction of a memory management unit (MMU) and a new Advanced Color Video Chip (ACVC) - also known as the Graphics Interrupt Memory Enhancer (GIME).

While the official name of the computer was the TRS-80 Color Computer 3, the Color Computer family was quite different from the line of business machines such as the TRS-80 Model I, II, III, and 4. While that family of computers used a Zilog Z80 microprocessor, the Color Computer family used a Motorola 6809E processor running at 0.89 MHz.

License

This project makes use of an MIT style license. Please see the file called LICENSE for more information. Note that this project may make use of other software that has separate license terms. See the section called Third Party Licenses and Attributions below for more information on those software components.

Compiling

You will need a copy of the Java Development Kit (JDK) version 8 or greater installed in to compile the JAR file. I strongly recommend using an open-source licensed JDK build (GPL v2 with Classpath Exception), available at https://adoptopenjdk.net and install OpenJDK 8 or OpenJDK 11.

To build the project, switch to the root of the source directory, and type:

./gradlew build

On Windows, switch to the root of the source directory, and type:

gradlew.bat build

The compiled Jar file will be placed in the build/libs directory.

Running

For the emulator to run, you will need to have the Java 8 Runtime Environment (JRE) installed on your computer. See Oracle's Java SE Runtime Environment Download page for more information on installing the JRE. Alternatively, you can use OpenJDK.

Simply double-clicking the jar file will start the emulator running. By default, the emulator will be in paused mode until you attach a system ROM to it. You can do so by clicking ROM, Load System ROM. You can also specify what ROM file to load via the command line (see Specifying a System ROM section below on how to specify a ROM on the command-line, and the Configuration File section below on how to create a configuration file so you don't have to specify the system ROM each time you start the emulator).

Specifying a System ROM

The system ROM refers to the basic operating system of the machine. Usually this is a Super Extended Color Basic ROM, or a cartridge ROM. The syntax to specify the system ROM is as follows:

java -jar build/libs/yacoco3e-1.0-all.jar --system /path/to/rom/file.rom

See the section on Configuration File for more information on how to create a configuration file so that you don't have to specify ROM files or switches on the command-line.

Trace Mode

It is possible to have the emulator provide a full disassembly of what is running as the emulator is running it. Note however that the speed of the emulator will be significantly slower:

java -jar build/libs/yacoco3e-1.0-all.jar --trace

Cassette Tapes

Reading

The emulator can read standard CAS files. To load a cassette file into the input buffer, click on the menu item Cassette, Open for Playback. You will be prompted to browse to a location on your computer where the cassette file is located. You can then issue CLOAD or CLOADM commands as usual in the emulator window.

You can also attach a cassette tape file to the emulator on startup with the following:

java -jar build/libs/yacoco3e-1.0-all.jar --cassette /path/to/cas/file

See the section on Configuration File for more information on how to create a configuration file so that you don't have to specify ROM files or switches on the command-line.

Writing

To write to a cassette file, you must first create a new cassette file. You can do this by clicking the menu item Cassette, New Cassette File. You will be prompted to create a new file on your computer where the cassette file contents will be saved.

Once the cassette file has been created, you can perform a CSAVE or CSAVEM as usual in the emulator window.

Once you have performed a CSAVE or CSAVEM, you must then flush the contents of the tape buffer to the actual file. You can to that by clicking the menu item Cassette, Flush Buffer to File.

Disk Drives

The emulator has built-in support for disk drive systems, however, it requires a Disk Basic ROM (1.0 or 1.1) to be loaded into the cartridge slot on the emulator with the --cartridge switch:

java -jar build/libs/yacoco3e-1.0-all.jar --cartridge /path/to/disk/basic/rom

Four virtual disk drives are available by default (drive numbers 0-3).

See the section on Configuration File for more information on how to create a configuration file so that you don't have to specify ROM files or switches on the command-line.

Loading a Disk Image

The emulator currently supports reading JV1 style disk images from the host computer. To load a disk image, click on the menu item Disk Drives, select the drive number you want (Drive 0, Drive 1, Drive 2, or Drive 3), and then select Load Virtual Disk. You will be prompted to select a location on your computer where the disk file will be loaded from. You can then use the disk associated with the drive you selected. For example, DIR 3 will list the directory contents of the disk in drive 3, while LOADM"2:EDTASM.BIN will load the Edtasm binary from drive 2.

Saving a Disk Image

The emulator currently support writing JV1 style disk images to the host computer. To save a disk image, click on the menu item Disk Drives, select the drive number you want (Drive 0, Drive 1, Drive 2, or Drive 3), and then select Save Virtual Disk. You will be prompted to select a location on your computer where the disk file will be saved to. Once entered, the contents of the drive will be saved to the virtual disk file, and can be loaded from the host computer in a future session.

Configuration File

The emulator allows you to create a simple configuration file so that you do not have to specify arguments on the command line. The configuration file is in YAML format, and supports the following keys:

  • systemROM - the full path to the ROM file to be used as the system ROM (e.g. Super Extended Color Basic ROM file).
  • cartridgeROM - the full path to the ROM file plugged into the cartridge (e.g. Megabug).
  • cassetteROM - the full path to the ROM file used in the cassette recorder.
  • drive0Image - the DSK image to be used in drive 0.
  • drive1Image - the DSK image to be used in drive 0.
  • drive2Image - the DSK image to be used in drive 0.
  • drive3Image - the DSK image to be used in drive 0.

Leaving any one of the keys out will result in the emulator ignoring that particular ROM image. An example YAML configuration file that specifies ROMs to use for the system, cartridge slot, cassette, and drive 0 is as follows:

systemROM: "C:\Users\basic3.rom"
cartridgeROM: "C:\disk11.rom"
cassetteROM: "C:\Users\zaxxon.cas"
drive0Image: "C:\megabug.dsk"

If you start the emulator without command-line arguments, it will look for a configuration file named config.yml in the current execution directory. This means you can just run the jar file or double click it without specifying anything at the command-line. If you want to specify a different configuration file to use, you must pass the --config option on the command-line:

java -jar build/libs/yacoco3e-1.0-all.jar --config "C:\Users\my-emulator-config.yml"

The order in which the emulator will attempt to interpret ROMs is:

  1. Command-line specified ROMs (e.g. the --cartridge switch)
  2. Command-line specified configuration file (e.g. with the --config switch)
  3. Looking for config.yml in the current directory

If none of the options above result in any valid ROMs to use for the system ROM, then the emulator will start, but will be in a paused mode. You can then attach ROM files manually using the menu system.

Keyboard

There are two different types of keyboards that the emulator supports.

Emulated Keyboard

The emulated keyboard will attempt to map multiple keystrokes into their corresponding Color Computer 3 key presses. This means for instance, if you type a " (double-quote) character on your keyboard, it will mimic pressing SHIFT-2 on the Color Computer 3 keyboard (which corresponds to the double-quote character).

The emulated keyboard maps just about every multi-key keypress to a proper Color Computer 3 counterpart. There is a single difference noted below:

CoCo 3 Key Keyboard Combination
BREAK ESCAPE

The emulated keyboard is enabled by default, as it provides a more natural mapping from a contemporary keyboard to the Color Computer 3 keyboard. This behaviour however, may cause problems with programs that rely on certain other keyboard presses and combinations. In which case, you may wish to use a pass-through keyboard setting (see below).

To switch to the emulated keyboard if it is currently not enabled, click on the menu option Keyboard, Emulated Keyboard. The option will have a selected icon next to it if it is enabled.

Pass-through Keyboard

The pass-through keyboard will not attempt to interpret multiple key presses. Instead, it will pass on key combinations as pressed on the keyboard. For instance, pressing SHIFT-2 will literally pass on SHIFT and 2 as the keyboard combination, and will ultimately produce a double-quote character ". For those who are not familiar with the Color Computer 3 layout, this behaviour may be confusing, as key combinations on a contemporary keyboard are not the same as on the Color Computer 3. The differences are noted below:

CoCo 3 Key Keyboard Combination
! SHIFT-1
" SHIFT-2
# SHIFT-3
$ SHIFT-4
% SHIFT-5
& SHIFT-6
' SHIFT-7
( SHIFT-8
) SHIFT-9
= SHIFT--
+ SHIFT-:
: '
* SHIFT-'
@ ALT
BREAK ESCAPE

To switch to the pass-through keyboard if it is currently not enabled, click on the menu option Keyboard, Pass-through Keyboard. The option will have a selected icon next to it if it is enabled.

Current Status

Below are a list of items that are currently working:

  • Can run a Super Extended Color Basic ROM
  • 6809 CPU full instruction set
  • 512K physical memory
  • Semigraphics Mode SG4, SG6, SG8, SG12, SG24
  • Graphics Modes G1C, G1R, G2C, G2R, G3C, G3R, G6C, G6R
  • Keyboard
  • ROM/RAM Mapping
  • MMU Task PARs ($FFA8 - $FFAF)
  • MMU Executive PARs ($FFA0 - $FFA7)
  • Vertical Offset Registers ($FF9D, $FF9E)
  • INIT 1 Register ($FF91)
  • SAM Display Offset Registers ($FFC6 - $FFD3)
  • SAM TY Bits ($FFDE, $FFDF)
  • SAM Mode Registers ($FFC0 - $FFC5)
  • SAM R1 Clock Speed Bits (FFD8, FFD9)
  • VDG Register ($FF22)
  • Cassette tape interface
  • IRQ Interrupts (both PIA and GIME)
  • Disk drive sub-system
  • Disk GUI interface for loading virtual disks
  • Disk GUI interface for saving virtual disks
  • JV1 style virtual disk drive support

Yet to be implemented:

  • JV3 style virtual disk drive support
  • DMK style virtual disk drive support
  • High resolution text modes (40, 64, 80 columns)
  • High resolution graphic modes (192, 200, 255 x 64, 80, 128, 160, 256, 320, 512, 640)
  • Video Resolution Register ($FF99)
  • Border Color Register ($FF9A)
  • Vertical Scroll Register ($FF9C)
  • Horizontal Offset Register ($FF9F)
  • Palette Registers ($FFB0 - $FFBF)
  • FIRQ and NMI interrupts
  • PIA2 interface
  • Sound

coco3java's People

Contributors

craigthomas avatar dependabot[bot] avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar

coco3java's Issues

Improve NTSC artifact colors

The emulator currently takes a fat pixel approach to emulating artifact colors. It performs a very rough approximation of whether to draw a red or blue pixel depending on the alternating patterns of black or white. While this does the job of incorporating colors into the display for artifact color modes, it appears blurry (the transition between colors in a true NTSC display would be more gradual with better gradation between pixels). The purpose of this enhancement is to generate a better drawing method that takes into account how NTSC artifacting works.

Add status bar for CPU clock rate and other information

Other emulators have a handy status bar near the bottom of the emulated window that display helpful status information such as CPU clock rate, mounted disk images, mounted tape images, and others. This would be a useful addition to the emulator as it would let you see at a glance what configuration is currently in use.

`PSHU` and `PULU` push and pull U instead of S

In a PSHU and PULU, the U register is pushed or pulled instead of the S register. This is causing strange behavior with any applications or games that make use of PSHU and PULU where the S register is meant to be saved instead of the U register.

Add execution limiter to the main execution loop

The emulator currently counts the number of ticks that each instruction takes when it is executed by the CPU. However, the number of operations per second are in no way limited to the number of operations that could be executed by an actual physical Color Computer 3. The purpose of this issue is to add an instruction execution rate limiter that would temporarily halt executing CPU instructions if the number of ticks surpasses what a real hardware CPU would be able to execute in the same time frame.

The way to achieve this goal is as follows:

  • Create a new variable in the Emulator class called remainingTicks that keeps track of how many ticks can be executed for the duration of the cycle.
  • Create a new function called refreshTicks in the Emulator class that restores remainingTicks to the correct number of ticks that can be run in a given cycle.
  • Run the refreshTicks function within the TimerTask.
  • In the main Emulator.run() method, a check should be performed before executing an instruction. If remainingTicks is greater than 0, then the instruction can be executed. If not, skip executing the instruction.

Cartridges fail to load on startup

When a cartridge is configured in the cartridgeROM option for the configuration file, it does not automatically start when the emulator is started.

Add control for NTSC artifacting

With certain graphics modes, NTSC artifacts generate more colors than were actually available on the Color Computer series. This is the case for the G6R mode, where only two color choices were available - black and white. With NTSC displays, the timing of the screen refresh led to certain pixel combinations of alternating black and white patterns to be displayed as red and blue instead. The emulator currently supports displaying NTSC artifacts when in this mode as a fat pixel approximation of how they would appear. However, it is possible to turn this behavior off entirely so that only the black and white pixels are displayed. The purpose of this feature request is to add a control to the emulator window that will allow the user to switch this behavior.

Tie CPU clock cycles to IOController

Now that there is a mechanism to limit the CPU clock cycles, it should be tied to the proper IO address in memory so that the high-speed pokes will work with the emulator. The following IO address ranges control clock cycles:

  • $FFD9 - poking a value here will set the clock rate to 1.78 MHz
  • $FFD8 - poking a value here will set the clock rate to 0.895 MHz

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.