# Package com.threerings.whirled.spot

Extends the Whirled services with the notion of locations, clusters, coordinates and orientation.

See: Description

Class Summary
Log: Contains a reference to the log object used by the Whirled Spot services.

## Package com.threerings.whirled.spot Description

Extends the Whirled services with the notion of locations, clusters, coordinates and orientation.

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.

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.

Locations and clusters
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.

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).

Orientation
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).

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.

Portals
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.

Example display
This is an example of how these concepts might look in a game providing top-down 2D display of its scenes.

The arrows would, of course, not be rendered but are shown to indicate the presence of locations (and portals) and their associated orientation information.