View source for Set.loop

The '''set.loop''' command assigns a loop to a screen object.

== Syntax ==

set.loop([[screen object|obj]] oA, [[number|byt]] LOOP);

== Remarks ==

The current [[loop]] of [[screen object]] '''oA''' is set to '''LOOP'''.

A [[View Resource (AGI)|view]] must be be assigned to the object first. If a view is not assigned, AGI raises [[trappable error #6]]. If '''LOOP''' is not a valid loop number, i.e. it exceeds the maximum number of available loops in the view, AGI raises [[trappable error #5]].

Be aware that there is a bug in all versions of AGI affecting the check for valid loop numbers. AGI only returns [[trappable error #5]] if the value of '''LOOP''' is GREATER than the total number of loops in the view. However, since loops are zero based (first loop is 0, second loop is one, etc.), the last valid loop would be total loop count minus one. If '''LOOP''' is EQUAL to the loop count, AGI doesn't raise an error, but the loop number is actually invalid, and using it will almost always end up in [[crashing AGI]].

When the loop changes, AGI checks to see if the current [[cel]] value of the screen object is now greater than the last cel in newly assigned loop. If it is, the cel is reset to 0; if not the screen object's cel value is not changed. 

== Possible Errors ==

In [[version]] 2.089 only, AGI raises [[trappable error #4]] if object number '''oA''' is invalid. In all later versions, 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 ==

<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="agi">
[ typical code to add a static view
animate.obj(o1);
load.view(8);
set.view(o1, 8);
set.loop(o1, 1);
set.cel(o1, 2);
position(o1, 20, 132);
stop.cycling(o1);
draw(o1);
</syntaxhighlight>

== Technical Information ==

{| border="1" cellpadding="2"
| style="background-color: #efefef" width="200" | '''Required Interpreter Version:'''
| width="175" | Available in all AGI versions.
|-
| style="background-color: #efefef" | '''Byte-Code Value:'''
| 43 (0x2B hex)
|}

== See Also ==

'''[[set.cel]]'''<br />
'''[[set.cel.v]]'''<br />
'''[[set.loop.v]]'''<br />
'''[[set.view]]'''<br />
'''[[set.view.v]]'''<br />
[[Category:Commands]]<br />