com.simsilica.ethereal.zone

Class ZoneManager

java.lang.Object

com.simsilica.ethereal.zone.ZoneManager

public class ZoneManager
extends java.lang.Object

Manages all of the zones for all of the players. This is used to update the status of active objects. The zone manager then makes sure that information gets to where it needs to go.

Object updates need to be done in the context of a 'frame' so that the updates can be properly grouped together. To do this, the game code that is reporting updates needs to call the ZoneManager methods using a specific life cycle:

• beginUpdate(frameTime): starts a new frame. The frame time will be used to stamp any state updates.
• updateEntity(...): record an update event for the specific entity within the current frame.
• remove(entityId): removes an entity from the zone manager. This can be called between beginUpdate() and endUpdate() but it can also be called outside of those calls and the removal will be enqueued for the next update. If this feature is used then make sure to also call add() if the object needs to come back.
• endUpdate(): closes updates to the current frame.
• add(entityId): used outside of beginUpdate()/endUpdate() if remove(id) is also used outside of beingUpdate()/endUpdate(). Calling remove(id) outside of a begin/end block will enqueue the removal for the next begin/end block. add() will remove it from this queue in case that removal hasn't been sent yet. Normally add() is not required as updateEntity() will add the entity if it hasn't already seen it.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	ZoneManager.DynamicZoneRange
protected class	ZoneManager.OctZoneRange The original ZoneRange implementation that maxed out at 8 zones, ie: 2x2x2.
protected static interface	ZoneManager.ZoneRange

Constructor Summary

Constructors

Constructor and Description
ZoneManager(int zoneSize) Creates a new ZoneManager with a ZoneGrid sized using zoneSize and with a history backlog of 12 frames.
ZoneManager(ZoneGrid grid) Creates a new ZoneManager with the specified grid representation and with a history backlog of 12.
ZoneManager(ZoneGrid grid, int historyBacklog) Creates a new zone manager with the specified grid representation and history backlog.

Method Summary

Modifier and Type	Method and Description
void	add(java.lang.Long id) Let's the zone manager know about a particular entity.
void	beginUpdate(long time) Starts history collection for a frame at the specified time.
void	endUpdate() Called to end update collection for the current 'frame'.
protected void	enterZone(java.lang.Long id, ZoneKey key)
boolean	getCollectHistory() Returns true if the ZoneManager is currently collecting history, false otherwise.
int	getFrameOverflowLimit()
int	getFrameUnderflowLimit()
ZoneGrid	getGrid() Returns the current zone specification used for partioning space into zones.
boolean	getSupportLargeObjects()
protected Zone	getZone(ZoneKey key, boolean create)
protected ZoneManager.ZoneRange	getZoneRange(java.lang.Long id, boolean create)
protected void	leaveZone(java.lang.Long id, ZoneKey key)
static void	main(java.lang.String... args)
protected void	objectWarped(java.lang.Long parent, java.lang.Long id, ZoneKey key)
StateFrame[]	purgeState() Called by a state collection process to return all of the history that has been collected since the last call to purgeState().
void	remove(java.lang.Long id) Removes the entity from the zone manager.
void	setCollectHistory(boolean b) Set to true if history should be collected or false if object updates should be ignored.
void	setFrameOverflowLimit(int frameOverflowLimit) Sets frame overflow limit.
void	setFrameRateLimits(int frameUnderflowLimit, int frameOverflowLimit) Sets frame update limits which are used to print warnings when ZoneManager update rate goes under or over the specified value.
void	setFrameUnderflowLimit(int frameUnderflowLimit) Sets frame underflow limit.
void	setSupportLargeObjects(boolean b) Set to true to support objects that are larger than the grid spacing.
void	updateEntity(java.lang.Long id, boolean active, com.simsilica.mathd.Vec3d p, com.simsilica.mathd.Quatd orientation, com.simsilica.mathd.AaBBox bounds) Updates an entity's position in the zone space.
void	updateEntity(java.lang.Long parent, java.lang.Long child, boolean active, com.simsilica.mathd.Vec3d p, com.simsilica.mathd.Quatd orientation, com.simsilica.mathd.AaBBox bounds)
protected void	updateZoneObject(java.lang.Long parent, java.lang.Long id, com.simsilica.mathd.Vec3d p, com.simsilica.mathd.Quatd orientation, ZoneKey key) Sends the object update to the specified zone.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ZoneManager

public ZoneManager(int zoneSize)

Creates a new ZoneManager with a ZoneGrid sized using zoneSize and with a history backlog of 12 frames.

ZoneManager

public ZoneManager(ZoneGrid grid)

Creates a new ZoneManager with the specified grid representation and with a history backlog of 12.

ZoneManager

public ZoneManager(ZoneGrid grid,
                   int historyBacklog)

Creates a new zone manager with the specified grid representation and history backlog.

Parameters:

grid - The grid settings used for zone partitioning.

historyBacklog - Designates how many frames of history to keep in each zone.

Method Detail

getGrid

public ZoneGrid getGrid()

Returns the current zone specification used for partioning space into zones.

setSupportLargeObjects

public void setSupportLargeObjects(boolean b)

Set to true to support objects that are larger than the grid spacing. This is a new experimental feature that may become the default behavior someday. In the mean time, applications have to specifically turn it on because the new code is less tested. The older internal zone range implementation would not support objects that spanned more than two zones in any direction (and will log an error when it encounters this). The thinking was that it could use a fixed size array and avoid constantly recreating it. The thing is it was always cloning it internally anyway whenever the range changed. The new code builds its array dynamically and can essentially support any zone range. It's probably just as good and just as memory efficient.

getSupportLargeObjects

public boolean getSupportLargeObjects()

setCollectHistory

public void setCollectHistory(boolean b)

Set to true if history should be collected or false if object updates should be ignored. This method is used internal to the framework for managing the lifecycle of dependent components. When a ZoneManager is not part of an active state collection process then it's important that it not collect any history because it might overflow its buffers since purge() is never called. Generally, the StateCollector will turn history collection on when it is ready to start periodically purging history. Defaults to false until a state collection process turns it on.

getCollectHistory

public boolean getCollectHistory()

Returns true if the ZoneManager is currently collecting history, false otherwise. When a ZoneManager is not part of an active StateCollector then it's important that it not track history.

setFrameRateLimits

public void setFrameRateLimits(int frameUnderflowLimit,
                               int frameOverflowLimit)

Sets frame update limits which are used to print warnings when ZoneManager update rate goes under or over the specified value. By default underflow limit is 60 and overflow limit is 70.

Throws:

java.lang.IllegalArgumentException - if values are negative or underflow limit is larger than the overflow limit.

setFrameUnderflowLimit

public void setFrameUnderflowLimit(int frameUnderflowLimit)

Sets frame underflow limit. ZoneManager will print warnings if frame update rate goes below this limit. By default underflow limit is 60.

Throws:

java.lang.IllegalArgumentException - if value is negative or larger than the overflow limit.

getFrameUnderflowLimit

public int getFrameUnderflowLimit()

setFrameOverflowLimit

public void setFrameOverflowLimit(int frameOverflowLimit)

Sets frame overflow limit. ZoneManager will print warnings if frame update rate goes above this limit. By default overflow limit is 70.

Throws:

java.lang.IllegalArgumentException - if value is negative or less than the underflow limit.

getFrameOverflowLimit

public int getFrameOverflowLimit()

getZoneRange

protected ZoneManager.ZoneRange getZoneRange(java.lang.Long id,
                                             boolean create)

beginUpdate

public void beginUpdate(long time)

Starts history collection for a frame at the specified time. All updateEntity() and remove() calls after this beginUpdate() will be collected together and associated with the specified frame time until endUpdate() is called.

updateEntity

public void updateEntity(java.lang.Long id,
                         boolean active,
                         com.simsilica.mathd.Vec3d p,
                         com.simsilica.mathd.Quatd orientation,
                         com.simsilica.mathd.AaBBox bounds)

Updates an entity's position in the zone space.

Parameters:

id - The ID of the object that has been moved.

active - Currently unused. Pass 'true' or the non-sleeping state of your object if you care to be accurate for future changes.

p - The position of the object in world space.

orientation - The orientation of the object in world space.

bounds - The 3D bounds of the object in WORLD SPACE. This is why it's passed every update and it allows it to change to be accurate as the object rotates and so on. But more importantly, it pushes the updating of the bounds to the thing actually controlling the position which might be able to more efficiently update it than we could internally.

updateEntity

public void updateEntity(java.lang.Long parent,
                         java.lang.Long child,
                         boolean active,
                         com.simsilica.mathd.Vec3d p,
                         com.simsilica.mathd.Quatd orientation,
                         com.simsilica.mathd.AaBBox bounds)

endUpdate

public void endUpdate()

Called to end update collection for the current 'frame'. See: beginUpdate()

purgeState

public StateFrame[] purgeState()

Called by a state collection process to return all of the history that has been collected since the last call to purgeState(). Generally, this method is called internal to the framework, usually by the StateCollector. The return array will contain one StateFrame[] for every beginUpdate()/endUpdate() block since the last purgeState(). Each StateFrame will contain all of the state updates for that frame divided into separate StateBlocks, one per active zone.

add

public void add(java.lang.Long id)

Let's the zone manager know about a particular entity. This is only required if remove() is used for objects that may come back later... like for objects that enter/leave the zone manager if they are awake/asleep. Essentially it just makes sure that the object isn't pending removal on the next update.

remove

public void remove(java.lang.Long id)

Removes the entity from the zone manager. This can also be used to temporarily deactivate an entity but then add() must be called if it is active again.

getZone

protected Zone getZone(ZoneKey key,
                       boolean create)

updateZoneObject

protected void updateZoneObject(java.lang.Long parent,
                                java.lang.Long id,
                                com.simsilica.mathd.Vec3d p,
                                com.simsilica.mathd.Quatd orientation,
                                ZoneKey key)

Sends the object update to the specified zone. If parent is null then 'child' is a child of the world.

objectWarped

protected void objectWarped(java.lang.Long parent,
                            java.lang.Long id,
                            ZoneKey key)

enterZone

protected void enterZone(java.lang.Long id,
                         ZoneKey key)

leaveZone

protected void leaveZone(java.lang.Long id,
                         ZoneKey key)

main

public static void main(java.lang.String... args)