Chapter 15: Compiler Limits and Memory Settings
This chapter describes the limits that constrain a program: both the hard constraints imposed by the target virtual machine and the configurable settings that control the compiler's own behavior. It collects the practical information a programmer needs when a project grows beyond default limits, when choosing between Z-machine and Glulx, or when fine-tuning the compiler for a production release.
15.1 Overview
Limits on a program come from two distinct sources:
-
Virtual machine constraints. The Z-machine and Glulx each define a fixed architecture - address widths, object table formats, and instruction encodings - that imposes absolute upper bounds. Compiler settings cannot change these limits; they are inherent in the target platform.
-
Compiler configuration. The compiler itself maintains internal tables and parameters that govern dictionary layout, attribute storage, stack size, and similar concerns. These are controlled with
$SETTING=valueoptions (see §12.4 for the syntax).
Since compiler version 6.36, the second category has been dramatically simplified. Most internal tables that formerly required fixed-size allocations now grow dynamically as needed. The settings that remain are those with semantic significance - they affect the format of the compiled output, not just how much workspace the compiler reserves during compilation.
The practical consequence is that modern projects rarely need to adjust compiler settings at all. When limits are encountered, they are almost always VM-imposed constraints that require either choosing a different Z-machine version or switching to Glulx.
15.2 Z-Machine Story File Size Limits
The Z-machine exists in several versions, each with its own size constraints. These are architectural limits defined by the Z-Machine Standards Document and cannot be overridden by compiler settings.
15.2.1 Size and Object Limits by Version
| Version | Max file size | Max objects | Max attributes | Max properties | Max globals |
|---|---|---|---|---|---|
| V3 | 128 KB | 255 | 32 | 31 | 240 |
| V4 | 256 KB | 65,535 | 48 | 63 | 240 |
| V5 | 256 KB | 65,535 | 48 | 63 | 240 |
| V6 | 512 KB | 65,535 | 48 | 63 | 240 |
| V7 | 512 KB | 65,535 | 48 | 63 | 240 |
| V8 | 512 KB | 65,535 | 48 | 63 | 240 |
The "max properties" column reflects the Z-Machine architectural limit (property
numbers 1-31 in V3, 1-63 in V4+). The compiler reserves a small number of
property slots for internal use (name, class inheritance, individual property
table), so the practical limit on user-declarable common properties is 29 in
V3 and 61 in V4+. Exceeding this limit produces the error "All 29 properties
already declared" (or "All 61 properties already declared"). Similarly, the "max
globals" column shows the architectural total of 240; the compiler reserves 7 of
those slots, so the user limit is 233 (see §15.2.2).
V3 is the original Infocom format. Its 128 KB file size limit, 255-object maximum, and 32 attributes make it unsuitable for large modern games. V5 is the default target and the best choice for most Z-machine projects. V8 doubles the packed address scale factor, allowing larger routine and string segments within a 512 KB file; it is the recommended choice for large Z-code games that exceed V5's 256 KB limit.
15.2.2 Other Z-Machine Limits
Several additional limits apply across all Z-machine versions:
-
Local variables: A maximum of 15 local variables per routine. This is a hard limit of the Z-machine instruction encoding.
-
Dictionary word resolution: In V3, dictionary words are resolved to 6 characters (stored in 4 bytes using Z-character encoding). In V4 and later versions, words are resolved to 9 characters (stored in 6 bytes). Words longer than the resolution limit are silently truncated by the parser.
-
Packed address scale factors: Routine and string addresses are stored as packed values. The scale factor determines the granularity of addressing and therefore the maximum addressable space:
Version Packed address scale Effective routine/string limit V3 ×2 128 KB V4-V5 ×4 256 KB V6-V7 ×4 (with offsets) 512 KB V8 ×8 512 KB V6 and V7 use separate routine and string offset values in the header to extend addressing beyond the basic scale factor.
-
Global variables: The Z-machine architecture provides 240 global variable slots. The compiler reserves 7 of them for internal use (four temporaries,
self,sender, andsw__var), leaving at most 233 user-declarable globals. See §3.1 for details. -
Abbreviations and dynamic strings: The Z-machine allocates a shared pool of exactly 96 slots for these two features combined. The defaults are
$MAX_ABBREVS=64and$MAX_DYNAMIC_STRINGS=32(summing to 96). If you change only one of the two, the compiler automatically sets the other to96 -that value. If you change both and they do not sum to 96, the compiler issues the warning "MAX_ABBREVS plus MAX_DYNAMIC_STRINGS must be 96 in Z-code; resetting both" and resets both to the 64/32 defaults. -
Property values per property: On the Z-machine, a single property may hold at most 32 values (64 bytes). For V3 common properties, the limit is tighter: 4 values (8 bytes). These are hard limits enforced by the compiler, resulting in an error such as "Limit (of 32 values) exceeded for property". In practice, they are rarely reached.
15.3 Glulx Limits
[Glulx] Glulx is a 32-bit virtual machine designed to overcome the Z-machine's size constraints. Its limits are far more generous:
-
Address space: 32-bit addressing provides a theoretical maximum of 4 GB for the story file. In practice, file sizes are limited by interpreter memory and the Glulx specification's use of signed offsets, but multi-megabyte games are routine.
-
Objects: There is no hard limit on the number of objects. The compiler allocates object records dynamically.
-
Attributes: Configurable via
$NUM_ATTR_BYTES. The default of 7 bytes provides 56 attributes. The value must follow the formula 4_n_ + 3 (so 7, 11, 15, 19, ...) up to a maximum of 39 bytes (312 attributes). -
Properties: There is no architectural limit on properties. The setting
$INDIV_PROP_START(default 256) determines the boundary between common and individual properties; properties numbered below it are common; those at or above it are individual. A single property may hold at most 32,768 values; this is a compiler-imposed limit that is effectively never reached in practice. -
Dictionary word resolution: Controlled by
$DICT_WORD_SIZE(default 9). Unlike the Z-machine, this is freely adjustable.$DICT_CHAR_SIZEcan be set to 4 for full Unicode dictionary entries. -
Local variables:
MAX_LOCAL_VARIABLESis set to 119 (including the internalspslot), giving a maximum of 118 usable local variables per routine (compared to 15 in the Z-machine). -
Stack size: Controlled by
$MAX_STACK_SIZE(default 4096 bytes). This can be increased for deeply recursive programs. -
Global variables: No fixed limit (dynamically allocated by the compiler).
-
Memory extension:
$MEMORY_MAP_EXTENSIONappends extra zero bytes to the story file for runtime use.$GLULX_OBJECT_EXT_BYTESadds extra bytes to each object record for custom data.
The combination of these generous limits makes Glulx the natural choice for large projects, games requiring extensive world models, or applications needing full Unicode support.
15.4 Configurable Compiler Settings
The following table lists all $SETTING=value options recognized by the current
compiler (version 6.44). The Z-machine specification determines the settings
marked "fixed" in the Z-code column, which cannot be changed when compiling for
Z-code. Settings marked "N/A" do not apply to that target.
For the syntax used to set these values, see §12.4.1. To display all current
values, run inform $LIST.
15.4.1 Dictionary and Text Settings
| Setting | Z-code default | Glulx default | Description |
|---|---|---|---|
$DICT_WORD_SIZE |
always 6 (fatal error if set otherwise) | 9 | Number of significant characters resolved per dictionary word. In Z-code, this setting is fixed at 6 - explicitly setting it to any other value is a fatal error - and the compiler auto-sizes each entry's encoded text to 4 bytes (6 Z-characters) in v3 and 6 bytes (9 Z-characters) in v4+, so omit it entirely for Z-code projects; see §15.7.1. In Glulx, it is freely adjustable; the encoded word then occupies DICT_WORD_SIZE × DICT_CHAR_SIZE bytes. |
$DICT_CHAR_SIZE |
1 (fixed) | 1 | Bytes per character in dictionary words. Set to 4 in Glulx for Unicode dictionary entries. |
$MAX_ABBREVS |
64 | N/A | Maximum number of declared abbreviations (a single Abbreviate directive may declare several). Z-code hard limit is 96. Not meaningful in Glulx (no abbreviation limit). |
$MAX_DYNAMIC_STRINGS |
32 | 100 | Maximum number of string substitution variables (@00, @(0), etc.). Z-code hard limit is 96. |
15.4.2 Grammar and Object Settings
| Setting | Z-code default | Glulx default | Description |
|---|---|---|---|
$GRAMMAR_VERSION |
1 | 2 | Grammar table format. Version 2 is the standard format used by modern libraries; version 1 is the older Infocom-style format. Version 3 is a compact format (Z-code only, new in 6.43). |
$INDIV_PROP_START |
64 (fixed) | 256 | First individual property number. Properties below this are common; those at or above are individual. |
$NUM_ATTR_BYTES |
6 (fixed) | 7 | Bytes used for attribute flags. Each byte provides 8 attributes (Z-code: 48; Glulx default: 56). |
15.4.3 Glulx-Specific Settings
[Glulx] These settings apply only when compiling for Glulx:
| Setting | Default | Description |
|---|---|---|
$MAX_STACK_SIZE |
4096 | Interpreter stack size in bytes. Increase for deeply recursive programs. |
$MEMORY_MAP_EXTENSION |
0 | Extra zero bytes appended to the story file, available as writable memory at runtime. |
$GLULX_OBJECT_EXT_BYTES |
0 | Additional bytes per object record (any non-negative value). Available for custom use by the game or library. |
15.4.4 Z-Code-Specific Settings
[Z-machine] These settings apply only when compiling for the Z-machine:
| Setting | Default | Description |
|---|---|---|
$ZCODE_HEADER_EXT_WORDS |
3 | Words in the Z-code header extension table. |
$ZCODE_HEADER_FLAGS_3 |
0 | Value of Flags 3 in the header extension (Z-Machine Standard 1.1). |
$ZCODE_FILE_END_PADDING |
1 | If 1, pad the story file to a multiple of 512 bytes. Set to 0 to omit padding. |
$ZCODE_MAX_INLINE_STRING |
32 | Maximum length of a string literal assembled inline rather than placed in the string pool. |
$ZCODE_COMPACT_GLOBALS |
0 | If 1, reuse global variable slots that are declared but never written. |
$ZCODE_LESS_DICT_DATA |
0 | If 1, use 2 data bytes per dictionary entry instead of 3, saving space in large dictionaries. |
15.4.5 Compiler Behavior Settings
These settings control compiler internals and output features:
| Setting | Default | Description |
|---|---|---|
$HASH_TAB_SIZE |
512 | Size of the symbol hash table. Larger values may speed compilation of very large programs. |
$TRANSCRIPT_FORMAT |
0 | Format of the gametext.txt file: 0 for human-readable, 1 for machine-parseable. |
$SERIAL |
auto | Six-digit serial number for the story file header. Default uses the compilation date (YYMMDD). |
15.4.6 Optimization and Output Flags
These Boolean settings (0 or 1) control compiler optimization passes and output format. See §12.5 for detailed descriptions of each.
| Setting | Default | Description |
|---|---|---|
$OMIT_UNUSED_ROUTINES |
0 | If 1, strip routines that are never called (dead-code elimination). |
$WARN_UNUSED_ROUTINES |
0 | If 1, warn about unused routines in game source; if 2, also in library files. |
$STRIP_UNREACHABLE_LABELS |
1 | If 1, remove labels in generated code that can never be reached. |
$OMIT_SYMBOL_TABLE |
0 | If 1, omit property, array, and symbol names from the output file. |
15.4.7 Dictionary and Grammar Flags
These Boolean settings (0 or 1) control dictionary-entry flags and grammar-table features. See §12.5 for detailed descriptions.
| Setting | Default | Description |
|---|---|---|
$DICT_IMPLICIT_SINGULAR |
0 | If 1, dictionary words in noun context automatically get the singular flag. |
$DICT_TRUNCATE_FLAG |
0 | If 1, flag bit 6 marks words truncated beyond $DICT_WORD_SIZE. |
$LONG_DICT_FLAG_BUG |
1 | If 1, retain legacy buggy handling of //p on long dictionary words. Set to 0 for correct behavior. |
$GRAMMAR_META_FLAG |
0 | If 1, enable per-action meta flags in the grammar table. |
15.5 Memory Allocation Model
Understanding how the compiler manages its own memory helps explain why most historical memory settings are no longer needed.
15.5.1 Dynamic Memory Lists
The compiler uses dynamic memory lists for nearly all internal tables. A
memory list is an array that starts empty (or with a small initial allocation)
and grows on demand. When a table needs more space, the compiler calls
ensure_memory_list_available(), which allocates room according to a simple
growth formula:
new_count = 2 × requested_count + 8
This exponential-with-headroom strategy means that a table that grows
incrementally (one item at a time) will double in capacity each time it
overflows, amortizing the cost of reallocation. The + 8 term ensures that very
small tables get a reasonable minimum allocation without requiring a separate
code path.
Memory lists never shrink during compilation. They are freed in bulk when the compiler finishes.
15.5.2 Tracking Memory Usage
The compiler tracks total allocated memory in the internal variable
malloced_bytes. You can inspect memory usage with the trace option:
inform $!MEM adventure.inf
This prints a line for each internal allocation and deallocation, showing the
purpose and size. For a summary of all compiler statistics, including memory,
use the -s switch:
inform -s adventure.inf
The statistics output includes the total memory allocated during compilation, which is useful for verifying that a build stays within the resources available on constrained systems.
15.5.3 What Remains Fixed
Not everything is dynamically allocated. The settings listed in §15.4 that affect the output format - dictionary word size, attribute byte count, stack size, and similar parameters - must be known before compilation begins because they determine the layout of the story file. These are genuine configuration values, not arbitrary workspace limits.
15.6 Removed and Obsolete Settings
Over Inform's history, memory settings have been removed. Attempting to use a removed setting produces a warning rather than an error, so that old build scripts continue to work.
Module and linking settings
The module compilation system (-M switch) and linking (Link directive) were
removed entirely. Any settings related to module linking are also obsolete.
If you are porting a project from an older compiler version, you can safely delete all of these settings.
15.7 When and How to Adjust Settings
Most projects will never need to change any compiler setting. When you do, it is usually in response to a specific compiler message or a conscious design decision about the output format. Here are the most common scenarios.
15.7.1 Enlarging Dictionary Word Resolution
[Glulx] The default dictionary resolution of 9 characters is sufficient for
most English-language games. For games in languages with long compound words
(such as German or Finnish), or for games that need to distinguish very similar
long words, increase $DICT_WORD_SIZE:
! In an ICL file or on the command line:
! $DICT_WORD_SIZE=12
! The parser will now distinguish the first 12 characters
! of each word, rather than 9.
For full Unicode dictionary support (necessary if your game accepts input in
non-Latin scripts), also set $DICT_CHAR_SIZE=4:
inform -G $DICT_WORD_SIZE=12 $DICT_CHAR_SIZE=4 adventure.inf
[Z-machine] Dictionary word size cannot be changed in Z-code: the compiler
auto-sizes each entry's encoded text to 4 bytes (holding 6 Z-characters) in
v3 and 6 bytes (holding 9 Z-characters) in v4+, and $DICT_WORD_SIZE must
be left at its Z-code default of 6 - any other value is a fatal error, not
silently ignored (see the note below).
Note: Due to a current compiler quirk, explicitly setting
$DICT_WORD_SIZEto any value other than 6 on the command line (or in an!%header comment) for a Z-code target is a fatal error, even if the value matches the version's natural byte size (e.g.,$DICT_WORD_SIZE=4for v3 still fails). Omit the setting entirely for Z-code projects.
15.7.2 Enabling Dead-Code Stripping
For production releases, enabling dead-code elimination can substantially reduce the story file size, especially when using the standard library:
inform -G $OMIT_UNUSED_ROUTINES=1 adventure.inf
To preview which routines would be removed without actually removing them, use the warning mode first:
inform -G $WARN_UNUSED_ROUTINES=2 adventure.inf
Level 2 reports unused routines in both the game source and library files. Level 1 reports only game-source routines.
15.7.3 Increasing the Glulx Stack Size
[Glulx] If your game uses deep recursion or complex nested function calls, you may encounter a stack overflow at runtime. The solution is to increase the stack allocation:
inform -G $MAX_STACK_SIZE=8192 adventure.inf
The value is in bytes. The default of 4096 is sufficient for most games; values of 8192 or 16384 handle all but the most extreme cases.
15.7.4 Adding Extra Attributes
[Glulx] If 56 attributes (the default) are not enough, increase
$NUM_ATTR_BYTES. The value must follow the pattern 4_n_ + 3:
inform -G $NUM_ATTR_BYTES=11 adventure.inf
This provides 88 attributes (11 × 8). The maximum is 39 bytes (312 attributes).
[Z-machine] The number of attribute bytes is fixed at 6 (48 attributes) by the Z-machine specification and cannot be changed.
15.7.5 Reserving Runtime Memory
[Glulx] The $MEMORY_MAP_EXTENSION setting appends extra writable bytes at
the end of the story file. This memory is available at runtime for custom data
storage by the game or library:
inform -G $MEMORY_MAP_EXTENSION=4096 adventure.inf
Similarly, $GLULX_OBJECT_EXT_BYTES reserves extra bytes in each object record:
inform -G $GLULX_OBJECT_EXT_BYTES=8 adventure.inf
These extra bytes are initialized to zero and can be read and written using assembly-level memory access.
15.7.6 Reducing Z-Code File Size
[Z-machine] When a Z-code game is pressing against size limits, several settings can reclaim small amounts of space:
$ZCODE_LESS_DICT_DATA=1saves one byte per dictionary entry by reducing the per-word data from 3 bytes to 2.$ZCODE_COMPACT_GLOBALS=1reuses global variable slots that are declared but never written.$OMIT_UNUSED_ROUTINES=1strips routines that are never called.$OMIT_SYMBOL_TABLE=1omits symbol names from the output.$ZCODE_FILE_END_PADDING=0omits the trailing padding that rounds the file to a 512-byte boundary.
These techniques are useful when a game is a few kilobytes over the V5 or V8 limit and switching to Glulx is not an option.
15.8 Practical Guidance
15.8.1 Choosing a Target Platform
The choice between Z-machine versions and Glulx is the single most important decision affecting limits. Here is a summary of the trade-offs:
| Criterion | Z-machine V5 | Z-machine V8 | Glulx |
|---|---|---|---|
| Max file size | 256 KB | 512 KB | Effectively unlimited |
| Max objects | 65,535 | 65,535 | No hard limit |
| Max attributes | 48 | 48 | 56+ (configurable) |
| Max properties | 63 | 63 | No hard limit |
| Integer size | 16-bit | 16-bit | 32-bit |
| Local variables | 15 | 15 | 118 |
| Dictionary resolution | 9 chars | 9 chars | Configurable |
| Interpreter support | Excellent | Good | Good |
| Multimedia | Limited | Limited | Full (via Glk) |
V5 is the right default for small to medium games. It offers the widest interpreter compatibility and is the compiler's default target.
V8 extends the file size limit to 512 KB without changing the instruction set. Choose V8 when your game exceeds 256 KB, but you want to remain in the Z-machine ecosystem.
Glulx removes nearly all size constraints. Choose it for large games, games requiring many attributes or properties, games needing 32-bit arithmetic, games with multimedia, or games targeting non-Latin scripts with Unicode support.
15.8.2 General Recommendations
-
Start with defaults. The compiler's default settings are appropriate for the vast majority of projects. Do not adjust settings preemptively.
-
Let the compiler tell you. When a limit is reached, the compiler produces a clear error or warning message identifying the constraint. Adjust the specific setting mentioned.
-
Prefer Glulx for large projects. If you find yourself adjusting multiple Z-machine limits, consider switching to Glulx with
-Ginstead. One target change often eliminates several workarounds. -
Clean up old settings. If you inherit a project with many
$MAX_*, remove them. The current compiler ignores them and produces warning messages. -
Use
-sto monitor. The statistics switch shows how much of each VM resource your game consumes. Run it periodically during development to catch approaching limits early:inform -s adventure.inf -
Use
$LISTto review. To see every configurable setting and its current value:inform $LIST
This is especially useful when diagnosing unexpected behavior caused by a setting inherited from an ICL file or header comment.