Game source files (.RAD) and Game Command Files (.CMD)
Loading a Game Source File
Loading a Saved Game
Saving a game in progress
Exiting Rexx-Adventure
Creating Rexx-Adventure games
The Source File Layout
A) Overview
Variable Definition
B) Comments
C) Header lines
Line 1 Title
Line 2 PlayerNum
Line 3 GlobalNum
D) Object Definitions
Intro Lines
Object Lines
Flag Lines
Content Lines
Verb Lines
IVerb Lines
Test Lines
Desc Lines
Code Lines
Debug Mode
Appendices
1) Data Structure
2) Sample Object
3) Built in Functions and Procedures
Introduction:
Thank you for trying Rexx-Adventure. This project began about 2 years ago when I decided to write a text adventure. I began looking around for a development system, and found Adventure Game Toolkit (AGT), which is a good system, but requires multiple files to create a single advnture.
I got bogged down in the text entry, and trying to keep track of things. The project sat for a long time. Then I got OS/2, and discovered REXX, and VX-REXX. I realized that I had never seen a text adventure engine for OS/2 on any FTP sites.
This package is released as Freeware. While you do not have to pay for it, it remains my
property. It may only be reporduced in its entirety and without modification. I do not limit the nethod of distribution, as long as there is no charge beyond the cost of the sotrage media.
If you like this pacakge, or even if you don't, please contact me at desantom@io.com and give your opinion.
Features:
Easy to use point-and-click interface.
An Engine, not a single game. Lets you write your own games.
Simple source creation for easy to write games.
Very little programming expertese required.
Object based source design. (Not Object Oriented because it does not suport Inheritance)
Absloutely Free!
Planned Features:
Indirect Object Support.
Re-sizable windows.
Sound support. Make your adventure talk.
Visiual source creation software. (Tentative)
A Compass Rose window.
Playing Rexx-Adventure:
Game source files (.RAD) and Game Command Files (.CMD):
Rexx-Adventure source files have the extension .RAD. These files hold every object and action possible within the game.
An adventure may also have an optional Command file, with the extension .CMD. This is used to hold functions that the programmer added to the basic set. Command files are limited in that they can not access the entire database. They are useful, however, for pot-up windows and the like.
Both of these files should have the same name.
Loading a Game Source File:
To load a source file, click on the "File Commands" menu, and the "Begin New Adventure"
option. Choose the desired file in the file dialog, and the game is loaded. While the game is loading, a dot is shown for each object loaded. This will give you a impression of the overall size of the game, and it makes me more comfortable to know that the program is running properly.
Loading a Saved Game:
Before you can load a saved game, you must first load the Source File for that game. I suggest keeping each Source File in its own sub-folder, so the save games and source files do not get confused.
Once the Source File is loaded, choose "Load Game" from the "File Commands" menu. Saved
games have the extension .RAS. Choose the saved game to load, and click OK.
Saving a game in progress:
Simply choose "Save Game" from the "File Commands" menu. Enter the file name to save in the file dialog, and the game will be saved. If a file already exists with the given name, you will be prompted whether to erase it or not.
Exiting Rexx-Adventure
Simply choose "Quit" from the "File Commands" Menu
Creating Rexx-Adventure games
The Source File Layout
Overview:
The entire data structure is contained in a single Compound Variable, named "Obj.".
There are five system variables. 'Title' identifies the game so that the save files will match the source files. 'PlayerNum' identifies which object is the player. This can allow multiple 'Player' objects, which the user can switch between. 'GlobalNum' defines the object whose Implied Verb takes care of tests to be performed every move. This includes incrementing the Move number, decrementing the number of moves for a light, and the appearance of Dwarves with nasty knives. 'ScrollBack' holds the current page number of the scrollback buffer that is in use. 'ScrollBack.' contains the scrollback buffer.
The data after these first 3 is made up of objects. An object can have 4 properties. Flags: variables specific to that object. (Note, flags are case sensitive). Contents: The Object numbers of any objects contained within the given object. Implied Verbs (IVerb), verbs that are automatic whenever the object is selected, usually used for exits, such as "North" and "up". And Verbs: actions that may be performed with or on the given object.
When the player clicks on an object, either in the Inventory, or in the Nouns box, One of 2 thing happens. If the object has an Implied Verb, the verb is executed. If it has normal Verbs, the list of Verbs is displayed in the Actions box. When a Verb is selected from the Actions box, that verb is executed.
When a verb is executed, its Tests are checked in succession. As soon as the conditions given are met, the Description lines for that test are shown, and the Code lines interpreted.
The source file is defined by individual lines. Each line has a header and a body, seperated by a colon. Lines must be in a certain order, using the following chart:
Header May Follow
; (comment) Anything ( Is ignored )
Intro Anything
Object Anything
Flag Object, Flag
Content Object, Flag, Content
IVerb Object, Flag, Content
Verb Object, Flag, Content, Desc, Code
Test Verb, IVerb, Desc, Code
Desc Test, Desc
Code Test, Desc, Code
Line Type Definitions:
Comments
Any line beginning with a semi-colon, ";", is ignored by Rexx-Adventure. These are used as comments, to describe in more detail the working of an object.
Header lines
The first three non-comment lines are very important.
Line 1, the Title
This line gives the adventure a name. This name is displayed in the title field of the window, along with the current room name of the player object. The title is also used the match saved games with source files.
Line 2 PlayerNum
This variable lets the engine know which of the objects in the game is the player. If you set the wrong value here, you could end up with a sofa that walks around pinking things up.
Line 3 GlobalNum
This variable holds the object number of a very special object. The object specified is expected to have an implied verb. Whenever any verb is executed, the IVerb of object # GlobalNum is executed as well, and ALL matching tests are performed. (Normally only the first is done.) This is useful for taking care of tedious tasks which would cause code to be repeated many times. For example, keeping track of the number ov moves. Without GlobalNum, every Test of every Verb in the entire game would have to increment the Move counter individually.
Object Definitions:
Intro Lines
Syntax: Intro: <Text>
Used to show the opening introduction, printed while the source file is loading.
Object Lines
Syntax: Object: <Obj Number> <Obj Name>
Defines the name and internal number of the object. More than one object may have the same name, but no two objects with the same name may be contained within the same third object.
Flag Lines:
Syntax: Flag: <Flag Name> <Value>
Set the starting value of a flag. Flags are like variables which are attached to objects, and are manipulated with the function GetFlag and the procedure SetFlag. There are a few pre-defined flags you need to know about.
Location - This flag tells where an object is located. For example if a Chair (#2) is in the Living Room (#1), then the 'Location' flag of Object 2 will equal 1.
Holds and Weight - Weight management is built into Rexx-Adventure, but is not required. To use the weight management feature, all objects which can contain other objects must have a 'Holds' flag, and all objects which can be moved must have a 'Weight' flag. The function WeightCheck will return 1 if an object will hold the added weight of a specified object.
For example, the Player object (#1) has a 'Holds' of 10. The player is carrying a Flashlight (Weight = 1) and a Bowling Ball (Weight 7). If the player tries to pick up a Lead Pipe (Weight = 4), the WeightCheck function will return a 0 (total weight 12), but will return 1 if he tries to pick up a Newspaper (Weight 1, total weight 9).
Content Lines:
Syntax: Content: <Object Number>
The Content list specifies what objects are contained within the current object. It is very important that the Content list of a container matches the 'Location' flags of the objects within it. The "DB Check" button which appears in Debug Mode tests all objects for such errors. If these pointers do not match, objects will not move around properly.
Verb Lines and IVerb Lines
These lines define what appears in the "Actions" box. An object can have an IVerb, one or more Verbs, or neither. Verbs and IVerbs can not coexist within the same object.
An IVerb is a verb that is automatic. When there is a door to the north, it makes no sense to click on "North" then have to click on the action "Go". Go is the only action that can be performed! Therefore, as soon as the Object "North" is selected, the IVerb is executed, without waiting for input from the "Actions" box.
Verbs are listed in the "Actions" box when an objec is selected.
Test Lines:
Syntax: Test: <Condition>
Test lines seperate different possibilities of a certain Verb. For example, an axe can be used to chop wood, but only when there is wood in the room. The test is a simple comparison, for example "PlayerNum=3", or "GetFlag(1,'LampOn')=1". If there is only one outcome of a verb, it still must have a test. Use a condition which is certain to be true, such as "1=1".
Desc Lines:
Syntax: Desc: <Descriptive Text>
Description text is entered as one line per paragraph. The "Text" box automatically wwraps the text for you. The text is displayed in the "Text" box.
Code Lines:
Syntax: Code: <Rexx Instructions>
The body of these lines is executed using the Rexx INTERPRET command. You use
Rexx-Adventure functions to move objects, change score, edit flags, and so forth.
Debug Mode
The "Options" menu lets you enter Debug Mode. In debug mode, 3 new items appear on the
Rexx-Adventure window. The DB-Check button checks to assure that the database structure is correct. That is, Object names and Object numbers are properly linked, Flag names and Flag numbers are properly linked, and Content lists match the Location flags of the contents. The results are displayed in the text window.
Above the "Actions" box is an entry field and a button. Rexx instructions are entered in the entry field, and Interpreted when the button is pressed. Note that a syntax error here will crash the enttire Rexx-Adventure program. This is a feature i put in to debug the data structure, and I thought it may come in handy for others too. It is not a feature to be used all the time, and I'm not going to put any time into making it bullet proof.
Appendix 1: Variable Structure.
Obj.0 = the highest object number defined
Obj.# = Object Name;Object comment
Obj.ObjectName = #
Obj.#.!Flags.0 = # of flags
Obj.#.!Flags.# = Value;Name
Obj.#.!Flags.Name = #
Obj.#.!Contents.0 = # of contents
Obj.#.!Contents.# = Object # of contained object
Either
Obj.#.!IVerb = Implied Verb Name (not really used, but handy)
Obj.#.!IVerb.!Test.0 = # of tests
Obj.#.!IVerb.!Test.# = Test Code
Obj.#.!IVerb.!Test.#.!Desc.0 = # of description lines
Obj.#.!IVerb.!Test.#.!Desc.# = Descrition Text
Obj.#.!IVerb.!Test.#.!Code.0 = # of code lines
Obj.#.!IVerb.!Test.#.!Code.# = code text
Or
Obj.#.!Verb.0 = # of Verbs
Obj.#.!Verb.# = Verb Name
Obj.#.!Verb.VerbName = #
Obj.#.!Verb.#.!Test.0 = # of tests
Obj.#.!Verb.#.!Test.# = Test Code
Obj.#.!Verb.#.!Test.#.!Desc.0 = # of description lines
Obj.#.!Verb.#.!Test.#.!Desc.# = Descrition Text
Obj.#.!Verb.#.!Test.#.!Code.0 = # of code lines
Obj.#.!Verb.#.!Test.#.!Code.# = code text
Appendix 2: Sample Object, the Steak.
The following is a sample object with extra comments added to explain its setup.
This is part of the 2 room sample adventure 'SAMPLE.RAD'.
;
; Object 7, the yummy raw steak
;
Object:7 Raw Steak
;
; Weight checking is in use, and the steak has a weight of 1.
;
Flag:Weight 1
;
; The steak is in the kitchen which is object #2.
;
Flag:Location 2
;
; Note that the steak can not contain anything, and therefore has no Content: lines.
;
;
; Nearly all objects will have a Look verb if they do not have IVerbs instead.
;
Verb:Look
;
; the outcome of a Look is always the same.
;
Test:1=1
Desc: The steak is big and juicy. It is also quite raw. You wonder how it could be so fresh without any refrigeration.
;
; this verb defines the object as pick-up-able. If an object is stationary, just don't define a
;"Get" verb.
;
Verb:Get
;
; the function IsHolding(<Object#>) returns True if Object# is contained within object PlayerNum.
;
Test:IsHolding(7)
Desc: You already have the steak, silly!
;
; IsPresent returns True if the specified object is in the same location as the ObjectNum.
; Actually, '1=1' would do the same thing, because only objects contained in PlayerNum, and in
; the same container as PlayerNum are listed, and only listed objects can be selected.
;
Test:IsPresent(7)
Desc: You pick up the raw steak.
Code:Call MoveObject 7, PlayerNum
Code:Call AddScore(5)
;
; This will never happen.
;
Test:1=1
Desc:Error, Error will robinson.
Verb:Drop
Test:IsHolding(7) & (GetFlag(1, 'Location') \= 3)
Desc: You put the raw steak on the nearest suitable surface.
Code:Call MoveObject 7, GetFlag(1,'Location')
Test:IsHolding(7) & (GetFlag(1, 'Location') = 3)
Desc: You toss the steak to the slavering dog. He leaps on it like he has not eaten in weeks. Once he has eaten, the dog seems much friendlier toward you.
Code:Call MoveObject 8, 10 /* send the mean dog to nowhere */
Code:Call MoveObject 9, 3 /* get the happy dog from nowhere */
Code:Call MoveObject 7, 10 /* send the steak to nowhere */
