Chances are if you’re reading this book you’re already at least a little familiar with adventure games, and maybe even more specifically interactive fiction or text adventures.⁠^[1] Hugo is a system for designing, programming, and running these. It is not the first such system — and it’s difficult to find substantial fault in any general way with the best of those systems that predate Hugo⁠^[2] — but Hugo does hope to extend the concepts developed in earlier, similar systems in order to make interactive fiction programming less cryptic, and more flexible and accessible to designers, as well as to add functionality in certain areas where other systems are lacking.

What does it mean to be a “system” for interactive fiction? In Hugo’s case, it means that not only does it provide an environment for running Hugo games — the rather exciting-sounding Hugo Engine — but also the means of creating them (the Hugo Compiler) and a tool for troubleshooting (the Hugo Debugger). Additionally, it includes the Hugo Library, in essence a suite of Hugo programming code providing the basic infrastructure for a Hugo game.

This book will serve as a means of becoming familiar with what Hugo is and what it does, and what is required to develop an interactive fiction game using Hugo, whether or not you have any prior programming experience.

Please see the Hugo License for detailed legal information. Hugo is copyrighted by its Author. Programs created using the Hugo Compiler are the property of the individual user who created them. The use of the Hugo library files (the “Hugo Library”) and the distribution of the Hugo Engine are authorized for the creation of non-commercial or shareware-based software. The use of the Hugo Library is allowed in commercial software, although copyright of the library files themselves remains with the Author. Commercial distribution of the Hugo Compiler, the Hugo Engine, and/or the Hugo Debugger may be allowed by arrangement with the Author. The source code for the Hugo Compiler, the Hugo Engine, and the Hugo Debugger (the “Hugo Source Code”) is available for porting to new platforms. Public distribution of modified versions of the Hugo Source Code is not permitted.

Those who have taken upon themselves the task of porting Hugo to various platforms include Julian Arnold (Acorn/RiscOS port), Gerald Bostock (OS/2 port), David Kinder (Amiga port), Bill Lash (original Unix/Linux port), Andrew Plotkin (Macintosh port using his Glk library), and Colin Turnbull (original Acorn Archimedes port). The author is considerably indebted to them, for all their work as well as for their input on how to improve the compiler and engine. Without their efforts, Hugo and the games created with it would not be available for so nearly as wide an audience.⁠^[3]

More than a few words of appreciation must be given to Volker Blasius, the original maintainer of the Interactive Fiction Archive at GMD, one of the key resources for interactive fiction players and developers, and a primary hub of material for contributors to (and readers of) the Usenet newsgroups rec.arts.int-fiction and rec.games.int-fiction. For years, Volker (earlier with the help of David M. Baggett and later with the help of David Kinder) undertook the substantial task of organizing and cataloguing thousands of existing files and a steady stream of new submissions. The IF Archive is now, as of this writing, housed on the web at https://www.ifarchive.org, and is currently maintained by David Kinder and Stephen Granade.

Thanks also to those whose comments and suggestions have contributed to making Hugo as powerful and usable as it is: Torbjörn Andersson, Julian Arnold, Dmitry Baranov, Mark Bijster, Jonathan Blask, Cam Bowes, Jason Brown, Daniel Cardenas, Jose Luis Cebrian, Gilles Duchesne, Jason Dyer, Miguel Garza, Jeff Jenness, Doug Jones, Alan MacDonald, Cena Mayo, Jesse McGrew, John Menichelli, Iain Merrick, Jim Newland, Jerome Nichols, Jason C. Penney, Giacomo Pini, Andrew Pontious, Vikram Ravindran, Gunther Schmidl, Robb Sherwin, Christopher Tate, Mark J. Tilford, Paolo Vece, and Dean Tessman, as well as to many other Hugo users. Graham Nelson’s Inform language helped give early shape to some of the ideas in Hugo’s development with regard to syntax and structure. Finally, sincere apologies on my part for any omission of those who have contributed to Hugo over the years in any way.

And thank you, as always, to Jennifer.

Please refer to the following conventions as they are used in this manual:

A number of files are part of the basic Hugo package. You’ll need to make sure to have these before you get started; a good starting point is the Hugo web page at https://www.generalcoffee.com/hugo.

Executable package. You’ll need, first and foremost, a version of Hugo compiled for your particular computer system, which will allow you to run existing Hugo programs, as well as compile and run your own. Usually the package itself is named something like:

although filenaming may vary between platforms. Generally, like in the examples above, Hugo comes in an archive file containing the various executables for a given platform. The package should contain the following files (although, again, filenames may differ; they’ll generally appear as filename, although on your system they may be lowercase or some combination of upper and lowercase, and the filename extension may vary or be absent):

Please note that the Hugo Compiler and the Hugo Debugger are not available for all systems; some packages for some systems contain only the Hugo Engine for playing Hugo games. To develop and compile your own games, the Hugo Compiler is necessary. The Hugo Debugger is a useful and powerful tool, but it is not essential for Hugo development.

Library package. You may be relieved to learn that you don’t have to write every last part of a Hugo game yourself. In fact, much of the basic infrastructure is provided by the Hugo Library, a set of existing Hugo source code files that you include in your game to manage the game world. Using the Hugo Library, you can easily create a small game that incorporates the basic behavior of a standard Hugo game. Normally these files can be found in a single archive called hugolib.zip:

The library also includes these three less commonly used files:

Additionally, the library contains two sets of files that, depending on user-specified settings, are optionally included by hugolib.h:

Sources. It’s probably a good idea as you delve into Hugo programming to have some existing source code to look at. sample.hug is a valuable resource to have handy since it contains examples of most aspects of Hugo programming. Additionally, you’re going to want to download shell.hug, which provides the very bare bones of a Hugo game for you to start building on:

An additional Hugo source file demonstrates the ability to create precompiled headers (and not something you probably need to worry about just now; it’s covered in App. E, Precompiled Headers):

Extras. The last essential remaining piece you’ll need to begin Hugo development in earnest is a text editor of some sort. This is what you’ll use to edit the Hugo source files that you’ll write and ultimately compile into working Hugo programs. On Windows or Macintosh you could use the pre-packaged Notepad or SimpleText (or TextEdit on Mac OS X) applications, respectively, but it’s really not recommended: there are far better inexpensive or even freeware editors available (and once you get deeper into programming, you’ll realize that the one sure investment you can make is an editor you’re comfortable with). On Unix-ish systems (including Linux), you’ll generally have a choice of editors including Emacs, vi, and a number of graphical user interface (GUI) programs. It’s a little beyond the scope of this book to even attempt to recommend an editor — since it’s as much a matter of personal preference as anything — so the best advice that can be given is to ask around, experiment, and find out what works best for you.

It would also be good preparation to become familiar with the terminal or console on your system. On Windows, this is the “MS-DOS Prompt” or “Command Prompt” under the Start menu, or type “command” (Windows 95/98) or “cmd” (Windows NT/2000/XP) from the “Run…​” option; on Unix systems, this will be bash or tcsh or some other kind of command shell. Other systems will have different names for their command-line environments (although on something like a pre-OS X Macintosh, there is no such thing as a terminal or console, so you needn’t worry about it).

The truth about writing interactive fiction games is that yes, it is programming, and no, there’s really no way around it. It’s impossible for a game design system to provide a cookie-cutter means of picking and choosing all the various facets of any relatively complex game so that by clicking on a few buttons a fully formed and entirely original game world and story will be produced. It doesn’t work that way. The attempt to determine at the outset all of the various game elements that will ever be needed by any game author in any type of game necessarily limits what authors are able to include in their games, as well as their ability to tailor gameplay, presentation, character interaction, geography, and other important aspects of a game to the needs of the particular work of interactive fiction they’re writing. So, in order to write the best interactive fiction games you’re capable of, you’ll need to do a at least a little programming. But that’s not reason to fret.

The word “programming” seems to hold a sort of mystique that, to the non-programmer, conjures up some unfathomable combination of knowledge and skills that shall remain forever inaccessible to outsiders. In fact, that’s pretty far from the truth. Programming is indeed a creative pursuit, but it is pretty much unique among creative pursuits in that it’s the only one that can be overcome by enough banging of keys: eventually you can make almost anything work.

If you’ve never done any programming before, you can probably expect to be slightly baffled by at least some of the early going in this manual. The truth about learning programming is that you’re probably not going to be able to read through this book (or any book on programming in any other programming language, for that matter) once, in proper sequence, from cover to cover, and be able to write programs expertly in the language. Many of these things will require the introduction of concepts that will only be discussed in full later on once a better grounding in the language is achieved. There will, in fact, be several places in this book (especially in the early sections) where readers will be encouraged to not worry if the subject matter at hand seems quite foreign. But rest assured that, after a brief initial period of acclimation, before long things like “objects”, “properties”, “routines”, “global variables”, “calling parameters”, and a host of others will be rolling off your tongue like the alphabet.

To make everything even easier, Hugo is designed so that writing very basic games will consist largely of defining and describing objects and locations in a very straightforward manner. All of the complex inner workings of the game — from the templates for standard rooms and objects and their related behaviors; to what happens when a player types >GO NORTH or >OPEN THE CARDBOARD BOX or any other command, recognized or unrecognized; to the rules of the game world for containment, edibility, bulk, switching things on or off, or any number of “physical” traits — are handled by the Hugo Library, and a prospective doesn’t have to worry about where these things are handled or how until he or she is ready to investigate deeper.

The way Hugo works is fairly standard for a modern programming language. A programmer begins with a source file, which is a human-readable text file (created and edited in a separate text-editing application). The source file contains all the various definitions, instructions, and other text that will ultimately form the content of the game. The content of a source file is formatted in the particular structure of the Hugo language — the programming language with which the majority of this manual will endeavor to help you become acquainted.

The programmer inputs the source file to a compiler (here, specifically, the Hugo Compiler), which takes the source code and generates an object file. The object file is — unlike a source file — not human readable, but has instead been translated by the compiler into a series of optimized instructions that are easily understood by the computer. The computer can then take that object file and execute it as a program, just like any application users regularly use (applications — like word processors and spreadsheets and browsers — which were probably produced by a compiler in exactly the same process as described here). The difference between a Hugo-generated program and such other compiled programs is that a Hugo program may, once compiled, be run on any platform for which the Hugo Engine exists. Normally a compiled program can only be executed on the platform for which it was compiled; Hugo programs are much more portable, and can be compiled on one platform and subsequently be run on any other of the large number of platforms that Hugo supports.

The Hugo Engine is the interpreter or runtime for compiled Hugo object files (also referred to as .HEX files, after their default extension meaning “Hugo executable”). It functions as a hosting environment in which to load the .HEX file, in sort of the same way that a browser loads a web page from the Internet.

Let’s take the first step by becoming acquainted with the tools we’ll be using. First and foremost is the Hugo Compiler. Compiler usage instructions may vary slightly depending on what computer and operating system you’re using.

If you’re using a GUI version of the compiler (such as the one for Windows), when you start the compiler it will display a form for you to enter the name of the Hugo program you want to compile, along with any other compilation options.

If you’re running a command-line version of the compiler, it will behave pretty much the same regardless of what system you’re on. Type

without any parameters to get a full listing of available compiler options and specifications. For example, the Unix and MS-DOS syntax for running the compiler is

It is not absolutely necessary to specify any switches, the name of the objectfile, or the sourcefile extension. The bare-bones version of the compiler invocation is

With no other parameters explicitly described, the compiler assumes an extension of .hug. The default object filename is <sourcefile>.hex.

Here’s how to compile the sample game from the sample.hug source code mentioned earlier in Sec. 1.5, “Packing List”. Make sure the compiler executable, library files, and sample game source code are all in the current directory, then type

or simply

and after a few seconds (or more, or less, depending on your processor and configuration) a screenful of statistical information will appear following the completed compilation (because of the -s switch). The new file sample.hex will have appeared in current directory. As well, the -l switch wrote all compile-time output (which would have included errors, had there been any) to the file sample.lst.

A number of switches may be selected via the invocation line. These are one or more single-letter (usually, at least) options that follow a - character. The available options are:

Also included on the invocation line before the sourcefile may be one or more limit settings. These settings are primarily for memory management, and limit the number of certain types of program elements, such as objects and dictionary entries. In order to allow the compiler to function optimally across a range of different computer platforms with differing memory management capabilities, the compiler does not automatically allow an unlimited number of all language elements. For the most part, you won’t need to worry about upping any of these settings until your Hugo games begin to reach larger sizes.

To list the settings, type:

You’ll see something like:

To change a non-static limit (and compile a source file), type:

For example, to compile the sample game with the maximum number of dictionary entries doubled from the default limit of 1024, and with the -l and -s switches set,

If a compile-time error is generated indicating that too many symbols of a particular type have been declared, it is probably possible to overcome this simply by recompiling with a higher limit for that setting specified in the invocation line.

See App. C, Limit Settings for a complete listing of valid limit settings.

It is possible to specify where the Hugo Compiler will look for different types of files. This can be done in the command line via:

For example, to specify that the source files are to be taken from the directory c:\hugo\source, invoke the compiler with

Valid directories (which can be listed using hc @list) are:

Advanced users may take advantage of the ability to set default directories using environment variables. (The method for setting an environment variable may vary from operating system to operating system.) The HUGO_<NAME> environment variable may be set to the <name> directory. For example, the source directory may be set with the HUGO_SOURCE environment variable. Command-line-specified directories take precedence over those set in environment variables. In either case, if the file is not found in the specified directory, the current directory is searched. (And if you’re not familiar with environment variables, again, don’t worry about it.)

Once the sample game has been successfully compiled, you can run it with the help of the Hugo Engine. The way in which you do this will vary depending on what platform you’re using.

By now, you should be able to:

Here’s an example: on the author’s machine, running under a Unix-like command line, the compiler executable hc is in a directory called /boot/home/hugo. The library files are in /boot/home/hugo/lib, and the source code for the game Future Boy! is in /boot/home/hugo/fb, with the main source file called future.hug.

It’s possible to call the compiler to compile Future Boy! with a number of different options, including specifying the appropriate directories for source and library files, increasing the maximum possible number of routines, and printing all debugging information, the object tree, and statistics to a file. (Assume that the current directory is /boot/home/hugo and that none of the switches or directories are set in the source.)

Here’s how that’s done:

(or hc -lios '$maxobjects=512' '@source=fb', etc. if the command shell requires that sequences beginning with $ or @ be contained in single-quotes or otherwise escaped).

This makes use of various command-line options, including multiple switches, limit settings, and directory specifications. It sets the desired switches, changes the modifiable limit MAXOBJECTS from the compiler default, and points the compiler to look for source files in the source subdirectory and library files in the lib subdirectory (from the current directory).

There are a couple of basic concepts to become familiar with in order to begin working with Hugo. Once you begin to become familiar with them, you will hopefully be able to look at a chunk of Hugo source code and — even if you don’t understand everything it’s doing — be able to at least get a sense of the general organization.

First of all, the bulk of programming in Hugo will involve the creation of what are called objects. The word “object” in this sense has two meanings. First of all, in a programming sense, objects are discrete subsections of source code. They are referred to by individual names, and they “do something”, whether that something is storing data or performing some set of functions or both. In the case of Hugo, however, these are not just abstract tools for structuring a program. Hugo objects are, more often than not, also representative of objects in the “physical world” of the game: people, places, and things. If, for example, you want to create a book in your game, you’ll create a book object that may comprise the description of the book, what’s written in it, how much it weighs, how many pages it has, what happens when you drop it, and anything else you choose to implement.

The rest of a Hugo program is mostly comprised of routines. These are the sections of code made up of commands or statements that facilitate the actual behavior of the program at different points in the story. (Routines can also be part of a containing object — we’ll get to that in a little while.) Routines are less frequently (although more frequently in other languages) called “functions” — they may be thought of as performing an operation or series of operations, and then optionally returning some kind of answer or result. A program may have a routine called DescribePlace which, when invoked (or “called”, in the parlance of programming) would print the description of a given location. The point of routines is that you don’t have to repeat the same code every time you want a particular task done: you just have to call the routine. Write once, use many times.

The idea of return values from a routine is an important one and, while sometimes puzzling to novices, is actually quite uncomplicated. For instance, often a particular function will be described as “returning true” or “returning false” — all this means is that when it’s done it returns either a non-zero value (usually 1) or a zero value, usually to indicate whether the function was successful or not at whatever it was being asked to do. A program will constantly be checking the return values of the routines it calls to determine if particular operations have been successful in order to decide what to do next. A routine can return any kind of value (listed shortly in Sec. 2.3, “Data Types”). A very simple example is a routine that performs a needed operation, such as adding two supplied values, a and b. Let’s call it AddTwoValues. When AddTwoValues is called with the two supplied values, it will return the sum a+b.

For those familiar with the common programming languages such as C or Basic (including Visual Basic), Hugo will not be entirely visually unfamiliar. Individual objects and routines — as well as conditional blocks — are enclosed in braces as in C ({…​}), but unlike C and other C-like languages, a semicolon is not required at the end of each line to tell the compiler when the line is finished, and the language itself is considerably less cryptic. Keywords, variables, routine and object names, and other tokens are not case-sensitive.

In the time-honored tradition of programming texts, the introduction to a new programming language is quite often a description of how to print the optimistic phrase “Hello, world” as an example of that particular language’s form and substance. In the almost-equally time-honored tradition of interactive fiction, we’ll start with the rallying cry “Hello, Sailor!”. Here’s how one accomplishes that in Hugo:

The entire program consists of one routine.

The Main routine is automatically called by the engine. It is from here that the central behavior of any Hugo program is controlled. In this case the task at hand is the printing of “Hello, Sailor!”, followed by a wait for a keypress (the pause) and an order to exit the program (i.e., quit it) so that we don’t strand the program waiting for input from the player, which is the normal order of Hugo business.⁠^[4]

Computer programs are mainly about two things: input and output (called i/o, for short), and modifying values. In fact, the bulk of a computer program (that is, what happens behind the scenes, whirring away, unbeknownst to the user) consists of setting, changing, and comparing various values. Hugo is no exception. All data in Hugo is represented in terms of 16-bit integers,⁠^[5] treated as signed (-32768 to 32767) or unsigned (0 to 65535) as appropriate. It’s up to the compiler and engine to decide what a particular value means in a given context. The name of any individual data type may contain up to 32 alphanumeric characters (as well as the underscore _).

All of the following are valid data types:

Most of these types are relatively straightforward, representing in most cases a simple value. As noted, some values are dynamic (modifiable), while others are static (non-modifiable). Dictionary entries are addresses in the dictionary table (comprising all dictionary words in the .HEX file), with the empty string "" having the value 0. Array addresses (as opposed to separate array elements) represent the address at which the array begins in the array table (comprising all array data in the .HEX file). Properties and attributes treated as discrete values represent the number of that property or attribute, assigned sequentially as the individual property or attribute is defined.

As mentioned, routines also return values, as do built-in⁠^[6] engine functions, so that

and

are also valid integer data types.⁠^[7]

It’s good medicine to be as descriptive as possible in naming symbols, regardless of what you’re naming. A variable that holds the count of a number of objects could be called n, but it’s almost always better (especially after the fact, when you’re looking at code you’ve written days or even months before) to call it something more helpful like object_count.

At this point it’s probably helpful to know that you can assign a value to a variable using the form:

For instance, to set the variable x equal to 5, you would use:

To set it equal to element 4 of array some_array, you would use:

When you want to get the return value of a routine, you would use:

If, then, you ever need to get the indexed address of a routine to use it as a value, as you may at some point, you obviously won’t be able to do:

again and hope that this time it will assign the address of Routine to the variable x, since that will assign to x the value returned by Routine. Instead, you can use the address operator &, as in:

which won’t actually call Routine but will instead only assign the routine’s address to x.

If any single command is too long to fit on one line, it may be split across several lines by ending all but the last with the control character \.

and

are the same as

and

String constants, such as in the below print statement, are an exception in that they do not require the \ character at the end of each line (although, as shown just above, it’s not wrong to use it).

will result in:

Care must be taken, however, to ensure that the closing quotes are not left off the string constant. Failing that, the compiler will likely generate a “Closing brace missing” or similar error when it overruns the object/routine/event boundary looking for a resolution to the odd number of quotation marks.

Also, most lines ending in a comma, and, or or will automatically continue on to the next line (if they occur in a line of code). In other words:

and

get compiled the same as:

and

This is provided primarily so that lengthy lines and complex expressions do not have to run off the right-hand side of the screen during editing, nor do they continually need to be extended using \ and the end of each line.

There is a complement to the \ line-control character: the : character allows multiple lines to be put together on a single line, i.e.:

or

Which the compiler translates to:

and

Comments allow you to insert notes into source code to serve as reminders, descriptions of what a particular chunk of code does, put a curse upon the libary/language author, or whatever else you want. Comments are very helpful, and beginning programmers tend to put in either too many comments or too few. Despite the complaints that some people may have about over-commented code — generally referring to commenting a line like:

with the rather obvious explanation of “set x equal to 5” — it’s always better to err on the side of too many comments in order to avoid the situation that every programmer find himself or herself in at least once (and once only if very, very lucky) of trying to remember what a piece of code does that you wrote yesterday, or last week, or several months ago. Comment, comment, comment.⁠^[9]

There are two types of comments. Comments on a single line begin with a !. Anything following on the line is ignored. Multiple-line comments are begun with !\ and ended with \!.

The compiler is pretty good about catching you when you do something that isn’t going to work. When it encounters something in your source code that doesn’t make sense, or is illegal in terms of the Hugo language, it’ll tell you.

A compiler error is generally of one of two types. A fatal error looks like this:

and halts compiler execution. Fatal errors include things like not being able to find a requested file, encountering some sort of i/o difficulty (such as not being able to read from or write to a necessary file), or having encountered something in the source code that makes it impossible to continue with compilation.

A non-fatal error typically looks like:

Non-fatal errors are usually programming mistakes: either doing something illegal (like trying to assign a value to something to which you’re not allowed to assign a value), making a syntax error such as using a symbol name that the compiler doesn’t know about (often due to a typing mistake), or making a formatting mistake (like missing something that the compiler knows is supposed to be coming next but you forgot to include). Unless the -a switch is specified at invocation to tell the compiler to quit after the first error, multiple non-fatal errors may be printed. The side-effect of this is that a specific error (particularly a formatting error) may affect many lines of code after it, so that the compiler — having become lost and not really knowing what you’re trying to do — may report a whole string of errors, even on lines that, if the compiler understood their proper context, would be error free.⁠^[10]

When a compiler issues a warning, it looks like:

Compilation will continue, but this is an indication that the compiler suspects a problem at compile-time.

If the -e switch has been set during invocation to generate expanded-format errors, error output looks like:

It prints the section of code that caused the error, followed by an explanation of the problem. Compilation will generally continue unless the -a switch has been set.

A number of special commands may be used that aren’t really part of a Hugo program per se, but rather give instructions to the compiler itself to determine (a) how the source code — or a part thereof — is read by the compiler and (b) what special output will be generated at compile-time. These special commands or instructions are called compiler directives, and are preceded with a # character to set them apart.

To set switches within the source code so that they do not have to be specified each time the compiler is invoked for that particular program, the line

will set the switches specified by <sequence>, where <sequence> is a string of characters representing valid switches, without any separators between characters. Many programmers may find it useful to make

the first line in every new program, which will automatically print a statistical summary of compilation (plus any warnings or errors) to the .lst list file.

Using

specifies that the file is to be used with version <version>.<revision> of the compiler. If the file and compiler version are mismatched, a warning will be issued.

To include the contents of another file at the specified point in the current file, use

where <filename> is the full path and name of the file to be read. When <filename> has been read completely, the compiler resumes with the statement immediately following the #include directive. There is no limit on the number of files that a single file may include; also, a file may include a file which includes another file which includes another file and so on.

A useful tool for managing Hugo source code is the ability to use compiler flags for conditional compilation. A compiler flag is simply a user-defined marker that can control which sections of the source code are compiled. In this way, a programmer can demarcate sections of a program that can be included or excluded at will. For example, the library files hugolib.h, verblib.h, and verblib.g check to see if a flag called DEBUG has been set previously (as it is in sample.hug). Only if it has do they include the hugofix.h and hugofix.g files, which in turn provide certain debugging features to a running Hugo program. (For a final version to be released to the general public for playing, then, by simply not setting the DEBUG flag those special features are not enabled.)

To set and clear flags, use

and

respectively.

Then, check to see if a flag is set or not (and include or exclude the specified block of source code) by using

or

Conditional compilation constructions may be nested up to 32 levels deep. (Note also that compiler flags can be specified in the invocation line as #<flag name>.)

#if set and #if clear are the long form of #ifset and #ifclear, allowing usage of #elseif for code such as:

Use #if defined <symbol> and #if undefined <symbol> to test if objects, properties, routines, etc. have previously been defined, where <symbol> is the name of the object, property, routine, etc. in question.

As seen above, the #message directive can be used as

to output <text> when (or if) that statement is processed during the first compilation pass.

Including error or warning before <text> as in

or

will force the compiler to issue an error or warning, respectively, as it prints <text>.

It is also possible to include inline limit settings, such as

in the same way as in the invocation line. However, an error will be issued if, for example, an attempt is made to reset MAXOBJECTS if one or more objects have already been defined. Any limit settings in the code of a program must be done before the particular data type for which a new limit is being set has been used.

By now you should:

To experiment a little, make a copy of sample.hug and call it something like test.hug so that we can modify and use it without changing the original sample game source code. Pick a line in the new file test.hug like:

and add some garbage letters to change it to

Now, when you compile, you’ll see:

Once we’ve seen the effect of that, go back and remove the asdf from test.hug. Next, let’s try adding the line:

to the start of test.hug. Compile again, and you’ll see this time a whole bunch of compiler errors. Most importantly are the first couple, which look something like:

Feel free to experiment with test.hug by adding comments, changing lines, commenting out various objects or routines or other sections of codes, and seeing what happens when you try to compile it and run it.

Objects are the building blocks of any Hugo program. Anything that will be accessible to a player during the game — including items, rooms, other characters, and even directions — will most likely be defined as an object. The basic object definition looks like this:

For example, a suitcase object might be defined as:

The enclosing braces are needed even if the object definition has no content (yet). The only data attached to the suitcase object are — from right to left — a name (“suitcase”), an internal identifier (mysuitcase), and membership in the basic object class.

The compiler assigns the object labeled <objectname> the next sequential object number. The first-defined object is object 0; the next-defined object is object number 1; the one after that is 2, etc. This is academic, however, as a programmer almost never need know what object number a particular object is — except for certain debugging situations — and can always refer to an object by its label <objectname>. If no explicit “object name” (or name property) is provided, the compiler automatically gives it the name (<objectname>), i.e., <objectname> in parentheses. That is, whereas

creates an object called “suitcase”,

creates an object called “(placeholder)”. Usually the latter is used for system objects or classes (see Sec. 3.5, “Classes”) that will never actually appear in a game.

In order for objects to have a “physical place” in the game, i.e., to be in a room or contained in another object or beside another object, they must occupy a position in the object tree. The object tree is a simple map which represents the relationships between all objects in the game. The total number of objects is held in the global variable objects.

The “nothing” object is defined in the library as object 0 and is referred to in code using the label nothing. This is the root of the object tree, upon which all other objects are based.⁠^[11] (And again, the name “nothing” is given to this first object by the library.)

When referring to object numbers, this manual is generally referring to the name given to the object in the source code: i.e., <objectname>. The compiler automatically assigns each object an object number, and refers to it whenever a specified <objectname> is encountered.

Here is an example of an object tree:

A number of built-in functions can be used to read the object tree.

and

Each function takes a single object as its argument, so that

and

To better understand how the object tree represents the physical world, the table, the chair, the book, and the player are all in the room. The bookmark is in the book. The bowl is on the table, and the spoon is on the bowl. The Hugo library will assume that the player object in the example is standing; if the player were seated, the object tree might look like:

and

To initially place an object in the object tree, use

in the object definition, or, alternatively

or simply

to give the object the same parent as <object> or, if <object> is not specified, the same parent as the last-defined object. If no such specification is given (i.e., if you don’t tell the compiler explicitly where to place the new object), the parent object defaults to 0 — the nothing object as defined in the library. All normal room objects have 0 as their parent.

Therefore, the expanded basic case of an object definition is

The table in the example presumably had a definition like

To put the suitcase object defined earlier into the empty room in shell.hug:

Objects can later be moved around the object tree using the move command as in:

which, essentially, disengages <object> from its old parent, makes the sibling of <object> the sibling of <object>’s elder, and moves <object> (along with all its possessions) to the new parent.

Therefore, in the original example, the command

would result in altering the object tree to this:

There is also a command to remove an object from its position in the tree:

which is the same as

The object may of course be moved to any position later.

Logical tests can also be evaluated with regard to objects and children. The structure

will be true if <object> is in <parent> (or false if not is used). In this way, you can write a piece of code that looks something like:

Attributes are essentially qualities that every object either does or doesn’t have.⁠^[13] An attribute is defined as

Up to 128 attributes may be defined. Those defined in hugolib.h include:

Some of these attributes are actually the same attribute with different names. This is primarily just to save on the absolute number of attributes defined and is accomplished via

where <attribute1> has already been defined. For example, the library equates visited with moved (since, presumably, they will never apply to the same object — rooms are never moved and objects are never visited), so:

In this case, an object which is visited is also, by default, moved, so it is expected that attributes which are aliased will never both need to be checked under the same circumstances. For the most part, you should never need to alias your own attributes, although it’s helpful to know what it means since the library does it, and you may run across it in other places.

Attributes are given to an object during its definition as follows:

To give the suitcase object some appropriate attributes at compile-time, expand the object definition to include

Even if an object was not given a particular attribute in its object definition, it may be given that attribute at any later point in the program with the command

where the not keyword clears the attribute instead of setting it. For example, when the suitcase is opened, somewhere (likely in the library), the command

will be executed. When the suitcase is closed, the command will be:

Attributes can also be read using the is and is not structures and evaluate to either true or false. In code, the expression

returns true (1) if <object> is (or is not, if not is specified) <attribute>. Otherwise, it returns false (0). Therefore, given the suitcase object definition:

the following equations hold true:

Properties are considerably more complex than attributes. First, not every object may have every property; in order for an object to have a property, it must be specified in the object definition at the time you create the object. As well, properties are not simple on/off flags. They are sets of valid data associated with an object, where the values may represent almost anything, including object numbers, dictionary addresses, integer values, and sections of executable code.

These are some valid properties as they would appear in an object definition (using property names defined in hugolib.h):⁠^[16]

The nouns property contains four dictionary addresses; the size property is a single integer value; the found_in property holds two object numbers; and the long and short description properties are both property routines, which instead of just containing one or more simple values stored as a data type are actually sections of executable code attached to the object.

The before property is a special case. This complex property routine is defined by the compiler and handled differently by the engine than a normal property routine. In this case, the property value representing the routine address is only returned if the global variables object and verbroutine contain the object in question and the address of the DoGet routine, respectively. If there is a match, the routine is executed before DoGet, which is the library routine (in verblib.h) that normally handles the taking of objects. (There is also a companion to before called after, which is checked after the verb routine has been called.) See Sec. 5.3, “Before and After Routines” for further elucidation.

There will be more on property routines and complex property routines later. For now, think of a property as simply containing one or more values of some kind.

A property is defined similiarly to an attribute as

A default value may be defined for the property using

where <default value> is a constant or dictionary word. For objects without a given property, attempting to find that property will result in the default value. If no default is explicitly declared, it is 0 (or "" or the nothing object, whatever is appropriate in context — since they all represent the same zero value).

The list of properties defined in hugolib.h is:

The following properties are also defined and used exclusively by the display object:

Property names may be aliased similarly to attributes using:

where <property1> has already been defined. The library aliases (among others) the following:

Whereas a simple property is expressed as

The number of elements to a property with more than a single value can be found via

and a single element is expressed as

To add some properties to the suitcase object, expand the object definition to:

Based on the parser’s rules for object identification, the suitcase object may now be referred to by the player as “big green suitcase”, “big case”, or “green suitcase” among other combinations. Even “big green” and “suit” may be valid, provided that these don’t also refer to other objects within valid scope such as “a big green apple” or “your suit jacket”.

One occasional source of befuddling code that doesn’t behave the way the programmer intended is not allowing enough slots for a property on a given object. That is, if an object is originally defined with the property

and later, the program tries to set

in order to make the object available in both the kitchen and the living room, it will have no substantial effect. That is, there will be no space initialized in <object>⁠’s property table for a second value under found_in. Trying to read <object>.found_in #2 will return a value of 0 — a non-existent property — not the number of the livingroom object.

To overcome this, if it is known that eventually a second (or third, or fourth, or ninth) value is going to be set — even if only one value is defined at the outset — use

in the object definition.

As might be expected, combinations of properties are read left-to-right, so that

is understood as

which is, in other words, the name property of the object stored in location.n_to.

Classes are objects that are specifically intended to be used as prototypes for one or more similar objects. They’re extremely useful for when you want to create a number of objects that will all share certain basic characteristics. Here is how a class is defined:

with the body of the definition being the same as that for an object definition, where the properties and attributes defined are to be the same for all members of the class.

For example:

The definition of an object derived from a particular class is begun with the name of the prototype object instead of object. All properties and attributes of the class are inherited (except for its position in the object tree), unless they have been explicitly defined in the new object (in which case they take precedence over any defaults defined in the class).

That is, although the box class is defined without the open attribute, the largebox object will begin the game as open, since this is in the largebox definition. It will begin the game as openable, as well, as this is inherited from the box class.

And while the largebox object will have the long_desc of the box class, the greenbox object replaces the default property routine with a new description.

It is also possible to define an object using a previous object as a class even though the previous object was not explicitly defined as a class (using the class keyword). Therefore,

is perfectly valid. We created what amounts to a “copy” of largebox, with a different name (“large red box” this time) and a different set of adjectives to refer to it.

Occasionally, it may be necessary to have an object or class inherit from more than one previously defined class. This can be done using the inherits instruction.

or even

The precedence of inheritance is in the order of occurrence. In either example, the object inherits its properties and attributes first from <class1>, then from <class2>, and so on.

The Hugo Object Library (objlib.h) contains a number of useful class definitions for things like rooms, characters, scenery, vehicles, etc. Sometimes, however, it may be desirable to use a different definition for, say, the room class while keeping all the others in the Object Library.

Instead of actually editing objlib.h,⁠^[19] use:

where <class> is the name of a previously defined object or class, such as room. All subsequent references to <class> will use this object instead of the previously defined one.

By now you should:

What is a variable, exactly? Let’s start with the difference between a constant value and a variable value. The number 6 is a constant: we can’t change it. We can’t tell the program: “In this particular circumstance, let’s treat this 6 like it was actually 21.” Consider a situation, however, where we may want to record a particular value at one point in order to refer to it later. In other words, we may want to use a value that we won’t know at the time we write the code that will be using it.

Here’s a piece of code that, as we’ll see shortly, prints a single line of output with a number in the middle:

That statement may print

or

or any other similar variation depending on what the variable temp happens to be equal to at the time.⁠^[21]

Hugo supports two kinds of variables: global and local. Either type simply holds an integer value, so a variable can hold a simple value, an object number, a dictionary address, a routine address, or any other standard Hugo data type through an assignment such as:

Global variables are visible throughout the program. They must be defined similarly to properties and attributes as

Local variables, on the other hand, are recognized only within the routine in which they are defined. They are defined using

Global variables must of course have a unique name, different from that of any other data object; local variables, on the other hand, may share the names of local variables in other routines.

In either case, global or local, the default initial value is 0 if no other value is given. For example,

is equal to 1100 when the program is run, and is visible at any point in the program, by any object or routine. On the other hand, the variables

are visible only within the block of code where they are defined, and are initialized to 0, 100, and 0, respectively, each time that section of code (be it a routine, property routine, event, etc.) is run.

The compiler defines a set of engine globals: global variables that are referenced directly by the engine, but which may otherwise be treated like any other global variables. These are:

The object, xobject, and verbroutine globals are set up by the engine depending on what command is entered by the player. The self global is undefined except when an object is being referenced (as in a property routine or event). In that case, it is set to the number of that object. The player variable holds the number of the object that the player is controlling; the endflag variable must be 0 unless something has occurred to end the game; and the prompt variable represents the dictionary word appearing at the start of an input line (which most programs set to > by convention).

The objects variable can be set by the program, but to no useful effect. The engine will reset it to the “real” value whenever referenced. (All object numbers range from 0 to the value of objects.) The system_status variable may be read (after a resource operation or a system call; see the relevant sections for an explanation of these functions) to check for an error value. See the section on “Resources” for possible return values.

Constants are simply labels that represent a non-modifiable value.

(Note the lack of an = sign between, for example, FIRST_NAME and John.)

results in:

Constants can, like any other Hugo data type, be integers, dictionary entries, object numbers, etc.

It is not absolutely necessary that a constant be given a definite value if the constant is to be used as some sort of flag or marker, etc. Therefore,

will have unique values from each other, as well as from any other constant defined without a specific value.

Sometimes it may be useful to enumerate a series of constants in sequence. Instead of defining them all individually, it is possible to use:

giving:

The start value is optional. If omitted, it is 0. Also, it is possible to change the current value at any point (therefore also affecting all following values).

giving:

Finally, it is possible to alter the step value of the enumeration using the step keyword followed by +n, -n, *n, or /n, where n is a constant integer value. To start with 1 and count by multiples of two:

giving:

Enumeration of global variables is also possible, using the globals specifier, as in:

Otherwise the specifier constants (as opposed to globals) is implied as the default.

Text can be printed — that is, output to the screen during running of a Hugo program — using two different methods. The first is the basic print command, the simplest form of which is

where <string> consists of a series of alphanumeric characters and punctuation.

The backslash character (\) is handled specially. It modifies how the character following it in a string is treated.⁠^[22]

As usual, a single \ at the end of a line signals that the line continues with the following line.

Examples:

After each of the above print commands, a newline is printed. To avoid this, append a semicolon (;) to the end of the print statement.

Print statements may also contain data types, or a combination of data types and strings. The command

will print the word located at the dictionary address specified by object.name, so that if object.name points to the word box, the resulting output would be:

To capitalize the first letter of the specified word, use the capital modifier.

To print the data type as a value instead of referencing the dictionary, use the number modifier. For example, if the variable time holds the value 5,

If number were not used, the engine would try to find a word at the dictionary address 5, and the result will likely be garbage.

Mainly for debugging purposes, the modifier hex prints the data type as a hexadecimal number instead of a decimal one. If the variable val equals 127,

The second way to print text is from the text bank, from which — if memory is in short supply — sections are loaded from disk only when they are needed by the program. This method is provided so that lengthy blocks of text — such as description and narration — do not take up valuable space if memory is limited. The command consists simply of a quoted string without any preceding statement.

or

Notice that a semicolon at the end of the statement still overrides the newline. The in-string formatting combinations are still usable with these print statements, but since each statement is a single line, data types and other modifiers may not be compounded. Because of that,

will write

to the .HEX file text bank, but

is illegal.

The color of text may be changed using the color command (also valid with the U.K. spelling colour). The format is

where the background color is not necessary. If no background color is specified, the current one is assumed). The input color is also not necessary — this refers to the color of player input and, if not given, is the same as the foreground color.

The standard color set with corresponding values and constant labels (defined in hugolib.h) is:

It is expected that, regardless of the system, any color will print visibly on any other color. Video technology and shortcomings of the visible light spectrum conspire to foil this plan, however, it is suggested for practicality that white (and less frequently bright while) be used for most text-printing. Blue and black are fairly standard background colors for light-colored (such as white) text — this is a common combination for default text (as is dark text, such as black, on a white background). A game author can use the DEF_FOREGROUND, DEF_BACKGROUND, DEF_SL_FOREGROUND, and DEF_SL_BACKGROUND colors (as is done in sample.hug and is the default in shell.hug) since this uses the colors supplied by the Hugo Engine, allowing the user to change colors to his or her liking if the port supports that capability.

Magenta printing on a cyan background is accomplished by

or

A current line can be filled — with blank spaces in the current color — to a specified column (essentially a tab stop) using the print to…​ structure as follows:

where the value following to does not exceed the maximum line length in the engine global linelength.

The resulting output will be something like:

Text can be specifically located using the locate command via

where

places text output at the top left corner of the current text window. Neither <column> nor <row> may exceed the current window boundaries — the engine will automatically constrain them as necessary.

As listed above, the following are valid printing sequences that may be embedded in printed strings:

The next set of formatting sequences control the appearance of printed text by turning on and off boldface, italic, proportional, and underlined printing. Not all computers and operating systems are able to provide all types of printed output; however, the engine can be relied upon to properly process any formatting — i.e., proportionally printed text will still look fine even on a system that has only a fixed-width font, such as a Unix text terminal or DOS output (although, of course, it won’t be proportionally spaced).

A statement like the following:

will result in output like:

Print style can also be changed using the Font routine in hugolib.h, so that in

the <font change code> can be one or more of:

and can subsequently be used alone or in combination such as:

It’s preferable to rely on the Font function and the various font constants instead of embedding multiple font-change formatting sequences because if for no other reason than it being clearer to understand when reading the source code.

Special characters can also be printed via formatting sequences. Note that these characters are contained in the Latin-1 character set; if a particular system is incapable of displaying it, it will display the normal-ASCII equivalent.

Hugo allows use of all standard mathematical operators:

which take precedence⁠^[23] over:

Comparisons are also valid as operators, returning Boolean true or false (1 or 0) so that

evaluate respectively to 3 and 5 if n is 1, and 2 and 4 if n is 2 or greater. Valid relational operators are

Logical operators (and, or, and not) are also allowed.

Using and results in true (1) if both values are non-zero. Using or results in true if either is non-zero; not results in true only if the following value is zero.

Additionally, bitwise operators are provided:

Any Hugo data type can appear in an expression, including routines, attribute tests, properties, constants, and variables. Standard mathematical rules for order of significance in evaluating an expression apply, so that parenthetical sub-expressions are evaluated first, followed by multiplication and division, followed by addition and subtraction.

Some sample combinations are:

Expressions can be evaluated and assigned to either a variable, a property, or an array element.

Prior to this point, little has been said about arrays. Arrays are sets of values that share a common name, and where the elements are referenced by number. Arrays are defined by

where <array size> must be a numerical constant.

An array definition reserves a block of memory of <array size>,⁠^[24] so that, for example,

reserves ten possible storage elements for the array.

Keep in mind that <array size> determines the size of the array, not the maximum element number. Elements begin counting at 0, so that test_array, with 10 elements, has members numbered from 0 to 9. Trying to access test_array[10] or higher will return a zero value (and, if running in the debugger, cause a debugger warning). Trying to assign it by mistake will have no effect.

To prevent such out-of-bounds array reading/writing, an array’s length may be read via:

where no element number is specified. Using the above example,

would result in 10.

Array elements can be assigned more than one at a time, as in

where <element1> and <element2> can be expressions or single values.

Elements need not be all of the same type, either, so that

is perfectly legal (although perhaps not perfectly useful). More common is a usage like

or

The array can then be accessed by

or

which would set the variable b to 4 + 2, or 6.

Because array space is statically allocated by the compiler, all arrays must be declared at the global level. Local arrays are illegal, as are entire arrays passed as arguments.⁠^[25] However, single elements of arrays are valid arguments.

It is, however, possible to pass an array address as an argument, and the routine can then access the elements of the array using the array modifier. For example, if items is an array containing:

The following:

can be called using

to produce the output

even though v is an argument (i.e., local variable), and technically not an array. The line

tells the engine to treat v as an array address, so that we can follow it with [<element number>].

Arrays also allow a Hugo programmer to implement what are known as string arrays, which are textual strings, somewhat similar but not identical to dictionary entries. Most significantly, since they are arrays, string arrays may be altered at runtime by a program (unlike dictionary entries, which are hard-coded into the program’s dictionary). A string array is an array containing a series of character values, terminated by a zero value.

If the array apple_array holds the string array apple, the actual elements of apple_array look like:

Hugo provides a handy way to store a dictionary entry in an array as a series of characters using the string built-in function:

For example,

will store up to 10 characters from word[1] into the array a.

It’s not necessary to look at the return value from string, but it can be useful, since it lets us know how many characters were written to the string. For example,

will store up to 10 characters of “microscopic” in the array a, and return the length of the stored string to the variable x.⁠^[26]

The Hugo Library defines the functions StringCopy, StringEqual, StringLength, and StringPrint, which are extremely useful when dealing with string arrays.

StringCopy copies one string array to another array.

For example,

copies the contents of b to a, while

copies only up to 5 characters of b to a.

StringEqual returns true only if the two specified string arrays are identical. StringCompare returns 1 if <string1> is lexically greater than <string2>, -1 if <string1> is lexically less than <string2>, and 0 if the two strings are identical.

StringLength returns the length of a string array, as in:

and StringPrint prints a string array (or part of it).

For example, if the array a contains “presto”,

will print “presto”, but

will print “res”.

An interesting side-effect of being able to pass array addresses as arguments is that it is possible to “cheat” the address, so that, for example,

will copy b to a, beginning with the third letter of b (since the first letter of b is b[0]).

It should also be kept in mind that string arrays and dictionary entries are two entirely separate animals, and that comparing them directly using StringCompare is not possible. That is, while a dictionary entry is a simple value representing an address, a string array is a series of values each representing a character in the string.

The library provides the following to overcome this:

which returns the same values (1, -1, 0) as StringCompare, depending on whether the string array is lexically greater than, less than, or equal to the dictionary entry.

There is also a complement to string: the dict built-in function, that dynamically creates a new dictionary entry at runtime. Its syntax is:

where the contents of <array> or parse$ are written into the dictionary, to a maximum of <maxlen> characters, and the address of the new word is returned.

However, since this requires extending the actual length of the dictionary table in the game file, it is necessary to provide for this during compilation. Inserting

at the start of the source file will write a buffer of <number> empty bytes at the end of the dictionary. (MAXDICTEXTEND is, by default, 0.)

Dynamic dictionary extension is used primarily in situations where the player may be able to, for example, name an object, then refer to that object by the new name, or whenever the game needs to introduce new words into the dictionary that are not known at compile-time. However, a guideline for programmers is that there should be a limit to how many new words the program or player can cause to be created, so that the total length of the new entries never exceeds <number>, keeping in mind that the length of an entry is the number of characters plus one (the byte representing the actual length). That is, the word test requires 5 bytes.)

Program flow can be controlled using a variety of constructions, each of which is built around an expression that evaluates to false (zero) or non-false (non-zero).

The most basic of these is the if statement.

The enclosing braces are not necessary if the code block is a single line. Note also that the conditional block may begin (and even end) on the same line as the if statement provided that braces are used.

If braces are not used for a single line, the compiler automatically inserts them, although special care must be taken when constructing a block of code nesting several single-line conditionals. While

may be properly interpreted, other constructions (particularly those involving some of the more complex program-flow concepts we’re about to get into) may not be. Therefore, it’s always best to be as clear as possible about your intent, more along the lines of:

More elaborate uses of if involve the use of elseif and else.

In this case, the engine evaluates each expression until it finds one that is true, and then executes it. Control then passes to the next non-if/elseif/else statement following the conditional construction. If no true expression is found, the default code block is executed. If, for example, <expression1> evaluates to a non-false value, then none of the following expressions are tested.

Of course, all three (if, elseif, and else) need not be used every time, and simple if-elseif and if-else combinations are perfectly valid.

In certain cases, the if statement may not lend itself perfectly to clarity, and the select-case construction may be more appropriate. The general form is:

In this case, the evaluation is essentially

There is no limit on the number of values (separated by commas) that can appear on a line following case.⁠^[28] The same rules for bracing multiple-line code blocks apply as with if (as well as for every other type of conditional block).

Basic loops may be coded using while and do-while.

Each of these executes the conditional code block as long as <expression> holds true. It is assumed that the code block somehow alters <expression> so that at some point it will become false; otherwise the loop will execute endlessly.

The only difference between the two is that if <expression> is false at the outset, the while code block will never run. The do-while code block will run at least once even if <expression> is false at the outset.

It is also important to recognize — with while or do-while loops — that the expression is tested each time the loop executes. The most important side effect of this is that if you’re doing something in the expression that has some effect — whether printing something, calling a function, or modifying some other value — this will happen every time the expression is evaluated.

The most complex loop construction uses the for statement:

For example:

First, the engine executes the assignment setting i = 1. Next, it checks to see if the expression holds true (if i is less than or equal to 15). If it does, it executes the print statement and the modifying assignment that increments i. It continues the loop until the expression tests false.

Not all elements of the for construction are necessary. For example, the assignment may be omitted, as in

and the engine will simply use the existing value of i, whatever it was before this point. With

the loop will execute endlessly, unless some other means of exit is provided.

The modifying expression does not have to be an arithmetic expression as shown above. It may be a routine that modifies a global variable, for example, which is then tested by the for loop.

A second form of a for loop is:

which loops through all the children of <object> (if any), setting the variable <var> to the object number of each child in sequence, so that

will print the names of each object in the mysuitcase object.

Hugo also supports jump commands and labels. A label is simply a user-specified token preceded by a colon (:) at the beginning of a line. The label name must be a unique token in the program.⁠^[29]

One final concept is important in program flow, and that is break. At any point during a loop, it may be necessary to exit immediately (and probably prematurely). The break statement passes control to the statement immediately following the current loop. In the example:

the break causes the immediately running while <expression2> loop to terminate, even if <expression2> is true. However, the external do-while <expression1> loop continues to run.

It has been previously stated that lines ending in and or or are continued onto the next line in the case of long conditional expressions. A second useful provision is the ability to use a comma to separate options within a conditional expression. As a result,

are interpreted as:

respectively.

The output will be:

with “boldface”, “italics” and “underlined” printed in their respective typefaces. “Get ready”, “Get set”, and “Go!” will all appear on the same line in three different colors.

The output will be:

As is evident above, a dictionary entry does not need to be a single word; any piece of text which is referred to by the program as a value gets entered into the dictionary table.

The argument 31 in the first call to the string function allows up to 31 characters from a to be copied to s1, but since the length of a is only 24 characters, only 25 values (including the terminating 0) get copied, and the string length of s1 is returned in len.

Since “A(pple)” is lexically less than “T(his…​)”, comparing the two returns -1. As “To(mato)” is lexically greater than “Th(is…​)”, StringCompare returns 1.

Routines are blocks of code that may be called at any point in a program. A routine may or may not return a value, and it may or may not require a list of parameters or arguments. (Some different uses of routines have already been encountered in previous examples, but here is the formal explication.) Routines are also sometimes referred to subroutines or functions, the latter particularly when they’re returning a value, i.e., performing some function and reporting the result.

A routine is defined as:

once again ensuring that the opening brace ({) comes on a new line following the routine specifier.

An example of a simple routine definition is:

Where TestRoutine takes a single value as an argument, assigns it to a local variable obj, executes a simple printing sequence, and returns the property value: obj.size.

The return keyword exits the current routine, and returns a value if specified. Both

and

are valid. If no expression is given, the routine returns 0. If no return statement at all is encountered, the routine continues until the closing brace (}), then returns 0.⁠^[30]

Once defined, TestRoutine can be called several ways:

will (assuming the mysuitcase object as been defined as previously illustrated) print

The return value will be ignored. On the other hand,

will print the same output, but will assign the return value of TestRoutine to the variable x.

Now, unlike C and similar languages, Hugo does not require that routines follow a strict prototype. Therefore, both

and

are valid calls for the above routine. In the first case, the argument obj defaults to 0, since no value is passed. (The parentheses are not necessary if no arguments are passed.) In the second case, the value 5 is passed to TestRoutine, but ignored.

Arguments are always passed by value, not by reference or address. A local variable in one routine can never be altered by another routine. What this means is that, for example, in the following routines:

calling TestRoutine would print “5” and not “10” because the local variable a in Double is only a copy of the variable passed to it as an argument.

These two routines would, on the other hand, print “10”:

The local a in TestRoutine is reassigned with the return value from the Double routine.

An interesting side-effect of a zero (0) return value can be seen using the print command.⁠^[31] Consider the The routine in hugolib.h, which prints an object’s definite article (i.e., “the”, if appropriate), followed by the object’s name property.

might result in

Note that the above print command itself really only prints

and

It is the The routine that prints

Since The returns 0 (the empty string, or ""), the print command is actually displaying

where the empty string ("") is preceded on the output line by The⁠’s printing of "the " (notice the trailing space) and the object name.

Property routines are slightly more complex than the simple routines described so far, but follow the same basic rules. Normally, a property routine runs when the program attempts to get the value of a property that contains a routine.

That is, instead of having the property value:

an object may contain the property:

Trying to read object.size in either case will return an integer value, although in the second case it is calculated by a routine.

Here’s another example. Normally, if <object> is the current room object, then <object>.n_to would contain the object number of the room to the north (if there is one). The library checks <object>.n_to to see if a value exists for it; if none does, the move is invalid.

Consider this:

and

or

In the first case, an attempt on the part of the player to move north would result in parent(player) being changed to the office object. In the second case, a custom invalid-move message would be displayed. In the third case, the custom invalid-move message would be displayed, but then the library would continue as if it had not found a n_to property for <object>, and it would print the standard invalid-move message (without a newline, thanks to the semicolon):

Property routines may be run directly using the run command:

If <object> does not have <property>, or if <object>.<property> is not a routine, nothing happens. Otherwise, the property routine executes. Property routines do not take arguments.

Remember that at any point in a program, an existing property may be changed using

A property routine may be changed using

where the new routine must be enclosed in braces.

It is entirely possible to change what was once a property routine into a simple value, or vice-versa, providing that space for the routine (and the required number of elements) was allowed for in the original object definition. Even if a property routine is to be assigned later in the program, the property itself must still be defined at the outset in the original object definition. A simple

or

will suffice.

There is, however, one drawback to this reassignment of property values to routines and vice-versa. A property routine is given a “length” of one value, which is the property address. When assigning a value or set of values to a property routine, the engine behaves as if the property was originally defined for this object with only one word of data, since it has no way of knowing the original length of the property data.

For example, if the original property specification in the object definition was:

and at some point the following was executed:

then the following would not subsequently work:

because the engine now believes <object>.found_in to have only one element — a routine address — attached to it.

Finally, keep in mind that whenever calling a property routine, the global variable self is normally set to the object number. To avoid this, such as when “borrowing” a property from another object from within a different object, reference the property via

using .. instead of the normal property operator.

The Hugo Compiler predefines two special properties: before and after. They are unique in that not only are they always routines, but they are much more complex (and versatile) than a standard property routine.

Complex properties like before and after are defined with

as in:

Here is the syntax for the before property:

The <usage> specifier is a value against which the specified object is matched. Most commonly, it is object, xobject, location, actor, parent(object), etc. The <verbroutine> is the name of a verb routine to which the usage in question applies.

When the Hugo Engine goes to execute a player command, it runs a series of tests on the various elements of the command, such as the object on which the specified verb is to be enacted.⁠^[32] Know for now that when a player command is executed, the before properties of the object (i.e., the direct object) and xobject (i.e., the indirect object)⁠^[33] are checked, then if neither has returned non-false, the appropriate <verbroutine> is run. Afterward, the after properties are checked; if neither returns non-false, a default message is normally printed by the verbroutine. In other words, before routines typically pre-empt the execution of a verbroutine, and after routines typically pre-empt the default response of a verbroutine.

When the <object>.before property is checked, with the global verbroutine set to one of the specified verbroutines in the before property, and <usage> in that instance is object, then the following block of code is executed. If no match is found, <object>.before returns false.

Here is an example applied to the mysuitcase object created previously:

When the player tries the command “eat suitcase”, the response printed will be:

and the normal verbroutine for eat, the library’s DoEat verbroutine, will not be run. When the player tries to “get the suitcase”, the library’s DoGet verbroutine will be run (since no before property interrupts it), but instead of the default library response (which is a simple “Taken.”), the game will print:

Finally, when the player tries to put something into the suitcase using, say, “put the book in the suitcase”, the normal DoPutIn routine will be run, but the custom response of the suitcase will be printed instead:

Each of these examples will return true (as property routines do by default), thereby overriding the engine’s default operation.⁠^[34] In order to fool the engine into continuing normally, as if no before or after property has been found, return false from the property routine.

will result in:

Since the after routine returns false, and the library’s default response for a successful call to DoGet is “Taken.”

It is important to remember that, unlike other property routines, before and after routines are also additive; i.e., a before (or after) routine defined in an inherited class or object is not overwritten by a new property routine in the new object. Instead, the definition for the routine is — in essence — added onto. An additive property is defined using the $additive qualifier, as in:

All previously inherited before/after subroutines are carried over. However, the processing of a before/after property begins with the present object, progressing backward through the object’s ancestry until a usage/verbroutine match is found; once a match is made, no further preceding class inheritances are processed (unless the property routine in question returns false).

If a non-specific block occurs before any block(s) specifying verbroutines, then the following blocks, if matched, will run as well so long as the block does not return true. If the non-specific block comes after any other blocks, then it will run only if no other object/verbroutine combination is matched.

A drawback of this non-specification is that all verbroutines are matched — both verbs and xverbs.⁠^[35] This can be particularly undesirable in the case of location before/after properties, where you may wish to be circumventing any action the player tries to perform in that location, but where the non-specific response will be triggered even for save, restore, etc. (i.e., xverbs).

To get around this, the library provides a function AnyVerb, which takes an object as its argument and returns that object number if the current verbroutine is not within the group of xverbs; otherwise it returns false. Therefore, it can be used via:

instead of

The former will execute the conditional block of code whenever the location global matches the current object and the current verbroutine is not an xverb. The latter (without using AnyVerb), will run for verbs and xverbs.

At least two routines are typically part of every Hugo problem: Init and Main. Init is optional but almost always implemented. If it exists, is called once at the start of the program (as well as during a restart command). The routine should configure all variables, objects, and arrays needed to set up the game state and begin the game. Here’s the Init routine from shell.hug:

Main is called every turn. It should take care of general game management such as moving ahead the counter, as well as running events and scripts.⁠^[38] The Main routine from shell.hug is as follows:

Events are useful for bringing a game to life, so that little quirks, behaviors, and occurrences can be provided for with little difficulty or complexity. Events are also routines, but their special characteristic is that they may be attached to a particular object, and they are run as a group by the runevents command. Events are defined as:

for global events, and

for events attached to a particular object.

If an event is attached to an object, it is run only when that object has the same grandparent as the player object, where “grandparent” refers to the last object before 0 (the nothing object as defined in hugolib.h), or can otherwise be determined to be in the player’s current location.⁠^[39]

While most of the previously discussed elements of programming with Hugo (such as events) are part of the internal architecture of the Hugo Engine, the means of running fuses, daemons, and scripts are written entirely in the Hugo language itself and contained in the Hugo Library.

A daemon is the traditional name for a recurring activity. Hugo handles daemons as special events attached to objects that may be activated or deactivated (i.e., moved in and out of the scope of runevents). Since the daemon class is defined in the library, define a daemon itself using:

The body of the daemon definition is empty. The daemon object is only needed to attach the daemon event to, so the daemon definition must be followed by:

Activate it by:

which moves the specified daemon object into scope of the player. This way, whenever a runevents command is given (as it should be in the Main routine), the event attached to <name> will run.

Deactivate the daemon using:

which removes the daemon object from scope.

A fuse is the traditional name for a timer — i.e., any event set to happen after a certain period of time. The fuse itself is a slightly more complex version of a daemon object, containing two additional properties as well as in_scope:

Similarly to a daemon, define a fuse in two steps:

and turn it on or off by:

and

where <setting> is the initial value of the timer property.

Scripts are considerably more complex than fuses and daemons. The purpose of a script (also called a character script) is to allow an object — usually a character — to follow a sequence of actions turn-by-turn, independent of the player. Up to 16 scripts may be running at once.⁠^[41]

A script is represented by two arrays: scriptdata and setscript. The latter was named for programming clarity rather than for what it actually contains. Here’s why:

To define a script, use the following notation:

Notice that setscript is actually an array, taking its starting element from the return value of the Script routine, which has <object> and <number> as its arguments.

Script returns a pointer within the large setscript array where <num> number of steps of a script for <object> may reside. A single script may have up to 32 steps. A step in a script consists of a routine and an object — both are required, even if the routine does not require an object. (Use the nothing object (0); see the CharWait routine in hugolib.h for reference.)

The custom in hugolib.h is that character script routines use the prefix Char although this is not required. Currently, routines provided include:

as well as the special routine

which indicates that a script will continually execute.

The sequence of routines and objects for each script is stored in the setscript array.

Scripts are run using the RunScripts routine, similar to runevents, the only difference being that runevents is an engine command while RunScripts is contained entirely in hugolib.h. The line:

will run all active object/character scripts, one turn at a time, freeing the space used by each once it has run its course.

Here is a sample script for a character named “Ned”:

Ned will go south, retrieve the cannonball object, bring it north, wait a turn, and drop it.

Other script-management routines in hugolib.h include:

The RunScripts routine also checks for before and after properties. It continues with the default action — i.e., the character action routine specified in the script — if it finds a false value.

To override a default character action routine, include a before property for the character object using the following form:

where <CharRoutine> is CharWait, CharMove, CharGet, CharDrop, etc.

The library routines — particularly the DoWait…​ verb routines (invoked whenever a player types “wait”, “wait for (someone)”, or “wait for 5 turns” — expect the event_flag global variable to be set to a non-false value if something happens (i.e., in an event or script) so that the player may be notified and given the opportunity to quit waiting. For instance, the character script routines in hugolib.h set event_flag whenever a character does something in the same location as the player.

If hugolib.h is to be used, the convention of setting event_flag after every significant event should be adhered to.

Every valid player command must specified. More precisely, each usage of a particular verb must be detailed in full by the source code. Grammar definitions must always come at the start of a program, preceding any objects or executable code. That is, if several additional grammar files are to be included, or new grammar is to be explicitly defined in the source code, it must be done before any files containing executable code are included, or any routines, objects, etc. are defined.

The syntax used for grammar definition is:

Now, what does that mean? Here are some examples from the library grammar file verblib.g:

Each verb or xverb header begins a new verb definition. An xverb is a special signifier that indicates that the engine should not call the Main routine after successful completion of the action. xverb is typically used with non-action, housekeeping-type verbs such as saving, restoring, quitting, and restarting.

Another thing that can be done is to specify:

which will have the effect of, instead of defining the verb with a dictionary word, checking at runtime some_object.noun as the verb word to be matched. What this allows is for the some_object.noun property to be a routine that can return varying values at runtime in order to provide for dynamic grammar, if required. However, since this sort of dynamic grammar isn’t often required, static grammar definitions are far more common.

Next in the header comes one or more verb words. Each of the specified words will share the following verb grammar exactly. This is why get and take in the above examples are defined separately, instead of as

In this way, the commands like

and

are allowable, while

and

won’t make any sense.

Each line beginning with an asterisk (*) is a separate valid usage of the verb being defined.

Up to two objects and any number of dictionary words may make up a syntax line. The objects must be separated by at least one dictionary word.

Valid object specifications are:

Dictionary words that may be used interchangeably are separated by a slash (/).

Two or more dictionary words in sequence must be specified separately. That is, in the input line:

the syntax line

will be matched, while

would never be recognized, since the engine will automatically parse “out” and “of” as two separate words; the parser will never find a match for “out of”.

Regarding object specification within the syntax line: once the direct object has been found, the remaining object in the input line will be stored as the xobject. That is, in the example immediately above, a valid object in the input line with the attribute container will be treated as the indirect object by the verb routine.

Consider the following:

This definition will result in something like

(assuming that “up” has been defined elsewhere as part of a different object name, as in objlib.h), because the processor processes the syntax

and determines that an invalid object name is being used; it never gets to

The proper verb definition would be ordered like

so that both “pick <object>” and “pick up <object>” are valid player commands. It’s generally good practice to make sure that more specific grammar precedes more general grammar for this reason.

To define a new grammar condition that will take precedence over an existing one — such as in verblib.g — simply define the new condition first (i.e., before including verblib.g).

A single object may be specified as the only valid object for a particular syntax:

will produce a “You can’t do that with…​” error for any object other than the magic_lamp object.

Using a routine name to specify an object is slightly more involved: the engine calls the given routine with the object specified in the input line as its argument; if the routine returns true, the object is valid — if not, a parsing error is expected to have been printed by the routine. If two routine names are used in a particular syntax, such as

then FirstRoutine validates the object and SecondRoutine validates the xobject.

Immediately after an input line is received, the engine calls the parser, and the first step taken is to identify any invalid words, i.e., words that are not in the dictionary table.

The next step is to break the line down into individual words. Words are separated by spaces and basic punctuation (including ! and ?) which are removed. All characters in an input line are converted to lowercase (except those inside quotation marks).

The next step is to process the four types of special “words” which may be defined in the source code.

Removals are the simplest. These are simply words that are to be automatically removed from any input line, and are generally limited to words such as “a” and “the” which would, generally speaking, only make grammar matching more complicated and difficult. The syntax for defining a removal is:

as in

Punctuation is similar to a removal, except it specifies the removal of individual characters instead of whole words:

as in

Synonyms are slightly more complex. These are words that will never be found in the parsed input line; they are replaced by the specified word for which they are a synonym.

as in

The above example will replace every occurrence of “myself” in the input line with “me”. Usage of synonyms will likely not be extensive, since of course it is possible to, particularly in the case of object nouns and adjectives, specify synonymous words which are still treated as distinct.

Compounds are the final type of special word, specified as:

as in

so that the input line

would be parsed to

Depending on the design of grammar tables for certain syntaxes, the use of compounds may make grammar definition more straightforward, so that by using the above compound,

is possible, and likely more desirable to

When the parser has finished processing the input line, the result is a specially defined (by the Hugo Engine) array called word[], where the number of valid elements is held in the global variable words. Therefore, in

the parser — using the removals defined in hugolib.h — will produce the following results:

would become

A maximum of thirty-two words is allowed. The period is in each case converted to the empty dictionary entry (""; dictionary address = 0), which is a signal to the engine that processing of the current command should end here.

It should by now be relatively straightforward how to go about adding a new verb (with appropriate grammar) — or even modifying an existing one. For instance, consider a game in which disco dancing plays an absolutely vital role, and where the command “>GET DOWN” must at all costs be implemented as a synonym for “>DANCE” or “>BOOGIE”.

For starters, you’ll need to add the initial grammar and verbroutine:

and

Keep in mind that the verb definition, as with all grammar, must come before any other code, definitions, etc. Now, you’ll have to add the “>GET DOWN” grammar:

Now, this must come both before any other code or definitions as well as the existing grammar for “>GET <object>” (from verblib.g). Otherwise, the regular grammar for

will take precedence. By superseding it, however, we ensure that any grammar matching the desired pattern will result in DoDance being called instead.

Because, the engine is unaware of such things as attributes, properties, and objects in anything but a technical sense,⁠^[42] there are provided a number of routines to facilitate communication between the engine and the program proper. Along with these junction routines are certain global variables and properties that are pre-defined by the compiler and accessed directly by the engine. They are: