Set.priority
The set.priority command sets an object's priority, and disables automatic priority assignment.
Syntax
set.priority(obj oA, byt PRI);
Remarks
The default behavior for screen objects is to automatically assign priority based on position. The set.priority command sets screen object oA’s priority to PRI and disables the automatic priority assignment.
To change the screen object back so the priority is automatically updated based on the object’s position, use the release.priority command.
Valid values for PRI are 3 - 15, with the following considerations:
- If PRI is 15, in addition to having a static priority value of 15, the screen object will also ignore all control lines and blocks.
- If PRI is less than 3, the object will not be drawn on the screen, as these values correspond to control lines and are not actually priority values; the object will still exist; it can still move about the screen, and it will cause collisions with other objects - it will just be invisible.
- If PRI is 3, the object will only be visible when on 'water' pixels.
If used to set the priority of the ego object (o0) to 15, then reserved flags f0 (ego on water) and f3 (ego touching signal line) will no longer be set when these conditions occur. If ego's priority is released, or set to a value less than 15, it returns to normal behavior.
Possible Errors
Do not use values of PRI greater than 15. The function that AGI uses to draw objects on the screen uses only the lower nibble (lowest four bits) of the priority value. For values greater than 15 this means priority equals PRI modulus 16, which would normally still allow for objects to be given a valid priority value and be drawn on the screen. However, any object with an assigned priority greater than 22 will disappear from the screen. In each interpreter cycle AGI uses objects' priority value to determine the order to draw them, so overlapping objects get drawn correctly. Objects with a fixed priority are given a 'virtual' y-position, so they get drawn in the right place. The virtual y-position is calculated as a two-byte word, so priorities above 22 get converted to a value that is above 255, which is the value that AGI tests against to determine if an object gets added to the screen. So objects with priority greater than 22 never get drawn.
In AGI versions with the set.pri.base command, when a custom priority is set, AGI uses a different function without a bug to draw the objects, so objects with priority greater than 22 would still draw on screen, but with a virtual y-position of 167, meaning they will always be drawn on top of all other objects.
AGI does not check that object number oA is a valid object. If it is not, this command will overwrite other data on the memory heap, which may cause unexpected results, including possibly crashing AGI.
Example
<syntaxhighlight lang="agi">
- define bird o4
... [ initialize object set.priority(bird, 15); [ the bird flies in front of everything </syntaxhighlight>
Technical Information
| Required Interpreter Version: | Available in all AGI versions. |
| Byte-Code Value: | 54 (0x36 hex) |
