Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
This is an emulator, assembler, and an implementation of the Forth programming language for Notch's DCPU-16. See the README for details.
C Forth Python Objective-C Makefile Shell
branch: sdl

This branch is 25 commits behind master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
emulator
.gitignore
LICENSE
Makefile
README
TODO
colortest.dasm
disasm.ft
font.bmp
goforth
goforth.dasm
goforth.ft
masm
quine.dasm
swapend
toasm
tohex

README

DCPU-16 Playground

This is an emulator, assembler, and an implementation of the Forth programming
language for notch's DCPU-16. See http://0x10c.com/doc/dcpu-16.txt for details,
although that spec is now unofficially superseded. Newer specs are collected
here:
  https://github.com/0x10cStandardsCommittee/0x10c-Specifications/tree/master/MOJANG

There are also a couple of useful scripts for swapping endianness of binary
images and dumping to hex in a format supported by some other emulators.


Quick Start

To build, just run:
  make
To run the goforth interpreter image:
  ./goforth
Other images can be run with:
  ./dcpu blah.img
For options, just try:
  ./dcpu


The Emulator

The emulator is written in C with curses for video display. It's well tested
and has a number of nice options. It builds on both Mac OS and Linux with gcc.

I think it's about as close to the current consensus specs as is achievable
with ncurses. Obviously bitmapped graphics aren't supported, so the LEM-1802
support doesn't support MEM_MAP_FONT or MEM_MAP_PALETTE. (They generate an
emulator warning, but are otherwise silently ignored.) It may be possible to
provided limited palette support, at least on fancier terminals, but it's
not a high priority unless someone asks for it. It's also difficult or 
impossible to fully support the documented key scan codes in curses, since
for example it's impossible to detect presses of shift/control in isolation.

The emulator supports the 'standard' LEM-1802 display, keyboard, and clock.
I'm not sure what other emulators are doing, but this one will refuse to
overflow the interrupt queue: new interrupts will be dropped and the emulator
will break to the debugger on attempted overflow. This seems friendlier than
'catching fire'.

For best colors, run in a terminal with good color support. You may have to
fiddle around to get curses to realize your colors are good. For example, 
try setting
  TERM=xterm-256color
if you're not having any luck. You can use
  ./dcpu colortest.img
to test things out. Apparently ncurses 5 doesn't really support 256 distinct
color pairs (well, it supports 256, but the first pair is reserved). So if
you have ncurses 5 (most Linux distros, it seems), white-on-white will probably
appear as your default terminal colors instead.


goforth

  'i figured i owned just dark skies, and that darkness fit me best.
   go, folks, go forth. trust your brain! trust your body!'

The real fun starts in goforth.dasm and goforth.ft. goforth is an
implementation of the Forth programming language for DCPU-16. There's still
plenty of work to be done, but it's already quite usable. For example, it
contains a built-in decompiler/disassembler and other amenities. (In fact, you
might take a look at the file disasm.ft for an example of some non-trivial code
written in goforth.)

The bootstrapped goforth image should run on any DCPU-16 1.7 emulator with
a compatible display/keyboard. (It'll run on others, too, but won't do much,
although custom images would be quite easy to create...)

The older (DCPU-16 1.1) version of goforth was tested on several other
emulators:
  * Notch's 'official' prototype, from http://dcpu.com/highnerd
    goforth runs correctly in this emulator, and you can play with it
    online here: http://matt.immute.net/files/goforth
    (This gives some evidence that my emulator is in good shape as well!)
  * interfect's dcpu-emu: https://bitbucket.org/interfect/dcpu-emu
    Runs correctly.
  * DCPU Studio: http://badsector.github.com/dcpustud
    Seems to run correctly (with 'use big endian words' and 'use keyboard
    buffer' options), but keyboard input is broken. I get mostly the right
    keypresses, but something about the buffer management is screwy and I
    end up losing sync, having to press keys twice, etc. I don't want to invest
    more time in keyboard compatibility until there's actually a spec.
  * deNULL's web emulator: http://dcpu.ru
    Seems to run correctly here, too, but the keyboard input is significantly
    different (all letters are caps, punctuation doesn't work) so it's a little
    hard to do too much testing.
  * http://0x10co.de
    Again, everything looks good, but keyboard input is (again, but
    differently) broken, so it's hard to do much. And again, I'm going to wait
    for a spec.
I am most interested in hearing whether the new 1.7 version works on other
emulators, but I've been busy updating my own and haven't checked the status
of many other emulators yet. As far as I know, there is not yet any official
1.7-compatible emulator from Notch.
  * http://0x10co.de/hiwhx
    Post-1.7, the keyboard handling is better specified and things look
    very good. There are a couple of fishy things, but I will boldly say
    that they're bugs in 0x10co.de, until I hear otherwise. ;)
  * http://fasm.elasticbeanstalk.com/?proj=rs5s77
    (The link is to a slightly out-of-date goforth image.) This looks very
    good. You won't see a cursor, because it seems to interpret the blink bit
    as "do not show", and it seems slower than it should be, but apart from
    that, everything looks good.
  * deNULL's web emulator: http://dcpu.ru
    As in the case of 0x10co.de, things look pretty good, but signed math
    is broken. It thinks -50/5, 50/-5 and 50/5 are all equal to 50 under DVI.
    DIV does know that 50/5 is 10.

In order to bootstrap the image, I've augmented the DCPU instruction set with 
three new instructions (all in non-basic format):
  img: dump ram to the file core.img, from address 0x0000 to (but not
       including) the address in the 'a' argument. if 'a' is 0, dump the
       entire heap (0x0000 to 0x10000)
  die: exit the emulator
  dbg: enter the emulator debugger
The latter two instructions are only used in special cases and are easily 
avoided. img is needed only to bootstrap the forth image.

ONCE AGAIN, THE BOOTSTRAPPED IMAGE WILL RUN ON ANY EMULATOR.


The Assembler

The assembler (masm) is in Python and has a number of idiosyncrasies. The
syntax has diverged from the consensus DCPU-16 assembler syntax in some
rather pointless ways, and it's quite limited. It works for my purposes,
but I don't recommend that you use it.


Credits

The built-in disassembler includes code from Brian Swetland's DCPU-16 emulator,
see the file disassembler.c for license and copyright info.

Something went wrong with that request. Please try again.