Load game worlds using a loading screen. More...

Inheritance diagram for Dragengine.Utils.GameWorldLoader:

Public Member Functions
void	cancelLoading ()
	Cancel loading. More...

void	dispose ()
	Dispose of game world loader to break reference loops. More...

Console	getConsole ()
	Console console. More...

DebugVerifyStubProperties	getDebugVerifyStubProperties ()
	Debug verify stub properties while loading or null if not used. More...

DecalBuilder	getDecalBuilder ()
	Decal builder used for world decals. More...

ElementClassList	getElementClassList ()
	Element classes list. More...

bool	getEnableNetworking ()
	Enable networking. More...

MutableID	getIDGenerator ()
	ID Generator or null. More...

bool	getIgnorePersistableElements ()
	Ignore persistable elements. More...

Loaders	getLoaders ()
	Loaders. More...

String	getPathWorld ()
	World file path. More...

PersistencyEnvironment	getPersistencyEnvironment ()
	Persistency environment or null. More...

FileReader	getPersistencyReader ()
	Persistency reader or null. More...

PreloadManager	getPreloadManager ()
	Preload manager. More...

StubGameWorld	getStubWorld ()
	Game world stub. More...

WindowLoading	getWindowLoading ()
	Loading window window. More...

GameWorldLoader	new ()
	Create game world loader using BaseGameApp parameters. More...

GameWorldLoader	new (Console console, Loaders loaders, ElementClassList elementClassList)
	Create game world loader. More...

GameWorldLoader	new (Console console, Loaders loaders, ElementClassList elementClassList, MutableID idGenerator)
	Create game world loader. More...

void	onLoadWorldFailed ()
	Loading world failed. More...

void	onLoadWorldFinished ()
	Loading world finished. More...

void	setDebugVerifyStubProperties (DebugVerifyStubProperties debug)
	Set debug verify stub properties while loading or null if not used. More...

void	setDecalBuilder (DecalBuilder decalBuilder)
	Set decal builder used for world decals. More...

void	setEnableNetworking (bool enable)
	Set if networking is enabled. More...

void	setIgnorePersistableElements (bool ignorePersistableElements)
	Set if persistable elements are ignored. More...

void	setPathWorld (String path)
	Set world file path. More...

void	setPersistency (PersistencyEnvironment environment, FileReader reader)
	Set persistency environment and reader. More...

void	setWindowLoading (WindowLoading window)
	Set loading window. More...

void	startLoading ()
	Start loading game world. More...

void	updateLoading ()
	Update loading. More...

Protected Member Functions
void	cleanUp ()
	Cleaning up. More...

void	createContentFromStub ()
	Create world content from stubs. More...

GameWorld	createGameWorld ()
	Create GameWorld instance. More...

void	createLoadingWindow ()
	Create loading window. More...

bool	getCleanUpStubWorld ()
	Clean up world stub. More...

void	loadWorld ()
	Load world. More...

void	persistencyCreateContentFromStub ()
	Create world content from stubs using persistency. More...

void	persistencyReadWorld ()
	Read world from persistency reader. More...

void	preloadResources ()
	Preload resources. More...

bool	reportPreloadProblems ()
	Log preloading problems. More...

void	setCleanUpStubWorld (bool cleanUpStubWorld)
	Set clean up world stub. More...

void	setStubWorld (StubGameWorld stub)
	Set game world stub. More...

void	startFrameUpdater ()
	Start frame updater if not started. More...

void	stopFrameUpdater ()
	Stop frame updater if running. More...

void	worldStoreNextIDAndRemapEntry ()
	Set world next object ID and add ID Remapper entry if required. More...

Detailed Description

Load game worlds using a loading screen.

Helps loading game worlds without doing all the heavy lifting yourself.

The loading process starts by calling createLoadingWindow(). The default implementation creates a WindowLoading, shows it on the BaseGameApp desktop and sets an input processor forwarding input to the the desktop. If you are not using BaseGameApp reimplement the method to fit your needs.

Then the world file is loaded using LoadWorld into a StubGameWorld. Subclasses can modify the stubs if required by overwriting loadWorld() and modifying the stub after super call.

Then all element classes from a list of element classes are preloaded. Element class properties are responsible to preload resources only once. Optionally only element classes used by element stubs can be preloaded. Depending on he game structure this can be faster. By default all element classes are loaded.

After all resources to preload have been determined the loadGameWorld() metho returns. This class updates every frame update to show preloading progress in the loading window.

Once all resources are preloaded onLoadWorldFinished() will be called. Before this method is called all preloading problems are reported using reportPreloadProblems(). Preload problems are not considered errors. Exceptions thrown during preloading are logged and preloading continues to not break preload tracking of element classes. If any exceptions have been thrown onLoadWorldFailed() will be called instead.

Afterwards onPreloadingFinished() is called the loading window will be closed. Subclass is only responsible to properly set up the game window and to take over input control.

For creating world decals a DecalBuilder is required. The class creates a DecalBuilder by default and sets the CollisionFilter to have bit 0 enabled. Subclass has to change this to fit their use case. A typical solution is to designate a bit to decals projecting so you can choose for all elements if they can receive a decal or not. The decal build requires an ElementVisitor to actually create decals. This is required since the DecalBuilder visits the world along the projection box with this visitor. The default AddDecalVisitor set visits only SimpleElement instances. Subclass can set an own AddDecalVisitor subclass to add decal creation support to other element classes.

This class is designed as single use with new instances created for each loading process. Only one GameWorldLoader should be active at once. If you need to run multiple instances in parallel you have to carefully manage the loading windows (for example use hidden ones).

Version 1.8

Added default handling for loading world using persistency. This requires two additional parameters to be set.

The setIDGenerator(MutableID) sets the ID Generator to use. This initializes the GameWorld with the next object ID while loading and adds an ID Remapper entry to assign world objects unique IDs starting with the next free ID.

The setPersistency(PersistencyEnvironment,FileReader) sets the persistency to load from. If set loading is slightly different loading the world content and restoring persisted states. Use this to load save states.

Member Function Documentation

◆ cancelLoading()

void Dragengine.Utils.GameWorldLoader.cancelLoading ( )

Cancel loading.

Call this after loadGameWorld() returned successfully to cancel the loading. Calls onLoadWorldFailed().

Note: This method can be called multiple times.

◆ cleanUp()

void Dragengine.Utils.GameWorldLoader.cleanUp ( )

protected

Cleaning up.

Note: This method can be called multiple times.

◆ createContentFromStub()

void Dragengine.Utils.GameWorldLoader.createContentFromStub ( )

protected

Create world content from stubs.

If persistency environment and reader are not null calls persistencyCreateContentFromStub().

Otherwise calls verifyPreloading(), createAndAddElements() and createWorldDecals() on the world stub.

Note: If DebugVerifyStubProperties is set verifies stub elements before creating them.

◆ createGameWorld()

GameWorld Dragengine.Utils.GameWorldLoader.createGameWorld ( )

protected

Create GameWorld instance.

Default implementation creates instance of GameWorld. Overwrite in subclass to create instance of your own class if used.

◆ createLoadingWindow()

void Dragengine.Utils.GameWorldLoader.createLoadingWindow ( )

protected

Create loading window.

◆ dispose()

void Dragengine.Utils.GameWorldLoader.dispose ( )

Dispose of game world loader to break reference loops.

Reimplemented in Dragengine.Gui.WindowGameWorld.Loader.

◆ getCleanUpStubWorld()

bool Dragengine.Utils.GameWorldLoader.getCleanUpStubWorld ( )

protected

Clean up world stub.

◆ getConsole()

Console Dragengine.Utils.GameWorldLoader.getConsole ( )

Console console.

◆ getDebugVerifyStubProperties()

DebugVerifyStubProperties Dragengine.Utils.GameWorldLoader.getDebugVerifyStubProperties ( )

Debug verify stub properties while loading or null if not used.

◆ getDecalBuilder()

DecalBuilder Dragengine.Utils.GameWorldLoader.getDecalBuilder ( )

Decal builder used for world decals.

◆ getElementClassList()

ElementClassList Dragengine.Utils.GameWorldLoader.getElementClassList ( )

Element classes list.

◆ getEnableNetworking()

bool Dragengine.Utils.GameWorldLoader.getEnableNetworking ( )

Enable networking.

◆ getIDGenerator()

MutableID Dragengine.Utils.GameWorldLoader.getIDGenerator ( )

ID Generator or null.

Version: 1.8

◆ getIgnorePersistableElements()

bool Dragengine.Utils.GameWorldLoader.getIgnorePersistableElements ( )

Ignore persistable elements.

◆ getLoaders()

Loaders Dragengine.Utils.GameWorldLoader.getLoaders ( )

Loaders.

◆ getPathWorld()

String Dragengine.Utils.GameWorldLoader.getPathWorld ( )

World file path.

◆ getPersistencyEnvironment()

PersistencyEnvironment Dragengine.Utils.GameWorldLoader.getPersistencyEnvironment ( )

Persistency environment or null.

Version: 1.8

◆ getPersistencyReader()

FileReader Dragengine.Utils.GameWorldLoader.getPersistencyReader ( )

Persistency reader or null.

Version: 1.8

◆ getPreloadManager()

PreloadManager Dragengine.Utils.GameWorldLoader.getPreloadManager ( )

Preload manager.

◆ getStubWorld()

StubGameWorld Dragengine.Utils.GameWorldLoader.getStubWorld ( )

Game world stub.

◆ getWindowLoading()

WindowLoading Dragengine.Utils.GameWorldLoader.getWindowLoading ( )

Loading window window.

◆ loadWorld()

void Dragengine.Utils.GameWorldLoader.loadWorld ( )

protected

Load world.

◆ new() [1/3]

GameWorldLoader Dragengine.Utils.GameWorldLoader.new ( )

Create game world loader using BaseGameApp parameters.

Creates a DecalBuilder and an AddDecalVisitor.

◆ new() [2/3]

GameWorldLoader Dragengine.Utils.GameWorldLoader.new	(	Console	console,
		Loaders	loaders,
		ElementClassList	elementClassList
	)

Create game world loader.

Creates a DecalBuilder and an AddDecalVisitor.

◆ new() [3/3]

GameWorldLoader Dragengine.Utils.GameWorldLoader.new	(	Console	console,
		Loaders	loaders,
		ElementClassList	elementClassList,
		MutableID	idGenerator
	)

Create game world loader.

Version: 1.8

Creates a DecalBuilder and an AddDecalVisitor.

◆ onLoadWorldFailed()

void Dragengine.Utils.GameWorldLoader.onLoadWorldFailed ( )

Loading world failed.

Game loader has been cleaned up before calling this method. It is safe to dispose() of the game loader upon entering this method.

Subclasses of BaseGameApp should call

BaseGameApp.getApp().cancelLoadGameWorld()

at the end of the implementation.

Note: This method can be called multiple times.

Reimplemented in Dragengine.Gui.WindowGameWorld.Loader.

◆ onLoadWorldFinished()

void Dragengine.Utils.GameWorldLoader.onLoadWorldFinished ( )

Loading world finished.

Game loader has been cleaned up before calling this method. For this reason the result of loading is provided as parameters. It is safe to dispose() of the game loader upon entering this method.

Subclasses of BaseGameApp should call

BaseGameApp.getApp().finishLoadGameWorld()

at the end of the implementation.

Reimplemented in Dragengine.Gui.WindowGameWorld.Loader.

◆ persistencyCreateContentFromStub()

void Dragengine.Utils.GameWorldLoader.persistencyCreateContentFromStub ( )

protected

Create world content from stubs using persistency.

Version: 1.8

Calls verifyPreloading(), createAndAddNonPersistableElements(), createAndAddPersistableElements(), loadAndAddPersistableElements and createWorldDecals() on the world stub.

Called by createContentFromStub() if persistency environment and reader is not null.

Note: If DebugVerifyStubProperties is set verifies stub elements before creating them.

Exceptions

EInvalidAction persistency environment or reader is null.

◆ persistencyReadWorld()

void Dragengine.Utils.GameWorldLoader.persistencyReadWorld ( )

protected

Read world from persistency reader.

Version: 1.8

Does nothing if persistency environment, reader or ID Generator is null.

Called by loadWorld().

◆ preloadResources()

void Dragengine.Utils.GameWorldLoader.preloadResources ( )

protected

Preload resources.

Preloads resources from all elements classes.

◆ reportPreloadProblems()

bool Dragengine.Utils.GameWorldLoader.reportPreloadProblems ( )

protected

Log preloading problems.

Returns: True if problems are present.

◆ setCleanUpStubWorld()

void Dragengine.Utils.GameWorldLoader.setCleanUpStubWorld ( bool cleanUpStubWorld )

protected

Set clean up world stub.

◆ setDebugVerifyStubProperties()

void Dragengine.Utils.GameWorldLoader.setDebugVerifyStubProperties ( DebugVerifyStubProperties debug )

Set debug verify stub properties while loading or null if not used.

◆ setDecalBuilder()

void Dragengine.Utils.GameWorldLoader.setDecalBuilder ( DecalBuilder decalBuilder )

Set decal builder used for world decals.

The old decal builder is disposed of if present.

◆ setEnableNetworking()

void Dragengine.Utils.GameWorldLoader.setEnableNetworking ( bool enable )

Set if networking is enabled.

◆ setIgnorePersistableElements()

void Dragengine.Utils.GameWorldLoader.setIgnorePersistableElements ( bool ignorePersistableElements )

Set if persistable elements are ignored.

◆ setPathWorld()

void Dragengine.Utils.GameWorldLoader.setPathWorld ( String path )

Set world file path.

◆ setPersistency()

void Dragengine.Utils.GameWorldLoader.setPersistency	(	PersistencyEnvironment	environment,
		FileReader	reader
	)

Set persistency environment and reader.

Version: 1.8

Set both to non-null to enable loading game world using persisted state.

Exceptions

EInvalidParam environment or reader is null but not both.

◆ setStubWorld()

void Dragengine.Utils.GameWorldLoader.setStubWorld ( StubGameWorld stub )

protected

Set game world stub.

◆ setWindowLoading()

void Dragengine.Utils.GameWorldLoader.setWindowLoading ( WindowLoading window )

Set loading window.

◆ startFrameUpdater()

void Dragengine.Utils.GameWorldLoader.startFrameUpdater ( )

protected

Start frame updater if not started.

◆ startLoading()

void Dragengine.Utils.GameWorldLoader.startLoading ( )

Start loading game world.

Set up all required parameters before calling this method, in particular setPathWorld().

◆ stopFrameUpdater()

void Dragengine.Utils.GameWorldLoader.stopFrameUpdater ( )

protected

Stop frame updater if running.

◆ updateLoading()

void Dragengine.Utils.GameWorldLoader.updateLoading ( )

Update loading.

For use by FrameUpdater.

◆ worldStoreNextIDAndRemapEntry()

void Dragengine.Utils.GameWorldLoader.worldStoreNextIDAndRemapEntry ( )

protected

Set world next object ID and add ID Remapper entry if required.

Version: 1.8

Set world next object ID is always done.

The ID mapper and ID generator is only adjusted if persistency environment and reader are null. If persistency is present the read and updated during readElementStubsFromFile() call later on. Make sure ID Generator has been read from persisted state before this function is called.

Remapper entry is added if the ID generator next ID is larger than 1. The ID Generator is always incremented by the last used object ID (next object ID - 1).

If ID Generator or persistency is null only sets the next object ID.

Called by loadWorld().

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

GameWorldLoader.ds

Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation

◆ cancelLoading()

◆ cleanUp()

◆ createContentFromStub()

◆ createGameWorld()

◆ createLoadingWindow()

◆ dispose()

◆ getCleanUpStubWorld()

◆ getConsole()

◆ getDebugVerifyStubProperties()

◆ getDecalBuilder()

◆ getElementClassList()

◆ getEnableNetworking()

◆ getIDGenerator()

◆ getIgnorePersistableElements()

◆ getLoaders()

◆ getPathWorld()

◆ getPersistencyEnvironment()

◆ getPersistencyReader()

◆ getPreloadManager()

◆ getStubWorld()

◆ getWindowLoading()

◆ loadWorld()

◆ new() [1/3]

◆ new() [2/3]

◆ new() [3/3]

◆ onLoadWorldFailed()

◆ onLoadWorldFinished()

◆ persistencyCreateContentFromStub()

◆ persistencyReadWorld()

◆ preloadResources()

◆ reportPreloadProblems()

◆ setCleanUpStubWorld()

◆ setDebugVerifyStubProperties()

◆ setDecalBuilder()

◆ setEnableNetworking()

◆ setIgnorePersistableElements()

◆ setPathWorld()

◆ setPersistency()

◆ setStubWorld()

◆ setWindowLoading()

◆ startFrameUpdater()

◆ startLoading()

◆ stopFrameUpdater()

◆ updateLoading()

◆ worldStoreNextIDAndRemapEntry()