Set.priority.v

The set.priority.v command sets an object's priority indirectly, and disables automatic priority assignment.

Syntax

set.priority.v(obj oA, var vPRI);

Remarks

The default behavior for screen objects is to automatically assign priority based on position. The set.priority.v command sets screen object oA’s priority to value of variable vPRI 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 vPRI are 3 - 15, with the following considerations:

• If value of vPRI is 15, in addition to having a static priority value of 15, the screen object will also ignore all control lines and blocks.
• If vPRI 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 vPRI 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 vPRI 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 screen 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

Code:

... [ initialize object
set.priority.v(o1, v51);</CODE>
<CODE>#define bird o4
...  [ initialize object
v51 = 15;
set.priority.v(bird, v51); [ the bird flies in front of everything

Technical Information

Required Interpreter Version:	Available in all AGI versions.
Byte-Code Value:	55 (0x37 hex)

See Also

release.priority
set.priority