Introduction

ADVSE is a adventure script and story engine that gives you the ability to write your own adventure games. It's written in C++ as this language combines execution speed and object orientation. You'll have to write a game definition file that directs the game and and create your own graphics, etc. The engine uses an interface similar to the well known LucasArts-like games. You can define persons, rooms, things and scripts. The scripts are written in a simple language fitting to the graphic engine. So you can't do everything with this engine, but you can do everything you'll need for a graphic adventure. The interface is very simple, you can click on things (left mouse button) or look at things (right mouse button). We realized that this is enough for an adventure, so this engine can handle two interface actions per object. When you think of existing adventure games and start to playing around with this engine, you'll experience that this isn't really a limitation.

Game description file

The main part of your adventure game is the game description file. In this file you have to put a list of all objects in the game. That are things, persons and rooms. And you have to decide which person is the player at the beginning of the game (yes, player switching is possible). The order of definitions doesn't matter and can be mixed between object types. The basic principle is that every thing must be carried by a person or contained in a room and every person must exist in a room. And of course every thing and person must be unique. Things can be transfered between persons and rooms, persons can be teleportated between rooms. Every object (that means every person, room or thing) can have a flag list that describes the object's state. Every flag can be changed and tested by script commands.

Persons

Persons have to be present in exactly one room. They may carry things, with the same features like rooms (\ref{room}), that means every person is also a collection (\ref{collection}). Every person has a name, a flag list (\ref{flaglist}) and two scripts that are executed every time the player clicks on the person or looks at the person. Again, like with rooms, you may list only what's needed by your game.

Rooms

The base of the game is a list of rooms. Each room has a name, a flag list (\ref{flaglist}), a list of persons (\ref{person}), a list of things (\ref{thing}) and two scripts (\ref{scriptlang}) that are called whenever the player enters or leaves this room. The room's graphics are contained in files that consist of the room's id and a file extension. So there is no need for further data in a room description. Exits are realized by a thing and it's script that teleports the player when he/she clicks on this thing. A room is also a collection (\ref{collection}) for things (\ref{thing}). So you can define which things are contained. For example definitions see the file game.txt. You may define only what you need. If not defined otherwise, the room's attributes hold empty values by default.

Things

Things have to be carried by a person or contained in a room. Every thing has a name and two scripts that are executed when the player clicks or looks at this thing. Additionally you may define one script per thing or per person that is executed whenever you use this thing with the given thing or person. And you can define a special default script, that is called whenever you use the thing with something for that no use script is given. This is similar to the switch command in C++. Again, like with rooms and persons, you may list only what's needed by your game.

Collections

Collections are no real objects in the game, but rooms and persons inherit a collection. A collection contains a list of things. No collections have to be defined directly in the game description file, you'll do that by defining rooms and persons.

Flag lists

Every object has a flag list. You can define any number of flags, each with it's own identifier and it's own integer value. You may set, invert and test flags during the game. You can define one script per flag, that is called, whenever the flag's value changes.

The starting player

Finally you have to decide, which person is the player at the beginning of the game. This is simple, just write a line \\ player IDENTIFIER; \\ to define the player. See the example game file game.txt

The scripting language

This is the real interesting part of the engine. With script commands you can modify any values of any objects you've defined. And you can test the values of flags, describe dialogues, display texts, set flags and so on. There are three special identifiers: this, other and actor. In a script you can refer to the object containing this script with this. In an thing's use script you can refer to the interaction partner with other. In any script you can refer to the player by the identifier actor. Since the player may change it wouldn't be a good idea to refer directly to person identifiers here.

Script commands

call

Call a given script explicitly. After the called script has returned, execution continues after this call.

call

scriptname

;

camera_follow

Set the camera up to follow a person.

camera_follow

personname

;

camera_pan_to

Set the camera up to pan to the given postion in the current room.

camera_pan_to

;

camera_set_to

Set the camera up to the given room and position.

camera_set_to

roomname

;

cutscene

This is similar to call or fork. A new thread is created executing the given script and the game runs in cutscene mode. Cutscene mode is quit automatically when this thread ends or when the user hits ESCAPE. The current thread (the one that executes the cutscene command) goes to sleep until the cutscene ends.

cutscene

scriptname

;

delay

Delay execution of this thread for a given number of milliseconds.

delay

milliseconds

;

fork

This is a non blocking call, that means the given script is called explicitly in a new thread while this thread continues execution simultaneously.

fork

scriptname

;

goto

Jump to a given label, that means continue execution of this thread at the given label. The label must be in the same script. Inter-script jumps are not possible.

goto

label

;

if

Conditional execution command. The expression is evaluated and if it's true (that means unequal to zero), the command after "if" is executed, if the expression is not true, the execution continues after the optional "else" keyword or after the wohle "if"-command if no "else" was defined. There can be ONE command after "if" or "else", but you can use a block as a command (like in C).

(

cond

)

command_if_cond_is_true

(

cond

)

command_if_cond_is_true

else

command_if_cond_is_false

image

Change image of a given thing. If no name of any thing is given, "this" is assumed.

image

filename

;

image

thingname

filename

;

inv_image

Change inventory image of a given thing. If no name of any thing is given, "this" is assumed.

inv_image

filename

;

inv_image

thingname

filename

;

invert

Invert a given flag (boolean invert). That means, if the flag is equal to zero, its value is set to one, or else its value is set to zero.

invert

flagname

;

move

Move a thing to a given room or person (no matter where it was before).

move

thingname

roomname

;

move

thingname

personname

;

print

Print a text string with the specified font and color to the given position.

fontnr

text

;

quit

Quit advse engine. This command quits the game (useful after game has been finished by the player).

quit

;

remove

Remove a thing from whereever it is. Functionally equivalent to "move thing to void".

remove

thingname

;

rename

Rename a person, a room or a thing.

rename

personname

text

;

rename

roomname

text

;

rename

thingname

text

;

return

End execution of current script and return to caller (or end thread if there is none).

return

;

say

Let any person say any sentence. If no person is given, "actor" is assumed. The thread waits until the sentence has finished display.

say

text

;

say

personname

text

;

select

This is the most complex command. A list of sentences is presented to the player, so he can choose one (dialogue!). The thread pauses until the player has made his choice. After that the thread jumps to the label associated with the choosen sentence. You may use "end" as special label, that means jump right after the "select" command. You may give a expression for every sentence, so that it is displayed (and choosen) only when this expression is true. The number of sentences to choose from is not limited by advse (but by memory or screen space).

select	{
	text	,	label
or
	cond	text	,	label
...
}

set

Set a flag to a given value (the result of the evaluation of a given expression). This is an assignment operation (like in C).

flagname

expr

;

set_pos

Set the image's position of any thing. The coordinates are given as expressions.

set_pos

thingname

expr1

expr2

;

showpicture

Displays a picture with the given filename and waits for the user to click any mouse button.

showpicture

filename

;

switch

Switch actor to another person.

switch

personname

;

take

Move a thing from whereever it is to the actor. Functionally equivalent to "move thing to actor".

take

thingname

;

teleport

Move a person to a given room and position.

teleport

personname

roomname

thingname

;

walk

Let a person walk to a given thing inside the room where the person is, or let it walk to another person in the same room. The thread waits until the destination is reached. If the player chooses a new destination for the actor after a thread has started a "walk" command for the actor, the thread is killed (because the old destination can't be reached anymore).

walk

personname

thingname

;

walk

personname

;

while

A simple loop. It is run if the expression is true and as long as it is. Either give a command after while that should get executed in a loop or a block.

while

(

cond

)

looped_command_if_cond_is_true

The tools

Walkmask editor

You have to provide a "walkmask" for every room. A walkmask is a two dimensional mesh, that means a net or graph of faces (triangles) and vertices (points). Only inside the area of a room that is covered by triangles of the walkmask a person can walk or stand. Walkspots should be inside the mask, but not neccessarily. The editor for the walkmask is included with advse2. Its name is simply "walkmask", just run it with the name of a room image as argument. The editor replaces the file extension with ".mask" for the walk mask file name. If a mask with that name exists, it is loaded by the editor. Just use the mouse to edit the mask. Possible modes or commands are available via keys, the keys are printed while editing. Hint: create the vertices surrounding the walk area first, then use "triangulate" and then remove unwanted triangles. Don't forget to save before quitting! The editor is simple, but powerful enough for its task.