VMU development

From dreamcast.wiki
Jump to navigation Jump to search
Various different faces of the VMU

Developing standalone games for the Sega Dreamcast's VMU (also known as VMS) is both a challenging and rewarding development feat. On one hand, it's not the easiest embedded device to target, given that it doesn't have a C compiler and has its own set of hardware eccentricities. On the other hand, the device features a rich instruction set, 3 different clock sources, a FAT filesystem, and many different peripherals which can be leveraged by a developer, making it something of a Sega Saturn of little 8-bit gaming devices.

While there is an active and ongoing effort within the scene to lower the barrier of entry into VMU development and to get more high-quality tutorials and materials out there for newbies, this page will hopefully serve as an entry point based on what is currently available.

Hardware

VMU's multiple segmented and banked address spaces
VMU System Block Diagram

A high-level overview of the VMU's technical specifications can be found here. A good initial look at application-development for the device can be found at Marcus Comstedt's VMU Programming Site. A combination of this site and the official VMU Development Manual is typically what is referenced while programming for the VMU. Between the two, a developer should have all of the hardware documentation necessary to cover the following concepts:

  • Address Spaces, memory segments and banks
  • Opcodes and instructions
  • Addressing modes
  • System vs application execution
  • Built-in firmware routines
  • Special Function Registers (SFRs)
  • Interrupt service routines and their configuration
  • Controlling clock and oscillator circuits
  • Driving the LCD display by writing to XRAM
  • Reading/Writing to extra Working Memory (WRAM)
  • Controlling the Base Timer, and 2 Timer/Counter peripherals
  • Driving the piezoelectric Buzzer for sound output
  • Detecting button presses on Port 3
  • Low-battery detection circuit and configuration
  • Serial communications via the 2 SIO interfaces

Programming

Since there is no C compiler for the VMU's 8-bit Sanyo CPU, development is traditionally done in Sanyo LC86k assembly language; however, it is now also possible to write C code indirectly targeting the device via emulation of the ARM Cortex M23 CPU.

C

Thanks to the uM23 emulator, it is now possible to indirectly write C code for the VMU. The code is cross-compiled for the ARM Cortex M23 target, and the resulting binary image is then loaded onto the VMU as a "DATA" file. The uM23 emulator, which must be loaded onto the device as the main "GAME" file, will then allow you to select an ARM binary image to run from its menu. More information can be found here.

LC86k Assembly Code

waterbear

The waterbear assembler/disassembler is the favored tool for creating VMU binaries, as it is cross-platform, is feature-rich, supports all undocumented opcodes and SFRs, and is still under active development.

LibPerspective

Due to the non-contiguous, banked nature of XRAM, it is actually a nontrivial engineering feat to blit an image to the LCD screen. LibPerspective is a simple rendering library developed to aid in such tasks. It is frequently used in modern VMU homebrew and will enable you to work with rendering bitmaps to the display much more quickly. More information can be found here.

VMS Tetris
Marcus Comstedt's "VMU Tetris"

The source code to Marcus Comstedt's VMU version of Tetris serves as a a great beginner resource, as it is well-commented and is a fairly complex game. The source code can be found here.

Audio Driver (ADVM)

jvsTSX has released an audio driver called ADVM open source on github. This is some pretty advanced buzzer usage with well-written code including comments, most likely the deepest the homebrew scene has gone with this peripheral. Definitely something to be checked out for doing any sort of audio signal generation on the device.

Tiny3D Engine
Tiny3D Engine in Action

Tiny3D Engine is a full-fledged 3D rendering engine, complete with OpenGL-style matrix stack, matrix/vector transformations, perspective matrix and division, line rendering and clipping, and 16-bit fixed point math routines. It was developed by The Rockin'-B and was originally released as a demo ROM featuring the engine with a menu that allowed for the configuration of the underlying 3D primitive and transformation matrix. The ROM and full source code can be found here.

Scrolling Text Demo

The source to a scrolling text tech demo by VirtuaMUnstaz can be found here: File:Scrolling Text Tech Demo.zip.

Raining Squares

Raining Squares is a tech demo which serves as a great example for newbies to the platform. More information can be found here.

Skeleton Application

The code for an example skeleton VMU application by Tyro can be found here: File:Skeleton VMU Application.zip

VMU Racketball
VMU Racketball Screen Capture

VMU Racketabll is an open-source VMU minigame developed by pxcla (Shirobon), which has been made available on github. It contains fantastic comments and has been developed with the intention of serving as a kind of tutorial/learning tool for VMU developers as well.

Advent Wreath

Advent Wreath is a VMU application developed by Marble_Granite, that was released to commemorate the 24th anniversary of the Dreamcast and the 1st day of Advent. It demonstrates button input, impressive animations, and grayscale effects. Its source code can be found here.

Official Demos

An assortment of (older) tools and demos adapted from the official documentation has been compiled by frozenbinarystudio from the DCEmu forums and is available here: File:VMU Development Resources.gz

VMU Script

A long-lost and forgotten VMU-specific pseudo scripting language which was around at the time of the Dreamcast's commercial lifespan and was used in at least one shipping commercial game. Unfortunately the language and tools have been lost to time.

These pages that were saved in the Wayback Machine appear to be the only bits of VMUScript left on the internet:

LIME

Dream Animator Tool for creating VMU Animations

Another lost VMU-specific language. Again, there are some pages preserved in the Wayback Machine:

Dream Animator

While not technically code or a programming language, the VMU Animator tool allowed for the easy creation of VMU animations or movies. These animations could then be exported to a VMS GAME file which could then be played on the actual device. Many of these animations are circulating around today, and the Booyaka website was an entire community based around them. Unfortunately the tool is rather dated and may not run under modern Windows. It can be found here: File:VMU Animator.zip. Note that the ElysianVMU emulator can play the intermediate .LCD files but cannot create or modify them.

DC Anim

DC Anim is another tool that allows you to edit and create your own VMU animations, supporting the same file format used by Dream Animator. It is available both as a Windows XP binary and as the source code.

BMOVIE

BMOVIE Promo

BMOVIE was an incredibly ambitious, technically impressive video encoder for the VMU, created by a homebrew VMU and Sega Saturn developer who went by "Rockin-B." It could create highly compressed animations for the device which could be exported then embedded into other applications. It supported extremely long animations, playback in reverse, and later on emulated grayscale effects via pixel ghosting. While it unfortunately seems as though the actual encoder tool, playback code, and documentation are lost to time, several tech demo videos still survive today as ROMs which prove it was more than just a myth. Rockin-B has since disappeared from the VMU and Saturn scenes without a trace, and any attempts to contact him have been in vain. What's left of his site can be found here.

Testing

Emulators

ElysianVMU's Flash Editor and Filesystem Manager

The favored emulator for VMU development and testing is the ElysianVMU emulator, as it is cross-platform, is ranked top for features and accuracy, and is still actively developed. The emulator also has an explicit goal of offering a debugging environment to facilitate development. Much of the debugger is still under active development; however, just features like the RAM and flash memory explorer widgets can be of great use during development. More information on EVMU as well as other VMU emulators can be found here.

Physical Device

Before publishing or distributing your game, it is highly recommended that you still test on physical hardware. There are various ways through which one can get a GAME file onto the actual device depending on your Dreamcast's configuration and peripherals.

  • VMU Tool (AKA Dream Explorer)
  • DreamShell
  • Web Browser
  • Nexus Memory Card
  • KOS VMU Game Loader Example

Tips and Tricks

Grayscale Graphics

Several VMU games emulate grayscale graphics by alternating a pixel between black and white, where the resulting shade of gray that is produced is a function of the alternation frequency. This is possible due to the physical hardware characteristics of the LCD screen, as a pixel is not instantaneously lit, but rather has a small "fade-in" period. The ElysianVMU emulator attempts to emulate this behavior with the "pixel ghosting" option.

Unconstrained Flash Access

While the BIOS-provided flash operations constrain reads and writes to within the boundaries of the GAME file, it is possible to write and read directly to and from flash using the STF and LDF undocumented VMU instructions (supported by Waterbear) respectively. These instructions are what the BIOS uses to implement the higher-level firmware calls. Several homebrew games and applications have leveraged these to access other files stored within the VMU. One example is Dmitry's uM23 emulator using LDF to read ARM binaries as separate "DATA" files on the same filesystem.

USB-Powered VMU Mod

If you're constantly finding yourself in need of replacement CR2032 batteries during development, consider doing the USB Powered VMU Hack on a spare VMU.

Sublime Text Syntax Definition

A syntax Sublime Text syntax definition for the LC86k assembly flavor, including instructions and SFRs can be found here. This makes Sublime Text a pretty decent development environment for working with VMU assembly.

Community

If you have any questions, want to share your work, would like to contribute in any way, or would like to hang out with a community of other people interested in VMU and Dreamcast development, try the following links:

  • DCEmulation Forums - One of the biggest, most prolific Dreamcast web forums, with a technical goldmine of information
  • Simulant Discord - The main hangout spot for Dreamcast developers within the scene
  • Elysian Shadows Discord - A smaller hangout for DC developers with many VMU-focused developers, including the authors of WaterBear, ElysianVMU, and uM23

References

Retrieved from "https://dreamcast.wiki/wiki/index.php?title=VMU_development&oldid=2563"