--------------------------------------------------------------------------------
 COMPILING ZYM
--------------------------------------------------------------------------------

Zym is meant to be compiled with SDCC using SymbosMake by Nerlaska (2007). Zym
was developed using SDCC 4.1; versions of SDCC from 4.1.13 on use the alternate
__sdcccall(1) calling convention which produces more efficient code but is not
(yet) compatible with SymbosMake.

To build, navigate to the directory containing make.ini on the command line and
run SymbosMake.exe. (You will need to adjust the relative paths of the #include
directives in symbio-minified.c to point to the correct folder for SymbosMake.)

Zym includes a "PC" mode which can be enabled by commenting out the line
    #define SYMBOS
in zym.c. This allows Zym to be compiled on gcc/mingw for testing purposes.
(Note that this mode expects an 80x25 terminal which can read ANSI escape
sequences.)

Uncommenting the lines
    #define PROFILER
    #define TRACE
provide other debugging functions, although there is no guarantee that these
will necessarily work or provide useful output.

UNDO can be disabled by commenting out the line:
    #define UNDO
This is mainly useful for freeing up a little space in the executable.

The size of the lowmem buffer can be adjusted by changing
    #define LOWMEMSIZE 0x6000
    #define LOWMEM_HIGHBYTE 0x60
to the appropriate sizes. Note that LOWMEMSIZE must be a multiple of 0x2000 and
that LOWMEM_HIGHBYTE must == LOWMEMSIZE >> 8.

--------------------------------------------------------------------------------
 OPTIMIZATION
--------------------------------------------------------------------------------

While SDCC is an optimizing compiler and generates decent code, there are a few
major targets for optimization. These have all been rewritten to generate
quicker code, but could be improved further by rewriting them in assembler:

- The instruction parsing routines at the start of execute_instructions().
- read8() - already assembler, but used multiple times by every instruction.
- branch() - used by ~40% of executed instructions in a typical Inform game.
- property_address() - expensive loop, ~5% of inst. in a typical Inform game.
- add_to_parsebuf() - expensive loop, mainly slows down command parsing in
                      games with a very large vocabulary.
					  
Contrary to what one might assume, read16(), write8(), and write16() are called
20-50x less often than read8() and are not a major target for optimization.

Slow routines in Z-code files may be found by using the #define TRACE option
and consulting a disassembly of the story file (use txd with the -n option to
give hex addresses). Typically you will find that these routines are some sort
of search loop which is slow just because it is running a lot of instructions.

Idea that hasn't yet been tried: rewrite the output messaging routines so that
Zym doesn't idle (i.e., Message_Sleep_And_Receive) every time it sends a string
to the shell, only when it needs to send another string before SymShell has
finished with the first one. This would theoretically allow Zym to keep running
in the background and marginally improve performance during text output.