Tutorial by Luca Bordoni, thanks to David Saphier and Allan Turvey
 
It’s suggested to read and understand the tutorials about the AGD character set and the ASM calls before continuing here.
 
Assembly routines inject “special effects” in our AGD projects. Even without being an assembly expert, there could be the need to include external machine code routines such as sound effects, compressed graphics or any other kind of enhanchement, and test the result.
 
As said in the ASM calls tutorial, using ASM values inside our AGD project will cause the program test to crash, because AGD calls the memory address pointed by the ASM values, which should be updated after the project completion. So, when the memory call doesn’t find the routine in that address, or when an imported routine collides with the main AGD kernel, the project will crash.
 
Well, the good news is that it’s possible to store small assembly routines into the memory area reserved to the character set. Then, calling that address through the ASM commands (refer to the ASM calls tutorial), the test phase will work perfectly, either allowing to test the assembly routine!
 
 
WHERE EXACTLY THE ASM ROUTINES HAVE TO BE STORED?
 
As said in the AGD character set tutorial, the chr-set starts with the space character at the address 31232 and lasts 768 bytes (8 bytes multiplied by 96 characters). It’s an usable memory area which won’t collide with the AGD kernel. In most cases, lowercase letters and symbols are unused. So, if we’re ok in using just capital letters and numbers in our project, we just have to choose a memory area to store the assembly (obviously considering the routine length).
 
The red characters in this chart stand for free memory zones…
 

 
…and here’re the memory references (as in AGD version 4.7):
 

 
 
A PRACTICAL EXAMPLE
 
It’s important to stay in the AGD chr-set menu while importing binary data. For example, let’s import a sound-fx binary file made with Dk Tronic’s Sound FX tool at the address 31440. Let’s enter the AGD chr-set menu, then import the 50 bytes binary file. Then, exiting and re-entering the chr-set menu, we’ll notice this changes:
 

 
The weird signs represent the imported binary data, so never change the pixels inside these characters!
 
Let’s write the ASM instructions to call the address 31440 into some event…

…and test the game. No crash, and the sound fx works!
 
The concept is applicable to the top memory area (up to 64767). Using upper memory addresses in the same way, AGD won’t crash; however, saving a project, the chr-set will be included, while the routines stored in high memory have to be saved apart, outside AGD.