Drag[en]gine Script Module DragonScript  1.23
Dragengine.Utils.GameWorldLoader Class Reference

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

Inheritance diagram for Dragengine.Utils.GameWorldLoader:
Dragengine.Gui.WindowGameWorld.Loader

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
EInvalidActionpersistency 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
EInvalidParamenvironment 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: