Home

Welcome to the help for the SUDS Player.

If you are new text adventures in general, there is a section just for you. Introduction to Interactive Fiction will give you a brief history lesson to get you up and running.

If you already understand the true meaning of 'XYZZY', and how to handle the pale blue eyes, you can skip that part. There is a tutorial to get you up and running with the SUDS way of doing things. It won't take long since SUDS is so easy.

Finally there is a section of how to debug your own games using SUDS. and a section on further reading and useful links.

Copyright © 2007, SUDS


Interactive Fiction

History

Around 1975, the first text adventure was created. This was called Adventure (This was originally known as Advent since file names then could only have up to six letters). The game was expanded and became Colossal Cave. This was rapidly spread around on the early internet and became a phenomenom. You can see it online at by playing it in flash. The adventure is well plotted out as a series of points and so has been ported many times.

The popularity lead to rise of other companies dealing with text adventures as a genre, just as shoot-em-ups are today. Famous examples are the Zork series by Infocom and Level 9.

As technology progressed, many players were able to exist in the same game at the same time. The aim of the game then would be to interact to other ends than just solving puzzles. The game would not necessarily have an ending. This type of game was known as a Multi-User Dungeon. Since SUDS is single player only, its obvious where our name came from.

As the eighties went by and more computer power became available, more graphics and sound were introduced. Eventually the text began to fall by the wayside and fully graphical adventures became available, such as Lucas Art's Loom and Monkey Island. Purely text adventures ceased to be a commercial enterprise.

However with the popular rise of the internet, the community has returned. We hope that you will enjoy SUDS, and are encouraged to make your own worlds to give to the community.

The terms of Interactive Fiction and Text Adventure are interchangable. SUDS prefers Text Adventure.


Tutorial

There are two levels of tutorial. The first is the basic if you are completely new to text adventures. This will get you used to the basic lost art of text input and problem solving. It really is easy.

The second is the new improved SUDS way of working. SUDS gives a layer of player automation which removes much of the laborious work needed with text adventures.


Basic Tutorial

Objective

The objective is to understand the basic workings of a text adventure. What you learn here will apply to any text adventure, not just SUDS.

Pre-requisites

Not a lot other than a basic grasp of English grammar.

Next >


Basic Lesson 1

Lesson 1 (of 6)

Start up the SUDS Player if you have not already done so. From the initial splash screen, hit the Install button. SUDS will look for a SUD Master file to install. Navigate to the directory Tutorials under the SUDS home directory (Probably c:\program files\SUDS\tutorials) and load the file Tutorial - Advanced.SUD.

The splash screen will return with the start screen for Cave Hunt. Ah, Wagner. Press New to start a new game. Read the introduction and hit continue. The main playing area will open up.

Before you do anything else, select the option of Hardcore from the View menu. This will remove the shiny SUDS icons from the sides of the screen and leave you with a purely basic text adventurer game.

(There are those who actually don't like SUDS because of the automation. You may grow to be one of them. Certainly once you learn to find your way around then typing will provide a quicker interface than using the mouse, and relying on automation may also dull yourself to how to solve some puzzles.)

< Previous | Next >


Basic Lesson 2

Lesson 2 (of 6)

The main box gives us a text description of the surrounding area. Decoration aside, there is a path to the south and there is a branch nearby. What now? (As the Player may be asking).

The next move is up to you. And heres how. First, we will look at basic movement.

The commands to SUDS are given by typing them in. Commands to text adventures are given using a terse grammar of a verb followed by perhaps one or two nouns. Movement is achieved by a single verb of the direction that we want to travel in. We know from the description that there is a path leading south, so enter:

South

into the edit box at the bottom of the player, and press return. (You don't need to select the box. Keyboard input automatically goes in here). And lo, you are rewarded by the report that you move south, followed by the description of the next room.

The main eight compass points are recognised as possible directions, followed by Up and Down. So now, since the description says that there is another exit to the ease, type

East

And so you move deeper into the cave complex.

< Previous | Next >


Basic Lesson 3

Lesson 3 (of 6)

Typing out the full direction each time will quickly become odious. Fortuately SUDS is very good at second guessing your input, and directions can all be compressed down to one or two letters. So the following inputs will all send the player off in a direction.

NW | N | NE
W |  | E
SW | S | SE

As well as U and D.

Further to that, to help rapid movement across several rooms at once, chains of directions can be entered together. So now entering

W,N

will take us out of the caves and back to the start room.

< Previous | Next >


Basic Lesson 4

Lesson 4 (of 6)

Lets interact with the environment next. We know that there is a branch near by. Objects can be picked up and carried around. When an object has been put into the player's pockets, that list is called the inventory. You can see the current objects you are carrrying by typing

Inventory

Thats interesting, you already have a bottle (though an empty one). Lets find more details about the bottle and the branch. The command to do this is Examine. Ideally, all items of note should yeild more information when examined. To do this, type

Examine Branch

The Player will give you some more details about the branch. As you have already seen, SUDS is very generous in allowing you to truncate your input. So any of the following inputs will achieve the same effect

Examine the curious branch

Examine branch

Ex b

'E br' would lead to confusion since the player would assume you are trying to travel east. Similarly with the bottle:

Examine the green glass water-bottle

examine bottle

ex bo

All produce information about the bottle. However in the case of 'Ex b' would bring up details about the branch. The Player can be only so helpful.

< Previous | Next >


Basic Lesson 5

Lesson 5 (of 6)

Lets go caving again, but the branch looks like it should be useful, so lets take that with us. Enter the command

Take branch

And the branch will be picked up and placed in the inventory. As expected, 't b' will also have the same effect Alternatively 'Get branch' will function in the same way, though Take sounds more polite. If you now type in

Inventory

There it is! Along with the bottle. It can still be examined. If we wanted to drop the branch for some reason, the command would be

Drop branch

Pick it up again, and lets go spelunking. Enter

S,E

To re-enter the caves


Basic Lesson 6

Lesson 6 (of 6)

The caves are getting more tight, but seem to be leading somewhere. Follow the tunnel to the south

S

Oh no! The branch prevents us from going further. Its too bulky. What to do? Well, you could try dropping the branch and continuing into the next chamber without it. However it really does look like it will serve a purpose later on. So how to get it through the crevice?

Try examining it again. Theres a clue in the description. Its made to be thrown, so maybe you can heave it ahead of you into the crevice before traveling through yourself. Sounds like a plan. Enter the text

Throw branch

Ah, nothing happened. Whys that? Well, you just specified that you were throwing the branch and not at the crevice in particular. You've re-invented the boomerang. Lets try again. Enter any of these

Throw the great big branch through the tiny crevice

Throw branch crevice

th br cr

Thats better. You are rewarded with a description of the branch sailing off into the darkness. Searching your inventory, or getting a redescription of the current room using

Look

will indeed confirm that the branch has left the vicinity.

Solving this puzzle we have tried two solutions of verb-noun (Throw and branch) and verb-noun-noun (Throw, branch and crevice). All command entries will require no more complicated input than this.

And thats all you need to find your way around text adventures. A basic grasp of direction, keenness to spot clues in the text and a level of cunning and intuition to resolve problems.

However SUDS is a bit more advanced than this. Proceed to the Advanced Tutorial and we'll see what makes SUDS special.

Theres maybe one last thing. You will have noticed by now that the text entry box auto completes your typing. This is mostly a great help. However it can be switched off by unselecting 'Text Entry Completion' from under the View menu.


Advanced Tutorial

Objective

To learn how the SUDS Player adds value to a normal text adventure game.

Pre-requisites

An understanding of how text adventure games work, and familiarity with the usual concepts like the inventory, basic movement. You can pick this up from the basic tutorial.


Advanced Lesson 1

Lesson 1 (of 8)

Fire up the SUDS player if you have not already done so. From the initial splash screen, hit the Install button. SUDS will look for a SUD Master file to install. Navigate to the directory Tutorials under the SUDS home directory (Probably c:\program files\SUDS\tutorials) and load the file Tutorial - Advanced.SUD.

The splash screen will return with the start screen for Cave Hunt with a quick blast of Wagner. Press New to start a new game. Read the introduction and hit continue. The main playing area will open up.

The toolbar of the SUDS Player should have a range of icons running across it, and two item boxes on the left of the screen like the screenshot below.

If you only have the basic file handing icons, unselect Hardcore from under the View menu. The full power of the SUDS Player will be made available to you. (There are those traditionalists who don't like the extra SUDS functionality. Hardcore removes it and just gives the plain text interface. This tutorial is for looking at the extras.)


Advanced Lesson 2

Lesson 2 (of 8)

From the description you are in a forest holding a bottle, with a branch nearby and a path to the south. But all this information is made available to you in the windows. Lets look at movement first.

The compass at the bottom left of the screen shows the available directions to move in. Currently only South is available in this room, so its arrow is filled in. Click on the South Arrow.

And so you move south, and are given a new room description. This is exactly the same as entering the verb 'S' by hand. The new room has exits north and east.

Click East, and then South in the next room. This will take you through a tight squeeze and deep into the cave complex. The Pool Cavern is illustrated.


Advanced Lesson 3

Lesson 3 (of 8)

At the top left of the screen, under the icon tool bar, are two tabs, 'Main Game' and 'Map'. Currently 'Main Game' is highlighted. Click on Map. This will bring the map to the fore, and replace some of the icons on the toolbar with map specific ones.

You will now be looking at the four rooms that make up this level, 'The Cave Complex'. The paths that you took to get here connect the rooms, and the path between the Dog-Leg Bend and the Pool Cavern is interrupted to show the tight squeeze. There is an exit Down from the Pool Cavern which hasn't yet been taken. The 'D' shows this.

On the right of the tool bar, the three magnifying glass icons allow different levels of magnification. Only the ZoomX1 icon will show room descriptions. Since the level is so small, we can leave it as ZoomX1 after you have experimented.

The Pool Cavern is filled in Green to show that that is your current location. Click on Dog-Leg Bend. This will highlight the room with a green border.

From the map icons, the left most two center the map on the current room and the selected room. Click on the green box icon. This will center the map on the current room. Clicking on the white box will center the map on the current selected room, the Dog-Leg Bend in this case. Since the map is only small at this point then the difference between the two is not great.

The Padlock icon will move the current selected room back to be the current location and hold it there until it is switched off.

The two scrolls will allow you to remotely view a rooms description, and make any notes. Click on the Dog-Leg Bend once more. Click on the 'View Description' button. This will produce a description of the room despite you not currently being there. It is a useful quick reference. You can leave the description window open while clicking on different rooms. Try it now.

Similar to this is the Location Notes button. Open this up while the Dog-Leg Bend is selected again. The Location Notes window is a mini-notepad to aid you as you progress and any ideas. Copy and paste the text below.

There is a tight squeeze going south. Will this be affected by what I carry?

And then press the Save button. Again, you may leave the window open whilst clicking around the map.


Advanced Lesson 4

Lesson 4 (of 8)

The final button brings open a compass similar to the compass directions on the front screen. As you are probably guessing, you can move around the map from here by remote control. Use this now to return to the Forest Space room by pressing North, West and the North. Notice how the highlighted green room will change after each move to show you your new location.

One word of warning about the compass is that it will obviously obscure any results of your movements and is advisable only to be used along paths that you know to be safe. If the location does not change as soon as you follow a path, you had better investigate. If the path you are trying to follow is actually blocked by an angry dragon that it getting irritated by you headbutting it, you do not want to keep moving using the map alone.

Once you are back at the start, click on the 'Main Game' tab. This will return you to the main screen and hide the map. The map specific icons will disappear along with the description boxes and compass if they are still open, and the activity specific icons will return. The map can be shown at any time by flicking between the two tabs.


Advanced Lesson 5

Lesson 5 (of 8)

Next we'll look at items. On the left are two item boxes. The top one, currently listing the Branch, is the environment box. All items, whether objects, people or scenery, that are in the current room are listed here. The lower box, containing the Bottle, is the inventory.

Look at the icons that have become available since we switched back from the map display to the main display. Each one maps to a commonly used verb to avoid having to type it in. The first two, with the eyes and the tick board, are Look and Inventory. Click each one now. The SUDS Player immediately reacts as though your have typed the text adventure stalwarts of Look and Inventory in by hand, and hit return in each case. Since both verbs don't have any other input then they are processed straight away.

The next button along with the microscope is Examine. Click this, and the button will switch down and stay there. Now move the mouse over the Inventory and Environment boxes. The cursor has changed to become two cogs. That means that there is a verb active and waiting to react with an item. If you now click on either box, you will trigger the examine reaction of either item. Yes, just the same as if you had typed it.

It is a wise move here to type 'Examine branch' and 'Examine bottle' and check that the results are identical. Although the mouse controls are a helpful productivity gain, it would be foolish to rely on them totally to solve puzzles and games.


Advanced Lesson 6

Lesson 6 (of 8)

The next button along of the glove with the ball is either Take or Drop depending on the context. Clicking on an item in the inventory will attempt to drop it, and clicking on an item in the environment will attempt to pick it up. Like Examine, both Take and Drop only require one input so react as soon as you click on an item. But what about a more complicated verb like Throw which may require two inputs?

Pick up the Branch and Bottle into the inventory and head off south and east. Two mouse clicks are all you need. Now move south. If you have already played the Basic lessons, you'll know what comes next. The Branch will stop you from proceeding through the tight squeeze. You'll have to throw it through ahead of you. Happily, there is already a Throw verb button to be used. Its the seventh icon along of the hand grenade.

Click the grenade. Next select the Branch in the inventory. Nothing immediately happens in the narrative, and that is because Throw expects two inputs and we've only given one. To show that a second input is expected, the cursor has changed to show a little question mark above the cogs. Next click on the crevice. Immediately there is a response. The narrative description command text will reply as:

Throw The Branch At The Crevice

Its not perfect English, though SUDS will always try its hardest to interpret your actions into plain English.

Before we follow the Branch, how do we throw items if we don't want the second input? Simply, click the same item twice. The cursor will have changed to be plain cogs cursor once more. Click the Bottle once to change the icon from the plain cogs to the one with the question mark, awaiting the second input. Now click on the Bottle a second time. The narrative description will only be:

Throw the Water-Bottle

Happily, you won't be able to vandalise the bottle.

Now go south.


Advanced Lesson 7

Lesson 7 (of 8)

You are in the Pool Cavern at long last. Its getting quite crowded in here in the environment and inventory boxes. Lets see what the Hermit has to say for himself. Select the Talk Bubble button on the tool bar, and then click on the Hermit in the environment box. The conversation box will open.

This is all quite obvious. You have a selection of possible responses to choose from at the bottom of the box, and a running narrative of the conversation in the top half of the box. Choose whatever responses you want until the conversation runs its course. Hes a grumpy bugger. The (un)smiley face in the title gives the current attitude of the person you are talking to. The Hermit's mouth will never rise. However, the shopkeeper in Roman Adventure II is much more expressive. If you show interest in his games and achievements then the face will smile and he will more helpful with his responses. If you aggressively try to claim his helmet then his responses will become terse and unhelpful, demonstrated by a grimace.

There is one more way of interacting with items. Select Look once more to get a fresh description of the environment. The local items are listed at the end of the location description. They are a different colour because they are hyper-links. Clicking on the Branch will produce a popup menu. There are two useful verbs, Examine and Take. Both immediately operate on the Branch. Clicking on the Hermit will produce Examine and Talk. You can rattle the Hermit's cage again by clicking on Talk a second time.

All the menus that are available by clicking on the hyper-links are also available as right-click options in the environment and inventory menus.


Advanced Lesson 8

Lesson 8 (of 8)

So now you have progressed a decent way into the adventure without having to press a single key. However, again it is worth remembering about not closing your options by relying simply on the options on the tool bar. It is fairly self-evident that that Bottle should be filled from the Pool. However this can only achieved by old-fashioned typing. So type in:

Fill Bottle from Pool

Ah, the bottle is lost. Well, you now know enough to complete the rest of the advanced tutorial yourself. And once you get a grasp of how SUDS games work, follow the equivalent tutorial that comes with the Constructor and make your own games.


Debugging

There are two useful tools in SUDS to aid debugging. The first is an item inspector which will give the current location and status of all items in the game, regardless of whether they are visible to the player or not. The second will allow you step through procedures whenever they are called. This will allow you to see whats going on in the background.

It is important to point out that the debugging can be made to be forbidden by the settings in the Constructor. On the General Settings page, there is an option called 'Testing Mode'. If this is unchecked then the debugging will not be available to the Player. This is useful when you are publicly releasing a final completed adventure.

Both debugging options are available under the Tools menu on the main screen. The first, Item List, will bring up a new window listing all the items in the game in the four type categories. Just like the item inspector in the Constructor.

There are four available options on the toolbar, (Or the menus, or the right click menu if you want). These are:

  • Report on GVs- Does exactly what it says on the tin. The current value of all the 30 global variables will be shown.
  • View Details - A mini report on the currently selected item will be shown, listing the current settings and attributes.
  • Move To - The player will magically teleport to the location of the selected item. This could potentially create a lot of problems in the game and lead to debugging impossible solution, so be careful.
  • Take - If its not already in your inventory then the selected item will magically appear there. This includes people and scenery, which wouldn't normally be possible. If the item is already in your inventory then they will be dropped in the current location.

So if you need to test how two items interact, you can summon both of them to the same location without having to set them up in the Constructor first.

The second debugging tool is the procedure inspector. This will activate if the option 'View Procedures' is ticked and a procedure is executed in the background. Try it now by loading the Advanced Tutorial into SUDS, ticking the option, and then moving south from the start room. Since the post-process procedure makes the fish swim around the caves, you can step through and watch the decision making. Similarly there is a procedure associated with moving south from the Dog-Leg Bend. You can experiment and watch the branching decision making by carrying the Branch or not. Checks can be manually decided by using the 'Set Decision' function.

At some points, you may find that you are only interested in debugging events triggered by the players actions and not the active tasks, nor the initialisation and post-turn procedures. All procedures that are given a procedure type of 'Active Task' in the Constructor will be ingnored if the option 'Debug Auto Procs' is ticked under the tools menu. It only becomes available if the 'View Procedures' option is active.


Further Reading

There are entire resources available on the internet now that text adventures have become popular again. Rather than list sites, theres nothing else that we can do other than point you to the magnificent list of connections on WikiPedia. This will be frequently updated and will give you all the hints, tips and ideas you could need on text adventures in general.

If you do get stuck with SUDS in particular, then drop by the SUDS website. The forums here will provide you with help on individual adventures, and how to get your own creations up and running.


Credits

SUDS was originally written in 1999 by Andy Elliot. This version had a purely mouse driven interface with no text input.

It was expanded and re-released in 2007 by Matthew Smith. This time it had a text interface while keeping the point-and-click idea, a skinnable interface for the Player and expanded functionality.

Andy was inspired by the book 'How To Write Adventure Games For The BBC Microcomputer Model B and Acorn Electron' by Peter Killworth. Matt was inspired by 'WriteYourOwnAdventurePrograms' by Jenny Tyler and Les Howarth.

SUDS is written in Borland Delphi. The following components were all invaluable:

THTMLLite from Dave Baldwin - Used for the native HTML rendering.

Alphaskins - These produced the lovely skinnable front end for the player.

ComponentAce - This amazing small but powerful database gives full native DB support without the need for external DLLs. SUDS is entirely driven by SQL.