Pueblo Enhancer’s Guide

This world is Pueblo 1.10 enhanced.

When it sees a line of that form, it sends the World this command:

PUEBLOCLIENT 1.10 md5=”checksum string”

In this example, '1.10' is the version of the Pueblo client sending the command, and the ‘md5’ parameter indicates a secure checksum string. This secure string should be stored in a secure location by the world. In future versions of Pueblo, we’ll allow you to perform some potentially abusable operations using this checksum, and you may wish to limit the users that may perform these operations.

Upon receiving this PUEBLOCLIENT command, the World may send the following sequence, to tell the Pueblo client to begin interpreting the World's output as HTML:

</xch_mudtext><img xch_mode=html>

You may want to send the "This world is Pueblo 1.10 enhanced" line and accept the PUEBLOCLIENT command before the user logs in, so that you can send HTML from the outset. You may also want to provide special commands for sending HTML-formatted text and convert other text to escaped HTML (converting < to &lt, etc.).

This is the sequence of changes we typically make when we're Pueblo Enhancing a MUD:

1. Create a new "flag" which indicates that a user is using a Pueblo compatible client. This flag should be removed from the player when they log out, since they may log in with both Pueblo and a text client.

On TinyMUSH, this was a literal flag and an object in the Master Room which had this code:

@adisconnect: @set %#=!html

On LP-MUD, this was a static int in player.c, so it got reset when they logged out automatically. We also added a new function to player.c: query_is_html(), which allows rooms and objects to query a player's object about whether it supports HTML.

2. Display the string "This world is Pueblo 1.10 enhanced" and watch for the PUEBLOCLIENT command coming back from the client. When you get PUEBLOCLIENT, set the flag created in step 1 above.

For TinyMUSH, we display this string as part of connect.txt and added an "external" command (like WHO and QUIT) called PUEBLOCLIENT. The only trick is that on TinyMUSH, the player object doesn't exist until they log in, so we had to set an HTML flag on the network descriptor, then copy it over when they log in.

For LP-MUD, we added this in player.c's logon2(). We also did an 'add_action("puebloclient", "PUEBLOCLIENT");' and the corresponding puebloclient function so that people could do a PUEBLOCLIENT after they log in, but this was optional.

You may also want to add support for 'PUEBLOCLIENT off', which turns off the HTML output for testing.

3. Add HTML escaping. HTML has a few special characters that require escaping. You should convert these characters to the corresponding HTML sequence, as described in the following table. (Note: those trailing semicolons inside the strings are important.)

Character:	HTML sequence:
<	&lt;
>	&gt;
&	&amp;
“	&quot;

In TinyMUSH, we did this in game.c's notify_check().

In LP-MUD, we did this in dgd/lib/player.c's catch_tell().

4. Now you won't be able to output any HTML anchors, since all your output will be escaped, so you need a second output path that gets around the HTML escaping you did in step 3.

In TinyMUSH, we added @emit/noreturn and @pemit/noreturn to allow MUSH coders to output non-escaped (and non-newlined) HTML. We added a flag to notify_check() which tells it not to do the escaping it normally does, and several "_noreturn" versions of the macros in externs.h (i.e. notify_noreturn() which included this flag to notify_check()).

In LP-MUD, we added write_html(), which was just like write() but skipped the HTML escaping. This was in dgd/lib/interactive.c. We also had to do tell_object_html(), catch_tell_html(), etc.

You basically have to duplicate the output path from the normal input points (write(), catch_tell(), etc.) down to the function where you do the escaping, either calling different functions or passing some flag that indicates that escaping should be skipped.

5. Add HTML anchors for exits. When you list the obvious exits in a room, you might want to have each exit be an anchor, like this:

<a xch_cmd="east" xch_hint="Go east">east</a>

In TinyMUSH, this was in look.c's look_exits().

In LP-MUD, this was in room/room.c and looked like:

while (i < sizeof(dest_dir))

{

if (this_player()->query_is_html())

{

/* Write the exit as an anchor */

write_html( " " + "<a xch_cmd=" );

write( dest_dir[i] );

write_html( " xch_hint=\"Go " );

write( dest_dir[i] );

write_html( "\">" );

write( dest_dir[i] );

write_html( "</a>" );

}

else

{

write( " " + dest_dir[i] );

}

}

Note that we mix the use of write() and write_html(). If the exit name has one of <>&" in it, you'll need those characters to be escaped, but you don't want the "<a", ">", or "</a>" to be escaped.

6. Add VRML URL support to rooms. When a user walks into a room, if that room has the URL of a VRML file associated with it, you want to send them a <img xch_graph=load href="<the URL>">.

For TinyMUSH, we added a new attribute: @vrml_url. When the user enters a room, we check to see if the user has HTML enabled, then check to see if the attribute exists on the room, all in move.c.

For LP-MUD, this was in room/room.c. We added a static string vrml_url;. In init(), we send the load if appropriate.

7. Do the same, for MIDI background sounds. This is just like the VRML URL support in #6, only for a sound URL.

8. If no VRML_URL is set on the room, send <img xch_graph=hide>

9. Build away!

If you're building VRML files, and want to put them on your own Web server, you'll need to tell your Web server what MIME type a VRML file is. If you're using NCSA or Apache HTTPD, add this line to config/mime.types:

x-world/x-vrml wrl vrml

If you Pueblo Enhance a MUD, send us your patches, so others can follow in your footsteps! Send them to info@chaco.com. If you run into problems enhancing your mud, send us mail at info@chaco.com.

You might want to join the pueblo-enhancers mailing list. To do so, send mail to pueblo-enhancers-request@chaco.com.

The Pueblo home page is http://www.chaco.com/pueblo/. It has the Pueblo FAQ, instructions on downloading the latest version, etc.

Also see

Pueblo HTML extensions

Pueblo VRML extensions

Adding Avatar support in VRML spaces

Building in LP-MUD

TinyMUSH Extensions

<xch_mode>

<xch_mudtext>