No Fuss, No MUS

October 4, 2000
by Alan Levine

This dispatch comes from you within easy sight of a white sand beach in New Zealand, but that is another story. From here, randomness still pervades.

For you Director developers, there is some powerful, untapped technology right under your nose. Been there for quite some time.

The Shockwave MultiUser Server (MUS) has been installed with Director since version 7; and for 99.67543% of the world, it just stays there in the Director folder. What is it? MUS allows you to create shared multimedia spaces, ones where the things we create in Director, Shockwave and projectors, can freely communicate with each other via the Internet. You can use it to easily shuttle native Director media across the net, or integrate email into your applications sans Xtras.

The most obvious targets are games and chat, "empowering users to experience a collaborative web experience...yadda yadda yadda", but think farther out of that box to applications that could have more than one person manipulating a simulation (learning, training), creative tools for collaboration (project planning, net-based whiteboards), or any application where you would like a function to open up communication lines between users or share data and media between them.

Peter Small and his avatar friends should be lapping this up. And where are all the Shockwave game coders? There should be cutting edge stuff front and center at the mothership Macromedia's gallery, making code freaks lather at the thought of ripping MUS code and making Flash look like a kiddie side show at the state fair. Aching for a "killer app", the MUS is waiting even for some small "flesh wound-inducing" apps.

There are some biggies out there, such as the addictive Pictionary-like game iSketch, the wicked and irreverent SissyFight, fun games and toys at Gamespark, and the cool lounge hangout of Mobiles Disco. And you can peek at a few others; but one problem in looking at many MUS sites is that besides the listed biggies, often there is no one else there! A single user in a multiuser site is a sort of bad Zen riddle.

So why is it that MUS seems like this year's lusterless fad, perhaps a new legacy for SaveToJava? Let's get out the crystal ball, just insert another quarter into the slot and we can proceed...

This time around, I toss out my own theories about why MUS is slipping for the future of the moas, woolly mammoths, and dodo birds. This guesswork comes out of time spent developing MUS applications, but mostly it's my own idle speculation, based very loosely on real world phenomena. Also, a big pink and green dolphin named "Bertha" just swam by and explained it all to me.

For one thing, Macromedia seems to treat MUS like a beta -- poorly documented, weakly supported, and left shivering in an obscure corner of their web site. Next, hosting the server is not viable for many, especially us little small fry developers -- the services are not out there in the back ads of the net trade mags. But mostly, coding MUS applications is not trivial, not for the faint of Lingo or the drag and drop animators. You gotta get your fingers deep and dirty in the Lingo.

Hence, without much "Fuss" you will not get much "MUS".

So, in this and the next installment of 24 articles I will cover "everything you wanted to know about MUS but were too afraid to post in a news forum". Just kidding.

This will take more than one column to get cooking. In this one, I will try to give an overview of how the whole thing works and present a strategy for creating a gateway to MUS applications. In subsequent articles I will take us through development of a simple application and try to untangle the database features (this gives me a few more weeks to learn it all ;-)).

For other sources of information, be sure also to check the DOUG archives for other MUS articles that review the syntax, connection steps, and basics of databases. Terry Schussler has MUS training in his roving seminar offerings. And Lingo-master Gary Rosenzweig has good basic MUS code in his book Advanced Lingo for Games.

Marooned from the Mothership?

Despite the glorious promise one can read on the MUS white papers at Macromedia, for a product that is more than 18 months old, it sure walks and talks like just-outta-beta. There are more important things for the mothership to flash about.

While the PDF docs you can download are nicely formatted, the treatment of topics is uneven. There are pages and pages on how to write a basic connection script, but only four paltry ones on using the database features. The code examples for the database section are fragments, and instead of examples, there is a one-paragraph theoretical narrative "scenario" of how one uses the database functions. I want code examples, demos, stuff I can dig into. There is no coverage of how you set up messaging to broadcast user interaction and environment updates to other users.

The meat of the documentation is a dictionary of functions, but for some reason it is split between MUS server handlers and database/group handlers, resulting in unnecessary flipping back and forth. This is like using a dictionary to help compose sentences where pages 1 to 1256 are nouns and pages 1257 to 3012 are verbs. Why split them? And for an added bonus, you get the terms used in the obsolete previous version of MUS! Yummy stuff.

But what is severely lacking is a solid, or semi-solid (heck, I will even take gelatinous), collection of demo files to work with. Yes, you get plenty to play with as far as chat rooms, but just try to find something that shows you how to use the database features, or demonstrates the types of messaging you have to do to manipulate sprites in a shared application! The few demo files that exist are cryptic, multi-authored (different approaches for creating code architecture), and look like scratch and dent demos from old conference presentations. What you can find sits out there in "poppy" land at:

http://poppy.macromedia.com/multiuser/openlingo.htm

One of the better-developed examples is the multiuser lobby and chat (look for links at http://www.macromedia.com/support/director/multiuser.html), which provides the source code as well. It allows you to fairly easily create an MUS "lobby", where people can meet and create sub-chat rooms to go off into and...chat. It does some interesting Lingo tricks to scale and colorize the display (I borrowed part of this approach for my own generic login movie), as well as reading in all of the configuration information via the Shockwave HTML parameters (borrowed this, too). I hope to cover this in future installment #3 or #4.

But what I could not do very well was to alter some of the programming logic. This is a good one to study and use if you can take the functionality as is. It does a lot of fancy messaging to the actorList for accessing the MUS objects, and I found it convoluted to follow the logic path. It is always nearly impossible to completely wrap your head around OPC (Other People's Code), no matter how well it is commented.

Another movie example I used quite a bit was the database example (http://www.macromedia.com/support/director/ts/documents/database_example.htm), which is actually tucked away in the MUS 2.0 information. I learned less about coding the database functions from here than from actually using it to create and test my DB attributes and objects. This will be discussed in glorious detail in installment #14 of this series.

Among the resources are an online news forum for MUS (news://forums.macromedia.com/macromedia.director.multiuser), of which about 75% consists of people asking non-MUS, general Director questions, and 24% consists of people asking whether there is a unix server for MUS. There are hardly any MUS peeps on Direct-L.

And if you need any more doubt about the level of corporate interest in the MUS: most of the support materials reside in a personal directory on a Macromedia web server called "poppy" somewhere within the bowels of the mothership's network.

On the other hand (finally, to say something nice about the mothership), one of the best resources is the Multiuser Developer Chats (http://poppy.macromedia.com/~sallen/multiuser/), held every Thursday at 5:00 PM (PST). This is a great way to demo projects, trade code ideas, and play with avatars in an MUS chat. And then people get a little silly too, which is okay for anyone other than the crabby On-Topic-Only crows on the listservs (we know who you are).

Setting Up Service

Since the underpinning of MUS is a server, one of your key issues will be dealing with finding/using a server. Out of the box and off the Director CD, your options are to set up a Mac or a PC with the MUS server software. You will want to do this on a machine that has a static IP address, and preferably not one that is being used as someone's workstation.

Of course, like all things served, the more RAM and the faster the net pipe on your host, the better off you will be. There are not many services I have heard of that offer MUS hosting. The best you might be able to do is find a net rack shack that will host a Mac/PC box that you bring in, mount, and admin yourself.

With a valid Director serial number, you can set up a server for up to 1,000 simultaneous connections. For development work and medium-scaled applications, this can be sufficient. Some shops are setting up a pool of servers to handle loads. You will not find out the load impact until you develop an MUS application and run it through a battery of tests (including modem access, if that is in your target audience).

The "load" is dependent, of course, on your pipe to the net (better flow with T1 than DSL), but also on the logic of your applications. The MUS is basically a broadcaster of text messages (see below) so you will experience high loads (SLOW) with either big fat messages or lots of recipients, or a wicked double-whammy of both. So your strategy should be to minimize the number of messages, minimize the size of messages, and send them to only the people who need to get them.

For many game approaches, the logic is simple -- meet in an open "lobby" area of the server, find a game partner, get mutual IP coordinates, and then leave the server to play the game directly between the players (see MUS Xtra "peer to "peer" example).

About 25-99% of the questions on the MUS news forum are, "Can the server run on unix/Linux?" The answer is no, nada, nein. The reply is, check out FuseLight (http://fuse.taivas.com/fuselight/), an open source Linux MUS server application. You will need a bit more server savvy to set up and use FuseLight, but its use in the Mobiles Disco supports its ability to scale to large numbers of users.

If you are really going for the big time, with lots of users and/or lots of messaging, you will see that the big players doing large-scale MUS applications are writing their own custom servers. Now, this is not a problem if you have access to a swift Java coder who can slap this out on a napkin in a few sessions at the pub. But this may not be the case for the rest of us pokey little developers. We'd rather design the visual interaction than hassle with writing thread engines and port parsing routines.

To summarize, then: the MUS server application is a snap to install and run on a desktop PC, and will work well for development and small-to-medium-range projects. If you are going for commercial glory, get a budget and roll your own code, or locate a Linux whiz kid who can get you up with FuseLight. What you do not typically get with the third-party servers are the features for directly shipping native Director media back and forth from client to server.

Finally, if you are just toying around (what I will cover in later articles), you can run an MUS application off of a test server at Macromedia (http://www.macromedia.com/support/director/ts/documents/trialserver.htm). Of course, this isn't what you want to do in the long run, but it would be sufficient to practice your MUS code while waiting for those lottery tickets to cash in for the big server box.

What is that Man Coding Behind the Curtain?

It takes some time to wrap your neurons around the layers of Lingo that you create with the MUS. At least it took mine some stretching and regular calisthenics to do so.

When you look at Lingo, the logic is largely based on "messages" (handlers with perhaps variable toting parameters) sent back and forth to different places (sprites, movie scripts, objects, Xtras, etc.) with specified "receivers" (your Lingo handlers) that are designed by you to receive the messages and do something.

For perhaps more than 95% of what you are doing, the messages are sent directly from one logic location and immediately acted upon somewhere else. We work hard to make this a fast process and promise not to tie ourselves up in "tight repeat loops."

A mouseUp script calls a handler that checks some parameters and then fires data to a set of specific sprites. It is like a relay race with handoffs of messages.

The MUS messaging is more akin to the use of Lingo event handlers such the mouseDownScript, the keyDownScript, on stepFrame in an object, on timeOut/timeoutscript, etc. (If you have never heard of these, then do not pass go, but go directly to your Lingo dictionary and peruse.) You use these "event" handlers to sit quietly and then jump into action only when some other action creates a message (a mousedown, a press of a key, a passage of idle time). You do not call them directly, but set them up to be antennae for specific frequencies.

The role of the MUS server is to be a giant relayer of messages from one user's Shockwave/projector to another or among a whole group. A message may be a single-word command that tells the receiver to call a local handler; it might be a string carrying the contents of a user's chat message; or it might be some Director native media, such as the media property of an avatar's icon. The message carries with it additional information such as for whom it is intended (everybody, a group of users, a single user), who sent it, the time it was sent, and a status code.

The Lingo you write for MUS applications serves two main roles: broadcasting messages that are to be shared with other specific users (this could be the text I type in a chat box, or it could be the position of my Pong paddle, which I just moved) and setting up receivers for reacting to these messages when they arrive at the computers of the other users in the same virtual space (displaying the chat message in a scrolling field, moving my opponent's Pong paddle to reflect its last adjusted position).

So you can think of the MUS as a giant telephone operator, a la Lily Tomlin's Geraldine, patching messages from sender to a party line of sendee, without the snorting and annoying "one ringy dingy, two ringy dingy" routine. All of the communication through the client end is done via the MUS Xtra, the telephone in this sad metaphor. Without the Xtra initialized, you have no phone calls.

Unless you've ever written this sort of application, it may take a while (or never) for the communication concepts to sink in. The thing you invariably face in MUS applications is latency issues -- delays between one user sending a message and others receiving and reacting to it. It keeps one from writing fast twitch games. If you want to code the next Quake, try another programming environment.

The other side of the coin is dealing with the "scope" of your MUS messages. If you are running many applications from your MUS server, you will want them appropriately tagged to be sent only to the users who should get them. If you end up broadcasting messages to all users on your server, it might bog down to a grinding, painful, client-displeasing halt.

When we look at the "scope" of messages, we find overlapping realms. The first is the connectionID, the identifier for one specific game or application. An MUS Pong game has a unique ID, different from the MUS poetry slam. The connectionID is used in establishing a communications connection with the server and for identifying data associated with your application in the server database functions.

The second realm of scope is the groups of users. This is how you channel messages to be sent or received by specific users rather than the entire world. Now, what is interesting is that you can have groups set up to be all the people playing Pong ("Gamers" group in the above diagram), or all of the people writing poetry ("artsy" group), so the two groups never interact. Movements of Pong paddles, ball locations, and scores mean nothing to the poets. Likewise, the discussion on rhyming schemes has no meaning in the Pong game.

But you could identify a group that is, say, all left-handed persons ("lefties"), including some playing Pong and some writing left-handed poems. And your users can belong to multiple groups. Think of groups as filters that shuttle messages to specified sets of people no matter what application they are using.

But wait, there is more to groups! If you create, say, three different groups to play Pong, they can all have a shared MUS environment (a Pong court, perhaps with different colors, different spin or bounce physics or music in the background) that is essentially an instance of your Director application, and it can be written so that the people at the beginners Pong court never interact with the group at the Atari Grandmasters arena. This functionality then allows you to make hundreds of cloned applications with different players in each. And you only need one Director movie to create this from.

Understanding groups helps you minimize MUS bottlenecks. The server load is calculated via the size of each message (say 1 kb of data) multiplied by how many people it needs to be sent to. If you can segment your users into reasonable and logical groups or even dispatch them to play as "peer-to-peer", then you can minimize sending data across a large crowd.

And life then is good. Or at least it heads in that direction.

Not a Trivial Pursuit

What you can do quite easily from the docs and the behaviors in the D8 library is to add a chat room or a simple whiteboard to your applications. The code underneath the hood is not for the faint of Lingo. If you find yourself thinking of altering much of its logic, you are in for heaps of underground Lingo mining work to modify the canned code. And advanced hair loss to boot.

I tried and failed. Well, partly. I will show in article installment #8 how I got my homegrown connection script to use the canned chat behaviors.

My advice (actually the advice someone else gave me) is, if you are doing anything beyond the most basic MUS, you will want to roll your own code. It is not horrendous and in the medium-to-long run, you end up with a much better comprehension of how it all works.

In approximate order, the sorts of things you will be doing in an MUS application are:

1. Creating an instance of the MUS Xtra as an object. This is your connection to everything else.
2. Creating a connection to your MUS server, sending the appropriate parameters, etc. You may be checking assigned users against a password database.
3. Putting the connected user into an appropriate "group" or creating the ability for users to join/create new groups. You may be reading group characteristics (e.g. data that describe the current conditions of the Pong game, or the text of the current poem being written) from the database.
4. Entering whatever interaction you have programmed. You need to identify what information needs to be sent to other users (position of my Pong paddle, direction of the ball I hit, etc.) and how your movie will react to that same sort of information sent by another user. These are the "callbackMessages" that listen for MUS messages and then relay information to other Lingo handlers to actually do the work.
5. Disconnect and clean up.

What is sad is that the bulk of the MUS documentation you can find emphasizes mostly what is easiest to do: establish the connection to the server. In my next article, I will detail my own approach for creating a general purpose connection movie, one that could be used for any type of MUS application I might create.

Coming Attractions

One reason this has taken a while to write (besides the time and effort in trying to learn MUS) is that it is quite a lot to digest and explain. If you are doing some MUS work, I'd appreciate hearing from you about the kinds of apps you are developing. Maybe we can beef up the stature of MUS apps.

The other reason this is taking so long to write is that the Kiwi beaches and mountains keep distracting me. Oh well.

Copyright 1997-2024, Director Online. Article content copyright by respective authors.