SwapRoom ( PLAYER, NEWROOM )

Changes the current room on the provided player by removing the topmost room on the top of the player's room stack and adding the provided one.

Returns nothing. Cannot be used in expressions.

This function sets the topmost room in a specific player's room stack to the provided room by "popping" the current room off the top of the stack (like PopRoom()), and then "pushing" the provided room onto the top of it (like PushRoom()), thus making it "current" for that player. From the moment that this function is executed, all functions and operations that use the current room (provided that its associated player is also current) will use the one provided until another call to SwapRoom (or the other room-changing functions) changes it again.

Calling SwapRoom() with the specified player when it has only one room in its room room-stack will have the same effect as though SetRoom() were called.

If SwapRoom() is called when a player has no current room, a room stack underflow will occur (due to a "pop" operation being called) and a FATAL error (and cue) will be thrown.

The Room Stack

The Room Stack is the mechanism by which TAME determines or maintains the current room per player. As the name implies, this is maintained by a structure called a stack.

The author can change what rooms each player is in (including the current player) by calling the different functions that manipulate this stack: SetRoom(), PushRoom(), PopRoom(), and SwapRoom(), each of which perform different stack operations.

Rooms are not exclusively owned like objects - more than one player can have the same room in their stack, and a room can be in a single player's room stack more than once. Just be careful if you, the author, choose to allow this: you should properly convey what room the current player is currently in at all times!

SetRoom() — Sets the current room on a player, after clearing its room stack.
PushRoom() — Adds a room onto a player's room stack, preserving the previous rooms on the stack.
PopRoom() — Removes the topmost room from a player's room stack.
PlayerHasRoomInStack() — Checks if a room is in a player's room stack.
CurrentRoomIs() — Checks the topmost room on a player's room stack against another room.
NoCurrentRoom() — Checks if a player is not in any room.