-
Notifications
You must be signed in to change notification settings - Fork 6
/
Copy pathREADME
168 lines (137 loc) · 7.79 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
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.