View source for End.of.loop

The '''end.of.loop''' command switches an object's [[cycle mode]] to &lsquo;end of loop&rsquo;.

== Syntax ==

end.of.loop([[screen object|obj]] oA, [[flag|flg]] fDONE);

== Remarks ==

In &lsquo;end of loop&rsquo; [[cycle mode]], [[screen object]] '''oA''' will cycle one time, in the forward direction, until the end of the loop is reached.

Setting the cycle mode to &lsquo;end of loop&rsquo; will automatically enable the object for [[updating]] if not currently enabled, and also enables the [[cycling property]].

[[Flag]] '''fDONE''' is reset to FALSE when the command is executed. When the last [[cel]] is reached, '''fDONE''' is set to TRUE.

Changing cycle mode does not change the current [[cel]]. The new cycle mode begins with whatever cel is currently assigned to the object. If the current cel is the last cel, no cycling will occur, as the object is already at the end of the loop. Flag '''fDONE''' will be set immediately.

Use the '''[[stop.cycling]]''' command to turn cycling off. The '''[[normal.cycle]]''', '''[[reverse.cycle]]''' and '''[[reverse.loop]]''' commands can be used to switch to other cycle modes.

== Possible Errors ==

AGI does not check that the [[screen object]] number oA is valid. If the object has not been [[initialized]] the '''end.of.loop''' command still sets the cycle mode to 'end of loop' and resets the flag; nothing else will happen though. If the object number exceeds the [[maximum number of objects]], this command will overwrite other data on the [[memory heap]], which will cause unexpected results, including possibly [[crashing AGI]].

Do not use '''end.of.loop''' and movement modes ('''[[move.obj]]''', '''[[follow.ego]]''' or '''[[wander]]''') one an object at the same time. The byte in the [[screen object data table]] that AGI uses to store the '''fDONE''' flag is also used by the movement modes. If you use a movement mode command while the '''end.of.loop''' command is active, the flag number gets overwritten, and when the object finishes cycling, the wrong flag will be set.

== Example ==

<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="agi">
#define door o7
...
[ initialize object
...
end.of.loop(door, f100);  [ open the door
if(isset(f100)) 
  {
  print("The door is open.");
  reset(f100);
  }
...
reverse.loop(door, f99);  [ close the door
if(isset(f99)) 
  {
  print("The door is shut.");
  reset(f99);
  }
</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:'''
| 73 (0x49 hex)
|}

== See Also ==

'''[[normal.cycle]]'''<br />
'''[[reverse.cycle]]'''<br />
'''[[reverse.loop]]'''<br />
'''[[stop.cycling]]'''<br />
[[Category:Commands]]<br />