The Inform 6 Programmer's Guide

Chapter 7: Objects, Classes, and Inheritance

The language is fundamentally object-oriented, and objects are the primary building blocks of any program, representing everything from rooms and items to abstract concepts and the player character. This chapter defines the object system, including object declarations, the object tree, properties, attributes, classes, and inheritance.

7.1 Object Declarations

An object is declared with the Object directive. The full syntax is:

Object [->...] [name] ["short name"] [parent]
    [with    property_list]
    [private property_list]
    [has     attribute_list]
    [class   class_list];

All parts except Object and the terminating semicolon are optional. The four body segments (with, private, has, class) may appear in any order and may be repeated. with is described in §7.4, has in §7.5, class in §7.7, and private in §7.14.

7.1.1 Basic Object Syntax

The simplest object declaration:

Object lamp;

This creates an object with the internal identifier lamp, no short name, no parent, no properties, and no attributes.

A more typical declaration includes a short name, parent, properties, and attributes:

Object lamp "brass lamp" study
    with name 'brass' 'lamp' 'lantern',
         description "A well-polished brass lamp.",
         before [;
             Burn: "The lamp is already quite hot.";
         ],
    has  light;

7.1.2 Components of an Object Declaration

  • Arrow (->): A run of arrows sets the new object's nesting depth to the number of arrows. The parent is then the most recently defined object whose own depth is one less than that. So -> (depth 1) makes the new object a child of the most recent root-level object, -> -> (depth 2) makes it a child of the most recent depth-1 object, and so on.
  • Identifier: The internal name used in source code to refer to the object. This is optional; anonymous objects can be created.
  • Short name: A double-quoted string used for display to the player at runtime. It is stored in the object's built-in short-name slot (in the Z-machine object header, or as the shortname field of a Glulx object), which is what print (object) obj outputs. Note that this is distinct from the standard library's short_name property, which (when defined) the library's (name)/(the) printing routines consult in preference to the built-in short name.
  • Parent: An identifier naming the parent object in the object tree. The object is placed as a child of this parent.

7.1.3 The Arrow Notation

The arrow notation provides a convenient way to build object hierarchies without explicitly naming parents:

Object kitchen "Kitchen";

Object -> table "wooden table" with name 'table' 'wooden';

Object -> -> plate "china plate" with name 'plate' 'china';

Object -> chair "chair" with name 'chair';

Here, table and chair are children of kitchen. The plate is a child of table. Each -> represents one level of nesting relative to the most recent object at the previous level.

7.2 The Nearby Directive

Nearby is a convenience form for declaring an object as a child of the most recently defined root-level object:

Object cave "Dark Cave";

Nearby rock "heavy rock"
    with name 'rock' 'heavy' 'boulder',
         description "An enormous boulder.";

It is exactly equivalent to Object -> rock "heavy rock" .... In particular, Nearby always sets the new object's tree depth to 1 (child of the most recent depth-0 object); it does not vary its placement based on the previous object's depth, and it is not equivalent to a chain of nested arrows.

7.3 The Object Tree

All objects in a program exist within a single tree structure. Every object (except root-level objects) has exactly one parent. Each object may have zero or more children. Siblings are children of the same parent, linked in a chain.

7.3.1 Tree Navigation Functions

The following system functions navigate the object tree:

Function Returns
parent(obj) The parent of obj, or nothing (0) if obj is a root
child(obj) The first child of obj, or nothing if no children
children(obj) The number of direct children of obj
sibling(obj) The next sibling of obj, or nothing if last
elder(obj) The previous sibling of obj, or nothing if obj has no parent or is the first child
eldest(obj) Same as child(obj) - the first child
younger(obj) Same as sibling(obj) - the next sibling
youngest(obj) The last child of obj

All eight tree-navigation functions above are system functions recognized directly by the compiler. parent, child/eldest, and sibling/younger translate straight to the underlying VM tree opcodes; children, youngest, and elder are compiled inline as short loops over those same opcodes.

7.3.2 Tree Manipulation Statements

Two statements modify the object tree at runtime:

move obj to new_parent;

Removes obj from its current position in the tree and makes it the first child of new_parent. It is a runtime error to move an object to be a descendant of itself.

remove obj;

Removes obj from the tree entirely, setting its parent to nothing. The object still exists but is no longer part of any hierarchy.

7.3.3 Iterating Over the Tree

The objectloop statement iterates over objects in the tree:

! All children of a parent
objectloop (x in kitchen)
    print (name) x, "^";

! All objects in the game
objectloop (x)
    if (x has light) print (name) x, " gives light.^";

See §5 for the full objectloop syntax.

7.4 Properties

Properties are named data slots attached to objects. Each property holds one or more word-sized values.

7.4.1 Common Properties

Common properties are shared across all objects in the game. They are defined with the Property directive:

Property weight;

Every object in the game can then use the weight property. If an object does not explicitly define a common property, accessing it returns the property's default value (0 unless set otherwise).

The number of common properties is limited:

  • Z-machine: Common properties occupy property numbers 1-63 on Z-machine versions 4 and later, or 1-31 on version 3. Two of those numbered slots are reserved by the compiler for internal use. Property 1 is always the built-in name property. Hence, the user-declarable limit is 61 common properties in v4 and later (one built-in name plus up to 60 declared with Property) and 29 in v3 (one built-in name plus up to 28 declared with Property). The standard library declares 47 properties with Property, which, together with name, gives 48 user-visible common properties.
  • Glulx: The limit depends on the INDIV_PROP_START setting (default 256), so by default common property numbers run 1-255 (INDIV_PROP_START - 1), of which INDIV_PROP_START - 3 (default 253, including the built-in name) are user-declarable. In practice, the limit is much higher than the standard library requires.

A default value can be set:

Property weight 0;

7.4.2 Individual Properties

Properties defined within a Class or Object that are not declared as common properties become individual properties. Individual properties exist only on objects that explicitly define them:

Object widget "widget"
    with gizmo_factor 42;

If gizmo_factor was never declared with Property, it becomes an individual property. Attempting to read an individual property from an object that does not provide it causes a runtime error, whether or not strict runtime checking is enabled (see §7.10). This is unlike a common property that an object lacks, whose default value is returned silently.

7.4.3 Property Values

A property can hold one or more word values:

Object box "box"
    with name 'box' 'container' 'crate',
         description "A sturdy wooden crate.",
         capacity 10;

The name property holds three dictionary word values. The description property holds a string address. The capacity property holds the integer 10.

A property value may also be an embedded routine:

Object door "oak door"
    with description [;
             if (self has open) "The oak door stands open.";
             "A heavy oak door, firmly closed.";
         ];

7.4.4 Property Access Operators

Properties are accessed with the . operator and related operators:

Operator Meaning
obj.prop Read the first word of the property value
obj.prop = val Write the first word of the property value
obj.&prop Get the byte address of the property data
obj.#prop Get the length of the property data in bytes

For multi-valued properties, the address and length operators are essential:

! Print all name words of an object
addr = obj.&name;
len = obj.#name / WORDSIZE;  ! WORDSIZE is 2 (Z) or 4 (Glulx)
for (i = 0 : i < len : i++)
    print (address) addr-->i, " ";

7.4.5 Additive Properties

A property declared as additive accumulates values through inheritance rather than being overridden:

Property additive before;

When a class defines before and a subclass also defines before, the values are concatenated rather than replaced. The standard library declares before, after, life, orders, describe, time_out, and each_turn as additive. The compiler also treats its built-in name property as additive without an explicit declaration.

7.4.6 Long Properties

Any property can hold more than one word of data. This is a long property:

Object thing
    with data 10 20 30 40;

The data property holds four words. Access individual words through the address:

addr = thing.&data;
val = addr-->2;  ! Gets the third word (30)

7.5 Attributes

Attributes are Boolean flags that can be set or cleared on any object. They are declared with the Attribute directive:

Attribute explosive;

7.5.1 Attribute Limits

  • Z-machine: Up to 48 attributes (numbered 0-47) on Z-machine versions 4 and later (32 attributes on version 3). The standard library declares approximately 32.
  • Glulx: Configurable at compile time via the $NUM_ATTR_BYTES setting. The default is 7 bytes, giving 56 attributes; the maximum is 39 bytes, giving 312 attributes. The value must satisfy the constraint 4k + 3 (i.e., one of 3, 7, 11, 15, ..., 39); if a value that does not satisfy this constraint is supplied, the compiler rounds it up to the next valid value and issues a warning. Set it on the command line, e.g., $NUM_ATTR_BYTES=15, to expand the attribute space.

7.5.2 Setting and Testing Attributes

Attributes are set in object declarations with has:

Object bomb "bomb" with name 'bomb', has explosive;

At runtime, attributes are manipulated with give and tested with has/hasnt:

give bomb ~explosive;       ! Clear the explosive attribute
give bomb light;            ! Set the light attribute

if (bomb has explosive)     ! Test if set
    "It might explode!";

if (lamp hasnt light)       ! Test if cleared
    "The lamp is dark.";

7.6 The Class Directive

A class is a template for creating objects. Classes are defined with the Class directive:

Class Treasure
    with value 0,
         description "A glittering treasure.",
    has  scored;

7.6.1 Creating Instances

Objects can be created from a class by naming the class before the object identifier:

Treasure gold_coin "gold coin"
    with name 'gold' 'coin',
         value 50;

The gold_coin object inherits all properties and attributes from Treasure, with value overridden to 50.

7.6.2 Pre-Created Instances

A class can specify several pre-created duplicate instances, made available as a pool for the create/destroy/recreate/copy class methods (see §7.11):

Class Weapon(10)
    with damage 1;

The (10) causes the compiler to manufacture a pool of 10 anonymous duplicate instances of Weapon at compile time (internally, one additional duplicate is also created and kept as an untouched prototype used by recreate and destroy). Each duplicate is initially placed as a child of the Weapon class object; the 10 pooled duplicates are ready-to-use instances that Weapon.create() can hand out and Weapon.destroy(obj) can return to the pool. The number of duplicates must be in the range 0 to 10000; if (N) is omitted, no duplicates are pre-created, and the class has no pool.

The (N) notation does not impose a global limit on how many instances of the class may exist: ordinary instance declarations (Weapon sword ...;) are unaffected by it.

7.6.3 Class as Object

Every Class is itself an object in the object tree. The class object can be referred to by name and used in expressions. metaclass(Treasure) returns Class.

7.7 Inheritance

7.7.1 Single Inheritance

When an object is declared as an instance of a class, it inherits all properties and attributes from that class. Explicitly specified properties override inherited ones (unless the property is additive):

Class Container
    with capacity 10,
    has  container open;

Container chest "wooden chest"
    with name 'chest' 'wooden',
         capacity 20;   ! Overrides inherited value

7.7.2 Multiple Inheritance

An object or class can inherit from multiple classes:

Class Lockable
    with with_key 0,
    has  lockable;

Class Container
    with capacity 10,
    has  container openable open;

Class LockableContainer
    class Lockable Container;

LockableContainer safe "iron safe"
    with name 'safe' 'iron',
         with_key brass_key;

When more than one class is listed, properties resolve in the following order:

  1. The object's own with segment always wins. Properties defined directly on the object override any value an inherited class would have supplied (for non-additive properties).
  2. For inherited non-additive properties, the first class in the class list that defines the property contributes its value; later classes are ignored for that property.
  3. For additive properties - those declared with Property additive ... (for example, before), together with the built-in name property, which the compiler treats as additive without such a declaration (§7.4.5) - values accumulate across the chain: the object's own value comes first, followed by the contributions of each listed class in declaration order.

7.7.3 Attribute Inheritance

Attributes are combined with logical OR across all parent classes. If any parent class has an attribute, the child inherits it. An explicit has ~attr in the child can clear an inherited attribute:

Class Fixture has static scenery;

Fixture pillar "stone pillar"
    with name 'pillar' 'stone',
    has  ~scenery;  ! Overrides: still static but not scenery

7.8 The metaclass() Function

The metaclass() system function determines the type of a value at runtime:

Value Type metaclass() Returns
An ordinary object Object
A class object Class
A routine address Routine
A string address String
nothing (0) or invalid nothing (0)
if (metaclass(x) == Object) print "It's an object.^";
if (metaclass(x) == Class)  print "It's a class.^";

7.9 The ofclass Operator

The ofclass operator tests whether an object is an instance of a given class:

if (obj ofclass Treasure) print "It's a treasure!^";

An object is considered ofclass a class if:

  • It was directly created from that class, or
  • It inherits from that class through any chain of class inheritance.

The negated form uses standard negation:

if (obj ofclass Treasure) ...  ! positive test
if (~~(obj ofclass Treasure)) ...  ! negated test

7.10 The provides Operator

The provides operator tests whether an object has a given property:

if (obj provides description)
    print (string) obj.description;
else
    print "You see nothing special.^";

This is essential for individual properties, which may not exist on all objects. Reading an individual property that an object does not provide causes a runtime error in both strict and non-strict builds - individual-property reads are compiled to the RV__Pr veneer routine, which reports the error unconditionally for individual-property numbers - so provides should be used to check first. (This is unlike reading a common property that an object lacks, which returns that property's default value silently.)

7.11 The create, recreate, destroy, copy, and remaining Class Methods

Classes provide built-in methods for managing a pool of pre-created instances (see §7.6.2). All of them are invoked on the class object, not on an individual instance.

The class-message machinery is unavailable on Z-machine v3: any use of Class.create, Class.recreate, Class.destroy, Class.copy, or Class.remaining produces a compile-time error ("Class messages are not supported in v3."). Use v5+ or Glulx for class-pool features.

7.11.1 create

new_obj = ClassName.create();

Removes one of the class's pre-created duplicates from the pool and returns it as a fresh instance. Returns false (0) if the pool is empty. Up to three extra arguments may be passed; if the new object provides a create property, it is called with those arguments.

7.11.2 recreate

ClassName.recreate(obj);

Resets obj to its initial class-defined state, restoring all property values and attributes to those of the class prototype. obj must be ofclass ClassName. Up to three extra arguments may be passed, in which case the object's create property (if any) is then called with them. This is useful for object pooling.

On Glulx, recreate first calls the object's destroy property (if provided) before resetting it; the Z-machine variant does not call destroy during recreate.

Class Bullet(20)
    with damage 5,
         speed 100;

! Reset a used bullet to its original state
Bullet.recreate(bullet_obj);

7.11.3 destroy

ClassName.destroy(obj);

Resets obj to its initial state and returns it to the class's pool of available duplicates so that a subsequent ClassName.create() call can re-issue it. obj must be ofclass ClassName. If the object provides a destroy property, it is called first.

7.11.4 copy

ClassName.copy(dst, src);

Copies attributes and property values from src to dst. The first argument is the destination and the second is the source. Both src and dst must be ofclass ClassName.

All attributes (positive and negative) are copied. For properties, only those that are declared by both src and dst and have the same length in both objects are copied; properties unique to one side, or declared with different lengths, are left unchanged. The copy is shallow: any addresses or object references stored in property data are duplicated as-is rather than deep-copied.

7.11.5 remaining

n = ClassName.remaining();

Returns the number of unused duplicates still in the class's pool.

7.12 Message Passing

When a property holds a routine, accessing the property with () calls the routine as a message:

obj.description();

This calls the embedded routine stored in obj.description, with self set to obj.

7.12.1 The self Variable

Inside any routine called as a property value (via message passing), the special variable self refers to the object that received the message:

Object mirror "mirror"
    with description [;
             print "You look at ", (the) self, " and see your reflection.^";
         ];

self is automatically set before the routine is called and restored afterward. It should not be explicitly assigned in normal code.

7.12.2 PrintOrRun Semantics

When the library accesses a property value, it typically uses PrintOrRun semantics: if the value is a string, it is printed; if it is a routine, it is called. The . operator returns the first word of the property data, which may be either a string address or a routine address.

7.13 The Superclass Operator ::

The :: operator accesses a property as defined by a specific class, bypassing any overrides:

val = obj.ClassName::property;

This retrieves the value of property as defined by ClassName, even if obj has overridden it:

Class Vehicle with speed 60;

Vehicle car "car" with speed 120;

! car.speed is 120
! car.Vehicle::speed is 60

7.14 Property Visibility

There is a single, narrow form of access control: an individual property may be declared in a private segment of an object or class definition instead of (or in addition to) the usual with segment.

Object safe "iron safe"
    with description "A heavy iron safe.",
    private combination 4271;

A property declared in a private segment of an object can only be accessed while the object itself is the current message recipient (i.e. while self == obj). The runtime helpers backing obj.prop, obj.&prop, obj.#prop, and obj provides prop all honor this test: when self is not the object, a private property is reported as not provided, exactly as if the object had never declared it. So from outside the object obj.&prop and obj.#prop return 0, obj provides prop returns false, and reading the value with obj.prop triggers the same runtime error as reading any unprovided individual property (in both strict and non-strict builds; see §7.10). The gate lives in the RA__Pr veneer routine, which matches a private property's entry in the individual-property table - flagged there as private - only while self == obj. All of obj.prop, obj.&prop, and obj.#prop reach RA__Pr for their private-property lookup, and obj provides prop compiles to the OP__Pr veneer routine, which contains no self == obj test of its own but also calls RA__Pr, so it too reports a private property as absent from outside the object.

Restrictions on private:

  • private applies only to individual properties. A name that has already been declared with the Property directive (i.e., a common property) cannot appear in a private segment.
  • The check is enforced only at the runtime helpers. Code that reaches into the property table directly through raw memory (->/--> on a stored property address, for example) is not subject to the self == obj test.
  • Apart from the private segment, there is no further notion of property privacy: any non-private property of any object is accessible from anywhere in the program through the property operators (§7.4.4) and the provides operator (§7.10), subject only to the runtime checks that confirm the object actually supplies that property.

7.15 Object Limits

Limit Z-machine Glulx
Maximum objects 255 (v3); v4+ limited only by memory Limited only by memory
Maximum common properties 31 (v3, of which 29 are user-declarable), 63 (v4+, of which 61 are user-declarable) INDIV_PROP_START - 1 (default 255), of which INDIV_PROP_START - 3 (default 253) are user-declarable
Maximum attributes 32 (v3), 48 (v4+) NUM_ATTR_BYTES × 8 (default 56, max 312)
Maximum data per common property 8 bytes / 4 words (v3), 64 bytes / 32 words (v4+) 32768 values per property
Maximum data per individual property 64 bytes / 32 words 32768 values per property
Maximum classes Capped at 256 by the compiler (VENEER_CONSTRAINT_ON_CLASSES_Z), and additionally capped by the object limit (on v3, four built-in metaclasses plus all user classes share the 255-object cap) Capped at 32768 by the compiler (VENEER_CONSTRAINT_ON_CLASSES_G); every class is an object and consumes an object-number slot

7.16 Object Numbering

Objects are numbered sequentially in the order they are encountered in the source code. The first four object numbers are reserved for the built-in metaclasses, in this order: Class (1), Object (2), Routine (3), and String (4). User-defined classes and objects share a single counter and are numbered from 5 upward in declaration order. The constant nothing (0) represents the absence of an object.

In Z-machine version 3, the object number must fit in a single byte, limiting the total to 255. In v4+, object numbers are 16-bit; in Glulx, they are 32-bit; in both cases, the practical limit is set by available memory rather than a fixed cap.

Object numbers are stable within a single compilation but may change if the source is modified. Code should always refer to objects by name, never by number.