com.threerings.whirled.client

## Class SceneDirector

- java.lang.Object
- - com.threerings.presents.client.BasicDirector
  - - com.threerings.whirled.client.SceneDirector

All Implemented Interfaces:
  com.threerings.crowd.client.LocationDirector.FailureHandler, com.threerings.crowd.data.LocationCodes, com.threerings.presents.client.InvocationReceiver, com.threerings.presents.client.InvocationService.InvocationListener, com.threerings.presents.client.SessionObserver, com.threerings.presents.data.InvocationCodes, SceneReceiver, SceneService.SceneMoveListener, SceneCodes

    public class SceneDirector
    extends com.threerings.presents.client.BasicDirector
    implements SceneCodes, com.threerings.crowd.client.LocationDirector.FailureHandler, SceneReceiver, SceneService.SceneMoveListener

The scene director is the client's interface to all things scene related. It interfaces with the scene repository to ensure that scene objects are available when the client enters a particular scene. It handles moving from scene to scene (it coordinates with the `LocationDirector` in order to do this).

Note that when the scene director is in use instead of the location director, scene ids instead of place oids will be supplied to `LocationObserver.locationMayChange(int)` and `LocationObserver.locationChangeFailed(int, java.lang.String)`.

### Nested Class Summary

Nested Classes
`static interface` `SceneDirector.MoveHandler` Used to recover from a problem after a completed moveTo.

### Nested classes/interfaces inherited from interface com.threerings.presents.client.InvocationReceiver

`com.threerings.presents.client.InvocationReceiver.Registration`

### Field Summary

### Fields inherited from interface com.threerings.whirled.data.SceneCodes

`SCENE_UPDATE, WHIRLED_GROUP`

### Fields inherited from interface com.threerings.crowd.data.LocationCodes

`ALREADY_THERE, MOVE_IN_PROGRESS, NO_SUCH_PLACE`

### Fields inherited from interface com.threerings.presents.data.InvocationCodes

`ACCESS_DENIED, E_ACCESS_DENIED, E_INTERNAL_ERROR, GLOBAL_GROUP, INTERNAL_ERROR`

### Constructor Summary

Constructors
Constructor and Description
`SceneDirector(WhirledContext ctx, com.threerings.crowd.client.LocationDirector locdir, SceneRepository screp, SceneFactory fact)` Creates a new scene director with the specified context.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `addPendingForcedMove(Runnable move)`
`void` `cancelMoveRequest()`
`void` `clientDidLogoff(com.threerings.presents.client.Client client)`
`void` `didLeaveScene()` Called to clean up our place and scene state information when we leave a scene.
`void` `forcedMove(int sceneId)` Used to communicate a required move notification to the client.
`SceneModel` `getPendingModel()` Returns the model loaded in preparation for a scene transition.
`int` `getPendingSceneId()` Returns the scene id set in preparation for a scene transition.
`Scene` `getScene()` Returns the display scene object associated with the scene we currently occupy or null if we currently occupy no scene.
`boolean` `movePending()` Returns true if there is a pending move request.
`void` `moveRequiresServerSwitch(String hostname, int[] ports)` Indicates that the client must switch to the specified server and reissue its move request in order to relocate to its desired scene.
`void` `moveSucceeded(int placeId, com.threerings.crowd.data.PlaceConfig config)` Indicates that a move succeeded.
`void` `moveSucceededWithScene(int placeId, com.threerings.crowd.data.PlaceConfig config, SceneModel model)` Indicates that a move succeeded and that the client's cached scene information should be updated with the supplied data.
`void` `moveSucceededWithUpdates(int placeId, com.threerings.crowd.data.PlaceConfig config, SceneUpdate[] updates)` Indicates that a move succeeded and that the client's cached scene information should be updated with the supplied data.
`boolean` `moveTo(int sceneId)` Requests that this client move the specified scene.
`boolean` `prepareMoveTo(int sceneId, ResultListener<com.threerings.crowd.data.PlaceConfig> rl)` Prepares to move to the requested scene.
`void` `recoverFailedMove(int placeId)`
`void` `requestFailed(String reason)`
`void` `setMoveHandler(SceneDirector.MoveHandler handler)` Sets the moveHandler for use in `recoverFailedMove(int)`.
`void` `setSceneRepository(SceneRepository screp)` Set the scene repository.
`void` `updateReceived(SceneUpdate update)` Called by SceneController instances to tell us about an update to the current scene.

### Methods inherited from class com.threerings.presents.client.BasicDirector

`clientDidLogon, clientObjectDidChange, clientWillLogon, isAvailableInStandalone, setAvailableInStandalone`

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### SceneDirector

    public SceneDirector(WhirledContext ctx,
                         com.threerings.crowd.client.LocationDirector locdir,
                         SceneRepository screp,
                         SceneFactory fact)

Creates a new scene director with the specified context.

Parameters:
  `ctx` - the active client context.
  `locdir` - the location director in use on the client, with which the scene director will coordinate when changing location.
  `screp` - the entity from which the scene director will load scene data from the local client scene storage. This may be null when the SceneDirector is constructed, but it should be supplied via `setSceneRepository(com.threerings.whirled.client.persist.SceneRepository)` prior to really using this director.
  `fact` - the factory that knows which derivation of `Scene` to create for the current system.

### Method Detail

#### setSceneRepository

    public void setSceneRepository(SceneRepository screp)

Set the scene repository.

#### getScene

    public Scene getScene()

Returns the display scene object associated with the scene we currently occupy or null if we currently occupy no scene.

#### movePending

    public boolean movePending()

Returns true if there is a pending move request.

#### moveTo

    public boolean moveTo(int sceneId)

Requests that this client move the specified scene. A request will be made and when the response is received, the location observers will be notified of success or failure.

Returns:
  true if the move to request was issued, false if it was rejected by a location observer or because we have another request outstanding.

#### prepareMoveTo

    public boolean prepareMoveTo(int sceneId,
                                 ResultListener<com.threerings.crowd.data.PlaceConfig> rl)

Prepares to move to the requested scene. The location observers are asked to ratify the move and our pending scene mode is loaded from the scene repository. This can be called by cooperating directors that need to coopt the moveTo process.

#### getPendingModel

    public SceneModel getPendingModel()

Returns the model loaded in preparation for a scene transition. This is made available only for cooperating directors which may need to coopt the scene transition process. The pending model is only valid immediately following a call to `prepareMoveTo(int, com.samskivert.util.ResultListener<com.threerings.crowd.data.PlaceConfig>)`.

#### getPendingSceneId

    public int getPendingSceneId()

Returns the scene id set in preparation for a scene transition. As with `getPendingModel()`, this is for cooperating directors.

#### moveSucceeded

    public void moveSucceeded(int placeId,
                              com.threerings.crowd.data.PlaceConfig config)

Description copied from interface: `SceneService.SceneMoveListener`
Indicates that a move succeeded.

Specified by:
  `moveSucceeded` in interface `SceneService.SceneMoveListener`
Parameters:
  `placeId` - the place object id of the newly occupied scene.
  `config` - metadata related to the newly occupied scene.

#### moveSucceededWithUpdates

    public void moveSucceededWithUpdates(int placeId,
                                         com.threerings.crowd.data.PlaceConfig config,
                                         SceneUpdate[] updates)

Description copied from interface: `SceneService.SceneMoveListener`
Indicates that a move succeeded and that the client's cached scene information should be updated with the supplied data.

Specified by:
  `moveSucceededWithUpdates` in interface `SceneService.SceneMoveListener`
Parameters:
  `placeId` - the place object id of the newly occupied scene.
  `config` - metadata related to the newly occupied scene.
  `updates` - updates that must be applied to the client's copy of a scene model to bring it up to date.

#### moveSucceededWithScene

    public void moveSucceededWithScene(int placeId,
                                       com.threerings.crowd.data.PlaceConfig config,
                                       SceneModel model)

Description copied from interface: `SceneService.SceneMoveListener`
Indicates that a move succeeded and that the client's cached scene information should be updated with the supplied data.

Specified by:
  `moveSucceededWithScene` in interface `SceneService.SceneMoveListener`
Parameters:
  `placeId` - the place object id of the newly occupied scene.
  `config` - metadata related to the newly occupied scene.
  `model` - a fresh copy of the most recent scene data for the newly occupied scene.

#### moveRequiresServerSwitch

    public void moveRequiresServerSwitch(String hostname,
                                         int[] ports)

Description copied from interface: `SceneService.SceneMoveListener`
Indicates that the client must switch to the specified server and reissue its move request in order to relocate to its desired scene.

Specified by:
  `moveRequiresServerSwitch` in interface `SceneService.SceneMoveListener`

#### requestFailed

    public void requestFailed(String reason)

Specified by:
  `requestFailed` in interface `com.threerings.presents.client.InvocationService.InvocationListener`

#### updateReceived

    public void updateReceived(SceneUpdate update)

Called by SceneController instances to tell us about an update to the current scene.

#### didLeaveScene

    public void didLeaveScene()

Called to clean up our place and scene state information when we leave a scene.

#### setMoveHandler

    public void setMoveHandler(SceneDirector.MoveHandler handler)

Sets the moveHandler for use in `recoverFailedMove(int)`.

#### forcedMove

    public void forcedMove(int sceneId)

Description copied from interface: `SceneReceiver`
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 `SceneService.moveTo(int, int, com.threerings.whirled.client.SceneService.SceneMoveListener)` request to move to the new scene.

Specified by:
  `forcedMove` in interface `SceneReceiver`

#### recoverFailedMove

    public void recoverFailedMove(int placeId)

Specified by:
  `recoverFailedMove` in interface `com.threerings.crowd.client.LocationDirector.FailureHandler`

#### clientDidLogoff

    public void clientDidLogoff(com.threerings.presents.client.Client client)

Specified by:
  `clientDidLogoff` in interface `com.threerings.presents.client.SessionObserver`
Overrides:
  `clientDidLogoff` in class `com.threerings.presents.client.BasicDirector`

#### cancelMoveRequest

    public void cancelMoveRequest()

#### addPendingForcedMove

    public void addPendingForcedMove(Runnable move)