Difference between revisions of "New.room"

From AGI Wiki
Jump to navigationJump to search
(Created page with "The new.room command switches the game to a new room. There is an indirect version of this command called '''new.room.v'''. <code>new.room(roomNumber...")
 
 
(9 intermediate revisions by one other user not shown)
Line 1: Line 1:
−
The new.room command switches the game to a new [[room]]. There is an [[Indirect Command|indirect]] version of this command called '''new.room.v'''.
+
The '''new.room''' command changes the current room number and forces an update.
  
−
<code>new.room(roomNumber);</code>
+
== Syntax ==
  
−
The following things happen automatically when this command is issued:
+
new.room([[number|byt]] ROOMNUM);
  
−
* All [[Animated Object|objects]] are unanimated.
+
== Remarks ==
−
* All resources except [[logic 0]] are discarded (removed from memory).
 
−
* The [[player.control]] command is executed.
 
−
* The [[unblock]] command is executed.
 
−
* The [[Set.horizon|horizon]] is set to 36.
 
−
* v1 (previous room number) is set to the value of v0 (room number)
 
−
* v0 (room number) is assigned roomNumber
 
−
* v16 (ego view number) is set to the [[VIEW Resource|view]] number assigned to [[ego]].
 
−
* The [[LOGIC Resource|logic]] for the new room is loaded (logic roomNumber).
 
−
* If ego was touching an [[Screen Edges|edge of the screen]], it is placed on the opposite side.
 
−
* [[Flag]] 5 (new room flag) is [[set]] (the flag is [[reset]] after the first cycle in the new room).
 
−
* Execution jumps to the start of logic 0.
 
  
−
== Parameters ==
+
The '''new.room''' command causes AGI to halt execution of the current [[logic]] script. The current [[room]] number is changed to '''ROOMNUM'''. The resources on the [[memory heap]] are dumped (with the exception of [[logic 0]]). The following actions are then taken to switch to the new room:
  
−
For new.room
+
# if a [[sound]] is playing, it is stopped and the 'done' [[flag]] is set to TRUE;
 +
# the [[memory heap]] is cleared by resetting the memory pointer to [[room.0]];
 +
# the [[keyboard]] buffer and [[controller flag table]] are cleared;
 +
# the [[script]] table is cleared;
 +
# the [[screen objects table]] is cleared - for each [[screen object]], the DRAWN and ANIMATED flags are cleared and the UPDATE flag is set; and the [[step size]], [[step time]], step counter, [[cycle time]] and cycle counter properties are set to 1;
 +
# all resource linked lists are cleared;
 +
# [[ego]]is set to [[player.control|player control]];
 +
# if a [[block]] is set, it is cleared;
 +
# the [[horizon]] is set to default value of 36;
 +
# [[reserved variable]] [[v0 (current room)]] is copied to reserved variable [[v1 (previous room)]];, and v0 is set to '''ROOMNUM''';
 +
# [[reserved variable|reserved variables]] [[v4 (object touching edge)]] and [[v5 (object edge code)]] are set to zero;
 +
# [[reserved variable]] [[v16 (ego view number)]] is set to current [[ego]] [[view]] number;
 +
# all open [[VOL files]] are closed (they will automatically be reopened when the [[logic]] for this room is loaded);
 +
# the [[logic]] for new room ([[reserved variable]] [[v0 (current room)]]) is loaded (note that the logic is loaded, but is not [[called]] automatically; you should use the '''[[call.v]]''' command in [[logic 0]] to call the room's logic in each [[interpreter cycle]]);
 +
# if a [[trace.info|trace logic]] has been specified, it gets loaded;
 +
# if [[ego]] was touching an edge in the previous room, it is positioned to opposite side of the new room ( i.e. if ego touched right edge, it is moved to left edge);
 +
# [[reserved variable]] [[v2 (ego edge code)]] is set to zero;
 +
# [[reserved flag]] [[f5 (new room)]] is set to TRUE;
 +
# the [[controller]] flag table is cleared;
 +
# the [[status line]], if enabled, is redrawn;
 +
# the [[input line]], if enabled, is redrawn, any text already on the input line before the '''new.room''' call is maintained;
 +
# [[reserved variable|reserved variables]] [[v4 (object touching edge)]], [[v5 (object edge code)]] and [[v9 (unknown word number)]] are set to zero;
 +
# [[reserved flag]] [[f2 (input received)]] is reset to FALSE (but reserved flag [[f4 (said found match) is not modified; this appears to be a minor bug, but it usually not an issue);
 +
# [[reserved variable]] [[v3(current score)]] is cached;
 +
# the [[interpreter cycle|cycle]] is then continued by jumping to the point where [[logic 0]] is executed.
  
−
* <code>roomNumber</code>: a number, 0-255, specifying which room to switch to
+
Keep in mind that the '''new.room''' command interrupts the [[interpreter cycle]], so any commands after a '''new.room''' command will never get executed.
  
 +
Also note that the '''new.room''' command does not affect the current display mode ([[graphics]] or [[text.screen|text]]); it will remain in the same mode.
  
−
For new.room.v
+
== Possible Errors ==
  
−
* <code>roomNumber</code>: a [[variable]], <code>v0-v255</code>, whose value specifies which room to switch to
+
If the logic matching '''ROOMNUM''' does not exist, AGI will raise a [[runtime error]] and crash.
  
−
 
+
== Example ==
−
== Possible errors ==
 
−
 
 
−
* the [[LOGIC Resource|logic resource]] must exist, or the game will crash with a [[Logic Not Found Error |logic not found error ]]
 
−
 
 
−
 
 
−
== Examples ==
 
−
 
 
−
The following code goes to room 25 if [[ego]] is touching the left edge of the screen:
 
−
 
 
−
<div class="CodeBlockHeader">Code:</div>
 
−
<div class="CodeBlockStyle">
 
−
<syntaxhighlight lang="agi">
 
−
#define ego_edge_code v2
 
−
#define left_edge      4
 
−
 
 
−
if (ego_edge_code == left_edge)
 
−
{
 
−
    new.room(25);
 
−
}
 
−
</syntaxhighlight></div>
 
−
 
 
−
 
 
−
The next example accomplishes the same task with <code>new.room.v</code>:
 
  
 
<div class="CodeBlockHeader">Code:</div>
 
<div class="CodeBlockHeader">Code:</div>
−
<div class="CodeBlockStyle">
 
 
<syntaxhighlight lang="agi">
 
<syntaxhighlight lang="agi">
−
#define ego_edge_code v2
+
[ typical code that changes rooms when ego reaches an edge
−
#define left_edge      4
+
if (edgeEgoHit == LEFT)  
−
 
+
  {
−
if (ego_edge_code == left_edge)
+
  new.room(75);
−
{
+
  }
−
  v202 = 25;
+
</syntaxhighlight>
−
  new.room.v(v202);
 
−
}
 
−
</syntaxhighlight></div>
 
−
 
 
−
== See also ==
 
−
 
 
−
* [[New room section|New Room Section]]
 
−
* [[player.control]]
 
−
* [[unblock]]
 
−
* [[set.horizon]]
 
−
* [[Special Variables|Special variables]]
 
−
* [[Special flags|Special Flags]]
 
−
* [[Defines]]
 
  
−
== Sources ==
+
== Technical Information ==
  
−
Some of the text in this article is taken from the [[AGI Studio]] help file.
+
{| 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:'''
 +
| 18 (0x12 hex)
 +
|}
  
−
[[Category:Logic Commands]]
+
== See Also ==
−
[[Category:Control Flow Commands]]
 
  
−
&nbsp;
+
'''[[new.room.v]]'''<br />
 +
[[Category:Commands]]<br />

Latest revision as of 17:56, 12 April 2019

The new.room command changes the current room number and forces an update.

Syntax

new.room(byt ROOMNUM);

Remarks

The new.room command causes AGI to halt execution of the current logic script. The current room number is changed to ROOMNUM. The resources on the memory heap are dumped (with the exception of logic 0). The following actions are then taken to switch to the new room:

  1. if a sound is playing, it is stopped and the 'done' flag is set to TRUE;
  2. the memory heap is cleared by resetting the memory pointer to room.0;
  3. the keyboard buffer and controller flag table are cleared;
  4. the script table is cleared;
  5. the screen objects table is cleared - for each screen object, the DRAWN and ANIMATED flags are cleared and the UPDATE flag is set; and the step size, step time, step counter, cycle time and cycle counter properties are set to 1;
  6. all resource linked lists are cleared;
  7. egois set to player control;
  8. if a block is set, it is cleared;
  9. the horizon is set to default value of 36;
  10. reserved variable v0 (current room) is copied to reserved variable v1 (previous room);, and v0 is set to ROOMNUM;
  11. reserved variables v4 (object touching edge) and v5 (object edge code) are set to zero;
  12. reserved variable v16 (ego view number) is set to current ego view number;
  13. all open VOL files are closed (they will automatically be reopened when the logic for this room is loaded);
  14. the logic for new room (reserved variable v0 (current room)) is loaded (note that the logic is loaded, but is not called automatically; you should use the call.v command in logic 0 to call the room's logic in each interpreter cycle);
  15. if a trace logic has been specified, it gets loaded;
  16. if ego was touching an edge in the previous room, it is positioned to opposite side of the new room ( i.e. if ego touched right edge, it is moved to left edge);
  17. reserved variable v2 (ego edge code) is set to zero;
  18. reserved flag f5 (new room) is set to TRUE;
  19. the controller flag table is cleared;
  20. the status line, if enabled, is redrawn;
  21. the input line, if enabled, is redrawn, any text already on the input line before the new.room call is maintained;
  22. reserved variables v4 (object touching edge), v5 (object edge code) and v9 (unknown word number) are set to zero;
  23. reserved flag f2 (input received) is reset to FALSE (but reserved flag [[f4 (said found match) is not modified; this appears to be a minor bug, but it usually not an issue);
  24. reserved variable v3(current score) is cached;
  25. the cycle is then continued by jumping to the point where logic 0 is executed.

Keep in mind that the new.room command interrupts the interpreter cycle, so any commands after a new.room command will never get executed.

Also note that the new.room command does not affect the current display mode (graphics or text); it will remain in the same mode.

Possible Errors

If the logic matching ROOMNUM does not exist, AGI will raise a runtime error and crash.

Example

Code:

<syntaxhighlight lang="agi"> [ typical code that changes rooms when ego reaches an edge if (edgeEgoHit == LEFT) 

 {
 new.room(75);
 }

</syntaxhighlight>

Technical Information

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

See Also

new.room.v

Retrieved from "http://agiwiki.sierrahelp.com//index.php?title=New.room&oldid=12539"