ZScript Technical FAQ (READ BEFORE POSTING BUGS)

[DarkDragon]

Q: Ack! I'm trying to do something to all items each frame, but ZC acts weird or crashes!

A: Great care must be taken whenever you invoke Waitframe() around pointers. As mentioned here, pointers become stale after each frame, and moreoever there's occasionally even greater subtlety. Consider for instance the following snippet:

int numitems = Screen->NumItems();
while(true)
{
   for(int i=0; i<numitems; i++)
   {
       item it = Screen->LoadItem(i);
       it->X++;
   }
   Waitframe();
}

Can you spot the problem?
Even though I'm refreshing the item pointers each frame, I'm NOT refreshing the number of items on the screen, so if the number of items decreases (say Link picks one up), one of the LoadItem() calls will return a dangling pointer. The fix is simple; just be sure to recompute both the pointers and the number of items each frame:

while(true)
{
   for(int i=0; i<Screen->NumItems(); i++)
   {
       item it = Screen->LoadItem(i);
       it->X++;
   }
   Waitframe();
}

[DarkDragon]

Q: Can I mix ASM and ZScript scripts?

A: Yes, if you're very, very careful.

In general adding ASM scripts in slots unused by ZScript is safe. Just realize that if you write to global or screen registers, you may be writing over values used by some of the ZScript scripts.

After every compilation the full ASM output of the compiler is written to allegro.log, so by inspecting this output you can determine what global variables are being used by ZScript, so that you can avoid (or not avoid!) using them in your ASM scripts.

On the other hand, directly modifying the ASM output of a ZScript compilation requires very, very great care, for several reasons:

1. Almost all of the D registers (currently D0-D6) are reserved as important scratch spaces for things like computing the stack frame offset of local variables, and should not be overwritten by foreign code.

2. ZScript-compiled code is heavily reliant on the stack for storing everything from local variables to parameters of function calls to this pointers. The state of the stack must thus also be preserved by foreign code.

3. Changing the line numbers of ZScript code requires a lot of work verifying that references to those line numbers (in things like GOTO) are modified accordingly. Even more tricky is that line numbers are sometimes indirectly stored in registers, pushed onto the stack, then popped off much later and used as return values via GOTOR.

4. If you ever decide to modify the ZScript code and recompile, you'll of course need to reapply your "patch."