Phoenix 0.02 for TI-85/86 by Patrick Davidson - Internal Documentation                

This is the internal documentation for the game Phoenix.  For information
on using the game, see the file 'PHOENIX.TXT'.  This document explains the
internal workings of the program.  It is mainly intended for people who
want to modify the game.

Since this is a very early version of the game, many of the internal
interfaces and data structures are still quite likely to be changed, so I
have not yet written the internal documentation for them.  However, the
introduction and description of the build process which produces code for
both the TI-85 and TI-86 from a single set of source files.

 _____________________________________ Table of Contents

 1. Introduction ..................................................... 19
 2. The Phoenix-Z80 build process .................................... 52

 _____________________________________ Introduction

Phoenix is free/open source software.  This means that everyone is allowed
to develop modified versions of the game.  Phoenix is now in the public
domain, so it may be used in any way without restrictions.

I chose this for the simple reason of trying to maximize the usefulness of
the program.  This provides many benefits, such as:

1) Allowing people who want to have a slightly different game to make it
   themselves with a minimum of effort.
2) Allowing intermediately-skilled programmers to learn from the design
   of the game.
3) Allowing the more advanced programmers to develop substantially different
   games based on this one more easily than writing new games from scratch.
4) Allowing the program to continue even if I stop supporting it myself.
                           
However, even though several people have talked to me about making such
modified games, nobody has actually released one yet.  To try to make it
easier for people to do that, I am releasing this document which describes
the internals of the game, and have also added many additional comments to
the code itself.

This document only provides an overview of the working of the game.  More
detailed information about specific functions is present in the comments of
the source files themselves.  (That is, it hopefully will be when/if I get
around to putting in more complete comments).

This document assumes that the reader has at least basic familiarity with
programming the Z80-based calculators in assembly.  If you are a complete
beginner, this is probably not the best resource for learning to program the
calculators.

 ______________________________________ The Phoenix-Z80 build process

Both the TI-85 and TI-86 version of the game are built from the same set of
source files.  This is accomplished by using a conversion program, a special
include file for the TI-86, and a few lines of conditionally assembled code
throughout the program.  The TI-85 version is the 'base' version which is
converted to run on the TI-86.

The conversion program 'srcto86' does only two simple tasks:  It removes all
cases of the & symbol used for relocation from source files (going into
#included files also), and also adds the line '#define __TI86__' to the top
of the output.  The program is run with the command 'srcto86 phoenixz.asm
phoenix.asm' to read from phoenixz.asm and write to phoenix.asm.  The
contents of any included files are put into the output file in converted
form; the originals are not changed.  The source code of this program is in
the file 'srcto86.c'.

The special include file 'ti-86.h' is used to simulate the TI-85's features.
First, it contains equates for TI-86 system calls that have the conventional
TI-85 names (that is, the TI-86's _puts is named D_ZT_STR).  This include
file defines all symbols used; it does not include any other files.  It also
includes code to simulate many functions available under Usgard that aren't
readily accessible on the TI-86, such as D_HL_DECI, GET_KEY, OTH_CLEAR, etc.
Note that while Asm86's 'asm86.h' include files does have equates for some of
those functions, many are only valid on ROM 1.2 so the routines really do
need to be rewritten here.  This include file also does partial emulation of
Usgard's interrupt system (supporting only one interrupt).  Finally, this
file provides an OTH_EXIT replacement which does write-back for saved game
and high score data; anything between the labels permanenet_data_start and
permanent_data_end will be written back to the variable.  This file also
provides a typical TI-86 header, setting the start address and providing
title information for shells.

The least elegant technique used is the conditional code, which has been kept
at a minimum.  Mainly, it is used in the main source file to include the
'ti-86.h' file for the TI-86, and otherwise to include 'usgard.h' and set
the program start to 0.  Also, conditional code is used in some places to
conditionally add PROGRAM_ADDR to addressed stored in data tables (in the
places where I thought this would be more convenient than relocating the
addressed themselves).

Supplied with Phoenix-Z80 is the batch file 'build.bat' which will perform
all steps to build the program automatically on DOS-based systems.  It also
builds the distribution archives 'phx85.zip' and 'phx86.zip'.  Look at it to
see how to produce the various files.  Note that it's steps require both
Usgard and Asm86 build tools to be installed, and that it also may be needed
to copy some files such as 'usgard.h' and 'tasm80.tab' into the directory you
are building Phoenix in if the build tools are unable to find these files.
