Function: PopRoom

PopRoom ( PLAYER )

Changes the current room on a specific player by removing ("popping") a room off the top of the player's room stack.

Parameters

Parameter	Type	Description
PLAYER	PLAYER	The player whose room stack will change.

Returns

Returns nothing. Cannot be used in expressions.

What It Does

This function changes the topmost room in a specific player's room stack by "popping" the topmost room off of it (thus making the previous room on the stack "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 PopRoom() (or the other room-changing functions) changes it again.

If PopRoom() is called with the specified player when it has only one room in its room stack, the player will have no current room, and attempts to resolve the current room will cause a FATAL error (and cue) to be thrown.

If PopRoom() is called with the specified player when it has no current room, a room stack underflow will occur 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!

Example

Since rooms are a "state" structure, you can use them for non-room things like conversations:

Conversation Example


// Actions
action modal a_go named "go" uses modes "north", "south", "west", "east";
action transitive a_examine named "look at", "examine", "x"; 
action transitive a_talkto named "talk to"; 
action general a_quit named "quit"; 

// Conversation Actions
action transitive a_talkabout named "talk about";
action general a_leave named "back", "leave"; 

// "Hidden" Actions
action general a_look; // queued every action.
action general a_roomcheck; // queued every action.

// ================== Topics (as objects) =======================

object archetype o_topic;
object ot_sports : o_topic named "sports";
object ot_music : o_topic named "music";
object ot_movies : o_topic named "movies";
object ot_dogs : o_topic named "dogs";

// ===================== All about Bob ==========================

room convo_bob
{
	onAction(a_look) {} // Do nothing on "look".

	// If "in" the conversation, this block will be hit instead of the player fallback.
	onAction(a_leave)
	{
		textln("You cease talking to Bob.");
		popRoom(player); // Go back to where you were.
	}

	onActionWith(a_talkabout, ot_sports)
	{
		textln("Bob says, \"Oh yeah! I love sports!\"");
	}

	onActionWith(a_talkabout, ot_movies)
	{
		textln("Bob says, \"Heck yeah! I love movies!\"");
	}

	onActionWith(a_talkabout, ot_dogs)
	{
		textln("Bob says, \"Oh man, I love dogs! They're adorable!\"");
	}

	// Omitting "music"

	onActionWithAncestor(a_talkabout, o_topic)
	{
		textln("Bob says, \"I dunno much about that.\"");
	}

	onActionWithOther(a_talkabout)
	{
		textln("That's not a topic of conversation.");
	}
}

object o_bob named "Bob"
{
	onAction(a_examine)
	{
		textln("That's Bob. He likes to talk about things (\"TALK TO\" him).");
	}

	onAction(a_talkto)
	{
		textln("You are now talking to Bob. (TALK ABOUT sports, movies, music, or dogs. You can LEAVE the conversation, too)");
		pushRoom(player, convo_bob); // Keep current room for "leave".
	}

	onRoomBrowse()
	{
		textln("Bob is here.");
	}
}

// ======================== Actual Rooms ==========================

room r_bedroom; // Prototyped due to early use in r_livingroom

room r_livingroom
{
	init()
	{
		giveObject(this, o_bob);
	}

	onAction(a_look)
	{
		textln("You are in the living room.");
		textln("North goes to the bedroom.");
		browse(this);
	}

	onModalAction(a_go, "north")
	{
		setRoom(player, r_bedroom);
	}
}

extend room r_bedroom
{
	onAction(a_look)
	{
		textln("You are in the bedroom.");
		textln("South goes to the living room.");
		browse(this);
	}

	onModalAction(a_go, "south")
	{
		setRoom(player, r_livingroom);
	}
}

player p_main
{
	init()
	{
		// add topics (so that they are always accessible to the player).
		giveObject(this, ot_sports);
		giveObject(this, ot_movies);
		giveObject(this, ot_music);
		giveObject(this, ot_dogs);
	}

	onAction(a_roomcheck)
	{
		if (!currentRoomIs(this, r_livingroom) && playerHasRoomInStack(this, r_livingroom))
			textln("(NOTE: You are still \"in\" the living room, but can't access things in it - \"TALK TO BOB\" will not work)");
	}

	onUnhandledAction(a_go)
	{
		textln("You can't go that way.");
	}

	onIncompleteCommand(a_talkto)
	{
		textln("TALK TO what?");
	}

	onUnhandledAction(a_talkto)
	{
		textln("I can't TALK TO that.");
	}

	onIncompleteCommand(a_talkabout)
	{
		textln("TALK ABOUT what?");
	}

	onUnhandledAction(a_talkabout)
	{
		textln("You must be conversing with somebody to TALK ABOUT things.");
	}

	onAction(a_leave)
	{
		textln("You're not in a conversation.");
	}

}

world
{
	init()
	{
		setRoom(p_main, r_bedroom);
		setPlayer(p_main); // from this moment on, this is the "player" keyword.
	}

	start()
	{
		textln("Type \"quit\" to quit, \"go\" and a compass direction to move between rooms.");
		textln("Examine things with \"look at\" or \"examine\".");
		textln("");
		queue a_look;
		queue a_roomcheck;
	}

	onAction(a_quit)
	{
		quit;
	}

	afterSuccessfulCommand()
	{
		queue a_look;
		queue a_roomcheck;
	}

}