misc.t file | source file

TADS 3 Library - miscellaneous definitions

This module contains miscellaneous definitions that don't have a natural grouping with any larger modules, and which aren't complex enough to justify modules of their own.

Summary of Classes

`CyclicEventList EventList ExternalEventList FinishOption FinishType GameMainDef RandomEventList RandomFiringScript Script ShuffledEventList ShuffledIntegerList ShuffledList StopEventList SyncEventList`

Summary of Global Objects

`adv3LibInit adv3LibPreinit finishOptionAmusing finishOptionCredits finishOptionFullScore finishOptionQuit finishOptionRestart finishOptionRestore finishOptionScore finishOptionUndo ftDeath ftFailure ftGameOver ftVictory libGlobal restoreOptionRestoreAnother restoreOptionStartOver settingsUI verboseModeSettingsItem`

Summary of Global Functions

`cls failedRestoreOptions finishGame finishGameMsg isListSubset main mainCommon mainRestore nilToList overrides partitionList processOptions runGame`

Global Functions

`cls ( )` | `misc.t[550]`

Clear the main game window. In most cases, you should call this rather than calling the low-level clearScreen() function directly, since this routine takes care of a couple of chores that should usually be done at the same time.

First, we flush the transcript to ensure that no left-over reports that were displayed before we cleared the screen will show up on the new screen. Second, we call the low-level clearScreen() function to actually clear the display window. Finally, we re-display any <ABOUTBOX> tag, to ensure that the about-box will still be around; this is necessary because any existing <ABOUTBOX> tag is lost after the screen is cleared.

`failedRestoreOptions ( )` | `misc.t[1992]`

Show failed startup restore options. If a restore operation fails at startup, we won't just proceed with the game, but ask the user what they want to do; we'll offer the options of restoring another game, quitting, or starting the game from the beginning.

`finishGame (extra)` | `misc.t[1981]`

finish the game, offering the given extra options but no message

`finishGameMsg (msg, extra)` | `misc.t[1903]`

Finish the game, showing a message explaining why the game has ended. This can be called when an event occurs that ends the game, such as the player character's death, winning, or any other endpoint in the story.

We'll show a message defined by 'msg', using a standard format. The format depends on the language, but in English, it's usually the message surrounded by asterisks: "*** You have won! ***". 'msg' can be:

- nil, in which case we display nothing
- a string, which we'll display as the message
- a FinishType object, from which we'll get the message

After showing the message (if any), we'll prompt the user with options for how to proceed. We'll always show the QUIT, RESTART, and RESTORE options; other options can be offered by listing one or more FinishOption objects in the 'extra' parameter, which is given as a list of FinishOption objects. The library defines a few non-default finish options, such as finishOptionUndo and finishOptionCredits; in addition, the game can subclass FinishOption to create its own custom options, as desired.

`isListSubset (a, b)` | `misc.t[2469]`

Determine if list a is a subset of list b. a is a subset of b if every element of a is in b.

`main (args)` | `misc.t[599]`

Main program entrypoint. The core run-time start-up code calls this after running pre-initialization and load-time initialization. This entrypoint is called when we're starting the game normally; when the game is launched through a saved-position file, mainRestore() will be invoked instead.

`mainCommon (prop, [args])` | `misc.t[624]`

Common main entrypoint - this handles starting a new game or restoring an existing saved state.

`mainRestore (args, restoreFile)` | `misc.t[614]`

Main program entrypoint for restoring a saved-position file. This is invoked from the core run-time start-up code when the game is launched from the operating system via a saved-position file. For example, on Windows, double-clicking on a saved-position file on the Windows desktop launches the interpreter, which looks in the save file to find the game executable to run, then starts the game and invokes this entrypoint.

`nilToList (val)` | `misc.t[2438]`

nilToList - convert a 'nil' value to an empty list. This can be useful for mix-in classes that will be used in different inheritance contexts, since the classes might or might not inherit a base class definition for list-valued methods such as preconditions. This provides a usable default for list-valued methods that return nothing from superclasses.

`overrides (obj, base, prop)` | `misc.t[678]`

Determine if the given object overrides the definition of the given property inherited from the given base class. Returns true if the object derives from the given base class, and the object's definition of the property comes from a different place than the base class's definition of the property.

`partitionList (lst, fn)` | `misc.t[2457]`

partitionList - partition a list into a pair of two lists, the first containing items that match the predicate 'fn', the second containing items that don't match 'fn'. 'fn' is a function pointer (usually an anonymous function) that takes a single argument - a list element - and returns true or nil.

The return value is a list with two elements. The first element is a list giving the elements of the original list for which 'fn' returns true, the second element is a list giving the elements for which 'fn' returns nil.

(Contributed by Tommy Nordgren.)

`processOptions (lst)` | `misc.t[2003]`

Process a list of finishing options. We'll loop, showing prompts and reading responses, until we get a response that terminates the loop.

`runGame (look)` | `misc.t[577]`

Run the game. We start by showing the description of the initial location, if desired, and then we read and interpret commands until the game ends (via a "quit" command, winning, death of the player character, or any other way of terminating the game).

This routine doesn't return until the game ends.

Before calling this routine, the caller should already have set the global variable gPlayerChar to the player character actor.

'look' is a flag indicating whether or not to look around; if this is true, we'll show a full description of the player character's initial location, as though the player were to type "look around" as the first command.

TADS 3 Library Manual
Generated on 8/21/2012 from TADS version 3.1.2