-- everything is a location, an object or a timer --

XVAN Library

 
(download as pdf)

Introduction

XVAN is an Interactive Fiction authoring system: a compiler, an interpreter and an authoring language. The XVAN distribution comes with a set of sample stories and a tutorial on how to create an XVAN story from scratch.

Why do I need the Library?

Actually you don’t. The compiler, interpreter and a simple text editor like notepad, textedit or vi are all that is needed to start creating stories.

But the Library offers a head start to begin writing XVAN stories. It has definitions for actions (verbs) commonly used in IF-works, definitions for mandatory objects,  as well as a basic dictionary and a set of attributes, flags and triggers that you most likely will need in your stories.

Everything in the Library is ‘normal’ XVAN code. It can be edited, deleted, expanded or replaced as you wish, as long as you comply with the XVAN language syntax.

The remainder of this document describes the contents of the Library:

  • Actions (in XVAN actions are called verbs);
  • locations;
  • objects;
  • timers;
  • artefacts (descriptions, flags, attributes and triggers);

 The annex describes how to include the Librray in your story.

In case you are unfamiliar with XVAN artifacts, each artifact section starts with a short explanation of the artifact. But you may also want to read the XVAN Introduction document for a more detailed description.

Quickly go to:

Verbs

Locations

Objects

Timers

Artefacts

Descriptions

Flags

Attributes

Triggers

Templates

Verbs

Locations

Objects

Timers

Redefining verbs and common triggers

IFI-XVAN library

Annex: using the Library in your story

 

Verbs

In XVAN, verbs can be more than just words. A verb may contain instructions to be executed as a default handler for user input. Default in the sense that no locations or objects in the story have code to handle the situation.

An example:

$VERB break
  “break [o_subject]”
    printcr(“Trying to break [the] [o_subject] is not particularly helpful.”)
ENDVERB

So, whenever a “break something” command from the user is not handled in the story, the verb will print the message that it’s not very helpful to do this.

The following verbs are available in the Library:

The verbs are listed in alphabetical order.

Verb

Synonym(s)

Description

are

 

 

ask

 

Ask someone about something.

break

 

Break an item.

close

 

Close an item.

cry

 

Cry.

do

 

 

does

 

 

drop

 

Drop an item.

examine

x, investigate

Examine an item.

exits

 

Lists the available exits from the current location. When a destination has been visited before, its name is listed as well.

get

take, grab

Get an item.

give

 

Give an item to someone/something.

go

 

Move through the world.

goto

 

Travel to a location that has been visited before.

hang

 

Hang an item on/in/behind/... another item.

has

 

 

have

 

 

help

 

Turn on/off syntax examples for verbs.

inventory

i

List the player’s possessions.

is

 

 

jump

 

Jump.

kick

 

Kick something.

kill

 

Kill someone.

knock

 

Knock on things.

listen

 

Listen, or listen to something.

lock

 

Lock an item.

look

l

Give long description of room and items in it.

move

 

Move an item.

open

 

Open an item.

poke

 

Poke (in) things.

put

 

Put an item in/on/… something.

quit

q

Quit the game.

read

 

Read an item.

remember

 

Remember something.

restart

 

Restart the game from the beginning.

restore

 

Restore previously saved progress.

save

 

Save current progress.

say

 

Say something to someone.

score

 

Print the player’s current score and the maximum possible score.

sing

 

Sing.

sit

 

Sit on things.

smell

 

Smell or smell something.

tell

 

Tell someone about something.

testmode

 

Read user input from a file instead of the keyboard.

thank

thanks

Thank someone.

throw

 

Throw an item in a direction or at/in/… another item.

tie

 

Tie an item to another item.

touch

 

Touch an item.

transcript

 

Log commands and replies in a textfile transcript.txt

turn

 

Turn an item.

undo

 

Tells that we don’t support undo.

unlock

 

Unlock an item.

untie

 

Untie an item from another item.

unuse

 

Sent by the IFI-XVAN GUI when an icon is dropped on an empty space. Default behavior is drop.

use

 

Sent by the IFI-XVAN GUI when a hyperlink is clicked. Default behavior is examine.

verbose

v

Toggle between always printing long room descriptions or only at first entrance.

wait

z

Wait 1 or more turns.

wear

 

Wear an item.

xyzzy

 

Tribute to Colossal Cave Adventure.

yell

 

Yell.

A more detailed overview of verbs, the input sentences they support and the flags and attributes they use is available in a separate document: “XVAN Library verbs”.

If your story needs additional verbs that are not in the Library, these can just be defined in the game source itself or in an external file that can be referenced from the game file.

Locations

In XVAN, the world is made up of locations. A location can be seen as a room with exits connecting it to other rooms. The player can move from location to location.

The Library version 1.3 has no predefined locations.

Objects

An object is an item that exists in the XVAN world. Unlike a location, it need not be fixed in place, it can be manipulated by the user (taken, opened, closed, destroyed,…).

An object is always contained in another object or in a location. Moving upwards in an object’s containment tree, you will always end up in a location as the top level.

The Library comes with four objects:

 

Object

Purpose

Remark

o_player

Represents the main character that is directed by the person playing the story.

The compiler will throw an error if there is no o_player object defined.

o_nst

No-such-thing object, used when resolving ambiguities in user input.

The compiler will throw an error if there is no o_nst object defined.

o_status_window

Display a status window in the upper part of the text window.

Only used in the Glk version of the interpreter.

o_all

Allows to refer to all objects in scope with certain verbs.

Works for following commands:

“take all”

‘take all from <something>”

“drop all”

“drop all <prepos> <something>”

o_it

Allows to refer to a previously mentioned location or object.

Is updated after every move, with the value of o_subject. Can be loaded with other values by clearing flag o_it.f_update_it and then assigning the desired value to attribute o_it.r_it Value must be a location or object.

If your story needs additional objects that are not in the Library, these can just be defined in the game source itself or in an external file that can be referenced from the game file.

Special note for object o_all

Commands with ‘all’ use common triggers t_take and t_drop that are defined in the Library in the all-object section. These are basic triggers with only necessary checks. In case an object in the game needs extra checks for take or drop, a local trigger with the same name t_get or t_drop must be defined in this object.

Timers

A timer is used to schedule future events, so you don’t have to check for it every turn. A timer has a value and counts up or down from that value. The timer is updated automatically when it’s on. Once a preset threshold is reached, the timer will fire a trigger. An example of the use of a timer is modeling a battery for a flashlight.

 The Library comes with one timer: 

Timer

Purpose

Remark

m_init

Used to start the story. The timer has value 0 and fires at 1. The trigger that is started is o_player.t_init (see artefacts section)

 

If your story needs additional timers that are not in the Library, these can just be defined in the game source itself or in an external file that can be referenced from the game file.

Artefacts

The Library comes with the following artefacts:

Descriptions

A description is an artefact that can hold a string of text. IF works generally have large chunks of text, which makes the code less readable (print statements can become very long and spread out over several lines). By storing the text in descriptions, all text for a specific object can be moved to a central place in the object code, which makes the code better readable.

Descriptions have following syntax:

d_description1   “This is a description text.”

Following descriptions are available from the Library:

All descriptions listed are so called common descriptions –  each location and object has them – unless stated otherwise.

Description

Purpose

Remark

d_sys

Describes how the player can refer to an object or a location.

d_sys may have more than 1 text string if  an object has more than 1 description.

d_exa

Description for examining an object.

 

d_entr_long

Long room description.

 

d_entr_short

Short room description.

 

d_remember

Memory description.

 

 If your story needs additional common descriptions that are not in the Library,  these can just be defined in the game source itself or in an external file that can be referenced from the game file.

$COMMON_DESCRS
  d_descr1, d_descr2, …

Flags

A flag is used to remember yes/no situations: can something be locked, is something locked, is something open, is something alive,

As an example: the verb ‘lock’ uses an object’s flag to check whether the command to lock something actually makes sense.

A flag definition looks like:

f_flag = <1 or 0>

Generally, value 1 (set) means yes and 0 (clear) means no.

Functions setflag() and clearflag() are used to manipulate flags.

Following flags are available from the Library:

All flags listed are so called common flags –  each location and object has them – unless stated otherwise.

Flag

Purpose

Default

Remark

f_alive

Tells if an object is alive.

0

 

f_any

Used to group objects for synchronize() and count() functions.

1

 

f_bypass

Tells the interpreter to always consider this object when mapping user input to objects.

0

System defined.

f_container

Tells if an object can contain other objects.

0

 

f_first

Used to determine when to print the starting text of the item list.

1

Local flag defined with the mandatory player object.

 

 

 

 

f_hidden

Tells the interpreter to never consider this object when mapping user input to objects.

0

System defined.

f_fixed

Tells whether an object is fixed in place.

 

 

f_lit

To determine whether an object is lit.

0

System defined.

f_lockable

Tells if an object can be locked.

0

Says nothing about the object actually being locked.

f_locked

Tells if an object is locked.

0

 

f_may_save

Tells if the game may be saved.

1

Local flag defined with the mandatory player object.

f_opaque

If no, object is see through.

0

System defined.

f_open

Tells if an object is open.

0

 

f_openable

Tells if an object can be opened.

0

Says nothing about the object actually being open.

f_scenery

 

0

 

f_seenbefore

If yes, short room description will be printed.

0

 

f_supporter

Tells is an object is a supporter (i.e. something can be put on it).

 

 

f_swap

If there is more than 1 system description, the interpreter will refer to a location or object with the same description as the player used.

0

System defined.

f_takeable

Tells if an object can be picked up.

0

 

f_verb_help

Used to determine if  verb syntax examples are active.

1

Local flag defined with the mandatory player object.

f_verbose

Tells whether to always print long room descriptions

0

Local flag defined with the mandatory player object.

f_wearable

Tells whether an item can be worn

0

 

f_worn

Tells whether an item is actually worn.

0

 

 If your story needs additional common flags that are not in the Library,  these can just be defined in the game source itself or in an external file that can be referenced from the game file.

$COMMON_FLAGS
  f_flag1 = 0
  f_flag2 = 1

Attributes

An attribute is used to remember information other than yes/no. Attributes can contain pretty much any type of information: location, object, number, description, another attribute, …

The “=” operator is used to assign a value to an attribute:

r_attribute = <value>

Following attributes are available from the Library:

All attributes listed are so called common attributes –  each location and object has them – unless stated otherwise.

Attribute

Purpose

Default

Remark

r_do

Storing an item’s conjugation for ‘to do’

does

 

r_have

Storing an item’s conjugation for ‘to have’

has

 

r_is

Storing an item’s conjugation for ‘to be’.

is

 

r_key

Store he key that unlocks a locked item.

none

 

r_max_score

The maximum score for the story.

0

Local attribute defined with the mandatory player object

r_nr_to_reveal

The number of items that must be printed when opening a container.

0

Local attribute defined with the mandatory player object

r_preposition

Building correct sentences when referring to an item’s position.

none

System defined.

r_score

The player’s current score.

0

Local attribute defined with the mandatory player object

 If your story needs additional common attributes that are not in the Library,  these can just be defined in the game source itself or in an external file that can be referenced from the game file.

$COMMON_ATTRIBUTES
r_attr1 = <value>
r_attr22 = <value>

Triggers

A trigger is a small program that is executed based on the input from the person playing the story. XVAN has a number of functions that can be used in triggers.

An example of a trigger is:

t_hidden_passage
  printcr(“Moving the rock reveals a dark passage down!”)
  printcr(“Your score just went up by 50 points.”)
  newexit(%this, down, l_cave)
  o_player.m_score += 50
  agree()

Explanation: this trigger creates a new exit from the current location downwards to the cave. The player’s score is increased with 50 points.

Printcr() and newexit() are examples of XVAN functions. An overview of XVAN functions is available in the document: “XVAN functions”.

We link the trigger to the applicable user input through a statement like:

“move [o_rock]” -> t_hidden_passage

This tells the interpreter to fire the trigger when the user command resolves to “move rock”.

The Library comes with the following triggers:

Description

Purpose

Remark

t_init

Starts the story. Prints the opening message and does some other stuff.

This is a local trigger defined in the player object’s trigger section.

t_move

Lets the player object travel through the world.

This is a local trigger defined in the player object’s trigger section.

t_entrance

The entrance() function calls the t_entrance trigger for each object in scope. The entrance() function is usually called when the player enters a new location.

 

t_i

Prints the item’s description for the inventory command.

In case an item must respond to the inventory command, the statement “inventory” ->t_i must be in the item’s trigger section.

t_reveal

Is used for printing a list of items separated by commas.

Attribute r_nr_to_reveal must be set to the correct value.

If your story needs additional common triggers that are not in the Library,  these can just be defined in the game source itself or in an external file that can be referenced from the game file.

$COMMON_TRIGGERS
  t_trigger1
    <trigger code>

  t_trigger2
    <trigger code>

Templates

The Library can be  used with any IF work created with XVAN. This gives a head start, you now only have to think about  locations, objects and timers.

Note: use the template files that come with the Library. Copy/pasting the templates from the text in this document may contain formatting characters that will cause compile errors.

Verbs

A verb can be defined in the story file with following syntax:

$VERB name
  PROLOGUE
    <actions to be performed before anything else for this verb is done>

  EPILOGUE
    <actions to be performed after everything for this verb has been done>

  “user command to respond to”
    <…code…>

  “user command to respond to”
    <…code…>

  DEFAULT
    <code to execute wen nothing else fired>
ENDVERB

User input is offered to locations and objects first. If the input is not handled there, then it is offered to the verb. Exception: the verb prologue – when present – is always executed first.

The Library comes with 48 verbs and some synonyms.

Locations

A location can be defined in the story file with following syntax:

$LOCATION l_location-identifier # location names must start with ‘l_’
  DESCRIPTIONS
    d_sys                   “system description 1”, “system description 2”
    d_entr_long      “long description, printed when entering the location”
     d_entr_short    “short description”
    d_other              “other descriptions”

  FLAGS
    f_flag1 = 0
    f_flag2 = 1

  ATTRIBUTES
    r_attribute1 = <attribute value>
    r_attribute2 = <attribute value>
  TRIGGERS
    some command that the player typed”    -> t_trigger1
    “teleport to [l_starship]”                             -> t_trigger2

  t_trigger1
    # code for trigger 1, sample below
    printcr(“You have started trigger 1.”)
    agree()

  t_trigger2
    move(o_player, l_starship)
    entrance(l_starship) # call t_entrance for starship and contained objects
    agree()
END_LOC

 Some remarks:

  • Lines starting with ‘#’ are comments.
  • Location identifiers must start with ‘l_’
  • l_location-identifier is only used in XVAN code to refer to the location.
  • d_sys descriptions are used to map user commands to the location.
  • d_sys text strings therefore must obey XVAN English grammar rules and must be in the dictionary

Objects

An object can be defined in the story file with following syntax:

$OBJECT l_object-identifier # location names must start with ‘o_’
  DESCRIPTIONS
    d_sys                 “system description 1”, “system description 2”
    d_entr_long     “long description, printed when entering the object’s location”
    d_entr_short   “short description”
    d_exa                “printed when the object is examined”
    d_other            “other descriptions”

  CONTAINED in l_location-identifier

  FLAGS
    f_flag 1      = 0
    f_takeable = 1  # may be picked up
  
  ATTRIBUTES
    r_attribute1 = <attribute value>
    r_attribute2 = <attribute value>

  TRIGGERS
    “some command that the player typed”  -> t_trigger1
    “inventory”                                                    ->t_i         # common trigger not defined here

    t_trigger1
      # code for trigger 1, sample below
      printcr(“You have started trigger 1.”)
      agree()
END_OBJ

 Some remarks:

  • The CONTAINED section tells where the object is located (location or other object).
    Other prepositions than ‘in’ may also be used. The preposition will be stored in the object’s r_preposition attribute, so it can be used in trigger code for printing, testing etc.
  • The t_i trigger is not defined with the object because it is a common trigger (see artifacts section).
    You may define a t_i trigger locally in the object’s trigger section if you need behavior that is different from the common trigger. The local trigger will then override the common trigger.

Timers

A timer can be defined with following syntax:

m_timer-id   # timer names must start with ‘m_’
 value  <number>  
 step  <number> # number to increase/decrease by
 direction  up / down  
 interval  <number> # update interval (1 updates every turn)
 state  go / stop  
 trigger_at  <number>  [or_more] / [or_less
 execute  <trigger>  

 Some remarks:

  • Because a timer is defined stand alone and not within a location or an object, the trigger to be executed must be preceded by the location or object to execute it for. E.g. o_lamp.t_empty.
  • The state can be manipulated with functions starttimer() and stoptimer().

Redefining verbs and common triggers

Suppose you need a verb or a trigger from the Library to behave different than is coded in the Library.

As an example, let’s assume you want the command ‘x’ not to be a synonym for ‘examine’ as defined in the Library, but to be a command to return the player’s to his previous location.

If you just add a new verb “$VERB x”, the XVAN compiler will throw a multiple defined verb error, because ‘x’ is already defined as a verb.

One way to handle this, would be the change the code in the Library:

$VERB examine SYNONYM x
  < …code… >
ENDVERB

would become:

$VERB examine
  < …code… >
ENDVERB

And you would define a new verb in your story:

$VERB x
  move(o_player, o_player.r_previous)
  entrance(o_player.r_previous)
ENDVERB

Although this works perfectly well, it introduces a version control issue with the Library as there is now a Library version specifically for this story. When distributing the sources of your story, you must also distribute the modified Library.

To prevent this issue, from XVAN 2.3.2 it is possible to redefine verbs and common triggers. In the example above it suffices to just redefine the verb ‘x’.

$REDEFINE_VERB x
  move(o_player, o_player.r_previous)
  entrance(o_player.r_previous)
ENDVERB

The XVAN compiler will remove ‘x’ as a synonym for examine and assign it to the new code. It is also possible to create synonyms with a redefine.

$REDEFINE_VERB x SYNONYM exit SYNONYM out
  move(o_player, o_player.r_previous)
  entrance(o_player.r_previous)
ENDVERB

Analogue to  $REDEFINE_VERB there is also $REDEFINE_TRIGGER, which redefines a common trigger.

IFI-XVAN library

As of XVAN version 2.3.4, a version with a graphical user interface (GUI) is available: IFI-XVAN.

IFI-XVAN consist of a back-end and a front-end, the back-end being XVAN and the front-end being the Brahman GUI developed by Strandgames. XVAN and GUI communicate by exchanging text strings according to the JSON-format.

The IFI Library contains several verbs, flags, attributes and triggers that are used by XVAN to communicate with the GUI. E.g. sending possible exits, updating the player’s current location, sending file names from pictures etc.

Note: for information on how to “ifify” an XVAN story, please refer to the IFI-XVAN document.

At the end of each turn, all necessary updates are sent to the GUI. This is an automatic process that does not require any coding by the author, as long as you use the IFI Library.

Following locations, objects, timers and artefacts are in the IFI library:

Verbs

Verb

Synonym(s)

Description

ifi_exits

--

Sends the current location’s exits to the GUI.

ifi_items

--

Sends the player’s inventory to the GUI.

lfi_people

--

Sends a list of characters the player has already met to the GUI.

ifi_loc

--

Sends the player’s current location’s id to the GUI.

ifi_map

--

Sends the story’s map data to the GUI.

ifi_picture

--

Sends the current locatoi’s background picture to the GUI.

Ifi_update_gui

--

Executes all of the above verbs.

 

Locations

Locations

Purpose

Remark

l_json

Home for several flags, triggers, attributes etc.

 

Objects

The ifi library has no predefined objects.

Timers

Timer

Purpose

Remark

m_ifi

Triggers the t_ifi trigger from l_json at the end of each move.

 

 

Descriptions

Description

Purpose

Remark

d_map_backimage

Used to store pathname of the story’s opening screen background image.

Path is always \images\coverimage.png relative to the datadir.

This is a local description with location l_json.

 

Flags

The ifi library has no predefined flags.

Attributes

Attribute

Purpose

Default

Remark

r_gx

A location’s x-coordinate on the map.

0

 

r_gy

A location’s y-coordinate on the map.

0

 

r_ifi_picture

Hold a location’s picture file path.

“”

 

r_ifi_icon

Hold an object’s icon file path.

“”

 

r_ifi_maplevel

Height level on a 3D map

0

Attribute with l_json object.

r_ifi_maptext

Header text for the map

0

Attribute with l_json object.

Advice is to define descriptions in the story and use t_entrance triggers to assign the right description to r-ifi_maptext.

 

Triggers

Description

Purpose

Remark

t_ifi

Execute all necessary ifi-actions at the end of a move.

Is a local trigger with location l_json.

t_ifi_items

If the object is in the player’s inventory, the object id and icon path will be sent to the GUI to display in the inventory.

 

t_ifi_items_id

Sends the object id to the GUI to display on the map.

Only applies to objects that are directly in the location (and not in other objects).

t_ifi_people

If the player has met the object before, it will send the object’s id and icon to the GUI.

Tests common flag f_seenbefore from the character.

t_ifi_place

Sends location information to the GUI.

Position on the map, exits, name, id, contained items. Used to draw the map.

t_ifi_exits

Sends exit information for a location

Used to render the clickable compass rose on the GUI.

 

Annex: using the Library in your story

The XVAN Library is a single file called something like “XVAN Library x-y.lib”.

The file must be placed in the same folder as your story file(s). In your story file, insert the .lib file with the line:

· $insert ".\\XVAN Library x-y.lib"

or

· $insert “.//XVAN Librray x-y.lib”

 

.

 

  (c) Marnix van den Bos contact: marnix@xvan.nl