Text Adventure games

[Collapsible Myth]

From Glaucon's post on the official TSW forums here


Overview
Introduced in update 1.8.5 is a way to create your own text adventure games to be played within The Secret World. Text adventure games in TSW are defined by creating a .xml file containing all of the data your game needs in order to run. This XML file is broken up into three primary types of element: game, room, and event. Your Text Adventure can only have one game, but every game can have infinite rooms and every room can have infinite events.

These .xml files are stored on your computer at

Funcom\The Secret World\Data\Gui\Customized\TextGames

.xml files stored here will behave the same way that custom UI mods do. They will not be overwritten by the patch process.

If you open that folder, you will see several .xml files named CustomGame1 through CustomGame6. These names are important, as it binds them to the PCs in the Seul PC Bang. In order to load your custom game into The Secret World, you overwrite these files with your own. Which file you choose to overwrite will determine which computer the game plays on.

Installing a Custom Text Adventure Game
To install a custom text adventure game, save the .xml file in

Funcom\The Secret World\Data\Gui\Customized\TextGames

Make sure to save the over one of the CustomGame files that are included by default, as this allows the PCs in the PC Bang in Seoul to load the file. You may have up to six custom text adventure games loaded at once.

Creating a Custom Text Adventure Game
To create your own custom text adventure game, edit one of the CustomGame files found at

Funcom\The Secret World\Data\Gui\Customized\TextGames

It does not matter which one you choose, as the file name only affects which computer the text game is displayed on. People who download your text adventure game may rename it anyway if they don't want to override another custom game that also uses that slot.

The files located in this folder already contain some filler rooms and events. The error you get when you use the PC with no custom game loaded is actually a working game, just one that doesn't do anything other than ask you to replace it. You will want to replace what is already in the file with your own data.

A custom text adventure game is made up of three different data structures. The first data structure is the game. You will only have one game element per file, and it serves mostly as a container. The second data structure is rooms. Rooms are the real meat of your game, and they define how your game reacts to a player's actions. A game can have any number of rooms. The third data structure is events. An event is anything that a player can do in a room. Rooms define the valid ways in which players can interact with your game.

Games
You only have one game element per file. This element contains the name of your game, whether or not to translate the game, and all of the room elements that make up your game. The game element is defined like this:

<game name="Your Game's Name" translation="0">
</game>

The name field will be displayed at the top of the TextGame window, so that players know which game they are playing. The translation field will tell the UI whether or not to translate your game. TRANSLATION SHOULD ALWAYS BE 0! If you set the translation field to 1, it will try to feed your text through the translation server, and you will end up with incorrect or no text being displyed.

The game element also contains Each room element in the game.

Rooms
You may have as many room elements as you want per game. Room elements define most of the text displayed by your game. Every room contains the name of the room, a unique room ID, the description of the room, and a custom error message for that room. A room element is defined within the game element like this:

<game name="Your Game's Name" translation="0">
[SIZE=5]<room name="The First Room" id="0" description="This is the first room in the game. There is a door to the south." error="Perhaps you should try the door.">
</room>
</game>

[/SIZE]
The name field defines the name of the room. This name will be displayed in the white bar near the top of the Text Game GUI. This name does not have to be unique, so you can use the same name for several rooms if you want to make them seem like they are all the same place.

The id field defines a unique ID for this room. This ID MUST BE UNIQUE. A room's ID is used to send a player to that room in response to an event. THE GAME ALWAYS STARTS IN THE ROOM WITH id="0".

The description field is where most of your game will come from. This field defines the block of text that will be displayed in the body of the UI. Use this text to provide clues for the players to react to, or to tell the players what is happening to them. (e.g. "The Ur-Draug sat on you, sorry. Game Over.")

The error field defines a custom error message for your room. The player will receive this error message whenever they provide input that doesn't match any of the events you have defined, or any of the special command words. You may define this field as error="" to use the TextGame's default error message, but it is sometimes useful to define something more relevant to the context of the room.

Room elements also contain event elements that are active in that room.

Events
An event defines a possible course of action by a player, and what happens as a result of this action. Every event contains an action, a target, an inventory item, a room ID to go to, an item to get, and an item to take. Events are defined within rooms like this:

<game name="Your Game's Name" translation="0">
[SIZE=5]<room name="The First Room" id="0" description="This is the first room in the game. There is a door to the south." error="Perhaps you should try the door.">
<event action="Go" target="South" inventoryItem="" outputId="1" itemGet="" itemTake=""/>
</room>
</game>
[/SIZE]

The action and target fields are basically identical. They define keywords that the player will need to input in order to trigger this event. The player must trigger all of the keywords in an event, and no extra keywords that are active in this room, in order to activate the event. It doesn't matter what order the player triggers them in, or if the player adds any extra non-keywords to their input. In the example above "Go South" would trigger this event. As would "South Go", "Go to the south", or "Go go gadget south pole!" However, just "Go" or "South" would not.

The inventoryItem is also compared to the user's input in much the same way as action and target are. The only difference is that the inventoryItem parameter will also be checked against the player's inventory before it is accepted. If the player tries to use an inventory item that they do not have, the event will fail and they will be informed that they do not have that item.

The outputId field defines which room the user will be moved to when this event is activated. It should match the id field of the room you want to send them to.

The itemGet field defines an inventory item to be added to the player's inventory upon activation of this event.

The itemTake field defines an inventory item to be removed from the player's inventory upon activation of this event. A special note, itemTake="*" will remove ALL items from the player's inventory.

NOTE: Player input is broken up by spaces. Therefore your actions, targets, and inventoryItems MUST BE SINGLE WORDS!

 

[Collapsible Myth]

Tips

General Tips

• Use the same room name in multiple rooms to make them feel like they are the same place.
• Use the \n character to insert linebreaks into your text.
• Have multiple events in a room that lead to the same place, don't expect players to know the exact right words to say.
• Use consistent vocabulary so that players know what to expect.
• Be careful with using events with keywords that would reasonably be added to other events in the same room. For example, "Go" "Ladder" and "Look" "Up" would cause "Go up the ladder" to fail.
• One word events are the simplest. If one word is all you need to know what a player wants to do, use only that one word.
• Remember that the order of input words is not set. "Get" "Key" is the same as "Key" "Get."
• Events are not shared between rooms. If you want a player to pick up an object and immediately go north, you have to set up the event to go north in the room that shows the player picking up the object.
• Keep inventory items simple. People playing the game can use the "inventory" command to see what they have, but they also need to be able to remember it without having that screen up.

Common Actions

• Room, Back, Return - These return the player to the last room they were in. In the event that they were looking at an object, they return the player to the base room.
• Look, Examine - These let the player inspect an object in greater detail.
• Use - Interact with an object, or use an inventory object.
• Take, Get, Steal - Pick up or take an object.
• Open - Open a door or closed Object.
• N, E, S, W, NE, SE, SW, NW, North, East, South, West, Northeast, Southeast, Northwest, Southwest - Cardinal directions. These are less confusing than using Left, right, forward, etc.
• Talk, Speak - Interact with a living entity.
• Yes, No - Respond yes or No.
• Give - Give an object to something