DynoSprite README ----------------- DynoSprite is a sophisticated, object oriented game engine for the TRS-80 Color Computer 3, written in 6809 assembly language. The build system runs on a modern computer to compile, assemble, and package a final disk image which can be loaded into an emulator or copied onto a physical disk for running on a real CoCo 3. The resulting CoCo program requires a 512K Coco 3 with a disk system (either 5 1/4" floppy drive, or CoCo SDC card, or CoCoNET ROM Pak, or similar). README Sections 1. Requirements and Pre-requisites for building DynoSprite 2. Building the DynoSprite Demo 2 Project 3. Other Documentation 4. Getting Started 1. Requirements and Pre-requisites ---------------------------------- The following software packages are required in order to build a DynoSprite project: - GNU Make - GCC compiler - Python 2.x - lwasm (available from: http://lwtools.projects.l-w.ca/) - ffmpeg (available from: https://www.ffmpeg.org/) or sox (available from: http://sox.sourceforge.net/) - MAME/MESS (optional, available from: http://mamedev.org/) * Linux Build Instructions * 1. Install the development tools (Make, GCC, Python) and ffmpeg 2. Download and build lwtools from the provided web link 3. Copy the 'lwasm' binary program into the tools/ folder of DynoSprite 4. (Optional) Install or build the MESS emulator, and copy the binary into the tools/ folder of DynoSprite. Make sure that it is named 'mess64' 5. Run 'make all' from the root folder of DynoSprite. This will produce a disk image file called 'DYNO6809.DSK' in the same folder as the makefile. 6. (Optional) Run 'make test' to start the MESS emulator with the disk image * Windows Build Instructions * The easiest way to build the DynoSprite engine under Windows is by using either one of the Cygwin or MinGW development environments, which may be downloaded here: https://www.cygwin.com/ http://www.mingw.org/ The usage and configuration of these environments is beyond the scope of this README file, but the general steps for building DynoSprite once the build environment has been set up are the same as for Linux. * OSX Build Instructions * OSX has undergone significant changes in recent years, so the steps for installing a suitable build environment for DynoSprite depend upon the OSX and XCode versions installed. If you have XCode 4.x or earlier, you can install the XCode Command-line tools. These should include GNU Make and GCC, and there should be a system-wide Python interpreter already installed from OSX. You can then install FFMPEG from a DMG package on the ffmpeg.org site and continue with the instructions for building under Linux. If you have XCode 5.x or newer, then you cannot get a GCC compiler from Apple. You could either modify the DynoSprite and lwtools makefiles to use 'clang' instead of GCC, or instead install GCC and GNU make from the Mac Ports project: https://www.macports.org/ Macports can also be used to install ffmpeg. After installing the necessary pre-requisites, continue with the Linux build instructions. 2. Building the DynoSprite Demo 2 Project ----------------------------------------- Type 'make' by itself to view all available build options: $ make DynoSprite makefile. Targets: all == Build disk image clean == remove binary and output files test == run test in MAME Build Options: RELEASE=1 == build without bounds checking / SWI instructions SPEEDTEST=1 == run loop during idle and count time for analysis VISUALTIME=1 == set screen width to 256 and change border color CPU=6309 == build with faster 6309-specific instructions Debugging Options: MAMEDBG=1 == run MAME with debugger window (for 'test' target) Special notes about audio conversion: - if you encounter errors from 'ffmpeg' during the audio conversion step, you may choose to use 'sox' instead of 'ffmpeg' by replacing the command in step 10 of the makefile with the following command: sox $< -r $(AUDIORATE) -c 1 -u -1 $@ Special notes about build targets: - 'make all' will build a file called DYNO6809.DSK, while 'make all CPU=6309' will build a file called DYNO6309.DSK - 'make test' will run the MESS emulator with the 6809 disk image. You must use 'make test CPU=6309' to run with the 6309 disk image. - 'make clean' will not delete either disk image, but will delete all other build products. Special notes about build options: - Release builds will be slightly faster than debug builds, by eliminating bounds checking. You can also include debug code in your game-specific assembly source code, using the 'IFDEF DEBUG' / 'ENDC' macros. - The SPEEDTEST option can be used to gather precise debugging data by measuring the number of idle CPUs cycles spent waiting for the next vertical retrace interrupt after a frame has been drawn. To use this: 1. Make a build and examine the list file: "build/list/dynosprite-pass2.lst" 2. Find the address of this line in main.asm: jsr Gfx_SpriteEraseOffscreen 3. Start MESS with 'make test MAMEDBG=1'. Set a breakpoint at the address found in step 2, using a command like: "bk $XXXX" 4. Press F5 to start and run the game until it breaks in the main loop. 5. Keep pressing F5 to generate each new frame, and observe the values in the registers. A and B will contain the (signed) distance in bytes (horizontal, A register) or rows (vertical, B register) with which the background plane was scrolled during the last frame redraw. X will contain the number of idle loop iterations which occurred before the vertical retrace interrupt was triggered. This loop is 15 CPU cycles long for the 6809 build, and 14 CPU cycles long for the 6309 build. The total number of CPU cycles in each 60Hz video field is 29,860. - The VISUALTIME option can be used to see a visual representation of the timing characteristics of your game. When this option is enabled, the 256x200 graphics mode is used instead of 320x200, and the border color is used to show when the game's main loop is busy. During the first 60hz video field when a new frame is being drawn, the border color will be blue while the game is processing and/or drawing, and black while in the idle loop, waiting for the next vertical retrace. If the game engine doesn't finish drawing a new frame within one 60hz video field time, then the border color will change to green. If the engine is still not finished when the 3rd video field time begins, the border color will be changed to red. So if you only see blue and black in the border, then your game should be running at 60hz all of the time. If you see green border, then you are dropping to 30hz for some frames, and if you see red then you are dropping to 20hz. 3. Other Documentation ---------------------- The doc/ folder contains the following additional documentation files: AddressMap.txt - CPU/GIME 8k block mappings during various operations in the DynoSprite engine, plus order and contents of data stored on heap Benchmarks.txt - Various benchmarking data gathered during development DynoSpriteUsage.txt - How DynoSprite works, and how it can be used to build a game Todo.txt - Notes regarding various features and enhancements which may be added in the future 4. Getting Started ------------------ To get an overall understanding of how DynoSprite works, and how an author can use DynoSprite to build his or her game, read the DynoSpriteUsage.txt guide and follow the instructions included within.