The Inform 6 Programmer's Guide

Chapter 31: Internationalization and Localization

The library separates language-dependent text and grammar from the core parser and world model. All English-specific behavior is isolated in a single file, english.h, which defines arrays, constants, and functions that the parser and verb library call through a well-defined interface. To translate a game into another language, one replaces english.h with a new language definition file that implements the same interface. This chapter documents that interface in full, covers the character-set directives available on each virtual machine, and describes the narrative voice and tense system introduced in library 6.12.

31.1 The english.h Language Definition File

The file english.h (1583 lines in library 6.12.8) is automatically included by parser.h and provides every piece of English-specific behavior that the library requires. It is organized into several parts: pronoun and descriptor tables, printing routines, text constants, pronoun helper functions, narrative voice conjugation helpers, and the main library message handler. This section provides a complete inventory.

31.1.1 Pronoun and Descriptor Arrays

The LanguagePronouns table array (line 125) maps English pronouns to Gender/Number/Animacy (GNA) bit patterns. Each entry consists of a dictionary word, a 12-bit GNA pattern, and the object the pronoun is initially connected to (NULL means unset):

Array LanguagePronouns table

  ! word        possible GNAs                   connected
  !             to follow:                      to:
  !             a     i
  !             s  p  s  p
  !             mfnmfnmfnmfn

    'it'      $$001000111000                    NULL
    'him'     $$100000100000                    NULL
    'her'     $$010000010000                    NULL
    'them'    $$000111000111                    NULL;

The 12-bit GNA pattern encodes which combinations of gender, number, and animacy each pronoun can refer to. Reading left to right, the bits correspond to: animate singular (male, female, neuter), animate plural (male, female, neuter), inanimate singular (male, female, neuter), inanimate plural (male, female, neuter). For example, 'it' has pattern $$001000111000 - it can refer to animate singular neuter, inanimate singular (all genders), matching objects like a dog or a table.

The LanguageDescriptors table array (line 138) maps words that can precede a noun - possessives, demonstratives, and articles - to GNA patterns, descriptor types, and connected objects:

Array LanguageDescriptors table

  ! word        possible GNAs   descriptor      connected
  !             to follow:      type:           to:
  !             a     i
  !             s  p  s  p
  !             mfnmfnmfnmfn

    'my'      $$111111111111    POSSESS_PK      0
    'this'    $$111111111111    POSSESS_PK      0
    'these'   $$000111000111    POSSESS_PK      0
    'that'    $$111111111111    POSSESS_PK      1
    'those'   $$000111000111    POSSESS_PK      1
    'his'     $$111111111111    POSSESS_PK      'him'
    'her'     $$111111111111    POSSESS_PK      'her'
    'their'   $$111111111111    POSSESS_PK      'them'
    'its'     $$111111111111    POSSESS_PK      'it'
    'the'     $$111111111111    DEFART_PK       NULL
    'a//'     $$111000111000    INDEFART_PK     NULL
    'an'      $$111000111000    INDEFART_PK     NULL
    'some'    $$000111000111    INDEFART_PK     NULL
    'lit'     $$111111111111    light           NULL
    'lighted' $$111111111111    light           NULL
    'unlit'   $$111111111111    (-light)        NULL;

The descriptor types POSSESS_PK, DEFART_PK, and INDEFART_PK are constants defined in the parser. The light and (-light) entries allow the parser to understand "lit lamp" and "unlit torch" as attribute tests.

The LanguageNumbers table array (line 163) maps number words to their numeric values:

Array LanguageNumbers table
    'one' 1 'two' 2 'three' 3 'four' 4 'five' 5
    'six' 6 'seven' 7 'eight' 8 'nine' 9 'ten' 10
    'eleven' 11 'twelve' 12 'thirteen' 13 'fourteen' 14 'fifteen' 15
    'sixteen' 16 'seventeen' 17 'eighteen' 18 'nineteen' 19 'twenty' 20;

The parser uses this table when it encounters a word that might be a number in the player's input, converting it to the corresponding integer.

31.1.2 Gender, Contraction, and Article Constants

Three constants (lines 180-183) define fundamental gender and article properties of the language:

Constant LanguageAnimateGender   = male;
Constant LanguageInanimateGender = neuter;

Constant LanguageContractionForms = 2;     ! English has two:
                                           ! 0 = starting with a consonant
                                           ! 1 = starting with a vowel

LanguageAnimateGender tells the library what gender to assume for animate objects that lack explicit male or female attributes. In English, this defaults to male (historically, the library defaults to "he" for unspecified animate objects). LanguageInanimateGender defaults to neuter.

LanguageContractionForms specifies how many variant forms of articles exist. English has two: one for words beginning with a consonant ("a dog") and one for words beginning with a vowel ("an egg"). Languages without contraction (e.g., those with a single indefinite article form) set this to 1.

31.1.3 Contraction and Article Functions

The LanguageContraction function (line 187) determines which contraction form applies to a given text:

[ LanguageContraction text;
    if (text->0 == 'a' or 'e' or 'i' or 'o' or 'u'
                or 'A' or 'E' or 'I' or 'O' or 'U') return 1;
    return 0;
];

It examines the first character of the object's short name. Returning 0 selects the consonant column of the article table; returning 1 selects the vowel column.

The LanguageArticles array (line 193) is a two-dimensional word array indexed by article row and contraction form. Each row contains six entries - capitalized definite, lowercase definite, and indefinite, for each contraction form:

Array LanguageArticles -->

 !   Contraction form 0:     Contraction form 1:
 !   Cdef   Def    Indef     Cdef   Def    Indef

     "The " "the " "a "      "The " "the " "an "          ! Articles 0
     "The " "the " "some "   "The " "the " "some ";       ! Articles 1

Row 0 is used for singular objects ("a"/"an"), and row 1 for plural objects ("some"). The LanguageGNAsToArticles array (line 205) maps each of the 12 GNA values to an article row:

                   !             a           i
                   !             s     p     s     p
                   !             m f n m f n m f n m f n

Array LanguageGNAsToArticles --> 0 0 0 1 1 1 0 0 0 1 1 1;

All singular GNA values (positions 0-2 and 6-8) map to row 0; all plural values (positions 3-5 and 9-11) map to row 1. The library computes the article to print by looking up an object's GNA, mapping it to an article row via LanguageGNAsToArticles, and then selecting the correct column based on the contraction form returned by LanguageContraction.

31.1.4 Direction and Number Printing

The LanguageDirection function (line 207) prints the English name of a compass direction given a direction property:

[ LanguageDirection d;
    switch (d) {
      n_to:    print "north";
      s_to:    print "south";
      ...
    }
];

The LanguageNumber function (line 225) prints an integer as English words. It handles zero, negative numbers, thousands, hundreds, teens, and compound forms with hyphens:

[ LanguageNumber n f;
    if (n == 0)    { print "zero"; rfalse; }
    if (n < 0)     { print "minus "; n = -n; }
    if (n >= 1000) { print (LanguageNumber) n/1000, " thousand";
                     n = n%1000; f = 1; }
    if (n >= 100)  {
        if (f == 1) print ", ";
        print (LanguageNumber) n/100, " hundred"; n = n%100; f = 1;
    }
    if (n == 0) rfalse;
    #Ifdef DIALECT_US;
    if (f == 1) print " ";
    #Ifnot;
    if (f == 1) print " and ";
    #Endif;
    switch (n) {
      1:    print "one";
      ...
      20 to 99: switch (n/10) {
        2:  print "twenty";
        ...
        }
        if (n%10 ~= 0) print "-", (LanguageNumber) n%10;
    }
];

Note the DIALECT_US conditional: British English uses "and" between hundreds and tens ("one hundred and twelve"), while American English omits it ("one hundred twelve"). Define Constant DIALECT_US; before including the library to select American conventions.

31.1.5 Time of Day

The LanguageTimeOfDay function (line 273) prints a time value in 12-hour AM/PM format:

[ LanguageTimeOfDay hours mins i;
    i = hours%12;
    if (i == 0) i = 12;
    if (i < 10) print " ";
    print i, ":", mins/10, mins%10;
    if ((hours/12) > 0) print " pm"; else print " am";
];

The status line printing code calls this function when the game uses Statusline time;.

31.1.6 Verb Printing and Debugging

The LanguageVerb function (line 281) maps abbreviated verb dictionary words to their full English names for use in parser messages:

[ LanguageVerb i;
    switch (i) {
      'i//','inv','inventory':
               print "take inventory";
      'l//':   print "look";
      'x//':   print "examine";
      'z//':   print "wait";
      'n//':   print "north";
      's//':   print "south";
      'e//':   print "east";
      'w//':   print "west";
      'ne//':  print "northeast";
      'nw//':  print "northwest";
      'se//':  print "southeast";
      'sw//':  print "southwest";
      default: rfalse;
    }
    rtrue;
];

The LanguageVerbIsDebugging function (line 308) identifies debugging verbs so the parser can give them full scope. It is wrapped in #Ifdef DEBUG so it only exists in debug builds:

#Ifdef DEBUG;
[ LanguageVerbIsDebugging w;
    if (w == 'purloin' or 'tree' or 'abstract'
                       or 'gonear' or 'scope' or 'showobj')
        rtrue;
    rfalse;
];
#Endif;

Two additional functions in english.h assist the parser with verb handling:

  • LanguageVerbLikesAdverb(w) (line 324): Returns true if the verb word w is intransitive and takes a direction adverb rather than a noun object (e.g., "go north" rather than "take lamp").
  • LanguageVerbMayBeName(w) (line 339): Returns true if the verb word w could also be an object name (e.g., "long" in "long sword" vs. "long" as a VERBOSE synonym).

31.1.7 Text Constants

Lines 346-407 define string constants used throughout the library for user interface text. These are separated into several groups:

Menu navigation keys (lines 346-357):

Constant NKEY__TX       = "N = next subject";
Constant PKEY__TX       = "P = previous";
Constant QKEY1__TX      = "  Q = resume game";
Constant QKEY2__TX      = "Q = previous menu";
Constant RKEY__TX       = "RETURN = read subject";

Constant NKEY1__KY      = 'N';
Constant NKEY2__KY      = 'n';
...

Status line labels (lines 359-364):

Constant SCORE__TX      = "Score: ";
Constant MOVES__TX      = "Moves: ";
Constant TIME__TX       = "Time: ";
Constant SCORE_S__TX    = "S: ";    ! Short forms for narrow displays
Constant MOVES_S__TX    = "M: ";
Constant TIME_S__TX     = "T: ";

Core prose fragments (lines 365-391):

Constant CANTGO__TX     = "You can't go that way.";
Constant FORMER__TX     = "your former self";
Constant MYFORMER__TX   = "my former self";
Constant YOURSELF__TX   = "yourself";
Constant MYSELF__TX     = "myself";
Constant YOU__TX        = "You";
Constant DARKNESS__TX   = "Darkness";
Constant THOSET__TX     = "those things";
Constant THAT__TX       = "that";
Constant THE__TX        = "the";
Constant OR__TX         = " or ";
Constant NOTHING__TX    = "nothing";
Constant IS__TX         = " is";
Constant ARE__TX        = " are";
Constant WAS__TX        = " was";
Constant WERE__TX       = " were";
Constant AND__TX        = " and ";
Constant WHOM__TX       = "whom ";
Constant WHICH__TX      = "which ";

Version and error reporting (lines 397-407):

Constant LIBERROR__TX   = "Library error ";
Constant TERP__TX       = "Interpreter ";
Constant VER__TX        = "Version ";
Constant RELEASE__TX    = "Release ";

A language definition file must define all of these constants with appropriate translations, as the library references them by name.

31.1.8 The LanguageLM Function

The LanguageLM function (line 797) is the largest component of english.h. It handles all library messages - the text printed in response to player actions and parser errors. It receives three arguments:

  • n - the message number, typically a switch label corresponding to an action name and sub-message index
  • x1 - the primary object involved (e.g., the noun)
  • x2 - the secondary object (e.g., the second noun), or other context

The function is structured as a large switch on action names, with nested switch statements on n for actions that produce multiple messages:

[ LanguageLM n x1 x2;
  Answer,Ask:
            print "There ";
            Tense("is", "was");
            " no reply.";
  Attack:   print "Violence ";
            Tense("isn't", "wasn't");
            " the answer to this one.";
  ...
  Close: switch (n) {
        1:  CSubjectIs(x1,true);
            print " not something ", (theActor) actor;
            Tense(" can close", " could have closed");
            ".";
        2:  CSubjectIs(x1,true); " already closed.";
        3:  CSubjectVerb(actor,false,false,"close",0,"closes","closed");
            " ", (the) x1, ".";
    }
  ...
];

LanguageLM handles over 70 action types with approximately 200 individual messages. It makes extensive use of the conjugation helper functions described in §31.5 to support narrative voice and tense variations. Every message uses Tense(), CSubjectVerb(), and related helpers rather than hard-coded strings, allowing all messages to adapt to first-person, second-person, or third-person narration in either present or past tense.

The library calls LanguageLM through the L__M wrapper function (see §30), which first checks for a LibraryMessages object that the game can use to intercept and replace individual messages.

31.2 Writing a New Language Definition File

To translate the standard library into a new natural language, one creates a replacement for english.h that implements the same interface. The parser (parser.h) and verb library (verblib.h) call Language* functions and reference Language* arrays and constants by name. This section documents the complete interface contract.

31.2.1 Required Arrays

A language definition file must define the following arrays:

LanguagePronouns - A table array where each entry consists of a dictionary word, a 12-bit GNA pattern, and a connected-object value. The parser uses this to resolve pronouns in player input.

LanguageDescriptors - A table array where each entry consists of a dictionary word, a 12-bit GNA pattern, a descriptor type constant (POSSESS_PK, DEFART_PK, or INDEFART_PK), and a connected-object value. The parser uses this to handle articles, possessives, and other pre-noun descriptors.

LanguageNumbers - A table array of alternating dictionary words and integer values. The parser uses this to convert number words in the player's input to numeric values.

LanguageArticles - A --> (word) array containing article strings. The array has dimensions (number of article rows) × (LanguageContractionForms × 3). Each group of three strings per contraction form contains the capitalized definite article, lowercase definite article, and indefinite article.

LanguageGNAsToArticles - A --> (word) array of 12 entries, one per GNA value, mapping each GNA to an article row index in LanguageArticles.

31.2.2 Required Constants

LanguageAnimateGender - The default attribute to assume for animate objects without explicit gender attributes. Must be male, female, or neuter.

LanguageInanimateGender - The default attribute to assume for inanimate objects. Typically neuter.

LanguageContractionForms - An integer specifying how many contraction forms the language uses. English uses 2 (consonant vs. vowel). A language with no article contraction uses 1. A language with three forms (e.g., based on the following consonant type) uses 3.

31.2.3 Required Functions

The following functions are called unconditionally by the library and must be defined:

LanguageContraction(text) - Receives the printed text of an object's short name (as a byte array). Returns an integer from 0 to LanguageContractionForms - 1 identifying which contraction form to use. The library uses this return value to select the correct column in LanguageArticles.

LanguageDirection(d) - Receives a direction property value (e.g., n_to, s_to) and prints the corresponding direction name in the target language.

LanguageNumber(n) - Receives an integer and prints it as words in the target language. Called by the library when printing numbers in prose (e.g., "There are three coins here").

LanguageTimeOfDay(hours, mins) - Receives hours (0-23) and minutes (0-59) and prints a formatted time string. Called by the status line code when the game uses Statusline time;.

LanguageVerb(i) - Receives a dictionary word and prints its full-form verb name. Returns true if the word was recognized, false otherwise. Used in parser messages like "I only understood you as far as wanting to [verb]".

LanguageVerbIsDebugging(w) - Receives a dictionary word and returns true if it is a debugging verb that needs all objects in scope. This is the one exception to the "called unconditionally" rule above: the library calls it only from SearchScope inside #Ifdef DEBUG (parser.h), so it is required only in DEBUG builds. Wrap the definition in #Ifdef DEBUG; ... #Endif; accordingly.

LanguageLM(n, x1, x2) - The main library message handler. Must handle all action messages and parser error messages. This is the largest and most complex function in the language definition file.

31.2.4 Optional Functions

The following functions are checked with #Ifdef before being called. If they are absent, the library uses default behavior:

LanguageInitialise - Called once at game startup during Initialise(). Use it to set up language-specific global state.

LanguageToInformese - Called during input tokenization to preprocess the raw input buffer before the parser analyses it. Useful for normalizing accented characters, expanding contractions, or handling language-specific input transformations. The english.h file defines this as an empty function.

LanguageIsVerb(buffer, parse, wordnum) - Called during verb identification. If defined, it gives the language file a chance to identify a word as a verb before the standard grammar tables are checked. It receives the input buffer, the parse table, and the word number being examined.

LanguageRefers(obj, wordnum) - Called during pronoun reference resolution. The second argument is a word number (an index into the parse buffer), not the word itself. If defined, allows the language file to provide custom logic for determining whether a given word can refer to a given object.

LanguageCommand(v) - Called when printing a command back to the player. If defined, lets the language file customize how commands are displayed.

LanguagePrintShortName(obj) - Called when printing an object's short name. If defined, allows the language file to override the default short-name printing. Return true to suppress the default print, false to let it proceed.

LanguageBanner - Called during the game banner display. If defined, replaces the default banner printing.

LanguageVersion - A string constant, not a routine. If defined, the library prints it (via print (string) LanguageVersion) as additional version information about the language definition file during the VERSION verb output.

LanguageVersionSub - Called during the VERSION verb handler. If defined, replaces the entire version display.

LanguageError - Called on library errors. If defined, allows the language file to provide custom error formatting.

31.2.5 The GNA System

The Gender/Number/Animacy (GNA) system encodes grammatical properties of objects and words using a 12-bit pattern. The 12 positions correspond to:

GNA Animacy Number Gender Index
0 Animate Singular Male 0
1 Animate Singular Female 1
2 Animate Singular Neuter 2
3 Animate Plural Male 3
4 Animate Plural Female 4
5 Animate Plural Neuter 5
6 Inanimate Singular Male 6
7 Inanimate Singular Female 7
8 Inanimate Singular Neuter 8
9 Inanimate Plural Male 9
10 Inanimate Plural Female 10
11 Inanimate Plural Neuter 11

A GNA pattern like $$001000111000 has bit 2 (animate singular neuter), bits 6-8 (inanimate singular all genders) set. This matches the pronoun "it", which can refer to a neuter animate creature or any singular inanimate object.

The parser computes an object's GNA from its attributes: animate sets the animate flag; male, female, and neuter set gender; pluralname sets plural. It then compares the object's GNA against the pronoun or descriptor pattern to determine compatibility.

31.2.6 The Article/Contraction System

The article selection mechanism works as follows:

  1. The library determines the object's GNA value (0-11).
  2. It looks up LanguageGNAsToArticles-->gna to get the article row.
  3. It calls LanguageContraction(obj.short_name_text) to get a contraction form (0 to LanguageContractionForms - 1).
  4. It computes the index into LanguageArticles: row * LanguageContractionForms * 3 + contraction_form * 3 + column, where column is 0 for capitalized definite, 1 for lowercase definite, or 2 for indefinite.
  5. It prints the string at that index.

For a language with three genders and two numbers but no contraction (French, for example), one would set LanguageContractionForms = 1 and provide article rows for each gender/number combination (le/la/les/un/une/ des), with LanguageGNAsToArticles mapping GNA values to the correct rows.

31.2.7 Required Text Constants

The language definition file must define all of the text constants listed in §31.1.7. The library references these constants by name throughout the parser and verb library code. The most critical ones are:

  • YOU__TX, YOURSELF__TX, MYSELF__TX - player reference text
  • DARKNESS__TX - the name shown in the status line in dark rooms
  • CANTGO__TX - the message printed for blocked exits
  • IS__TX, ARE__TX, WAS__TX, WERE__TX - verb forms
  • THE__TX, THAT__TX, OR__TX, AND__TX - articles and conjunctions
  • SCORE__TX, MOVES__TX, TIME__TX - status line labels

31.3 Character Sets: The Zcharacter Directive

[Z-machine] The Zcharacter directive controls the character encoding tables used by the Z-machine. It is available only when compiling for the Z-machine; the compiler errors if you use it in Glulx mode.

The Z-machine encodes text using three alphabets:

  • A0 (lowercase): 26 letters, initially a-z
  • A1 (uppercase): 26 letters, initially A-Z
  • A2 (punctuation/special): the number of usable or replaceable positions depends on which form of Zcharacter is used. Indices 0 and 1 are never printable (the Z-machine reserves them for the ZSCII-escape signal and newline, respectively). In the full-replacement (three-string) form (§31.3.1 Form 1), all of indices 3-25 are supplied by the author's string (23 characters), and the compiler forces index 2 to the tilde ~. In the per-character single-argument form (§31.3.1 Form 2), the compiler scans from index 2 upward but skips indices 12, 13, and 19 (., ,, and ~), leaving 21 replaceable positions (chars.c:221-242). Initially, A2 contains digits and common punctuation.

Characters in A0 are the most compact (one Z-character each). Characters in A1 or A2 require a shift character prefix (two Z-characters). Any character outside these alphabets must be encoded as a four-Z-character ZSCII escape sequence, which is expensive.

31.3.1 Directive Forms

The Zcharacter directive has four forms:

Form 1: Replace all three alphabets

Zcharacter "abcdefghijklmnopqrstuvwxyz"
           "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
           "0123456789.,!?_#'/-:()+";

Each string replaces one alphabet: A0 (26 characters), A1 (26 characters), A2 (23 characters: the compiler fills indices 3-25 from this string and forces index 2 to ~; indices 0 and 1 are not part of the printable alphabet - they are the Z-machine's ZSCII-escape and newline slots). The compiler replaces the entire alphabet array for each position.

Form 2: Add a single character to alphabet A2

Zcharacter '@{00E9}';

This attempts to place the given Unicode character into an unused position in alphabet A2. The compiler scans A2 positions left to right, skipping positions 12, 13, and 19 (which correspond to ., ,, and ~ - characters considered essential). It replaces the first position whose character hasn't been used in any compiled text. If no positions are available, the operation fails silently.

Form 3: Define or extend a custom ZSCII table

Zcharacter table
    $00E9   ! é (e-acute)
    $00E8   ! è (e-grave)
    $00EA   ! ê (e-circumflex)
    $00EB   ! ë (e-diaeresis)
    ;

This replaces the default ZSCII extension table entirely. Each number is a Unicode code point to be mapped into the ZSCII range 155-251. The first entry (without the + flag) resets the high-water mark to 0, clearing any previous mappings. You can define up to 97 custom characters (ZSCII codes 155 through 251).

A leading + after table instead preserves the existing entries and appends to them:

Zcharacter table + $0100 $0101 $010C $010D;

The + sign preserves existing entries and appends new ones. The plus_flag is passed to new_zscii_character(), which skips the zscii_high_water_mark reset.

Form 4: Set word-terminating characters

Zcharacter terminating 129 130 131;

The terminating keyword takes a list of ZSCII code numbers (not strings or character constants). The compiler writes them into a dedicated terminating-characters table in the story file, separate from the dictionary. Unlike the other forms, it does not alter the character-encoding alphabets or the ZSCII extension table.

31.3.2 Practical Example

A game using French accented characters might include:

! Add frequently-used accented characters to alphabet A2
! so they encode compactly (2 Z-characters instead of 4)
Zcharacter '@{00E9}';  ! é
Zcharacter '@{00E8}';  ! è
Zcharacter '@{00EA}';  ! ê
Zcharacter '@{00E0}';  ! à
Zcharacter '@{00E7}';  ! ç
Zcharacter '@{00EE}';  ! î
Zcharacter '@{00F4}';  ! ô
Zcharacter '@{00FB}';  ! û

! Define ZSCII table for all accented characters needed
Zcharacter table
    $00E9 $00E8 $00EA $00EB   ! é è ê ë
    $00E0 $00E2               ! à â
    $00E7                     ! ç
    $00EE $00EF               ! î ï
    $00F4                     ! ô
    $00F9 $00FB               ! ù û
    ;

Characters placed in alphabet A2 via Zcharacter 'x' encode in two Z-characters instead of four, so frequently-used accented letters should be added to A2 when possible. Characters that only need to be representable (but not necessarily compact) should be in the ZSCII extension table.

31.3.3 Limitations

  • The Z-machine can support at most 97 extra characters (ZSCII 155-251) beyond the base Latin-1 set.
  • Unicode characters beyond U+FFFF cannot be placed in the ZSCII table.
  • When using the per-character single-argument form (Zcharacter 'x'), alphabet A2 has 21 replaceable positions. Indices 0 and 1 are not printable slots (the Z-machine uses them for the ZSCII-escape signal and newline, respectively), and three positions (., ,, and ~ at indices 12, 13, and 19) are skipped as essential punctuation, leaving the remaining 21 positions (digits 0-9 and miscellaneous punctuation) available for replacement (chars.c:221-242). When using the full-replacement three-string form, 23 positions are provided by the author (indices 3-25), and the compiler forces index 2 to ~.
  • The Zcharacter directive is rejected with an error in Glulx mode.

31.4 Unicode Support in Glulx

[Glulx] Glulx provides full Unicode support without the character-set limitations of the Z-machine. There is no need for Zcharacter directives or custom alphabet tables; any Unicode character can be used directly.

31.4.1 Unicode in Strings

The @{NNNN} escape notation allows arbitrary Unicode code points in strings and character constants:

! Unicode characters can be used directly in Glulx strings
print "Caf@{00E9} @{2014} a nice caf@{00E9}.^";
! Prints: Café - a nice café.

! Em dash (U+2014) and curly quotes
print "@{201C}Hello,@{201D} she said.^";
! Prints: "Hello," she said.

The @{...} syntax accepts 1 to 6 hexadecimal digits specifying a Unicode code point. The compiler converts these to the target encoding during compilation.

31.4.2 Character Mapping

The compiler maintains a chain of character mappings between different encoding systems:

  • Source text is read as ISO 8859-1 by default, or as UTF-8 if the character_set_unicode flag is set (via the -Cu compiler switch).
  • ISO 8859-1 ↔ Unicode: The compiler maintains an internal mapping from ISO 8859-1 byte values to Unicode code points.
  • Unicode ↔ ZSCII: Internal conversion functions map Unicode to ZSCII codes and vice versa. For Glulx, these are used during compilation, but the runtime operates directly on Unicode.

The conversion functions:

extern int unicode_to_zscii(int32 u)
{   int i;
    if (u < 0x7f) return u;
    for (i=0; i<zscii_high_water_mark; i++)
        if (zscii_to_unicode_grid[i] == u) return i+155;
    return 5;
}

extern int32 zscii_to_unicode(int z)
{   if (z < 0x80) return z;
    if ((z >= 155) && (z <= 251))
        return zscii_to_unicode_grid[z-155];
    return '?';
}

31.4.3 Huffman Compression and Unicode

Glulx uses Huffman compression for strings. The compiler tracks distinct Unicode characters beyond U+00FF. The compiler records the position in the Huffman entity table where Unicode character entries begin, allowing the decompression code to distinguish Unicode entries from ASCII entries and abbreviation references.

When a Unicode character beyond the Latin-1 range appears in a string, the compiler:

  1. Records it in the Unicode character table.
  2. Assigns it a Huffman entity for compression.
  3. In the output file, encodes it as a multi-byte Huffman sequence.

At runtime, the Glulx interpreter's string-decoding code handles these transparently, printing the correct Unicode character to the output stream.

31.4.4 UTF-8 Source Files

The compiler's -Cu switch sets the character_set_unicode flag, enabling UTF-8 decoding of source files. When active, the compiler performs UTF-8 multi-byte decoding when it encounters high-bit characters (bytes with bit 7 set). This allows source files to contain accented characters and non-Latin scripts directly, without @{...} escapes:

! With -Cu, UTF-8 source files can contain characters directly
print "Hélas, c'est la vie.^";

31.4.5 Glulx Unicode Output and Detection

Glulx supports Unicode output through a dedicated opcode, while interpreters advertise Unicode support through a Glk gestalt selector:

  • @streamunichar (opcode 0x73) - Outputs a single Unicode character to the current output stream. The compiler uses this to print individual Unicode characters outside the Latin-1 range.

  • glk_gestalt(gestalt_Unicode, 0) - The gestalt_Unicode selector (value 15) is a Glk gestalt selector passed to the glk_gestalt function, not to the Glulx @gestalt opcode (which has its own separate selector namespace), to test whether the interpreter supports Unicode I/O. Games that need to verify Unicode support at runtime can check this gestalt value.

For further details on Glulx I/O and string handling, see §29.

31.5 Narrative Voice and Tense Control

Library 6.12 introduced a system for varying the narrative voice and tense of library messages. By default, the library uses second-person present tense ("You take the lamp"), but it can be configured for first-person ("I take the lamp"), third-person ("George takes the lamp"), and past tense ("You took the lamp") narration. This system is documented in voices_and_tenses.txt in the library distribution.

Using these settings from game code - the narrative_voice/narrative_tense reference tables and the CSubject routine reference - is covered in §21.8-§21.9. This section focuses on the english.h implementation and on writing voice-aware messages for a new language.

31.5.1 Configuration Properties and Constants

Two constants control this:

Constant PRESENT_TENSE 0;
Constant PAST_TENSE    1;

The SelfClass class, from which the default selfobj player object is derived, defines two properties that control narration:

Class  SelfClass
  with ...
        narrative_voice 2,
        narrative_tense PRESENT_TENSE,
        ...
  has   concealed animate proper transparent;
  • narrative_voice - Controls grammatical person:
    • 1 = first person ("I")
    • 2 = second person ("You") - the default
    • 3 = third person ("He/She/George")
  • narrative_tense - Controls grammatical tense:
    • PRESENT_TENSE (0) - the default
    • PAST_TENSE (1)

These properties belong to the player object. Changing them at runtime immediately affects all subsequent library messages.

31.5.2 Switching Voice at Runtime

To switch the narrative voice, set the properties on the player object:

! Switch to third-person past tense
player.narrative_voice = 3;
player.short_name = "George";
player.narrative_tense = PAST_TENSE;

When narrative_voice is 3, the library uses the player object's short_name property as the character name. The object should have the proper attribute to prevent the library from printing "the George". Set male or female as appropriate for pronoun selection.

For body-switching (changing which object the player controls), the ChangePlayer routine reassigns the player global to the new object; it does not copy narrative_voice or narrative_tense. Because the narration helpers read these properties from whichever object is currently player, the new player object must carry its own settings. Setting up a flashback in past tense is straightforward:

[ BeginFlashback;
    player.narrative_tense = PAST_TENSE;
    print "^[You remember...]^";
];

[ EndFlashback;
    player.narrative_tense = PRESENT_TENSE;
    print "^[The memory fades.]^";
];

31.5.3 The CSubjectVerb Function

The core conjugation function is CSubjectVerb (in english.h). All library messages that print a subject-verb combination call this function or one of its specialized wrappers:

[ CSubjectVerb obj reportage nocaps v1 v2 v3 past;
    if (past && player provides narrative_tense
             && player.narrative_tense == PAST_TENSE) {
        v1 = past;
        v2 = past;
        v3 = past;
    } else {
        if (v2 == 0) v2 = v1;
        if (v3 == 0) v3 = v1;
    }
    if (obj == player) {
        if (player provides narrative_voice)
          switch (player.narrative_voice) {
          1:  print "I ", (string) v1; return;
          2:  ! Do nothing (fall through to default).
          3:  CDefart(player);
              print " ", (string) v3; return;
          default: RunTimeError(16, player.narrative_voice);
        }
        if (nocaps) { print "you ", (string) v2; return; }
        print "You ", (string) v2; return;
    }
    SubjectNotPlayer(obj, reportage, nocaps, v2, v3);
];

The full parameter reference (obj, reportage, nocaps, the present-tense forms v1/v2/v3, and past) and a worked example showing the output for each voice and tense are in §21.9. One english.h-specific detail: when reportage is true and the subject is not the player, the function prepends a reporting preamble via L__M(##Miscellany, 60, actor).

31.5.4 Specialized Conjugation Helpers

english.h provides wrapper functions for common English verbs. Each follows the same pattern as CSubjectVerb but with the verb forms built in:

CSubjectIs(obj, reportage, nocaps): Prints the subject with the appropriate form of "to be":

Voice Present Past
1 "I'm" "I was"
2 "You're" "You were"
3 "George is" "George was"

CSubjectIsnt(obj, reportage, nocaps) (line 593): Negative form of "to be":

Voice Present Past
1 "I'm not" "I wasn't"
2 "You aren't" "You weren't"
3 "George isn't" "George wasn't"

CSubjectHas(obj, reportage, nocaps) (line 609):

Voice Present Past
1 "I've" "I had"
2 "You've" "You'd"
3 "George has" "George had"

CSubjectWill(obj, reportage, nocaps) (line 625):

Voice Present Past
1 "I'll" "I would"
2 "You'll" "You'd"
3 "George will" "George would"

CSubjectCan(obj, reportage, nocaps) (line 641): Delegates to CSubjectVerb with "can" / "could".

CSubjectCant(obj, reportage, nocaps) (line 645): Delegates to CSubjectVerb with "can't" / "couldn't".

CSubjectDont(obj, reportage, nocaps) (line 649): Delegates to CSubjectVerb with "don't" / "doesn't" / "didn't".

31.5.5 The Tense Helper

The Tense function is a low-level helper that prints one of two strings depending on the current tense:

[ Tense present past;
    if (player provides narrative_tense
        && player.narrative_tense == PAST_TENSE) {
        if (past == false) return;
        print (string) past;
    }
    else
        print (string) present;
];

If past is 0 (false), the function prints nothing in past tense. This is useful for verb suffixes that exist in present tense but not in past tense. Library messages use Tense extensively:

! From LanguageLM, the Answer/Ask action:
print "There ";
Tense("is", "was");
" no reply.";
! Present: "There is no reply."
! Past:    "There was no reply."

31.5.6 Pronoun and Demonstrative Functions

Several functions handle pronoun selection based on narrative voice, gender, and number:

CThatOrThose(obj) (line 451) - Prints the nominative subject pronoun. For the player object, respects narrative_voice:

Voice Output
1 "I"
2 "You"
3 (player name)

For non-player objects, prints "He", "She", "Those", or "That" based on attributes.

CTheyreOrThats(obj) (line 469) - Prints the subject with a contracted form of "to be", aware of both voice and tense:

Voice Present Past
1 "I'm" "I was"
2 "You're" "You were"
3 "George's" "George was"

ThatOrThose(obj) (line 417) - Accusative (object) pronoun. For the player: "me" (voice 1), "you" (voice 2), or the definite article name (voice 3). For non-player objects: "him", "her", "those", or "that".

ItOrThem(obj) (line 434) - Accusative reflexive pronoun. For the player: "myself" (voice 1), "yourself" (voice 2), or the definite article name (voice 3). For non-player objects: "him", "her", "them", or "it".

IsOrAre(obj) (line 486) - Prints "is" or "are" (present) / "was" or "were" (past) based on whether obj has pluralname or is the player.

OnesSelf(obj) (line 654) - Reflexive pronoun: "myself" (voice 1), "yourself" (voice 2), "himself"/"herself" (voice 3), or appropriate third-person form for non-player objects.

31.5.7 Actor Reference Functions

theActor(obj) (line 705) - Prints a lowercase nominative pronoun for the subject. For the player object:

Voice Output
1 "I"
2 "you"
3 "he"/"she"/"it" (based on attributes)

For non-player objects: "he", "she", "they", or "that".

Possessive(obj, caps) (line 671) - Prints the possessive pronoun for obj, with optional capitalization:

Voice Output (caps=false) Output (caps=true)
1 "my" "My"
2 "your" "Your"
3 "George's" "George's"

For non-player objects: "his", "her", "their", or "its".

PossessiveCaps(obj) (line 701) - Convenience wrapper that calls Possessive(obj, true).

31.5.8 Additional Helper Functions

SubjectNotPlayer(obj, reportage, nocaps, v2, v3, past) (line 497)

  • Internal helper used by CSubjectVerb and its wrappers when obj is not the player. Handles reportage mode, plural/singular verb agreement, and tense selection for third-party NPCs.

CSubjectVoice(obj, v1, v2, v3, past) (line 533) - Prints only the verb form (without the subject name) selected by narrative voice and tense. Useful when the subject has already been printed separately.

SupportObj(obj, s1, s2) (line 726) - Prints s1 if obj has the supporter attribute, s2 otherwise. Used in messages about containers vs. supporters.

PluralObj(obj, s1, s2, past) (line 731) - Prints s1 if obj has pluralname, s2 otherwise, but overrides with past if narrative tense is past. Used for singular/plural verb agreement in action messages.

DecideAgainst() (line 755) - Prints a complete sentence indicating the actor decided against an action, using CSubjectVerb to handle voice and tense:

[ DecideAgainst;
    CSubjectVerb(actor, false, false, "decide",0,"decides","decided");
    print " that";
    Tense("'s not", " wasn't");
    " such a good idea.";
];

31.5.9 Writing Voice-Aware Library Messages

When writing custom library messages (via LibraryMessages or a replacement LanguageLM), always use the conjugation helpers rather than hard-coded strings. This ensures messages adapt correctly to voice and tense changes:

! WRONG: hard-coded second-person present
Eat: "You eat ", (the) x1, ". Delicious!";

! RIGHT: voice and tense aware
Eat:
    CSubjectVerb(actor, false, false, "eat", 0, "eats", "ate");
    print " ", (the) x1, ". Delicious!";

For messages that include auxiliary verbs, use the specialized helpers:

! "You can't eat that." / "I couldn't eat that." / etc.
CSubjectCant(actor, true);
" eat ", (ThatOrThose) x1, ".";

For conditional text that varies by tense alone, use Tense:

print "Nothing ";
Tense("happens", "happened");
".";

For further information on replacing and intercepting library messages, see §30.