{{tag>dragonscript appbehavior}}
<WRAP youarehere>
[[:start|Start Page]] >> [[main|DragonScript Scripting Language]] >> [[dragengine:modules:dragonscript:abstractions|Abstraction Layers: How you want to build your Game]] >> [[dragengine:modules:dragonscript:behavior_elements|Behavior Elements]] >> **GABehaviorStateMachine**
</WRAP>

====== GABehaviorStateMachine ======

Game app behavior running a state machine (*.desm) on the BaseGameApp. The state machine is loaded from the application configuration and runs for the whole lifetime of the application. Other game app behaviors and state machines can add actions and conditions to it to control the application flow, for example showing logos, changing input processors or quitting the engine.

The class works similar to [[behavior_statemachine|ECBehaviorStateMachine]].

The state machine is configured in the application configuration file like this example:

<code xml>
<parameterTree>
    <string path='appBehavior/stateMachine/path'>/content/statemachines/game.desm</string>
    <string path='appBehavior/stateMachine/debug'>SM-Game</string>
</parameterTree>
</code>

Multiple instances can be added to the application using an identifier. If the path is not set or the file is missing an empty state machine is used.

To access this behavior from other application behaviors use ''GABehaviorStateMachine.getBehaviorInApp()''. If more than one state machine is used use ''GABehaviorStateMachine.getBehaviorInApp(id)'' with the identifier of the desired state machine. Add actions and conditions in the ''initGame()'' function.

====== Configuration ======

The state machine is configured in the application configuration file using these keys:

===== appBehavior/stateMachine/path =====

Set path to state machine file to load.

  * Full name: ''appBehavior/stateMachine/path'' or ''appBehavior/stateMachine({id})/path''
  * Type: string
  * Default Value: empty string
  * Expected File Type: ''*.desm''
  * Example (*.deeclass) <code xml><string path='appBehavior/stateMachine/path'>/content/statemachines/game/game.desm</string></code>

===== appBehavior/stateMachine/debug =====

Enable debug logging for the state machine using the given logging name.

  * Full name: ''appBehavior/stateMachine/debug'' or ''appBehavior/stateMachine({id})/debug''
  * Type: string
  * Default Value: <null>
  * Example (*.deeclass) <code xml><string path='appBehavior/stateMachine/debug'>SM-Game</string></code>

====== Actions ======

This behavior adds these state machine actions.

===== engine.update =====

Update game engine parameters and run game engine actions.

^Parameter^Value^Description^
|resetTimers| |Reset engine timers. Calling this is useful after initial game loading to ensure next frame update starts with huge elapsed time accumulated.|
|restart|string|Restart engine with the given value. Allows to return to the same state after restart.|
|log|string|Log message to console.|
|quit| |Quit game immediately.|

This is an example of using this action to reset timers after lengthy loading:
<code xml>
<action name='engine.update'>
  <parameter name='resetTimers'/>
</action>
</code>

===== app.update =====

Update application parameters and run application actions.

^Parameter^Value^Description^
|inputProcessor|''desktop'', ''bindings'', ''none''|<WRAP>Set input processor.
  * ''desktop'': Input is processed by BaseGameApp.getDesktop(). Use this for main menus where mouse and keyboard should work like in regular applications.
  * ''bindings'': Input is processed by BindingManager. This runs game related commands bound to input devices. Use this for typical game use.
  * ''none'': Input is not processed at all. Useful to prevent user input for a short time.
</WRAP>|
|desktop.guiTheme|string|Load [[guitheme|Gui Theme]] and assign it to BaseGameApp desktop.|
|settings.save| |Save settings.|
|bindings.save| |Save bindings.|
|loadGameWorld.cancel| |Cancel loading game world.|
|loadGameWorld.finish| |Finish loading game world.|

This is an example of using this action to set input processing to bindings:
<code xml>
<action name='app.update'>
  <parameter name='inputProcessor'>bindings</parameter>
</action>
</code>

===== windowLogo.update =====

Update window logo parameters and run window logo actions. Allows to show logos as typically done on game start up. The logo window is faded in, stays a short time, then fades out again.

^Parameter^Value^Description^
|show|''dragengine'', ''image'', ''video''|Logo to show.|
|image|string|Path to image to show. Required if ''show'' is set with ''image'' as value.|
|sound|string|Path to sound/music to play. Optional if ''show'' is set.|
|video|string|Path to video to show. Required if ''show'' is set with ''video'' as value.|
|event|string|Event to run on the state machine once the logo finished (faded out). Required if ''show'' is set.|

This is an example of using this action to show an image logo:
<code xml>
<action name='windowLogo.update'>
  <parameter name='show'>image</parameter>
  <parameter name='image'>/content/logo.avif</parameter>
  <parameter name='sound'>/content/logo.ogg</parameter>
  <parameter name='event'>logo finished</parameter>
</action>
</code>

===== windowGameWorld.set =====

Set WindowGameWorld parameters.

^Parameter^Value^Description^
|visible|''true'', ''false''|Show/hide WindowGameWorld.|
|cameraDirector|''playerControlledActor''|<WRAP>Set camera directory in active world.
  * ''playerControlledActor'': Assign instance of #@LinkApiDocDEDS2_HTML~classDragengine_1_1CameraDirectors_1_1PlayerControlledActorCameraDirector.html,PlayerControlledActorCameraDirector~@#.
</WRAP>|
|cameraDirector.loadCamera|string|Load camera parameters from ''.decamera'' file.|
|cameraDirector.pivot|vector|Rotation point.|
|cameraDirector.pivot.aboveGround|float|Pivot point at desired distance above ground.|
|cameraDirector.localMatrix.position|vector|Position part of local matrix.|
|cameraDirector.localMatrix.rotation|vector|Rotation part of local matrix. Rotation is in degrees.|
|cameraDirector.azimuth|float|Vertical rotation.|
|cameraDirector.azimuth.lock|''true'', ''false''|Do to not update azimuth from locomotion changes.|
|cameraDirector.elevation|float|Horizontal rotation.|
|cameraDirector.elevation.lock|''true'', ''false''|Do not update elevation from locomotion changes.|
|cameraDirector.distance|float|Distance.|
|cameraDirector.useOrientation|''true'', ''false''|Camera rotates together with the element.|
|cameraDirector.bone|string|Name of bone to use as rotation point. Requires [[behavior_component|ECBehaviorComponent]] to be present.|

This is an example of using this action to hide the WindowGameWorld:
<code xml>
<action name='windowGameWorld.set'>
  <parameter name='visible'>false</parameter>
</action>
</code>

===== windowGameWorld.update =====

Update WindowGameWorld parameters and run WindowGameWorld actions.

^Parameter^Value^Description^
|addBehavior|string|Create game world behavior from named game world behavior factory and add it to active game world.|
|addBehavior.id|string|Identifier to use for ''addBehvior''. Default is empty string.|
|createElement|string|Create element with value named element class and add it to the active game world.|
|createElement.spawn|string|Name of spawn point to spawn element at.|
|clearWorld| |Clear the active game world if present.|
|loadWorld|string|Start loading world from ''.deworld'' file and assigns it as active world once finished successfully. See events ''windowGameWorld.loadWorld.*''.|
|loadWorld.enableNetworking|''true'', ''false''|Enable networking.|
|loadWorld.ignorePersistableElements|''true'', ''false''|Persistable elements are ignored. Set to true for loading persisted game states.|
|runEvent|string|Run event on [[gwbehavior_btsm|GWBehaviorBTSM]] in the active game world. This allows application state machine to interact with element behavior state machines inside the game world.|

This is an example of using this action:
<code xml>
<action name='windowGameWorld.update'>
  <parameter name='runEvent'>inventory closed</parameter>
</action>
</code>

====== Conditions ======

This behavior adds these state machine conditions.

===== engine.check =====

Evaluate engine parameters.

^Parameter^Value^Description^
|engine.appActive|''true'', ''false''|Application window is active.|
|engine.editMode|''true'', ''false''|Engine is in edit mode. For regular games this is ''false''.|
|engine.supportsService|string|Engine supports named service.|
|engine.supportsService.not|string|Engine does not support named service.|

This is an example of using this condition to check if a game service is supported and can be used (in this example modding using Mod.io):
<code xml>
<action name='myAction'>
  <condition>engine.check</condition>
  <parameter name='engine.supportsService'>Mod.io</parameter>
</action>
</code>

===== app.check =====

Evaluate application parameters. ''app.config.'' checks ''BaseGameApp.getConfiguration()''. ''app.setting.'' checks ''BaseGameApp.getSettings()''. Configuration and setting values can be various data types. These comparisons require boolean and integer values. Other values fail the test if their ''toString()'' implementation does not produce a value convertible to an integer value or boolean value (''true'', ''false''). If you just want to test for equality you can use string type too.

^Parameter^Value^Description^
|app.config|string|Configuration key to compare. Used together with the ''app.config.*'' comparisons.|
|app.config.equal|string|Configuration value equals value.|
|app.config.notEqual|string|Configuration value does not equal value.|
|app.config.less|integer|Configuration value is less than value. Requires int value.|
|app.config.lessOrEqual|integer|Configuration value is less than or equal to value. Requires int value.|
|app.config.greater|integer|Configuration value is greater than value. Requires int value.|
|app.config.greaterOrEqual|integer|Configuration value is greater than or equal to value. Requires int value.|
|app.setting|string|Setting key to compare. Used together with the ''app.setting.*'' comparisons.|
|app.setting.equal|string|Setting value equals value.|
|app.setting.notEqual|string|Setting value does not equal value.|
|app.setting.less|integer|Setting value is less than value. Requires int value.|
|app.setting.lessOrEqual|integer|Setting value is less than or equal to value. Requires int value.|
|app.setting.greater|integer|Setting value is greater than value. Requires int value.|
|app.setting.greaterOrEqual|integer|Setting value is greater than or equal to value. Requires int value.|
|services.initialized|''true'', ''false''|All initializing services have finished.|

This is an example of using this condition to check a string configuration value:
<code xml>
<action name='myAction'>
  <condition>app.check</condition>
  <parameter name='app.config'>game/mode</parameter>
  <parameter name='app.config.equal'>multiplayer</parameter>
</action>
</code>

This is an example of using this condition to check an integer configuration value:
<code xml>
<action name='myAction'>
  <condition>app.check</condition>
  <parameter name='app.config'>game/maxPlayers</parameter>
  <parameter name='app.config.lessOrEqual'>2</parameter>
</action>
</code>

===== windowGameWorld.check =====

Evaluate WindowGameWorld parmaeters.

^Parameter^Value^Description^
|visible|''true'', ''false''|WindowGameWorld is visible.|

This is an example of using this condition:
<code xml>
<action name='myAction'>
  <condition>windowGameWorld.check</condition>
  <parameter name='visible'>true</parameter>
</action>
</code>

====== Events ======

This behavior runs these state machine events.

===== initGame =====

Run after all game app behaviors have initialized.

===== servicesInitialized =====

Run once when all game service initialization has finished.

===== update =====

Run every frame. The event parameter is the elapsed time in seconds.

===== appActivated =====

Run when the application window has been activated.

===== appDeactivated =====

Run when the application window has been deactivated.

===== windowGameWorld.loadWorld.finished =====

Loading game world started by ''windowGameWorld.loadWorld'' has finished successfully and the loaded world is now the active world.

===== windowGameWorld.loadWorld.failed =====

Loading game world started by ''windowGameWorld.loadWorld'' has failed. The active game world has not changed.

====== Required Behaviors ======

This behavior requires no other behaviors.

====== Optional Behaviors ======

This behavior does not support optional behaviors.

====== API Documentation ======

#@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1GABehaviorStateMachine.html,GABehaviorStateMachine~@#.

Since DragonScript Module Version ''1.35''

====== Use Cases ======

  * Drive higher level application logic using state machine.
  * Drive UI interaction using state machine.

====== Live Examples ======

  * [[https://github.com/LordOfDragons/deexamples|DEExamples Repository]]