Axbasic provides a large set of functions for use with the automapper.
For the most part, we use functions, rather than statements, so we can test whether an action was successful or not. Don't forget that you can use ;axbasichelp to see precisely which values each function returns.
This Section assumes that the Locator task is running and that it knows something about the character's current location.
The Openmap () function opens the automapper window, and the Closemap () function closes it. Only one automapper window can be open at a time, so both functions return the value 1 if the window was successfully opened/closed, or if the window was already open/closed.
If you script needs to know whether the window is open or not, you can use the Ismap () function. It returns 1 if the window is already open.
The Axmud Guide demonstrates how the automapper window can be in one of three modes - wait, follow or update. You can change the mode using the Setmapmode () function.
LET result = Setmapmode ("wait")
LET result = Setmapmode ("follow")
LET result = Setmapmode ("update")
In this case it's especially important to test the result, because the mode you want might not be available, in which case the function returns 0.
The Getmapmode$ () function returns the current mode: one of the strings "wait", "follow" and "update" (or an empty string, if the automapper window isn't open.)
You can automate the process of drawing a map using an Axbasic script, if you want to.
The Addregion () function creates a new region named Mordor. The return value is the region's model number, or 0 if the region couldn't be created.
LET number = Addregion ("Mordor")
Using the Addtempregion () function, you can create a temporary region which is automatically deleted when the automapper window closes. If you don't specify a region name, one is chosen for you.
LET number = Addtempregion ("Mordor")
LET number = Addtempregion ()
Regions can be deleted with the Delregion () function. The function returns 1 on success, 0 on failure.
LET result = Delregion ("Mordor")
The Deltempregions () deletes all temporary regions. It returns 0 only if there are no temporary regions to delete.
LET result = Deltempregions ()
You can test whether a region exists, or not, with the Isregion () function. The function returns 1 if the named region exists, or 0 if it doesn't.
LET result = Isregion ("Mordor")
Note that region names are case-sensitive, so mordor is not the same as Mordor.
You can also test whether a region is temporary, or not. This function returns 1 only if the named region exists and is a temporary region.
LET result = Istempregion ("Mordor")
The same applies to any region that you've marked, for your own convenience, as finished.
LET result = Isfinished("Mordor")
By the way, you can set the visible region using the Setregion () or Setregionnum () functions.
LET result = Setregion ("Mordor")
LET result = Setregionnum (number)
If you want to know which region is the visible one, you can retrieve those same values using the Getregion$ () and Getregionnum () functions.
Once your map has some regions, you can start adding rooms. The Addfirstroom () function draws a room in the middle of the map.
LET number = Addfirstroom ()
The next step is to mark that room as the current room.
LET result = Setroomnum (number)
By the way, if you leave out the room number, the current room is reset, meaning that there is no current room.
LET result = Setroomnum ()
Having done that, you can add new rooms by specifying coordinates relative to the current room. These coordinates must be in the form (x, y, z).
For example, to create rooms immediately to the west and east of the current room:
! Room to the west of the current room
LET result = Addroom (-1, 0, 0)
! Room to the east of the current room
LET result = Addroom (1, 0, 0)
To create rooms to the north and south of the current room, but with a small gap between them:
! Room to the north of the current room
LET result = Addroom (0, -2, 0)
! Room to the south of the current room
LET result = Addroom (0, 2, 0)
To create rooms in the levels immediately above and below the current room:
! Room below the current room
LET result = Addroom (0, 0, -1)
! Room above the current room
LET result = Addroom (0, 0, 1)
Labels are also drawn relative to the current room. As well as specifying the relative coordinates you must specify the label text. For example, to create a label to the southeast of the current room:
! Add a label northeast of the current room
LET result = Addlabel ("This is a label", 2, 2, 0)
There are no Axbasic functions for deleting rooms and labels. You'll have to do that manually.
By default, exits are automatically added to the map as your character moves around the world (if the current room is set, and if the automapper is in update mode).
Axbasic v1.005 adds a number of functions to add or remove exits from a room, or to modify them. In general, you'll need to know the room number. In the examples below, we'll use a room numbered #100.
The Addexit () function adds a single exit to a room, returning the new exit's number.
LET number = Addexit (100, "south")
If the exit isn't in one of one of Axmud's 'primary' directions (compass directions like 'north' and 'southwest', as well as 'up' and 'down'), then the automapper will draw the exit in the first available direction. For example, if this out exit is the room's first exit, it will be drawn in a northerly direction.
LET number = Addexit (100, "out")
If you don't want to leave it to chance, you can specify the direction yourself. The direction must not be in use by some other exit.
LET number = Addexit (100, "out", "west")
Having created the exit, we can connect it to a destination room...
LET result = Connectexit (number, 101)
...and then disconnect it, leaving it with no destination room.
LET result = Disconnectexit (number)
So-called 'twin' exits are a linked pair of exits, usually a two-way exit. A two-way exit might link rooms A and B together, with a "north" exit from room A leading to room B, and a "south" exit from room B leading to room A.
Having created a single exit with a call to Addexit (), we can convert it into a two-way exit with a call to Addtwinexit (). If an opposite exit already exists, it is used; otherwise a new exit is created.
LET twin_number = Addtwinexit (number)
So-called 'hidden' exits exist in the world, but are not always visible in the room's description.
After creating an exit, we can convert it into a 'hidden' exit.
LET result = Sethiddenexit (number)
The same function converts a hidden exit back into a normal exit. Note that 'hidden' exits are always visible in the automapper window.
You can test whether an exit is hidden, or not, with the Ishiddenexit () function. The function returns 1 if the numbered exit is hidden, or 0 if it isn't.
LET result = Ishiddenexit (number)
A 'random' exit is one that has more than one possible destination. The world may select a random destination, each time your character goes through the exit, or the destination may depend on the game state.
After creating an exit, we can convert it into a 'random' exit.
There are a few different types of 'random' exit. For example, the exit may lead to a room in the same region:
LET result = Setrandomexit (number, "same")
Or, it may lead to a room in any region:
LET result = Setrandomexit (number, "any")
In some worlds, travelling through the exit transports the character to a randomly-generated region, which is destroyed when the character leaves the area. In this situation, Axmud can create a temporary region that's deleted at the end of the session.
LET result = Setrandomexit (number, "temp")
To convert a 'random' exit back to a normal exit, just omit the second argument.
LET result = Setrandomexit (number)
Other values are not recognised; you must specify "same", "any" or "temp", if you specify a value at all.
You can get the type of random exit with the Getrandomexit$ () function. It returns one of the three values above, or "none" if the exit isn't random (or doesn't exist).
LET type$ = Getrandomexit$ (number)
(It can also return the value "room", if the exit has a designated list of destination rooms. This type of random exit can't be created by Axbasic, but it can be created manually in the automapper window.)
Exit ornaments give more information about an exit, and are drawn in a different way by the automapper. You can use ornaments to distinguish between locked and unlocked doors, for example.
To add an ornament to an exit, we can use the Setornament () function. For example, to create an ordinary locked door:
LET result = Setornament (number, "lock")
We could also create a door that can't be locked, but can be opened and closed.
LET result = Setornament (number, "open")
Some locked doors can be opened with a lockpick, or broken down by brute strength:
LET result = Setornament (number, "pick")
LET result = Setornament (number, "break")
Some exits are impassable: they are visible in the room's description, but the character cannot actually pass through them.
LET result = Setornament (number, "impass")
A 'mystery' exit is one that is currently impassable, but might be open at some point the future.
LET result = Setornament (number, "mystery")
To remove an exit ornament, just omit the second argument.
LET result = Setornament (number)
Other values are not recognised; you must specify "lock", "open", "pick", "break", "impass" or "mystery", if you specify a value at all.
You can get the type of exit ornament with the Getornament$ () function. It returns one of the six values above, or "none" if the exit doesn't have an ornament (or doesn't exist).
LET type$ = Getornament$ (number)
There are plenty of functions for fetching information about the exits that have already been drawn.
The first step is to fetch the number of exits in the current room:
LET count = Getroomexits ()
Once you have that number - and assuming that it isn't 0, meaning that the room has no exits - you can get the exits' directions. For example, if you know there are three exits in the current room, you can display their directions thus:
PRINT Getexit$ (1)
PRINT Getexit$ (2)
PRINT Getexit$ (3)
Exits are stored in a list in a fixed order, which means that as long as you don't add or remove any exits from the room, Getexit$ (2) will always return the same direction.
Before you retrieve any further information about an exit, you'll need to know its model number. All exits in the map have a number that's unique across all regions, so the following function might return a value like 999:
LET exit_num = Getexitnum (1)
The argument represents the first exit in the current room's list of exits. In a room with three exits, you would use 2 or 3 as arguments, instead.
Once we have the exit's model number, we can find the model number of the destination room.
LET room_num = Getexitdest (exit_num)
Often you can move between two adjacent rooms by going north and then south again. This pair of exits are called twin exits. We can find an exit's twin like this:
LET twin_exit_num = Getexittwin (exit_num)
The Axmud Guide describes various exit types, such as incomplete, unallocated and impassable. The following function returns a string describing the exit type.
LET exit_type$ = Getexittype$ (exit_num)
You might also find the Getexitstatus$ () function useful for working out which exits are connected to rooms in different regions.
An exit in the direction portal might actually be drawn on the map as a north exit. An actual north exit is definitely drawn on the map as a north exit. To get the direction in which an exit is actually drawn:
LET dir$ = Getexitdrawn$ (exit_num)
You can test whether an exit still exists using the Isexit () function. The function returns 1 if the numbered exit exists, or 0 if it doesn't.
LET result = Isexit (exit_num)
Exits can be deleted, if necessary, with the Delexit () function.
LET result = Delexit (exit_num)
The following functions apply to the automapper's current room. To get the room's model number:
LET number = Getroomnum ()
To get the room's title (brief description):
LET title$ = Getroomtitle$ ()
To get the room's verbose description, stored as a single string (even if it was received as multiple lines of text):
LET descrip$ = Getroomdescrip$ ()
To get the room tag or the room guild (or an empty string, if the current room has no room tag or room guild):
LET tag$ = Getroomtag$ ()
LET guild$ = Getroomguild$ ()
You can test whether a room still exists using the Isroom () function. The function returns 1 if the numbered room exists, or 0 if it doesn't.
LET result = Isroom (number)
Rooms can be deleted, if necessary, with the Delroom () function.
LET result = Delroom (number)
The Locator task is capable of extracting a room's current contents. This doesn't work at most worlds, because few MUDs display the contents list in an unambiguous way. However, if the information is available to the Locator task, it's available to your Axbasic scripts.
The Getroomobjects () returns the number of objects in the current room.
LET count = Getroomobjects ()
If you want to, you can restrict that list to the number of sentient beings, or the number of weapons, and so on.
LET count = Getroomobjects ("sentient")
LET count = Getroomobjects ("weapon")
Getroomobjects () only accepts a limited selection of strings: "weapon", "armour", "garment", "char" (for characters), "minion", "sentient", "creature", "portable", "decoration" and "custom".
In a room containing three objects, those objects are numbered 1 to 3. We can retrieve the strings "big axe", "smelly orc" and "pile of treasure" using the following lines:
PRINT Getobject$ (1)
PRINT Getobject$ (2)
PRINT Getobject$ (3)
We can also retrieve each object's type, in this case the strings "weapon", "sentient" and "portable":
PRINT Getobjecttype$ (1)
...
We can furthermore retrieve the main noun, in this case the strings "axe", "orc" and "treasure":
PRINT Getobjectnoun$ (1)
...
This function will tell us whether Axmud believes the object is alive, or not. The function returns 1 for living beings and 0 for everything else, possibly including any nasty monsters you've recently dispatched to the afterlife:
PRINT Getobjectalive (1)
...
Axmud might store 10 gold coins as a single object, or as ten separate ones, depending on the current world profile's settings. In this case, the functions Getroomobjects () and Getobjectcount () return different results:
! Display 1, because Axmud has stored the gold coins
! as a single object
PRINT Getroomobjects (1)
! Display the actual number of objects in the game,
! which is 10
PRINT Getobjectcount (1)
There are few more functions to cover.
A direction like "north" can be abbreviated to "n" using the Abbrevdir$ () function, and restored using the Unabbrevdir$ () function.
LET dir$ = "north"
LET abbrev$ = Abbrevdir (dir$)
PRINT abbrev$
LET old$ = Unabbrevdir (abbrev$)
PRINT old$
REVPATH (a statement, not a function) takes an array of movement commands, and reverses them, transforming north northwest up east into west down southeast south. Here's an example.
DATA "north", "northwest", "up", "east"
DIM stuff$ (4)
FOR a = 1 TO 4
READ stuff$ (a)
NEXT a
REVPATH stuff$
FOR a = 1 TO 4
PRINT stuff$ (a)
NEXT a
If a room's description is different during daylight and at night, Axmud can store both descriptions. You can use the Setlight () function to set Axmud's current light status, and you can use the Getlight$ () function to retrieve it.
(The default values for Axmud's light status are "day", "night" and "dark". The light status is "day" unless it has been changed to another value.)
If you have administrative privileges at your MUD, your map may contain the path to each room's source code file. This path can be retrieved with the Getroomsource$ () function.
If you've added a lot of room tags to the rooms in your map, you can set the current room using a room tag rather than with a model number.
LET result = Setroomtagged ("bank")
Finally, when the automapper gets lost, if remembers the room that used to be the current room. The model number of that room can be retrieved with the Getlostroom () function.