Implementing New Directions in TADS 3

I have found nothing more frustrating than the past couple of hours spent trying to figure out how to create new directions in TADS 3. For a start, I spent much too long discovering that the one obvious piece of source code on the subject, "Relative Direction System for TADS 3" by Michael J. Roberts (part of Rat In Control) does not in fact show you how to implement new directions, and instead had to figure this all out by searching through the library files.

The default directions are defined in three different files (travel.t, actions.t and en_us.t) and in a style which favours elegance over newbie-accessibility. I can now reveal that implementing new directions in TADS 3 is very simple, when you know how.

You should be able to stick the following code into your files and have it work:

//A new direction object
forwardDirection: Direction
name = 'forward'
dirProp = &forward
//an integer to sort this direction
//relative to other directions
//we'd give 'backwards' greater than 8000
//for example, so 'forwards' is always listed
//before it
sortingOrder = 8000
;

//the grammar rule for this direction object
//type 'forward' or 'f'
//to try and head in this direction
//(more synonyms preferable)
grammar directionName: 'forward' | 'f' : DirectionProd
dir = forwardDirection
;

/*
* According to actions.t:
*
* "To make it more convenient to use
* directional travel actions as
* synthesized commands, [we] define a set of
* action classes for the specific
* directions."
*/
DefineAction(Forward, TravelAction)
getDirection = forwardDirection
;

//kill the old 'forward' command.
//The only useful piece of code I found in
//"Relative Direction System for TADS 3" by
//Michael J. Roberts
//(It has been modified)
replace grammar directionName(fore): ' ': DirectionProd ;

You could then use this in the form:

firstRoom: Room 'The First Room'
"You are in the first room."
forward=secondRoom
;

secondRoom: Room 'The Second Room'
"You are in the second room.
Why not now implement a backward command
so you can get out of here?"
;

This concludes another edition of, "Why doesn't the Internet tell me...?"