We love to document. Provided an initial description of what services the

whirled.spot package will provide and created a Log class for the package. git-svn-id: svn+ssh://src.earth.threerings.net/narya/trunk@617 542714f4-19e9-0310-aa3c-eee0fc999fb1
2001-11-13 00:12:20 +00:00
parent 3154885777
commit 17281a9db3
4 changed files with 146 additions and 0 deletions
@@ -0,0 +1,38 @@
+//
+// $Id: Log.java,v 1.1 2001/11/13 00:12:20 mdb Exp $
+
+package com.threerings.whirled.spot;
+
+/**
+ * A placeholder class that contains a reference to the log object used by
+ * the services provided by this package.
+ */
+public class Log
+{
+    public static com.samskivert.util.Log log =
+	new com.samskivert.util.Log("whirled.spot");
+
+    /** 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,108 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+  <head>
+    <!-- $Id: package.html,v 1.1 2001/11/13 00:12:20 mdb Exp $ -->
+  </head>
+  <body bgcolor="white">
+
+    Extends the Whirled services with the notion of locations, clusters,
+    coordinates and orientation.
+
+    <p> The basic Whirled services facilitate a game that provides a
+      connected set of scenes and the ability for the bodies to move from
+      a scene to its neighboring scenes. The Spot package extends those
+      services by providing the notion of locations within scenes which a
+      body can occupy and which, while occupied, cannot be occupied by
+      other bodies.
+    </p>
+
+    <p> The philosophy is that a game that uses these services wants to
+      create a constrained universe where a body cannot simply stand
+      anywhere on the screen, but can only stand in a set of predefined
+      locations.  This is a simplified mechanism for providing finer
+      grained locality management, such that expensive distance monitoring
+      algorithms need not be used to determine who can interact (speak)
+      with others in a particular scene. For many games, the overhead of
+      tracking each users' position in near-realtime coupled with a
+      complex message broadcasting system that dispatches messages to
+      users in geometric proximity to one another is serious overkill and
+      does not add sufficient value to the game to merit inclusion.
+    </p>
+
+    <p><b>Locations and clusters</b><br>
+
+      The Spot package provides a functional approximation in the form of
+      clusters of locations, with predefined coordinates, that are
+      sufficiently proximal that bodies in that cluster of locations can
+      all speak to one another. The locations for a particular scene are
+      specified in advance which serves the additional purpose of putting
+      a limit on the number of bodies that can be standing (and
+      participating) in a particular scene. This puts a natural upper
+      bound on the amount of network traffic that will be generated by the
+      need to broadcast scene updates to all occupants of a scene.
+    </p>
+
+    <p> Locations also serve as entry and exit points for a scene,
+      providing a means both for the graphical user interface to identify
+      the location at which bodies enter and exit a scene as well as
+      providing a spatial context for the connections between scenes
+      (i.e. the exit to the scene to the north can be located in the
+      northward part of a scene display).
+    </p>
+
+    <p><b>Orientation</b><br>
+
+      Locations define a notion of orientation which is assigned a priori,
+      along with the coordinates of the location and which can be
+      interpreted by the graphical display as the direction that body
+      sprites should face when standing on that location.  Clusters of
+      locations can be constructed such that all of the bodies standing in
+      that cluster appear to be facing one another which provides visible
+      reinforcement that members of the cluster can "hear" the
+      conversation, while members of other clusters cannot. The
+      orientation of entry and exit locations are also useful in
+      establishing an initial orientation for a body sprite that enters a
+      scene based on the visualization of the entrance mechanism (i.e. if
+      they appear to enter through the door, the body sprite should be
+      oriented as if it just walked in the proper direction through the
+      door).
+    </p>
+
+    <p> Because the Spot services redefine the scope at which speak
+      messages are normally distributed (the Crowd services would, by
+      default, have speak messages dispatched to everyone in the entire
+      scene because the scene is a place and the default chat mechanisms
+      dispatch speak messages to all occupants of a place), it defines an
+      additional communication mode known as shouting, which conveys the
+      message to everyone in the entire scene.
+    </p>
+
+    <p><b>Portals</b><br>
+
+      Portals are a combination of locations and the standard Whirled
+      notion of neighboring scenes. They contain the coordinates to which
+      a body sprite would traverse prior to exiting to a neighboring scene
+      (generally so that they appear to walk to whatever visual
+      representation of the portal is provided by the scene, like a door
+      or perhaps simply the edge of the scene). Conversely, they represent
+      the coordinates at which a body arriving from same neighboring scene
+      would appear in the displayed scene.
+    </p>
+
+    <p><b>Example display</b><br>
+
+      This is an example of how these concepts might look in a game
+      providing top-down 2D display of its scenes. <br>
+    </p>
+
+    <center>
+      <img align="center" src="images/scene.png" alt="Example scene image">
+    </center>
+
+    <p> The arrows would, of course, not be rendered but are shown to
+      indicate the presence of locations (and portals) and their
+      associated orientation information.
+    </p>
+
+  </body>
+</html>