Blueprints (Programming)

Blueprints are templates for contructing areas on the fly. This is useful if you want to create generic areas (like hosts in cyberspace, or floors of a building) that can be brought into existence on an as-needed basis. Blueprints also allow players to design areas and have them constructed in the real world via the Freedom City Construction node in the HellMOO intartubes.

The generic blueprint is an $area that allows you to duplicate its contents, creating an identical area. This allows one to design an area using whatever $room and $exit types are appropriate, then make as many copies of it as necessary (perhaps you have a block filled with row houses that are all alike).

When you create a $blueprint, the blueprint sets up a room at coordinates 0,0,0. You can enter this room and begin building as you normally would by calling its edit() verb on the command line or via eval. Once invoked you will be transported to the virtual space you are building the blueprint for. When you decide that you're finished editing, you can type 'commit' to be taken back to the blueprint's location. Note that non-programmers can only edit blueprints in the matrix.

When you enter the blueprint it is also added to your features list, so several new commands become available to you (or to players, or anyone who edits the $blueprint).

 bpname <name>,alias1,alias2,etc -- changes the name of the blueprint

 bpdesc <text> -- describes the blueprint

 rooms -- gives you a list of room numbers to use when linking to an existing room

 dig <direction> to <room name|existing room number> -- creates a new room or links to an existing one.  The room's parent will be the one selected by the 'type' command when focusing on a room, or whatever is set by the blueprint's :default_room verb.  By default, :default_room returns the first room in the room type list given in its .types property (more on this later).  Newly created exits will also be parented to the currently selected type or the blueprint's default.

 bury <direction> -- removes a room and the exits connected to it

 focus -- allows the architect to focus on a room, exit, or object.  Once you've set a focus, you can operate on that object with the commads below.

 ren*ame <name>,alias1,alias2,etc -- renames the user's focus

 desc*ribe <text for the description> -- set the description of the user's focus object

 mess*ages -- shows the available messages for the user's focus

 mess*ages <message_name> <new_message> -- sets the named message to the text given by the new message

 type -- show available types for the focus
 type <num> -- select type <num> for the focus

Note that as a programmer you can also use all of your existing building tools in a $blueprint, or copy in rooms from elsewhere. The simplified building interface mentioned above is intended mainly to allow construction by players.

Setting up a new $Blueprint type requires setting a few key properties:

types -- This is a list of lists that defines what can be constructed within this blueprint via the construction tools. Each list element is a list containing a generic type and a list of available subtypes for that generic. The only required types are $room and $exit, so at a bare minimum your $Blueprint's type list should look like this:

 types = {{$room, {$room}}, {$exit, {$exit}}

Ideally it would include a concise list that contains the generics that would be common to the type of area that you're trying to create. For instance, the generic host blueprint defines these types for building matrix areas:

 types = {{$room, {#1835}}, {$exit, {#2124, #2178}}

The first room and exit in your subtype list are important as they are what will be retured by the blueprint's :default_room and :default_exit methods, which are used to determine the types used by the 'dig' command.

area_type -- This points to the object that will be the parent of the area created to hold the rooms you define in your blueprint. Set this to whatever is appropriate for the area you'll be creating (it should be some descendant of $area).

Once you've got it all set up, you'll be ready to call the area's :instantiate method. Be careful about what you instantiate, though, this could be an enormous source of database bloat if not used properly. Once an area is instantiated it will be given an :uninstantiate verb that will allow you to clean it up if necessary, but creating and recycling large numbers of objects (as almost any blueprint will) is an expensive operation that can cause some lag for everyone on the server.

instantiate will return the object number of a newly-created area that matches the one in the blueprint. You can then link it in however you choose, just don't lose it!

-- Main.SpunkY - 11 Dec 2006