Behold Vilya, Ring of Air and repository for our game and virtual worldly

extensions to the distributed environment provided by Narya. git-svn-id: svn+ssh://src.earth.threerings.net/vilya/trunk@1 c613c5cb-e716-0410-b11b-feb51c14d237
2006-06-23 17:58:11 +00:00
commit a4df87e52f
317 changed files with 45818 additions and 0 deletions
@@ -0,0 +1,56 @@
+//
+// $Id: Log.java 4191 2006-06-13 22:42:20Z ray $
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2004 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.whirled.zone;
+
+/**
+ * A placeholder class that contains a reference to the log object used by
+ * the Whirled Zone services.
+ */
+public class Log
+{
+    public static com.samskivert.util.Log log =
+	new com.samskivert.util.Log("whirled.zone");
+
+    /** Convenience function. */
+    public static void debug (String message)
+    {
+	log.debug(message);
+    }
+
+    /** Convenience function. */
+    public static void info (String message)
+    {
+	log.info(message);
+    }
+
+    /** Convenience function. */
+    public static void warning (String message)
+    {
+	log.warning(message);
+    }
+
+    /** Convenience function. */
+    public static void logStackTrace (Throwable t)
+    {
+	log.logStackTrace(com.samskivert.util.Log.WARNING, t);
+    }
+}
@@ -0,0 +1,51 @@
+//
+// $Id: ZoneAdapter.java 4191 2006-06-13 22:42:20Z ray $
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2004 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.whirled.zone.client;
+
+import com.threerings.whirled.zone.data.ZoneSummary;
+
+/**
+ * The zone adapter makes life easier for a class that really only cares
+ * about one or two of the zone observer callbacks and doesn't want to
+ * provide empty implementations of the others. One can either extend zone
+ * adapter, or create an anonymous instance that overrides the desired
+ * callback(s).
+ *
+ * @see ZoneObserver
+ */
+public class ZoneAdapter implements ZoneObserver
+{
+    // documentation inherited from interface
+    public void zoneWillChange (int zoneId)
+    {
+    }
+
+    // documentation inherited from interface
+    public void zoneDidChange (ZoneSummary summary)
+    {
+    }
+
+    // documentation inherited from interface
+    public void zoneChangeFailed (String reason)
+    {
+    }
+}
@@ -0,0 +1,69 @@
+//
+// $Id: ZoneDecoder.java 4145 2006-05-24 01:24:24Z ray $
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2006 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.whirled.zone.client;
+
+import com.threerings.presents.client.InvocationDecoder;
+import com.threerings.whirled.zone.client.ZoneReceiver;
+
+/**
+ * Dispatches calls to a {@link ZoneReceiver} instance.
+ */
+public class ZoneDecoder extends InvocationDecoder
+{
+    /** The generated hash code used to identify this receiver class. */
+    public static final String RECEIVER_CODE = "2d900cf54355111b4bb4befcdff42b82";
+
+    /** The method id used to dispatch {@link ZoneReceiver#forcedMove}
+     * notifications. */
+    public static final int FORCED_MOVE = 1;
+
+    /**
+     * Creates a decoder that may be registered to dispatch invocation
+     * service notifications to the specified receiver.
+     */
+    public ZoneDecoder (ZoneReceiver receiver)
+    {
+        this.receiver = receiver;
+    }
+
+    // documentation inherited
+    public String getReceiverCode ()
+    {
+        return RECEIVER_CODE;
+    }
+
+    // documentation inherited
+    public void dispatchNotification (int methodId, Object[] args)
+    {
+        switch (methodId) {
+        case FORCED_MOVE:
+            ((ZoneReceiver)receiver).forcedMove(
+                ((Integer)args[0]).intValue(), ((Integer)args[1]).intValue()
+            );
+            return;
+
+        default:
+            super.dispatchNotification(methodId, args);
+            return;
+        }
+    }
+}
@@ -0,0 +1,315 @@
+//
+// $Id: ZoneDirector.java 4145 2006-05-24 01:24:24Z ray $
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2004 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.whirled.zone.client;
+
+import java.util.ArrayList;
+
+import com.samskivert.util.ResultListener;
+
+import com.threerings.presents.client.BasicDirector;
+import com.threerings.presents.client.Client;
+
+import com.threerings.crowd.data.PlaceConfig;
+
+import com.threerings.whirled.client.SceneDirector;
+import com.threerings.whirled.data.SceneModel;
+import com.threerings.whirled.data.SceneUpdate;
+import com.threerings.whirled.util.WhirledContext;
+
+import com.threerings.whirled.zone.Log;
+import com.threerings.whirled.zone.data.ZoneSummary;
+import com.threerings.whirled.zone.util.ZoneUtil;
+
+/**
+ * The zone director augments the scene services with the notion of zones.
+ * Zones are self-contained, connected groups of scenes. The normal scene
+ * director services can be used to move from scene to scene, but moving
+ * to a new zone requires a special move request which can be accomplished
+ * via the zone director. The zone director also makes available the zone
+ * summary which provides information on the zone which can be used to
+ * generate an overview map or similar.
+ */
+public class ZoneDirector extends BasicDirector
+    implements ZoneReceiver, ZoneService.ZoneMoveListener,
+               SceneDirector.MoveHandler
+{
+    /**
+     * Constructs a zone director with the supplied context, and delegate
+     * scene director (which the zone director will coordinate with when
+     * moving from scene to scene). A zone director is required on the
+     * client side for systems that wish to use the zone services.
+     */
+    public ZoneDirector (WhirledContext ctx, SceneDirector scdir)
+    {
+        super(ctx);
+        _ctx = ctx;
+        _scdir = scdir;
+        _scdir.setMoveHandler(this);
+
+        // register for zone notifications
+        _ctx.getClient().getInvocationDirector().registerReceiver(
+            new ZoneDecoder(this));
+    }
+
+    /**
+     * Returns the summary for the zone currently occupied by the client
+     * or null if the client does not currently occupy a zone (not a
+     * normal situation).
+     */
+    public ZoneSummary getZoneSummary ()
+    {
+        return _summary;
+    }
+
+    /**
+     * Adds a zone observer to the list. This observer will subsequently
+     * be notified of effected and failed zone changes.
+     */
+    public void addZoneObserver (ZoneObserver observer)
+    {
+        _observers.add(observer);
+    }
+
+    /**
+     * Removes a zone observer from the list.
+     */
+    public void removeZoneObserver (ZoneObserver observer)
+    {
+        _observers.remove(observer);
+    }
+
+    /**
+     * Requests that this client move the specified scene in the specified
+     * zone. A request will be made and when the response is received, the
+     * location observers will be notified of success or failure.
+     */
+    public boolean moveTo (int zoneId, int sceneId)
+    {
+        return moveTo(zoneId, sceneId, null);
+    }
+
+    /**
+     * Requests that this client move the specified scene in the specified
+     * zone. A request will be made and when the response is received, the
+     * location observers will be notified of success or failure.
+     */
+    public boolean moveTo (int zoneId, int sceneId, ResultListener rl)
+    {
+        // make sure the zoneId and sceneId are valid
+        if (zoneId < 0 || sceneId < 0) {
+            Log.warning("Refusing moveTo(): invalid sceneId or zoneId " +
+                        "[zoneId=" + zoneId + ", sceneId=" + sceneId + "].");
+            return false;
+        }
+
+        // if the requested zone is the same as our current zone, we just
+        // want a regular old moveTo request
+        if (_summary != null && zoneId == _summary.zoneId) {
+            return _scdir.moveTo(sceneId);
+        }
+
+        // otherwise, we make a zoned moveTo request; prepare to move to
+        // this scene (sets up pending data)
+        if (!_scdir.prepareMoveTo(sceneId, rl)) {
+            return false;
+        }
+
+        // let our zone observers know that we're attempting to switch
+        // zones
+        notifyObservers(Integer.valueOf(zoneId));
+
+        // check the version of our cached copy of the scene to which
+        // we're requesting to move; if we were unable to load it, assume
+        // a cached version of zero
+        int sceneVers = 0;
+        SceneModel pendingModel = _scdir.getPendingModel();
+        if (pendingModel != null) {
+            sceneVers = pendingModel.version;
+        }
+
+        // issue a moveTo request
+        Log.info("Issuing zoned moveTo(" + ZoneUtil.toString(zoneId) +
+                 ", " + sceneId + ", " + sceneVers + ").");
+        _zservice.moveTo(_ctx.getClient(), zoneId, sceneId, sceneVers, this);
+        return true;
+    }
+
+    // documentation inherited
+    protected void fetchServices (Client client)
+    {
+        _zservice = (ZoneService)client.requireService(ZoneService.class);
+    }
+
+    // documentation inherited
+    public void clientDidLogoff (Client client)
+    {
+        super.clientDidLogoff(client);
+
+        // clear out our business
+        _zservice = null;
+        _summary = null;
+        _previousZoneId = -1;
+    }
+
+    /**
+     * Called in response to a successful {@link ZoneService#moveTo}
+     * request.
+     */
+    public void moveSucceeded (
+        int placeId, PlaceConfig config, ZoneSummary summary)
+    {
+        if (_summary != null) {
+            // keep track of our previous zone info
+            _previousZoneId = _summary.zoneId;
+        }
+        
+        // keep track of the summary
+        _summary = summary;
+
+        // pass the rest off to the standard scene transition code
+        _scdir.moveSucceeded(placeId, config);
+
+        // and let the zone observers know what's up
+        notifyObservers(summary);
+    }
+
+    /**
+     * Called in response to a successful {@link ZoneService#moveTo}
+     * request when our cached scene was out of date and the server
+     * determined that we needed some updates.
+     */
+    public void moveSucceededWithUpdates (
+        int placeId, PlaceConfig config, ZoneSummary summary,
+        SceneUpdate[] updates)
+    {
+        // keep track of the summary
+        _summary = summary;
+
+        // pass the rest off to the standard scene transition code
+        _scdir.moveSucceededWithUpdates(placeId, config, updates);
+
+        // and let the zone observers know what's up
+        notifyObservers(summary);
+    }
+
+    /**
+     * Called in response to a successful {@link ZoneService#moveTo}
+     * request when our cached scene was out of date and the server
+     * determined that we needed an updated copy.
+     */
+    public void moveSucceededWithScene (
+        int placeId, PlaceConfig config, ZoneSummary summary, SceneModel model)
+    {
+        // keep track of the summary
+        _summary = summary;
+
+        // pass the rest off to the standard scene transition code
+        _scdir.moveSucceededWithScene(placeId, config, model);
+
+        // and let the zone observers know what's up
+        notifyObservers(summary);
+    }
+
+    /**
+     * Called in response to a failed zoned <code>moveTo</code> request.
+     */
+    public void requestFailed (String reason)
+    {
+        // let the scene director cope
+        _scdir.requestFailed(reason);
+
+        // and let the observers know what's up
+        notifyObservers(reason);
+    }
+
+    // documentation inherited from interface
+    public void forcedMove (int zoneId, int sceneId)
+    {
+        Log.info("Moving at request of server [zoneId=" + zoneId +
+                 ", sceneId=" + sceneId + "].");
+
+        // clear out our old scene and place data
+        _scdir.didLeaveScene();
+
+        // move to the new zone and scene
+        moveTo(zoneId, sceneId, null);
+    }
+
+    /**
+     * Called when something breaks down after successfully completely a
+     * <code>moveTo</code> request.
+     */
+    public void recoverMoveTo (int sceneId)
+    {
+        if (_previousZoneId != -1) {
+            moveTo(_previousZoneId, sceneId);
+
+        } else {
+            _scdir.moveTo(sceneId);
+        }
+    }
+
+    /**
+     * Notifies observers of success or failure, depending on the type of
+     * object provided as data.
+     */
+    protected void notifyObservers (Object data)
+    {
+        // let our observers know that all is well on the western front
+        for (int i = 0; i < _observers.size(); i++) {
+            ZoneObserver obs = (ZoneObserver)_observers.get(i);
+            try {
+                if (data instanceof Integer) {
+                    obs.zoneWillChange(((Integer)data).intValue());
+                } else if (data instanceof ZoneSummary) {
+                    obs.zoneDidChange((ZoneSummary)data);
+                } else {
+                    obs.zoneChangeFailed((String)data);
+                }
+
+            } catch (Throwable t) {
+                Log.warning("Zone observer choked during notification " +
+                            "[data=" + data + ", obs=" + obs + "].");
+                Log.logStackTrace(t);
+            }
+        }
+    }
+
+    /** A reference to the active client context. */
+    protected WhirledContext _ctx;
+
+    /** A reference to the scene director with which we coordinate. */
+    protected SceneDirector _scdir;
+
+    /** Provides access to zone services. */
+    protected ZoneService _zservice;
+
+    /** A reference to the zone summary for the currently occupied
+     * zone. */
+    protected ZoneSummary _summary;
+
+    /** Our zone observer list. */
+    protected ArrayList _observers = new ArrayList();
+
+    /** Our previous zone id. */
+    protected int _previousZoneId = -1;
+}
@@ -0,0 +1,58 @@
+//
+// $Id: ZoneObserver.java 4191 2006-06-13 22:42:20Z ray $
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2004 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.whirled.zone.client;
+
+import com.threerings.whirled.zone.data.ZoneSummary;
+
+/**
+ * The zone observer interface makes it possible for entities to be
+ * notified when the client moves to a new zone.
+ */
+public interface ZoneObserver
+{
+    /**
+     * Called when we begin the process of switching to a new zone. This
+     * will be followed by a call to {@link #zoneDidChange} to indicate
+     * that the change was successful or {@link #zoneChangeFailed} if the
+     * change fails.
+     *
+     * @param zoneId the zone id of the zone to which we are changing.
+     */
+    public void zoneWillChange (int zoneId);
+
+    /**
+     * Called when we have switched to a new zone.
+     *
+     * @param summary the summary information for the new zone or null if
+     * we have switched to no zone.
+     */
+    public void zoneDidChange (ZoneSummary summary);
+
+    /**
+     * This is called on all zone observers when a zone change request is
+     * rejected by the server or fails for some other reason.
+     *
+     * @param reason the reason code that explains why the zone change
+     * request was rejected or otherwise failed.
+     */
+    public void zoneChangeFailed (String reason);
+}
@@ -0,0 +1,40 @@
+//
+// $Id: ZoneReceiver.java 4145 2006-05-24 01:24:24Z ray $
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2004 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.whirled.zone.client;
+
+import com.threerings.presents.client.InvocationReceiver;
+
+/**
+ * Defines, for the zone services, a set of notifications delivered
+ * asynchronously by the server to the client.
+ */
+public interface ZoneReceiver extends InvocationReceiver
+{
+    /**
+     * Used to communicate a required move notification to the client. The
+     * server will have removed the client from their existing scene and
+     * the client is then responsible for generating a {@link
+     * ZoneService#moveTo} request to move to the new scene in the
+     * specified zone.
+     */
+    public void forcedMove (int zoneId, int sceneId);
+}
@@ -0,0 +1,67 @@
+//
+// $Id: ZoneService.java 4145 2006-05-24 01:24:24Z ray $
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2004 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.whirled.zone.client;
+
+import com.threerings.presents.client.Client;
+import com.threerings.presents.client.InvocationService;
+
+import com.threerings.crowd.data.PlaceConfig;
+import com.threerings.whirled.data.SceneModel;
+import com.threerings.whirled.data.SceneUpdate;
+
+import com.threerings.whirled.zone.data.ZoneSummary;
+
+/**
+ * Defines the client interface to the zone related invocation services
+ * (e.g. moving between zones).
+ */
+public interface ZoneService extends InvocationService
+{
+    /** Used to deliver responses to {@link #moveTo} requests. */
+    public static interface ZoneMoveListener extends InvocationListener
+    {
+        public void moveSucceeded (
+            int placeId, PlaceConfig config, ZoneSummary summary);
+
+        public void moveSucceededWithUpdates (
+            int placeId, PlaceConfig config, ZoneSummary summary,
+            SceneUpdate[] updates);
+
+        public void moveSucceededWithScene (
+            int placeId, PlaceConfig config, ZoneSummary summary,
+            SceneModel model);
+    }
+
+    /**
+     * Requests that that this client's body be moved to the specified
+     * scene in the specified zone.
+     *
+     * @param zoneId the zone id to which we want to move.
+     * @param sceneId the scene id to which we want to move.
+     * @param version the version number of the scene object that we have
+     * in our local repository.
+     * @param listener the object that will receive the callback when the
+     * request succeeds or fails.
+     */
+    public void moveTo (Client client, int zoneId, int sceneId,
+                        int version, ZoneMoveListener listener);
+}
@@ -0,0 +1,58 @@
+//
+// $Id: SceneSummary.java 3310 2005-01-24 23:08:21Z mdb $
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2004 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.whirled.zone.data;
+
+import com.samskivert.util.StringUtil;
+
+import com.threerings.io.Streamable;
+
+/**
+ * The scene summary class is used to provide info about the connected
+ * group of scenes that make up a zone. The group of scenes that make up a
+ * zone is a self-contained set of scenes, connected with one another (by
+ * portals) but not to any scenes outside the group.
+ */
+public class SceneSummary implements Streamable
+{
+    /** The id of this scene. */
+    public int sceneId;
+
+    /** The name of this scene. */
+    public String name;
+
+    /** The ids of the scenes to which this scene is connected via
+     * portals. */
+    public int[] neighbors;
+
+    /** The directions in which each of the neighbors lay. */
+    public int[] neighborDirs;
+
+    /**
+     * Generates a string representation of this instance.
+     */
+    public String toString ()
+    {
+        return "[sceneId=" + sceneId + ", name=" + name +
+            ", neighbors=" + StringUtil.toString(neighbors) +
+            ", neighborDirs=" + StringUtil.toString(neighborDirs) + "]";
+    }
+}
@@ -0,0 +1,35 @@
+//
+// $Id: ZoneCodes.java 4191 2006-06-13 22:42:20Z ray $
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2004 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.whirled.zone.data;
+
+import com.threerings.whirled.data.SceneCodes;
+
+/**
+ * Contains codes used by the zone services.
+ */
+public interface ZoneCodes extends SceneCodes
+{
+    /** An error code indicating that a zone identified by a particular
+     * zone id does not exist. Usually generated by a failed moveTo
+     * request. */
+    public static final String NO_SUCH_ZONE = "m.no_such_zone";
+}
@@ -0,0 +1,125 @@
+//
+// $Id: ZoneMarshaller.java 4145 2006-05-24 01:24:24Z ray $
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2006 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.whirled.zone.data;
+
+import com.threerings.crowd.data.PlaceConfig;
+import com.threerings.presents.client.Client;
+import com.threerings.presents.data.InvocationMarshaller;
+import com.threerings.presents.dobj.InvocationResponseEvent;
+import com.threerings.whirled.data.SceneModel;
+import com.threerings.whirled.data.SceneUpdate;
+import com.threerings.whirled.zone.client.ZoneService;
+import com.threerings.whirled.zone.data.ZoneSummary;
+
+/**
+ * Provides the implementation of the {@link ZoneService} interface
+ * that marshalls the arguments and delivers the request to the provider
+ * on the server. Also provides an implementation of the response listener
+ * interfaces that marshall the response arguments and deliver them back
+ * to the requesting client.
+ */
+public class ZoneMarshaller extends InvocationMarshaller
+    implements ZoneService
+{
+    // documentation inherited
+    public static class ZoneMoveMarshaller extends ListenerMarshaller
+        implements ZoneMoveListener
+    {
+        /** The method id used to dispatch {@link #moveSucceeded}
+         * responses. */
+        public static final int MOVE_SUCCEEDED = 1;
+
+        // documentation inherited from interface
+        public void moveSucceeded (int arg1, PlaceConfig arg2, ZoneSummary arg3)
+        {
+            _invId = null;
+            omgr.postEvent(new InvocationResponseEvent(
+                               callerOid, requestId, MOVE_SUCCEEDED,
+                               new Object[] { Integer.valueOf(arg1), arg2, arg3 }));
+        }
+
+        /** The method id used to dispatch {@link #moveSucceededWithScene}
+         * responses. */
+        public static final int MOVE_SUCCEEDED_WITH_SCENE = 2;
+
+        // documentation inherited from interface
+        public void moveSucceededWithScene (int arg1, PlaceConfig arg2, ZoneSummary arg3, SceneModel arg4)
+        {
+            _invId = null;
+            omgr.postEvent(new InvocationResponseEvent(
+                               callerOid, requestId, MOVE_SUCCEEDED_WITH_SCENE,
+                               new Object[] { Integer.valueOf(arg1), arg2, arg3, arg4 }));
+        }
+
+        /** The method id used to dispatch {@link #moveSucceededWithUpdates}
+         * responses. */
+        public static final int MOVE_SUCCEEDED_WITH_UPDATES = 3;
+
+        // documentation inherited from interface
+        public void moveSucceededWithUpdates (int arg1, PlaceConfig arg2, ZoneSummary arg3, SceneUpdate[] arg4)
+        {
+            _invId = null;
+            omgr.postEvent(new InvocationResponseEvent(
+                               callerOid, requestId, MOVE_SUCCEEDED_WITH_UPDATES,
+                               new Object[] { Integer.valueOf(arg1), arg2, arg3, arg4 }));
+        }
+
+        // documentation inherited
+        public void dispatchResponse (int methodId, Object[] args)
+        {
+            switch (methodId) {
+            case MOVE_SUCCEEDED:
+                ((ZoneMoveListener)listener).moveSucceeded(
+                    ((Integer)args[0]).intValue(), (PlaceConfig)args[1], (ZoneSummary)args[2]);
+                return;
+
+            case MOVE_SUCCEEDED_WITH_SCENE:
+                ((ZoneMoveListener)listener).moveSucceededWithScene(
+                    ((Integer)args[0]).intValue(), (PlaceConfig)args[1], (ZoneSummary)args[2], (SceneModel)args[3]);
+                return;
+
+            case MOVE_SUCCEEDED_WITH_UPDATES:
+                ((ZoneMoveListener)listener).moveSucceededWithUpdates(
+                    ((Integer)args[0]).intValue(), (PlaceConfig)args[1], (ZoneSummary)args[2], (SceneUpdate[])args[3]);
+                return;
+
+            default:
+                super.dispatchResponse(methodId, args);
+                return;
+            }
+        }
+    }
+
+    /** The method id used to dispatch {@link #moveTo} requests. */
+    public static final int MOVE_TO = 1;
+
+    // documentation inherited from interface
+    public void moveTo (Client arg1, int arg2, int arg3, int arg4, ZoneService.ZoneMoveListener arg5)
+    {
+        ZoneMarshaller.ZoneMoveMarshaller listener5 = new ZoneMarshaller.ZoneMoveMarshaller();
+        listener5.listener = arg5;
+        sendRequest(arg1, MOVE_TO, new Object[] {
+            Integer.valueOf(arg2), Integer.valueOf(arg3), Integer.valueOf(arg4), listener5
+        });
+    }
+
+}
@@ -0,0 +1,53 @@
+//
+// $Id: ZoneSummary.java 3726 2005-10-11 19:17:43Z ray $
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2004 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.whirled.zone.data;
+
+import com.samskivert.util.StringUtil;
+
+import com.threerings.io.SimpleStreamableObject;
+import com.threerings.util.Name;
+
+/**
+ * The zone summary contains information on a zone, including its name and
+ * summary info on all of the scenes in this zone (which can be used to
+ * generate a map of the zone on the client).
+ */
+public class ZoneSummary extends SimpleStreamableObject
+{
+    /** The zone's fully qualified unique identifier. */
+    public int zoneId;
+
+    /** The name of the zone. */
+    public Name name;
+
+    /** The summary information for all of the scenes in the zone. */
+    public SceneSummary[] scenes;
+
+    /**
+     * Generates a string representation of this instance.
+     */
+    public String toString ()
+    {
+        return "[zoneId=" + zoneId + ", name=" + name +
+            ", scenes=" + StringUtil.toString(scenes) + "]";
+    }
+}
@@ -0,0 +1,41 @@
+//
+// $Id: ZonedBodyObject.java 4145 2006-05-24 01:24:24Z ray $
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2004 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.whirled.zone.data;
+
+import com.threerings.whirled.data.ScenedBodyObject;
+
+/**
+ * A system that uses the zone services must provide a body object
+ * extension that implements this interface.
+ */
+public interface ZonedBodyObject extends ScenedBodyObject
+{
+    /**
+     * Returns the zone id currently occupied by this body.
+     */
+    public int getZoneId ();
+
+    /**
+     * Sets the zone id currently occupied by this body.
+     */
+    public void setZoneId (int zoneId);
+}
@@ -0,0 +1,74 @@
+//
+// $Id: ZoneDispatcher.java 4145 2006-05-24 01:24:24Z ray $
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2006 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.whirled.zone.server;
+
+import com.threerings.crowd.data.PlaceConfig;
+import com.threerings.presents.client.Client;
+import com.threerings.presents.data.ClientObject;
+import com.threerings.presents.data.InvocationMarshaller;
+import com.threerings.presents.server.InvocationDispatcher;
+import com.threerings.presents.server.InvocationException;
+import com.threerings.whirled.data.SceneModel;
+import com.threerings.whirled.data.SceneUpdate;
+import com.threerings.whirled.zone.client.ZoneService;
+import com.threerings.whirled.zone.data.ZoneMarshaller;
+import com.threerings.whirled.zone.data.ZoneSummary;
+
+/**
+ * Dispatches requests to the {@link ZoneProvider}.
+ */
+public class ZoneDispatcher extends InvocationDispatcher
+{
+    /**
+     * Creates a dispatcher that may be registered to dispatch invocation
+     * service requests for the specified provider.
+     */
+    public ZoneDispatcher (ZoneProvider provider)
+    {
+        this.provider = provider;
+    }
+
+    // documentation inherited
+    public InvocationMarshaller createMarshaller ()
+    {
+        return new ZoneMarshaller();
+    }
+
+    // documentation inherited
+    public void dispatchRequest (
+        ClientObject source, int methodId, Object[] args)
+        throws InvocationException
+    {
+        switch (methodId) {
+        case ZoneMarshaller.MOVE_TO:
+            ((ZoneProvider)provider).moveTo(
+                source,
+                ((Integer)args[0]).intValue(), ((Integer)args[1]).intValue(), ((Integer)args[2]).intValue(), (ZoneService.ZoneMoveListener)args[3]
+            );
+            return;
+
+        default:
+            super.dispatchRequest(source, methodId, args);
+            return;
+        }
+    }
+}
@@ -0,0 +1,104 @@
+//
+// $Id: ZoneManager.java 3350 2005-02-15 00:58:16Z mdb $
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2004 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.whirled.zone.server;
+
+import com.threerings.crowd.data.BodyObject;
+import com.threerings.whirled.zone.data.ZoneSummary;
+import com.threerings.whirled.zone.data.ZonedBodyObject;
+
+/**
+ * A zone is a collection of scenes organized into a connected group. A
+ * user can wander around within a zone, moving from scene to scene via
+ * the standard mechanisms. To move between zones, they must use a special
+ * mechanism (like at the dock, they can move from an island zone into
+ * their ship zone; or they can move from an island zone into their house
+ * zone). A zone provides scene summary information that can be used to
+ * display a map of the zone to the client.
+ */
+public interface ZoneManager
+{
+    /**
+     * Used to notify requesters when an asynchronous zone load has
+     * completed (successfully or not).
+     */
+    public static interface ResolutionListener
+    {
+        /**
+         * Called when a zone was successfully resolved.
+         */
+        public void zoneWasResolved (ZoneSummary summary);
+
+        /**
+         * Called when a zone failed to resolve.
+         */
+        public void zoneFailedToResolve (int zoneId, Exception reason);
+    }
+
+    /**
+     * Resolves and delivers the scene summary information for the
+     * requested zone. Zone resolution is an asynchronous process, which
+     * necessitates this callback-style interface.
+     *
+     * @param zoneId the qualified zone id of the zone to resolve.
+     * @param listener the listener that should be notified when the zone
+     * is successfully resolved or is known to have failed to resolve.
+     */
+    public void resolveZone (int zoneId, ResolutionListener listener);
+
+    /**
+     * Called when a body has requested to leave a zone. The zone manager
+     * may return null to indicate that the body is allowed to leave the
+     * current zone or a string error code indicating the reason for
+     * denial of access (which will be propagated back to the requesting
+     * client).
+     *
+     * @param body the body object of the user that desires to depart
+     * their current zone (which can be obtained by casting the {@link
+     * BodyObject} to a {@link ZonedBodyObject}).
+     */
+    public String ratifyBodyExit (BodyObject body);
+
+    /**
+     * Called when a body has requested to enter a zone. The zone manager
+     * may return null to indicate that the body is allowed access to the
+     * zone or a string error code indicating the reason for denial of
+     * access (which will be propagated back to the requesting client).
+     * This method is called <em>after</em> the zone is resolved so that
+     * the zone manager may complete the ratification process without
+     * blocking (which it must do).
+     *
+     * @param body the body object of the user that desires access to the
+     * specified zone.
+     * @param zoneId the id of the zone to which the user desires access.
+     */
+    public String ratifyBodyEntry (BodyObject body, int zoneId);
+
+    /**
+     * Called when a body has been granted access to a zone. This method
+     * must not block.
+     *
+     * @param body the body object of the user that was just granted
+     * access to a zone.
+     * @param zoneId the id of the zone to which they were granted access.
+     */
+    public void bodyDidEnterZone (BodyObject body, int zoneId);
+}
@@ -0,0 +1,303 @@
+//
+// $Id: ZoneProvider.java 3860 2006-02-17 01:08:01Z mthomas $
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2004 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.whirled.zone.server;
+
+import com.threerings.presents.data.ClientObject;
+import com.threerings.presents.data.InvocationMarshaller;
+import com.threerings.presents.server.InvocationException;
+import com.threerings.presents.server.InvocationProvider;
+
+import com.threerings.crowd.data.BodyObject;
+import com.threerings.crowd.data.PlaceConfig;
+import com.threerings.crowd.data.PlaceObject;
+import com.threerings.crowd.server.LocationProvider;
+
+import com.threerings.whirled.data.SceneModel;
+import com.threerings.whirled.data.SceneUpdate;
+import com.threerings.whirled.data.ScenedBodyObject;
+import com.threerings.whirled.server.SceneManager;
+import com.threerings.whirled.server.SceneRegistry;
+
+import com.threerings.whirled.zone.Log;
+import com.threerings.whirled.zone.client.ZoneService.ZoneMoveListener;
+import com.threerings.whirled.zone.data.ZoneCodes;
+import com.threerings.whirled.zone.data.ZoneSummary;
+import com.threerings.whirled.zone.data.ZonedBodyObject;
+
+/**
+ * Provides zone related services which are presently the ability to move
+ * from zone to zone.
+ */
+public class ZoneProvider
+    implements ZoneCodes, InvocationProvider
+{
+    /**
+     * Constructs a zone provider that will interoperate with the supplied
+     * zone and scene registries. The zone provider will automatically be
+     * constructed and registered by the {@link ZoneRegistry}, which a
+     * zone-using system must create and initialize in their server.
+     */
+    public ZoneProvider (LocationProvider locprov, ZoneRegistry zonereg,
+                         SceneRegistry screg)
+    {
+        _locprov = locprov;
+        _zonereg = zonereg;
+        _screg = screg;
+    }
+
+    /**
+     * Processes a request from a client to move to a scene in a new zone.
+     *
+     * @param caller the user requesting the move.
+     * @param zoneId the qualified zone id of the new zone.
+     * @param sceneId the identifier of the new scene.
+     * @param sceneVer the version of the scene model currently held by
+     * the client.
+     * @param listener the entity to inform of success or failure.
+     */
+    public void moveTo (ClientObject caller, int zoneId, int sceneId,
+                        int sceneVer, ZoneMoveListener listener)
+        throws InvocationException
+    {
+        // avoid cluttering up the method declaration with final keywords
+        final BodyObject fsource = (BodyObject)caller;
+        final int fsceneId = sceneId;
+        final int fsceneVer = sceneVer;
+        final ZoneMoveListener flistener = listener;
+
+        // look up the caller's current zone id and make sure it is happy
+        // about their departure from the current zone
+        if (!(caller instanceof ZonedBodyObject)) {
+            Log.warning("Request to switch zones by non-ZonedBodyObject!? " +
+                        "[clobj=" + caller.getClass() + "].");
+            throw new InvocationException(INTERNAL_ERROR);
+        }
+        ZonedBodyObject zcaller = (ZonedBodyObject)caller;
+        ZoneManager ozmgr = _zonereg.getZoneManager(zcaller.getZoneId());
+        if (ozmgr != null) {
+            String msg = ozmgr.ratifyBodyExit(fsource);
+            if (msg != null) {
+                throw new InvocationException(msg);
+            }
+        }
+
+        // look up the zone manager for the zone
+        ZoneManager zmgr = _zonereg.getZoneManager(zoneId);
+        if (zmgr == null) {
+            Log.warning("Requested to enter a zone for which we have no " +
+                        "manager [user=" + fsource.who() +
+                        ", zoneId=" + zoneId + "].");
+            throw new InvocationException(NO_SUCH_ZONE);
+        }
+
+        // resolve the zone!
+        ZoneManager.ResolutionListener zl = new ZoneManager.ResolutionListener()
+        {
+            public void zoneWasResolved (ZoneSummary summary) {
+                continueMoveTo(
+                    fsource, summary, fsceneId, fsceneVer, flistener);
+            }
+
+            public void zoneFailedToResolve (int zoneId, Exception reason) {
+                Log.warning("Unable to resolve zone [zoneId=" + zoneId +
+                            ", reason=" + reason + "].");
+                flistener.requestFailed(NO_SUCH_ZONE);
+            }
+        };
+        zmgr.resolveZone(zoneId, zl);
+    }
+
+    /**
+     * This is called after we have resolved our zone.
+     */
+    protected void continueMoveTo (
+        BodyObject source, ZoneSummary summary, int sceneId, int sceneVer,
+        ZoneMoveListener listener)
+    {
+        // avoid cluttering up the method declaration with final keywords
+        final BodyObject fsource = source;
+        final ZoneSummary fsum = summary;
+        final int fsceneVer = sceneVer;
+        final ZoneMoveListener flistener = listener;
+
+        // give the zone manager a chance to veto the request
+        ZoneManager zmgr = _zonereg.getZoneManager(summary.zoneId);
+        String errmsg = zmgr.ratifyBodyEntry(source, summary.zoneId);
+        if (errmsg != null) {
+            listener.requestFailed(errmsg);
+            return;
+        }
+
+        // create a callback object that will handle the resolution or
+        // failed resolution of the scene
+        SceneRegistry.ResolutionListener rl = null;
+        rl = new SceneRegistry.ResolutionListener() {
+            public void sceneWasResolved (SceneManager scmgr) {
+                // make sure our caller is still around; under heavy load,
+                // clients might end their session while the scene is
+                // resolving
+                if (!fsource.isActive()) {
+                    Log.info("Abandoning zone move, client gone " +
+                             "[who=" + fsource.who()  +
+                             ", dest=" + scmgr.where() + "].");
+                    // No one to respond to, just mark that we're okay with it.
+                    InvocationMarshaller.setNoResponse(flistener);
+                    return;
+                }
+                finishMoveTo(fsource, fsum, scmgr, fsceneVer, flistener);
+            }
+
+            public void sceneFailedToResolve (int sceneId, Exception reason) {
+                Log.warning("Unable to resolve scene [sceneid=" + sceneId +
+                            ", reason=" + reason + "].");
+                // pretend like the scene doesn't exist to the client
+                flistener.requestFailed(NO_SUCH_PLACE);
+            }
+        };
+
+        // make sure the scene they are headed to is actually loaded into
+        // the server
+        _screg.resolveScene(sceneId, rl);
+    }
+
+    /**
+     * This is called after the scene to which we are moving is guaranteed
+     * to have been loaded into the server.
+     */
+    protected void finishMoveTo (
+        BodyObject source, ZoneSummary summary, SceneManager scmgr,
+        int sceneVersion, ZoneMoveListener listener)
+    {
+        // move to the place object associated with this scene
+        PlaceObject plobj = scmgr.getPlaceObject();
+        int ploid = plobj.getOid();
+
+        try {
+            // try doing the actual move
+            PlaceConfig config = _locprov.moveTo(source, ploid);
+
+            // now that we've finally moved, we can update the user object
+            // with the new scene and zone ids
+            source.startTransaction();
+            try {
+                ((ScenedBodyObject)source).setSceneId(scmgr.getScene().getId());
+                ((ZonedBodyObject)source).setZoneId(summary.zoneId);
+            } finally {
+                source.commitTransaction();
+            }
+
+            // check to see if they need a newer version of the scene data
+            SceneModel model = scmgr.getScene().getSceneModel();
+            if (sceneVersion < model.version) {
+                SceneUpdate[] updates = scmgr.getUpdates(sceneVersion);
+                if (updates != null) {
+                    listener.moveSucceededWithUpdates(
+                        ploid, config, summary, updates);
+                } else {
+                    listener.moveSucceededWithScene(
+                        ploid, config, summary, model);
+                }
+
+            } else {
+                // then send the moveTo response
+                listener.moveSucceeded(ploid, config, summary);
+            }
+
+            // let the zone manager know that someone just came on in
+            ZoneManager zmgr = _zonereg.getZoneManager(summary.zoneId);
+            zmgr.bodyDidEnterZone(source, summary.zoneId);
+
+        } catch (InvocationException ie) {
+            listener.requestFailed(ie.getMessage());
+
+        } catch (RuntimeException re) {
+            Log.logStackTrace(re);
+            listener.requestFailed(INTERNAL_ERROR);
+        }
+    }
+
+    /**
+     * Ejects the specified body from their current scene and sends them a
+     * request to move to the specified new zone and scene. This is the
+     * zone-equivalent to {@link LocationProvider#moveBody}.
+     *
+     * @return null if the user was forcibly moved, or a string indicating
+     * the reason for denial of departure of their current zone (from
+     * {@link ZoneManager#ratifyBodyExit}).
+     */
+    public String moveBody (ZonedBodyObject source, int zoneId, int sceneId)
+    {
+        if (source.getZoneId() == zoneId) {
+            // handle the case of moving somewhere in the same zone
+            _screg.sceneprov.moveBody((BodyObject) source, sceneId);
+
+        } else {
+            // first remove them from their old location
+            String reason = leaveOccupiedZone(source);
+            if (reason != null) {
+                return reason;
+            }
+
+            // then send a forced move notification
+            ZoneSender.forcedMove((BodyObject)source, zoneId, sceneId);
+        }
+        return null;
+    }
+
+    /**
+     * Ejects the specified body from their current scene and zone. This
+     * is the zone equivalent to {@link
+     * LocationProvider#leaveOccupiedPlace}.
+     *
+     * @return null if the user was forcibly moved, or a string indicating
+     * the reason for denial of departure of their current zone (from
+     * {@link ZoneManager#ratifyBodyExit}).
+     */
+    public String leaveOccupiedZone (ZonedBodyObject source)
+    {
+        // look up the caller's current zone id and make sure it is happy
+        // about their departure from the current zone
+        ZoneManager zmgr = _zonereg.getZoneManager(source.getZoneId());
+        String msg;
+        if (zmgr != null &&
+            (msg = zmgr.ratifyBodyExit((BodyObject)source)) != null) {
+            return msg;
+        }
+
+        // remove them from their occupied scene
+        _screg.sceneprov.leaveOccupiedScene(source);
+
+        // and clear out their zone information
+        source.setZoneId(-1);
+
+        return null;
+    }
+
+    /** The entity that handles basic location changes. */
+    protected LocationProvider _locprov;
+
+    /** The zone registry with which we communicate. */
+    protected ZoneRegistry _zonereg;
+
+    /** The scene registry with which we communicate. */
+    protected SceneRegistry _screg;
+}
@@ -0,0 +1,88 @@
+//
+// $Id: ZoneRegistry.java 4191 2006-06-13 22:42:20Z ray $
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2004 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.whirled.zone.server;
+
+import com.samskivert.util.HashIntMap;
+
+import com.threerings.presents.server.InvocationManager;
+
+import com.threerings.crowd.server.PlaceRegistry;
+import com.threerings.whirled.server.SceneRegistry;
+
+import com.threerings.whirled.zone.Log;
+import com.threerings.whirled.zone.util.ZoneUtil;
+
+/**
+ * The zone registry takes care of mapping zone requests to the
+ * appropriate registered zone manager.
+ */
+public class ZoneRegistry
+{
+    /** Implements the server-side of the zone-related services. */
+    public ZoneProvider zoneprov;
+
+    /**
+     * Creates a zone manager with the supplied configuration.
+     */
+    public ZoneRegistry (InvocationManager invmgr, PlaceRegistry plreg,
+                         SceneRegistry screg)
+    {
+        // create a zone provider and register it with the invocation
+        // services
+        zoneprov = new ZoneProvider(plreg.locprov, this, screg);
+        invmgr.registerDispatcher(new ZoneDispatcher(zoneprov), true);
+    }
+
+    /**
+     * Registers the supplied zone manager as the manager for the
+     * specified zone type. Zone types are 7 bits and managers are
+     * responsible for making sure they don't use a zone type that
+     * collides with another manager (given that we have only three zone
+     * types at present, this doesn't seem unreasonable).
+     */
+    public void registerZoneManager (byte zoneType, ZoneManager manager)
+    {
+        ZoneManager old = (ZoneManager)_managers.get(zoneType);
+        if (old != null) {
+            Log.warning("Zone manager already registered with requested " +
+                        "type [type=" + zoneType + ", old=" + old +
+                        ", new=" + manager + "].");
+        } else {
+            _managers.put(zoneType, manager);
+        }
+    }
+
+    /**
+     * Returns the zone manager that handles the specified zone id.
+     *
+     * @param qualifiedZoneId the qualified zone id for which the manager
+     * should be looked up.
+     */
+    public ZoneManager getZoneManager (int qualifiedZoneId)
+    {
+        int zoneType = ZoneUtil.zoneType(qualifiedZoneId);
+        return (ZoneManager)_managers.get(zoneType);
+    }
+
+    /** A table of zone managers. */
+    protected HashIntMap _managers = new HashIntMap();
+}
@@ -0,0 +1,47 @@
+//
+// $Id: ZoneSender.java 4145 2006-05-24 01:24:24Z ray $
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2006 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.whirled.zone.server;
+
+import com.threerings.presents.data.ClientObject;
+import com.threerings.presents.server.InvocationSender;
+import com.threerings.whirled.zone.client.ZoneDecoder;
+import com.threerings.whirled.zone.client.ZoneReceiver;
+
+/**
+ * Used to issue notifications to a {@link ZoneReceiver} instance on a
+ * client.
+ */
+public class ZoneSender extends InvocationSender
+{
+    /**
+     * Issues a notification that will result in a call to {@link
+     * ZoneReceiver#forcedMove} on a client.
+     */
+    public static void forcedMove (
+        ClientObject target, int arg1, int arg2)
+    {
+        sendNotification(
+            target, ZoneDecoder.RECEIVER_CODE, ZoneDecoder.FORCED_MOVE,
+            new Object[] { Integer.valueOf(arg1), Integer.valueOf(arg2) });
+    }
+
+}
@@ -0,0 +1,66 @@
+//
+// $Id: ZoneUtil.java 4191 2006-06-13 22:42:20Z ray $
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2004 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.whirled.zone.util;
+
+/**
+ * Server-specific, zone-related utility functions.
+ */
+public class ZoneUtil
+{
+    /**
+     * Composes the zone type and zone id into a qualified zone id. A
+     * qualified zone id is what should be passed around so that the
+     * server can determine the zone type from the zone id when necessary.
+     */
+    public static int qualifyZoneId (byte zoneType, int zoneId)
+    {
+        int qualifiedZoneId = zoneType;
+        qualifiedZoneId <<= 24;
+        qualifiedZoneId |= zoneId;
+        return qualifiedZoneId;
+    }
+
+    /**
+     * Extracts the zone type from a qualified zone id.
+     */
+    public static int zoneType (int qualifiedZoneId)
+    {
+        return (0xFF000000 & qualifiedZoneId) >> 24;
+    }
+
+    /**
+     * Extracts the zone id from a qualified zone id.
+     */
+    public static int zoneId (int qualifiedZoneId)
+    {
+        return (0x00FFFFFF & qualifiedZoneId);
+    }
+
+    /**
+     * Returns an easier to read representation of the supplied qualified
+     * zone id: <code>type:id</code>.
+     */
+    public static String toString (int qualifiedZoneId)
+    {
+        return zoneType(qualifiedZoneId) + ":" + zoneId(qualifiedZoneId);
+    }
+}