Tutorial by Luca Bordoni, thanks to David Saphier and Allan Turvey
 
This tutorial requires a bit of assembly basics, it’s at least important to know the meaning of the PEEK and POKE commands in Basic and how the ASM calls work in AGD. It’s suggested to read and understand the tutorials about the ASM calls and Store ASM into AGD character set before continuing here.
 
 
READ/WRITE MEMORY DATA USING AGD
 
Every time an AGD game starts, the values stored in all variables, including LIVES and SCORE, are resetted. There’re just two circumstances to consider:
 
– the game ends after loosing all lives (lost game event);
– the game ends in victory (completed game event).
 
In the first case, the reset is ok. Instead, in case of victory, there could be the need to retrieve some variables if the game has to continue (e.g. residual lives and score). Since AGD doesn’t consider this recovery, it’s possible to “hang” some variables into memory locations and do the magic.
 
 
SOME ESSENTIAL CONCEPTS
 
ASM 62
It reads a single byte (0 to 255) declared by the next ASM, storing the value into the accumulator.
Assembly equivalent: LD a,N
 
ASM 58
It means “PEEK” (read) the byte stored into a memory address declared by the next couple of ASM commands (because a memory address is greater than 255), storing the byte into the accumulator.
Assembly equivalent: LD a,(NN)
 
ASM 50
It means “POKE” (write) into the memory address declared by the next couple of ASM commands, a byte previously stored into the accumulator (e.g. through an ASM 62 or ASM 58 command).
Assembly equivalent: LD (NN),a
 
 
GLOBAL VARIABLES REFERENCES IN AGD 4.7

So, the instruction “LET LIVES = 3” is equivalent to this sequence of ASM commands:

 
 
RECOVER REMAINING LIVES AFTER A VICTORY
 
The LIVES variable is usually managed in the game initialisation and kill player events. The residual value has to be handled just in case of victory, so the events involved will be the game initialisation and the completed game.
 
In the completed game event we’ll read the byte stored in the reserved LIVES memory address. Then the value will be copied in a custom free memory address. Just for test purposes, let’s choose the last usable address 64767. Now take in mind that:
 
– when all lives are lost, the byte stored in the address 64767 will be equal to zero;
– as long as the game continues, the LIVES value (and the byte stored in high memory) will be greater than zero.

Next step, in the game initialisation event, we need to detect if the play comes from a previous victory, holding the recovered LIVES value; otherwise, the lives have to be resetted.

 
 
RECOVER THE SCORE AFTER A VICTORY
 
As said, the SCORE variable stores a sequence of six ascii characters, without handling a real number format. The six bytes are stored from 34495 to 34500 and each one represents the ascii value for a character number.
 
Every time a new game starts the SCORE is resetted to zero by AGD in this way:
 
34495, 48
34496, 48
34497, 48
34498, 48
34499, 48
34500, 48
 
The number 48 is the ascii correspondence for the “0” character (find all the ascii values in the Basic Programming manual, Appendix A).
 
If we need to continue a play after a victory the score has to skip the reset by AGD; let’s explain how.
 
It’s possible to recover each byte from the above addresses using the same method explained for the LIVES variable, or using an assembly routine which does the magic. The following assembly code was written by the brilliant Allan Turvey. Few lines of assembly code to fullfill a double task:
 
– store the six bytes in high memory;
– restore them again into the SCORE addresses skipping the default reset at the game start.
 
The routine can be stored directly into the AGD character set. This is the assembly, including the comments explaining the steps:

 
 
SCORE RESET
 
AGD doesn’t allow to reset the score through a specific instruction. Having implemented the above “score recovery” special routine, it’s also needed to reset the values if the game ends.
 
Here’s a simple routine by Allan Turvey to save in the chr-set and call from the game initialisation event:

So here’s how the completed game and game initialisation events should finally look:

If we’re ok using the AGD character-set to store the score routines, download the binary file directly from here, then just inject the bin file into the AGD character-set.
Exit from the charset menu and re-enter, the changes will look like this:
 

 
Now all we have to do is to call the routines from the events, as explained.