Python Universe Builder

• pub.py - defines "global" variables
• pubcore.py - defines essential datatypes, functions, and constants
• pubverbs.py - defines standard verbs
• pubobjs.py - defines standard objects

There are several key concepts to understand in PUB. First, it is fully object-oriented; if you're comfy with that concept, skip to the next paragraph. Here's the idea: you define a class, which is a data structure with certain attributes (name, description, and so on). A class also defines some functions which can be applied to objects of that class. So far, pretty simple. Here's the neat bit: when defining a new class, you don't have to start from scratch. Instead, you can declare a base class, and your new class will automatically inherit all the attributes and functions of that base class. You just define whatever new properties or different functions make your new class different from its base.

There are only two big sets of related classes: Things and Verbs. Other PUB classes include Event, which keeps track of some code to be executed in the future; the Scheduler, which maintains a list of Events; the Command class, which stores the actor, verb, and objects involved in any action; and the Parser class, which takes a string (e.g., typed by the player) and breaks it into Commands.

Everything you see in the game -- the rooms, the rocks, the characters, even you (the player) -- is a Thing. A Thing is a Python object which has attributes such as name, desc, and size, and methods like GetName(), GetNote(), and so on. These are all explained in the Thing page of the library reference. Two methods especially deserve note:

• PreObj: this function is called before executing any command in which this Thing is an object. It gives the Thing an opportunity to cancel the command if it's not feasible.
  
• PostObj: this function is called after the execution of any command in which this Thing was an object, but before any output is printed to the user (and other actors in the game). It gives the Thing an opportunity to produce nonstandard output, or take other action which should result from that command.

What happens when the player types a command?

• The player's input is accepted by Player.Act(). This calls
  • Actor.DoCommandString(), which converts the string into a Command, and passes it to
    • Verb.Do(), which simply schedules a call to
    • Verb.Begin(). This method does two things:
      • Verb.DoPrechecks(), which calls:
        1. the PreWitness() method of the room (and the room containing this room, etc.)
        2. all the objects' PreObj() methods
        3. the actor's PreAct() method, if any
        If any of these methods return CANCEL, the command is cancelled
      • otherwise, a call to Verb.Finish() is scheduled for some time in the future (determined by Verb.GetDuration)
  • If there are more commands in the string, this repeats
• (back in Player.Act), Scheduler.Update() is called...
  • This finds and executes the next event, which may be a call to
    • Verb.Finish(), which updates the game objects, then calls
      • Verb.DoPostchecks, which calls
        1. the PostWitness() method of the room (and the room containing this room, etc.)
        2. all the objects' PostObj() methods
        3. the actor's PostAct() method, if any
        ...stopping when any of these methods return CANCEL
      • if none CANCEL, it sends standard output