Pueblo enhancer's guide 1.0

This document describes the protocol by which a World (MUD, MUSH, MOO, etc.) can determine whether or not a user's client software supports the Pueblo enhancements, and then interact with Pueblo clients to take advantage of all of Pueblo's special features.

First off, you should check the Chaco ftp site to see if there's a patch for your mud server already. Look in pub/pueblo/enhanced on either ftp2.chaco.com or ftp.chaco.com.

The Pueblo client watches for lines of this form:

     This world is Pueblo 1.0 Enhanced.
	

If you like, you can direct MUD users to the Pueblo download URL this way:

     This world is Pueblo 1.0 Enhanced.  See http://www.chaco.com/pueblo/.
	

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

     PUEBLOCLIENT 1.0
	

(Where the '1.0' is the version of the Pueblo client sending the command) 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.0 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.).

Try to make your PUEBLOCLIENT command support as flexible as possible. In particular, don't look for only the current version of Pueblo, since that will break your server when a new release of Pueblo comes out. It's likely that Pueblo will send additional information appended to the PUEBLOCLIENT command in the future, so accepting unexpected characters after the version number would also be a good idea.

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

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 @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.0 Enhanced" and watch for the 'PUEBLOCLIENT 1.0' command coming back from the client. When you get PUEBLOCLIENT, set the flag created in "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: '<', '>', '&', and '"'. In your "normal" output routine, you should convert these characters to these strings, respectively: "&lt;", "&gt;", "&amp;", and "&quot;". Those trailing semicolons inside the strings are important.

   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/html and @pemit/html 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 "_html" versions of the macros in externs.h (i.e. notify_html() 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. Send us your patches. We'd love to put them up on our web and ftp sites, so people using a server like yours can benefit from your hard work.

10. Build away!

If you're building VRML files or using MIDI, and want to put them on your own Web server, you'll need to tell your Web server what MIME type to use for those file types. If you're using NCSA or Apache HTTPD, add these lines to config/mime.types:

	x-world/x-vrml                  wrl vrml
	audio/x-midi			mid midi
	

Future Addition: Co-surfing

Chaco is adding the ability for a Pueblo-enhanced server to direct Pueblo to view a URL. This makes server-directed tours of the web possible. Here is the syntax for this feature:

The server will send an

	<XCH_REDIRECT TARGET="WebTracker" href=http://... xch_surf=notify>
	

This will cause URL to be loaded either to WebTracker or an external Webbrowser.

When the user navigates to a new URL, Pueblo will send a command to the mud with the following syntax

	pueblosurf href=http://...
	

The server can notify the client to stop sending the tracking information by sending <XCH_REDIRECT xch_surf=stoptracking>

If the user has configured WebTracker as their web browser, then all of the above can be done.

The client can also send the following commands to the server

	pueblosurf xch_surf=CannotTrack
	

This is sent if we are unable to track user navigation.

	pueblosurf xch_surf=LoadError
	

Occurs when Pueblo is unable to load the requested URL.

Using these features, users can "co-surf" the web, or the MUD server can direct their web browser to view certain locations.

If you Pueblo Enhance a world, 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.

webmaster@chaco.com
Copyright © 1995, Chaco Communications, Inc. All rights reserved.
Chaco, Pueblo, VR Scout, and the Chaco logo are trademarks of Chaco Communications, Inc.