User Tools

Site Tools


dragengine:modules:dragonscript:locomotion

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
dragengine:modules:dragonscript:locomotion [2017/02/22 14:27] – [FPS Locomotion] dragonlorddragengine:modules:dragonscript:locomotion [2024/03/14 16:43] (current) dragonlord
Line 1: Line 1:
 +{{tag>dragonscript locomotion actor ai}}
 <WRAP youarehere> <WRAP youarehere>
 [[:start|Start Page]] >> [[dragengine:modules:dragonscript:main|DragonScript Scripting Language]] >> **Locomotion** [[:start|Start Page]] >> [[dragengine:modules:dragonscript:main|DragonScript Scripting Language]] >> **Locomotion**
Line 4: Line 5:
  
 ====== Locomotion ====== ====== Locomotion ======
-Locomotion defines the movement, looking, turnging and stance states of actors. The DragonScript module provides basic locomotion implementation using the [[http://dragengine.rptd.ch/docs/dragonscript/scriptapi/latest/classDragengine_1_1Scenery_1_1Locomotion.html|locomotion class]]. Three kinds of locomotion types are well supported and can be extended according to needs. For performance reasons the locomotion class is implemented as native class. It is possible to extend the behavior but requires extending the class in a specific way to work. Whenever the player or an AI routine creates input new goals are set in the locomotion. The locomotion class then updates the actual values. Internal this uses [[gamedev:smoothvalue|smooth values]] to smoothly apply changes over time. The resulting parameters can then be used to update colliders for collision testing and animator instances for calculating animation states.+Locomotion defines the movement, looking, turnging and stance states of actors. The DragonScript module provides basic locomotion implementation using the #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1Locomotion.html,locomotion class~@#. Three kinds of locomotion types are well supported and can be extended according to needs. For performance reasons the locomotion class is implemented as native class. It is possible to extend the behavior but requires extending the class in a specific way to work. Whenever the player or an AI routine creates input new goals are set in the locomotion. The locomotion class then updates the actual values. Internal this uses [[gamedev:smoothvalue|smooth values]] to smoothly apply changes over time. The resulting parameters can then be used to update colliders for collision testing and animator instances for calculating animation states.
  
 ====== Parameters ====== ====== Parameters ======
Line 64: Line 65:
 |Can turn in-place|true| |Can turn in-place|true|
  
-Drive Input Parameter Sets like this:+Drive //Input Parameter Sets// like this:
 ^Parameter-Set^Goal value^ ^Parameter-Set^Goal value^
 |Analog moving direction|Calculate //movingDirection// depending on pressed buttons (forward, backward, strafe-left, strafe-right). Parameter value is then //movingDirection// + //Look left-right//.Value. Without pressing buttons the actor moves into the direction he is looking. //movingDirection// provides strafing behavior.| |Analog moving direction|Calculate //movingDirection// depending on pressed buttons (forward, backward, strafe-left, strafe-right). Parameter value is then //movingDirection// + //Look left-right//.Value. Without pressing buttons the actor moves into the direction he is looking. //movingDirection// provides strafing behavior.|
Line 89: Line 90:
 |Turn left-right|Turning is used here to turn the body into the direction the actor is moving. Set value to Look left-right.Goal. Optionally you can set the value to 0 if the player presses no movement keys to stop the body moving.| |Turn left-right|Turning is used here to turn the body into the direction the actor is moving. Set value to Look left-right.Goal. Optionally you can set the value to 0 if the player presses no movement keys to stop the body moving.|
  
-FPS locomotion is somewhat simpler to understand and is somewhat cheaper to calculate. There are two ways to handle the animation. The first solution is to use the same setup as in the natural locomotion case. Most of the time though an 8-way animation setup is used. In this case 8 animations of walking/running are created each representing the same movement but in a different direction relative to the camera direction. 8 animations are typically chosen this this way each animation is 45 degrees rotate compared to the next animation working well with digital input from 4 direction keys (north, north-west, west, south-west, south, south-east, east, norh-east). This setup requires more animation work to be done but has the advantage that all kinds of moving directions can be blended together with good quality. As a side note this setup could be also used for the naturla locomotion case but it is a bit delicate to get working in a pleasant way. This setup can be easily build using the [[http://dragengine.rptd.ch/docs/dragonscript/scriptapi/latest/classDragengine_1_1Scenery_1_1ARGroup.html|group animator rule]] using the select mode. There the 8 animations can be added as 8 rules in the group and selecting being driven by the moving orientation.+FPS locomotion is somewhat simpler to understand and is somewhat cheaper to calculate. There are two ways to handle the animation. The first solution is to use the same setup as in the natural locomotion case. Most of the time though an 8-way animation setup is used. In this case 8 animations of walking/running are created each representing the same movement but in a different direction relative to the camera direction. 8 animations are typically chosen this this way each animation is 45 degrees rotate compared to the next animation working well with digital input from 4 direction keys (north, north-west, west, south-west, south, south-east, east, norh-east). This setup requires more animation work to be done but has the advantage that all kinds of moving directions can be blended together with good quality. As a side note this setup could be also used for the naturla locomotion case but it is a bit delicate to get working in a pleasant way. This setup can be easily build using the #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1ARGroup.html,group animator rule~@# using the select mode. There the 8 animations can be added as 8 rules in the group and selecting being driven by the moving orientation.
  
 ====== Vehicle Locomotion ====== ====== Vehicle Locomotion ======
Line 108: Line 109:
 |Analog moving direction|0 if moving forward, 180 if moving backward.| |Analog moving direction|0 if moving forward, 180 if moving backward.|
 |Turn left-right|CurrentValue +/- turnSpeed * elapsedFrameTime. Turning speed is in degrees per second. Use positive value to turn left and negative to turn right.| |Turn left-right|CurrentValue +/- turnSpeed * elapsedFrameTime. Turning speed is in degrees per second. Use positive value to turn left and negative to turn right.|
 +
 +Vehicle locomotion is the simplest locomotion type of the three and the cheapest. Disabling the turning adjustments and in-place turning is important to avoid the vehicle suddenly turning when the looking around approaches the border.
 ====== Animator and collider control ====== ====== Animator and collider control ======
-Locomotion allows to set an [[http://dragengine.rptd.ch/docs/dragonscript/scriptapi/latest/classDragengine_1_1Scenery_1_1AnimatorInstance.html|animator instance]] and mapping controllers. If set the locomotion updates the animator instance controllers with the appropriate locomotion values automatically upon updating. This is a convenience behavior of the locomotion class to improve performance since all this work is repetitive and can be done faster in C++ than inside scripts. The locomotion class documentation contains a list of supported controller mapping constants. The example below shows a typical setup.+Locomotion allows to set an #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1AnimatorInstance.html,animator instance~@# and mapping controllers. If set the locomotion updates the animator instance controllers with the appropriate locomotion values automatically upon updating. This is a convenience behavior of the locomotion class to improve performance since all this work is repetitive and can be done faster in C++ than inside scripts. The locomotion class documentation contains a list of supported controller mapping constants. The example below shows a typical setup.
  
 <code> <code>
Line 125: Line 128:
 </code> </code>
  
-====== Body tilting ====== +The table below lists the available controllers and what they are best used for: 
-Body tilting provides support to adjust animations of actors to better fit them to uneven groundBody tilting require [[http://dragengine.rptd.ch/docs/dragonscript/scriptapi/latest/classDragengine_1_1Scenery_1_1ColliderCollisionTest.html|collider collision tests]] to determine the distances required to calculate proper tilting. The testing is done after the physics simulation stepFor this reason locomotion calculation has to be split into a part before physics simulation (during Element.think) and a part after physics simulation (during Element.postThink)Locomotion can be set to do no body tilt calculation, single or weightedIn **single mode** one collision test is used usually straight under the actor. The hit normal on the ground is used to calculate the tilting on a virtual plane located under the actor with the hit normal matching the plane normal. This is fast and for many situations reasonable solutionIn **weighted mode** 4 collision tests are used each of them located near feet like if the actor is quadripedal (if not really the case)The image below shows the layout.+^Attribute^Description^ 
 +|Elapsed time|Increments controller using elapsed frame time. Use for all playback driven animations permanently playing.
 +|Look up-down|Value of //Look up-down// output parameterUse for actor looking up-down without moving body.
 +|Look left-right|Value of //Look left-right// output parameter. Use for actor looking left-right without moving body. With vehicles this could be used for example for rotating turrets.| 
 +|Moving speed|Value of //Moving speed// output parameter. Use to blend between different movement animations like walking and running. The value can not be used for blending between moving forward and backward since moving speed is always positive.| 
 +|Moving direction|Value of //Moving direction// output parameter. Use for actors using FPS type locomotion to blend between 4-way or 8-way movement animations. The most simple solution is using a //Group Animator Rule// set to the //Select// type and placing 8 //Animation Rule// inside one for each directionThe first animation has to be backwards with the following animations rotating clock-wiseThe group then properly blends between them with no extra work.
 +|Relative moving speed|Value of //Moving speed// output parameter using the value of //Moving direction// to produce negative values if moving backwardsUse for actors using natural type locomotion to blend between different movement animations including forward/backward variationsBuilding such an animator is more complex but yields good results.| 
 +|Turning speed|Value of //Turning speed// output parameter. Use to blend with animations of the actor turning left or right. Turning speed is positive for turning left and negative for turning right.| 
 +|Stance|Value of //Stance// output parameter. Use to blend between different stances of an actor. The meaning of the value is up to the script user. Only requirement is that values are between 0 and 1.| 
 +|Displacement|Value of //Moving speed// output parameter multiplied by the elapsed time. Use for movement animations to match the playback to the actual distance travelled. For this to work set the animator controller upper limit to the two times the stride length of the actor (if you use an animation with one walk cycle). The actor will then always move with the correct speed avoid feet sliding. This attribute works best for vehicle type locomotion for example tanks.
 +|Time turn in-place|Value of //Turn in-place// output parameter. Use for animation of actor turning without moving. The attribute starts playing back similar to //Elapsed time// if the actor starts turning in place and stops once finished.| 
 +|Tilt offset|Value of //Tilt offset// output parameter. Use to offset actor root bone downwards due to tilting. The value is the required offset in metersUsing this attribute moves actors on titled surfaces into a favorable position for inverse kinematic rules.| 
 +|Tilt up-down|Value of //Tilt up-down// output parameter. Use to blend with animation of actor in tilted position. Value is degrees of tilting. Positive values represent ground falling down to the left and negative falling down to the right.
 +|Tilt left-right|Value of //Tilt left-right// output parameter. Use to blend with animation of actor in tilted position. Value is degrees of tilting. Positive values represent ground falling down to the front and negative falling down to the back.|
  
-<WRAP center box 350px>+====== Body tilting ====== 
 +<WRAP box right :en 350px>
 {{ :dragengine:modules:dragonscript:locomotion_tilt_weighted.png |Weighted body tile testing locations}} {{ :dragengine:modules:dragonscript:locomotion_tilt_weighted.png |Weighted body tile testing locations}}
 <WRAP centeralign>Weighted body tile testing locations.</WRAP> <WRAP centeralign>Weighted body tile testing locations.</WRAP>
 </WRAP> </WRAP>
 +Body tilting provides support to adjust animations of actors to better fit them to uneven ground. Body tilting require #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1ColliderCollisionTest.html,collider collision tests~@# to determine the distances required to calculate proper tilting. The testing is done after the physics simulation step. For this reason locomotion calculation has to be split into a part before physics simulation (during Element.think) and a part after physics simulation (during Element.postThink). Locomotion can be set to do no body tilt calculation, single or weighted. In **single mode** one collision test is used usually straight under the actor. The hit normal on the ground is used to calculate the tilting on a virtual plane located under the actor with the hit normal matching the plane normal. This is fast and for many situations reasonable solution. In **weighted mode** 4 collision tests are used each of them located near feet like if the actor is quadripedal (if not really the case). The image below shows the layout.
  
 The results are weighted to get a best matching virtual ground plane. This mode is most expensive but the results are more stable and of higher quality. Once done the tilt result can be applied to animator instance controlls as any other locomotion state. The results are weighted to get a best matching virtual ground plane. This mode is most expensive but the results are more stable and of higher quality. Once done the tilt result can be applied to animator instance controlls as any other locomotion state.
  
 <code> <code>
-// set up locomotion body tilt for an actor using the weighted method +func void init() 
-locomotion.setTiltMode( Locomotion.TILT_WEIGHTED ) +  // set up locomotion body tilt for an actor using the weighted method 
- +  locomotion.setTiltMode( Locomotion.TILT_WEIGHTED ) 
-// create collision filter shared by all tests +   
-var LayerMask category = LayerMask.new() +  // create collision filter shared by all tests 
-category.setBit( GameState.CL_AI )      // we are an collider for doing actor ai +  var LayerMask category = LayerMask.new() 
- +  category.setBit( GameState.CL_AI )      // we are an collider for doing actor ai 
-var LayerMask filter = LayerMask.new() +   
-filter.setBit( GameState.CL_GEOMETRY )  // we can hit geometry like the ground +  var LayerMask filter = LayerMask.new() 
-filter.setBit( GameState.CL_AI )        // we can hit other actor ai colliders +  filter.setBit( GameState.CL_GEOMETRY )  // we can hit geometry like the ground 
- +  filter.setBit( GameState.CL_AI )        // we can hit other actor ai colliders 
-var CollisionFilter collisionFilter = CollisionFilter.new( category, filter ) +   
- +  var CollisionFilter collisionFilter = CollisionFilter.new( category, filter ) 
-// set collision test. the test points are located above the ground since otherwise tilting up can not +   
-// be detected. as a rule of thumb the test distance should be two times the start height. for each +  // set collision test. the test points are located above the ground since otherwise tilting up can not 
-// test a ray test is used. this is the fastest solution and works well for most situations. +  // be detected. as a rule of thumb the test distance should be two times the start height. for each 
-var float offset = 0.5                  // height above ground to start testing +  // test a ray test is used. this is the fastest solution and works well for most situations. 
-var Vector testDistance = Vector.new( 0.0, -offset * 2.0, 0.0 )          // distance to test downwards +  var float offset = 0.5                  // height above ground to start testing 
- +  var Vector testDistance = Vector.new( 0.0, -offset * 2.0, 0.0 )          // distance to test downwards 
-locomotion.setCCTTiltFrontLeft( ColliderCollisionTest.new( touchSensor, touchSensorShape,+   
- collisionFilter, Vector.new( -0.2, offset, 0.2 ), testDistance ) ) +  locomotion.setCCTTiltFrontLeft( ColliderCollisionTest.new( touchSensor, touchSensorShape,
- +    collisionFilter, Vector.new( -0.2, offset, 0.2 ), testDistance ) ) 
-locomotion.setCCTTiltFrontRight( ColliderCollisionTest.new( touchSensor, touchSensorShape,+  locomotion.setCCTTiltFrontRight( ColliderCollisionTest.new( touchSensor, touchSensorShape,
- collisionFilter, Vector.new( 0.2, offset, 0.2 ), testDistance ) ) +    collisionFilter, Vector.new( 0.2, offset, 0.2 ), testDistance ) ) 
- +  locomotion.setCCTTiltBackLeft( ColliderCollisionTest.new( touchSensor, touchSensorShape,
-locomotion.setCCTTiltBackLeft( ColliderCollisionTest.new( touchSensor, touchSensorShape,+    collisionFilter, Vector.new( -0.2, offset, -0.2 ), testDistance ) ) 
- collisionFilter, Vector.new( -0.2, offset, -0.2 ), testDistance ) ) +  locomotion.setCCTTiltBackRight( ColliderCollisionTest.new( touchSensor, touchSensorShape,
- +    collisionFilter, Vector.new( 0.2, offset, -0.2 ), testDistance ) ) 
-locomotion.setCCTTiltBackRight( ColliderCollisionTest.new( touchSensor, touchSensorShape,+   
- collisionFilter, Vector.new( 0.2, offset, -0.2 ), testDistance ) ) +  // add mappings so our animator uses the calculated values 
- +  locomotion.addControllerMaping( controllerTiltOffset, Locomotion.ATTR_TILT_OFFSET ) 
-// add mappings so our animator uses the calculated values +  locomotion.addControllerMaping( controllerTiltUpDown, Locomotion.ATTR_TILT_UP_DOWN ) 
-locomotion.addControllerMaping( controllerTiltOffset, Locomotion.ATTR_TILT_OFFSET ) +  locomotion.addControllerMaping( controllerTiltLeftRight, Locomotion.ATTR_TILT_RIGHT_LEFT ) 
-locomotion.addControllerMaping( controllerTiltUpDown, Locomotion.ATTR_TILT_UP_DOWN ) +end
-locomotion.addControllerMaping( controllerTiltLeftRight, Locomotion.ATTR_TILT_RIGHT_LEFT )+
  
 // tilt is enabled so during Element.postThink the tilt is updated automatically and the result // tilt is enabled so during Element.postThink the tilt is updated automatically and the result
 // applied to animator instance controllers // applied to animator instance controllers
-locomotion.updatePostLocomotion( elapsed )+func void postThink( float elapsedFrameTime ) 
 +  locomotion.updatePostLocomotion( elapsedFrameTime ) 
 +end
 </code> </code>
  
 ====== State control and frame update ====== ====== State control and frame update ======
-To update the locomomotion multiple calls are used. After the player has provided input the [[http://dragengine.rptd.ch/docs/dragonscript/scriptapi/latest/classDragengine_1_1Scenery_1_1Locomotion.html#ac5190fabffbd9da821ab224e142d2766|updateLooking()]] method can be used to smooth the input and to update the goal values used by the locomotion calculation step. Once the input is updated the locomotion can be calculated using [[http://dragengine.rptd.ch/docs/dragonscript/scriptapi/latest/classDragengine_1_1Scenery_1_1Locomotion.html#a74bdb2d85b3a3b2b92898011d8a1c2f4|updateLocomotion()]] method. This calculates all the needed locomotion states using native code. This call is used during Element.think(). After the physics simulation is done the [[http://dragengine.rptd.ch/docs/dragonscript/scriptapi/latest/classDragengine_1_1Scenery_1_1Locomotion.html#a86f426d718f0a534c745258bdc99e533|updatePostLocomotion]] method can be called to calculate body tilting and potential other calculations requiring physics test results. Afterward the animation instance has to be updated if not assigned to be done by the locomotion instance directly.+To update the locomomotion multiple calls are used. After the player has provided input the #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1Locomotion.html#ac5190fabffbd9da821ab224e142d2766,updateLooking()~@# method can be used to smooth the input and to update the goal values used by the locomotion calculation step. Once the input is updated the locomotion can be calculated using #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1Locomotion.html#a74bdb2d85b3a3b2b92898011d8a1c2f4,updateLocomotion()~@# method. This calculates all the needed locomotion states using native code. This call is used during Element.think(). After the physics simulation is done the #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1Locomotion.html#a86f426d718f0a534c745258bdc99e533,updatePostLocomotion~@# method can be called to calculate body tilting and potential other calculations requiring physics test results. Afterward the animation instance has to be updated if not assigned to be done by the locomotion instance directly.
  
 If you want to enhance the locomotion class you have to be careful about the calling structure. The native classes methods call themselves internally for performance reasons. The entire late binding is skipped. Overwriting the update calls has no effect in this case. To partially change behavior you have to implement the updateLocomotion() and updatePostLocomotion() calls yourself and call the native methods from the script. This allows to inject your changes in the right place. This all works since it is no problem to call a method from script if it is a native class but the native class. If you want to enhance the locomotion class you have to be careful about the calling structure. The native classes methods call themselves internally for performance reasons. The entire late binding is skipped. Overwriting the update calls has no effect in this case. To partially change behavior you have to implement the updateLocomotion() and updatePostLocomotion() calls yourself and call the native methods from the script. This allows to inject your changes in the right place. This all works since it is no problem to call a method from script if it is a native class but the native class.
  
 ====== Player Input Tracker ====== ====== Player Input Tracker ======
-To help with managing the player input for use with locomotions the DragonScript module provides a helper class [[http://dragengine.rptd.ch/docs/dragonscript/scriptapi/latest/classDragengine_1_1Utils_1_1PlayerInputTracker.html|PlayerInputTracker]]. This class is not mandatory but reduces implementation needs. The player input tracks what inputs the player has provided so far and calculates the goal locomotion changes my smoothing the changes over time using [[gamedev:smoothvalue|smooth values]]. Tracks digital input (pressing buttons like forward or strafing) as well as analog input (mouse, joystick axes). Call updateLocomotion() to smooth the input values and setting the appropriate goal values in a locomotion instance.+To help with managing the player input for use with locomotions the DragonScript module provides a helper class #@LinkApiDocDEDS2_HTML~classDragengine_1_1Utils_1_1PlayerInputTracker.html,PlayerInputTracker~@#. This class is not mandatory but reduces implementation needs. The player input tracks what inputs the player has provided so far and calculates the goal locomotion changes my smoothing the changes over time using [[gamedev:smoothvalue|smooth values]]. Tracks digital input (pressing buttons like forward or strafing) as well as analog input (mouse, joystick axes). Call updateLocomotion() to smooth the input values and setting the appropriate goal values in a locomotion instance.
  
 +The //Player Input Tracker// supports all three mentioned locomotion types and has similar //Switches// like the locomotion class to disable individual calculations. The most simple use is like this:
 +<code>
 +// create an input tracker and set parameters
 +func void init()
 +  tracker.setSpeedLookLeftRight( 45.0 ) // degrees per second
 +  tracker.setSpeedLookUpDown( 45.0 ) // degrees per second
 +  tracker.setSpeedTurnLeftRight( 30.0 ) // degrees per second. for vehicle type locomotion
 +  tracker.setCanTurn( true ) // player turning commands are used
 +  tracker.setCanMove( true ) // player movement commands are used
 +  tracker.setCanChangeStance( true ) // player stance change commands are used
 +  tracker.setSpeedWalk( 3.0 ) // meters per second. you can set backward speed individually
 +  tracker.setSpeedRun( 8.0 ) // meters per second. you can set backward speed individually
 +end
 +
 +// in reaction to player input commands alter state
 +func void playerPressForward()
 +  tracker.setMoveForward( true ) // button press (true), button release (false).
 +end
 +
 +func void playerMoveMouse( Point mouseMovement )
 +  // mouse movement during this frame update for natural and fps locomotion
 +  tracker.setAnalogLookLeftRight( mouseMovement.getX() )
 +  tracker.setAnalogLookUpDown mouseMovement.getY() )
 +end
 +
 +func void playerPressTurnVehicle()
 +  tracker.setTurnLeft( true ) // turning for vehicle type locomotion
 +end
 +
 +// then during each Element.think() call let the tracker update the locomotion
 +func void think( float elapsedFrameTime )
 +  tracker.updateLocomotion( locomotion, elapsedFrameTime )
 +end
 +</code>
dragengine/modules/dragonscript/locomotion.1487773678.txt.gz · Last modified: 2017/02/22 14:27 (external edit)