Dragengine.Utils.ElementResolver Class Reference

Resolve element links. More...

Inheritance diagram for Dragengine.Utils.ElementResolver:

Classes
class	Request
	Resolve request. More...
class	ResolveException
	Resolve failure. More...

Public Member Functions
void	add (FileReader reader, Block ablock)
	Add resolve request.
void	add (UniqueID id, Block ablock)
	Add resolve request.
void	addAllowFail (FileReader reader, Block ablock)
	Add resolve request which is allowed to fail.
void	addAllowFail (UniqueID id, Block ablock)
	Add resolve request which is allowed to fail.
void	addBehavior (FileReader reader, Block ablock)
	Add resolve request for BehaviorInstance.
void	addBehavior (UniqueID id, int behaviorInstanceIndex, Block ablock)
	Add resolve request for BehaviorInstance.
void	addBehaviorAllowFail (FileReader reader, Block ablock)
	Add resolve request for BehaviorInstance which is allowed to fail.
void	addBehaviorAllowFail (UniqueID id, int behaviorInstanceIndex, Block ablock)
	Add resolve request for BehaviorInstance which is allowed to fail.
Request	getAt (int index)
	Pending request at index.
ElementResolver	new ()
	Create resolver.
void	resolve (GameWorld gameWorld)
	Resolve elements.

Static Public Member Functions
static void	writeToFile (FileWriter writer, Element element)
	Write parameters to file suitable for add(UniqueID, Block).
static void	writeToFileBehavior (FileWriter writer, ECBehaviorInstance behaviorInstance)
	Write parameters to file suitable for addBehavior(UniqueID, int, Block).

Public Attributes
Array	pRequests

Detailed Description

Resolve element links.

Helper class to resolve element identifiers read from file readers. While loading elements from files the elements referenced by identifiers very well can not be present yet in the game world since they show up in the file at a later time. To support such links the UniqueID of an element is saved. Once read it has to be resolved once all elements are present in the game world. The best time for this is during a call to Element.enterFrame(). An instance of this class has to be placed in elements requiring resolving behavior. To resolve an encountered element add a resolve request to the instance of this class with a block to use. The following code example shows how to use this class.

class MyElement extends Element
   var ElementResolver pElementResolver
   var Element pElementInHands
   
   func new()
      pElementResolver = ElementResolver.new()
   end
   
   func void readFromFile(FileReader reader)
      ...
      if hasElementInHands
         pElementResolver.add(UniqueID.readFromFile(reader), block Element resolved
            pElementInHands = resolved
         end)
      end
   end
   
   func addToGameWorld()
      // request enterFrame() to be called once. works fine for both creating or loading
      // elemente. in case of creating new elements there are simply no request to resolve
      getGameWorld().addEnterFrameOnce(this)
   end
   
   func void enterFrame()
      // resolve all elements. once finished all request are removed. if a resolve request
      // fails the block is called with a null element. it is the responsibility of the
      // block to handle this situation.
      pElementResolver.resolve(getGameWorld())
   end
end

BehaviorsElement Behaviors

This class is also able to resolve BehaviorElement behaviors. During saving you have to store both the BehaviorElement UniqueID as well as the behavior instance index. The DefaultECBehavior class provides this information. While resolving the block is called with BehaviorInstance as parameter. In general you will change this to parameter type to match the behavior stored.

class MyElement extends Element
   var ElementResolver pElementResolver
   var MyBehavior.Instance pElementInHands
   
   func new()
      pElementResolver = ElementResolver.new()
   end
   
   func void readFromFile(FileReader reader)
      ...
      if hasElementInHands
         var UniqueID id = UniqueID.readFromFile(reader)
         var int index = reader.readUShort()
         pElementResolver.addBehavior(id, index, block MyBehavior.Instance behavior
            pElementInHands = behavior
         end)
      end
   end
   
   func addToGameWorld()
      // request enterFrame() to be called once. works fine for both creating or loading
      // elemente. in case of creating new elements there are simply no request to resolve
      getGameWorld().addEnterFrameOnce(this)
   end
   
   func void enterFrame()
      // resolve all elements. once finished all request are removed. if a resolve request
      // fails the block is called with a null element. it is the responsibility of the
      // block to handle this situation.
      pElementResolver.resolve(getGameWorld())
   end
end

Allow Failure Support (version 1.24)

Resolving can be now done optionally by using #addAllowFail() and #addBehaviorAllowFail() instead of #add() and #addBehavior(). This allows code to be resilient against resolving objects gone missing, for example due to modding or edge cases. If used the block can be called with null if resolving failed instead of throwing an exception.

Member Function Documentation

add() [1/2]

void Dragengine.Utils.ElementResolver.add	(	FileReader	reader,
		Block	ablock
	)

Add resolve request.

Same as #add(UniqueID,Block) but reads the UniqueID from file reader.

add() [2/2]

void Dragengine.Utils.ElementResolver.add	(	UniqueID	id,
		Block	ablock
	)

Add resolve request.

Add request to resolve element by identifier. Once resolved block is called with resolved element as parameter. If resolving fails ResolveException is thrown.

addAllowFail() [1/2]

void Dragengine.Utils.ElementResolver.addAllowFail	(	FileReader	reader,
		Block	ablock
	)

Add resolve request which is allowed to fail.

Version

1.24

Same as #addAllowFail(UniqueID,Block) but reads the UniqueID from file reader.

addAllowFail() [2/2]

void Dragengine.Utils.ElementResolver.addAllowFail	(	UniqueID	id,
		Block	ablock
	)

Add resolve request which is allowed to fail.

Version

1.24

Add request to resolve element by identifier. Once resolved block is called with resolved element as parameter. If resolving fails block is called with null as parameter.

addBehavior() [1/2]

void Dragengine.Utils.ElementResolver.addBehavior	(	FileReader	reader,
		Block	ablock
	)

Add resolve request for BehaviorInstance.

Same as #addBehavior(UniqueID,int,Block) but reads the parameters from file reader. Reads first a UniqueID from file reader then a UShort as behavior index.

addBehavior() [2/2]

void Dragengine.Utils.ElementResolver.addBehavior	(	UniqueID	id,
		int	behaviorInstanceIndex,
		Block	ablock
	)

Add resolve request for BehaviorInstance.

Add request to resolve element by identifier and behavior inside element by instance index. Once resolved block is called with resolved behavior instance as parameter. If resolving fails ResolveException is thrown.

addBehaviorAllowFail() [1/2]

void Dragengine.Utils.ElementResolver.addBehaviorAllowFail	(	FileReader	reader,
		Block	ablock
	)

Add resolve request for BehaviorInstance which is allowed to fail.

Version

1.24

Same as #addBehaviorAllowFail(UniqueID,int,Block) but reads the parameters from file reader. Reads first a UniqueID from file reader then a UShort as behavior index.

addBehaviorAllowFail() [2/2]

void Dragengine.Utils.ElementResolver.addBehaviorAllowFail	(	UniqueID	id,
		int	behaviorInstanceIndex,
		Block	ablock
	)

Add resolve request for BehaviorInstance which is allowed to fail.

Version

1.24

Add request to resolve element by identifier and behavior inside element by instance index. Once resolved block is called with resolved behavior instance as parameter. If resolving fails block is called with null as parameter.

getAt()

Request Dragengine.Utils.ElementResolver.getAt

(

int

index

)

Pending request at index.

new()

ElementResolver Dragengine.Utils.ElementResolver.new

(

)

Create resolver.

resolve()

void Dragengine.Utils.ElementResolver.resolve

(

GameWorld

gameWorld

)

Resolve elements.

Resolves all requests calling request blocks with the resolved element as parameter. Removes all requests after processing all of them successfully. If an element can not be resolved a ResolveException is thrown and no request is removed.

writeToFile()

static void Dragengine.Utils.ElementResolver.writeToFile ( FileWriter  writer, Element  element  )

static

Write parameters to file suitable for add(UniqueID, Block).

writeToFileBehavior()

static void Dragengine.Utils.ElementResolver.writeToFileBehavior ( FileWriter  writer, ECBehaviorInstance  behaviorInstance  )

static

Write parameters to file suitable for addBehavior(UniqueID, int, Block).

Member Data Documentation

pRequests

Array Dragengine.Utils.ElementResolver.pRequests

---

The documentation for this class was generated from the following file:

• ElementResolver.ds