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
    OBJPAGES=1     == num of pages to use levels and objects
    OBJPAGEGUARD=0 == num bytes to reserve at top of each object code page
  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.