tkMOO-light - XMCP/1.1 Setup Example

Setting up XMCP/1.1 for the first time

Installing XMCP/1.1 on your MOO for the first time and then getting the client to use your new objects can be confusing. I had a look at what was needed to install XMCP/1.1 for the first time on a new MOO, and these notes show you what steps to take to take to get things working.

The basic process is firstly to install the XMCP/1.1 Driver and Feature Objects. Then install some application objects, like the Generic Desktop or Generic Whiteboard. Finally you can configure your tkMOO-light client to operate with your own objects, and then you're ready to go.

Port the essential objects. Read the Notes on Porting New Objects to a MOO if you're really new to all this.
1. XMCP/1.1 Driver
2. XMCP/1.1 Feature Object
  1. On a JHCore MOO you need to 'fixup' the feature.
```
@fix-commands #feature
```
3. Make the Driver trust the Feature object
```
;#driver.trusted = setadd(#driver.trusted, #feature)
```
4. It's a good idea to allow the Driver to trust you too
```
;#driver.trusted = setadd(#driver.trusted, #me)
```
5. Tell the Feature Object where the Driver is
```
;#feature.driver = #driver
```
Port the generic objects for the applications you want
1. Generic Desktop
  1. Tell the Generic Desktop where the Driver is
```
;#gd.driver = #driver
```
2. Generic Whiteboard
  1. Tell the Generic Whiteboard where the Driver is
```
;#gw.driver = #driver
```
3. The Generic Desktop needs to know where the Generic Whiteboard is so that Desktops can display Whiteboards with the correct icon:
```
;#gd.whiteboard = #gw
```

Create your own application objects

@create gd named desktop
@create gw named colouring book

Set up the Client. The worlds.tkm definition for your MOO should contain these lines:

...
ConnectScript: connect %u %p
ConnectScript: @wrap off
ConnectScript: @xmcp_challenge
ClientMode: line
...

Make sure that your authentication key is set. You only need to type this once each time you connect to your MOO. If you've set the client up to call @xmcp_challenge then you should never have to type the command again (see above).
```
@addfeature #feature
@xmcp_challenge
```
At this time you should see the message:
XMCP/1.1 Authentication set.
If you don't see the message, then something's wrong, and you should check that you've set the values of #driver.trusted and #feature.driver correctly.
Use the objects
1. Your personal desktop. This command should produce a desktop window on your screen.
```
put me on desktop
```
2. Your personal whiteboard. This command should produce a whiteboard window on your screen.
```
watch colouring book
```

Notes on Porting New Objects to a MOO

You can usually port MOO code by copying the given text straight into a MOO session. You'll need to be a $programmer on the MOO, naturally. The first section of each *.moo file contains the inital object creation command and commands to create and assign values to the object's properties. This is what the top of the file for the XMCP/1.1 Driver (xdr) looks like:

    @create $thing named XMCP/1.1 Driver (xdr):XMCP/1.1 Driver (xdr),xdr
    @prop xdr."authentication_keys" {} rc
    ;xdr.("authentication_keys") = {{#253, "33554454"}, {#221, "16777238"}}
    @prop xdr."trusted" {} rc
    ;xdr.("trusted") = {#252, #221}
    @prop xdr."debug" 0 rc
    @prop xdr."tag" 9 rc 
    ;xdr.("key") = 0
    ;xdr.("aliases") = {"XMCP/1.1 Driver (xdr)", "xdr"} 
    ;xdr.("description") = {"A driver for XMCP/1.1 Server->Client messages.  
	This object implements a message passing system on MOOs
	that don't have native MCP-like protocol support.", "", 
        ".trusted = {#owner, #, [#, ...]}"}
    ;xdr.("unique") = 0

The first line uses the '@create' command to create an object, giving it the alias 'xdr'. When you issue this command the MOO will respond with a message like:

    You now have XMCP/1.1 Driver (xdr) (aka xdr) with object number #287
    and parent generic thing (#5).

You'll need to change the lines in the *.moo file that begin with:

    ;xdr.("...

so that 'xdr' is replaced by the object number of the new object you created. With the 'xdr' string replaced the remainder of this section of the file should now look like this:

    @prop xdr."authentication_keys" {} rc
    ;#287.("authentication_keys") = {{#253, "33554454"}, {#221, "16777238"}}
    @prop xdr."trusted" {} rc
    ;#287.("trusted") = {#252, #221}
    @prop xdr."debug" 0 rc
    @prop xdr."tag" 9 rc
    ;#287.("key") = 0
    ;#287.("aliases") = {"XMCP/1.1 Driver (xdr)", "xdr"}
    ;#287.("description") = {"A driver for XMCP/1.1 Server->Client messages.  
	This object implements a message passing system on MOOs
	that don't have native MCP-like protocol support.", "", 
        ".trusted = {#owner, #, [#, ...]}"}
    ;#287.("unique") = 0

Note that you don't need to change the lines in the *.moo file that begin with:

    @prop xdr."...

Once these changes have been made you can proceed to issue them to the MOO.

Reasons for Error Reports

Even if you follow these guidelines the porting process may still produce errors, fortunately you can ignore some of these. Some of the object's properties mentioned in the *.moo file may be owned by MOO wizards, in which case you may not be able to alter their values. The MOO will usually correctly assign its own values to these properties.

If you forget to change the 'xdr' to the object number of the newly created object then MOO will complain and give an error traceback like this:

    #-1:Input to EVAL, line 1:  Variable not found
    ... called from built-in function eval()
    ... called from #59:eval_cmd_string (this == #79), line 18
    ... called from #59:eval*-d (this == #79), line 10
    (End of traceback)

This error might occurr if you try sending MOO the command:

    ;xdr.("unique") = 0

instead of:

    ;#287.("unique") = 0

If this error occurrs then you should edit the *.moo file to replace the relevant 'xdr' strings and send the corrected text to the MOO.