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.

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.  Right now this is mostly intended for use in the matrix, where 
   we can get away with such interfaces.  

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 is intended mainly to allow 
   construction by players, and will be expanded as time permits.

Setting up a $Blueprint 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 (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, as there is currently no easy way to clean up after yourself 
   and this could be an enormous source of database bloat if not used carefully.

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