AGD Key Location Search Tool - by Mulder 2010

This program is designed to help you add joystick support and re-definable key
options to games made with Jonathan Cauldwell's 'Arcade Game Designer'.

It works by searching for the following code in the game code...

LD A,x
CALL zzzzz

Once it finds such an event in the code, it will display a message with
information about it so that you can look at it and decide if it might be
related to key detection.

First, load in the Search Tool and then insert the tape of your raw AGD game
code.  It should load the code automatically and then display a menu.

Press 1 to start a search.

Now, you'll be waiting a while, so make a cup of tea!

After some time, information will start to appear on the screen...

Address - This is printed in yellow and is the address you need to poke when
setting up joystick controls or new keys.

Value - Preceded with V=, this is the byte value at the address.

Key - Preceded with K=, this is the byte value represented as a Key value.

Routine Address - Preceded with AD=, this shows the address where the CALL jumps
to.

At some point, the screen may get full (you'll see the Scroll? prompt).  It's a
good idea to grab a pen and paper here.  You should know what keys are used in
your game and what they do.  Any time one of these keys appears in the list on
the screen, write down the yellow address, the value of the byte, the function
which the key represents (up, down, left, right, fire, whatever), and the
routine address.

Press enter to continue the search, it will remove the scroll prompt.

When the search is over, it will beep for 5 seconds, then you can press any key
to go back to the menu.

Now, go to the Table of Key Values.

Decide what new keys you want the game to use (they could be 67890 for Sinclair
Joystick or 56780 for Cursor, whatever you like).

Now, write down the values for these new keys next to the functions they will
represent on your piece of paper for every address you noted down.

Find the most common Routine address which is associated with ALL your keys on
your paper and now, note down all the yellow addresses that are associated with
it, they key direction for each one and the new key value for each one.

Stop the Search tool with BREAK.

Now, poke the new values into the yellow addresses.

Test the game.  This can often be done with RANDOMIZE USR 35800, but other start
addresses may be valid depending on the version of AGD you used to make the
game, etc...

Did your new keys work?  Yes?  Then thoroughly test the game to make sure they
work in all situations possible.  If this is the case, your work is done, you
know how to change the controls in your game!

If no, then go back to your notes.  Which Routine address is the next most
common?  Do the same for this address, note down all the yellow addresses that
are associated with it, they key direction for each one and the new key value
for each one.  Now poke all those yellow addresses with their new values, and
start the game again...

Did your new keys work?  Yes?  Then thoroughly test the game to make sure they
work in all situations possible.  If this is the case, your work is done, you
know how to change the controls in your game!

If no, then you can repeat the previous steps for less and less common routine
addresses until the new keys work.

If the game crashes during testing, then it's likely that you've poked a false
positive that has appeared in the list with one of your old keys associated with
it.  Strike off the last set of addresses you poked and don't poke them again.
You'll need to poke all of the other addresses that didn't cause the crash again
after re-loading the game code.


EXAMPLE:

I loaded a game into the tool and did a search

The search turned up these results....

For routine address 37816
45584 left
45595 right
45617 left
45647 fire
45679 right
45745 fire
45777 up
45788 fire

For routine address 37792
47437 up
47518 up
47538 down
47572 right
47638 left
47760 fire

Now, ALL my keys were associated with the routine at 37792, even though that's
not the most common routine.  So, I poked those addresses with new key values
first.

This did not work, so I the poked all the addresses for 37816 as that was the
most common and was at least associated with most of my keys.  This did work, so
I knew that I had found all the addresses I needed to poke.

It's useful to have the old values for the addresses handy, e.g. you will
probably want an option in your game menu that sets them back to normal for
keyboard control after somebody has selected joystick and then wants to play
with keys again.