Differences

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

--- 1.2.0:charactercontrolling [2024/01/23 09:02] – created - external edit 127.0.0.1
+++ 1.2.0:charactercontrolling [2024/01/29 13:39] (current) – admin
@@ Line 75: / Line 75: @@
 __**Remark:**__ All available input codes are defined in **Gorilla.Controller.Input.Consts.pas**.
-==== User-Friendly Events  ====
-For individual treatment you can disable or overwrite those predefined hotkeys.
+==== Modification  ====
-The basic character controller component catches all input events, handles them and throws back user-friendly events.
-^Event ^Description^
+=== Axis Movement  ===
-|OnIdle |OnIdle event getting raised when first person controller switches to idle mode.|
-|OnMove |OnMove event getting raised in doOnMoveForward, doOnMoveBackward, doOnMoveLeft, doOnMoveRight and DoOnGamePadThumbstickPos methods, used by keyboard hotkeys and gamepad thumbstick movement.|
-|OnRotate |OnRotate event getting raised if the view was rotated by DoOnGamePadThumbstickPos or DoOnMouseMove.|
-|OnBoost |OnBoost event getting raised when boost mode was activated or deactivated.|
-|OnCrouch | OnCrouch event getting raised when crouching was activated or deactivated.|
-|OnCrawl|OnCrawl event getting raised when crawling was activated or deactivated.|
-|OnJump|OnJump event getting raised when first person controller is jumping.|
-|OnAim |OnAim event getting raised when aiming mode was activated or deactivated.|
-|OnPush |OnPush event getting raised when pushing mode was activated or deactivated.|
-|OnPull |OnPull event getting raised when pulling mode was activated or deactivated.|
-|OnCustomAction |OnCustomAction event getting raised by keyboard custom action hotkeys and gamepad buttons.|
-|OnClick |OnClick event getting raised by clicking left, middle or right mouse button.|
-|OnStart |OnStart event getting raised when start hotkey was activated.|
-|OnMode |OnMode event getting raised when mode hotkey was activated.|
-|OnBack |OnBack event getting raised when back hotkey was activated.|
-|OnNavigate |OnNavigate event getting raised when menu navigation was triggered.|
-|OnHotKey |OnHotKey event getting raised when a registered hotkey was triggered. It's a central callback event for all hotkeys. Parallel to it hotkey specific events will be raised: OnIdle, OnMove, OnBoost, OnCrouch, OnJump, OnCustomAction, OnClick, OnStart, OnMode, OnBack and OnNavigate|
-|OnTriggerPoint |If a TGorillaTriggerPointManager component was linked to the first person controller, a trigger-point check will automatically be performed on movement. If then a trigger-point is in reach, the OnTriggerPoint event will be raised.|
-==== Movement  ====
+The default character controllers only move along the X and Z axis.
-Because movement is not always equal in every game, we implemented some easy-to-use property to control it.
+You can enable or disable axis movement by the lock properties:
 ^Property ^Description ^
@@ Line 108: / Line 88: @@
 |LockYAxis |Lock or unlock Y-axis for movement. Enable this property if you don't want the character to force movement on y direction.|
 |LockZAxis |Lock or unlock Z-axis for movement. Enable this property if you don't want the character to force movement on Z direction.|
-|MoveSideways |Activate or deactive to move character sideways on move-left/right hotkeys. If this mode is deactivated, the character will rotate on move-left/right hotkey instead.|
+Even if we unlock it, up and down movement along the y-axis is still not possible by default.
+There's no interaction with the underlying area.
+You can implement that yourself by OnMove and OnRotate event
+=== Speed  ===
+In case movement or rotation speed does not suit your needs.
+You can of course modify those values, too.
+^Property ^Description ^
+|Speed |Get or set speed of movement. A basis speed value applied to direction vector. Default value is 1.0.|
+|RunningSpeedBoost|Boost factor on speed if state is fpBoost. Values between 1-1000 are allowed. Default value is 2.0.|
+|MouseControllerSpeed|Get or set mouse speed. The value controls camera rotation speed. Default value is 0.075.|
+|GamePadThumbstickSpeed|Get or set gamepad controller thumbstick speed for movement and rotation speed. Default value is 0.5.|
+|CrawlingSpeedReduction|Factor of reduction on speed if state is fpCrawling. Values between 0.0 - 1.0 are allowed. Default value is 0.15.|
+|CrouchingSpeedReduction|Factor of reduction on speed if state is fpCrouching. Values between 0.0 - 1.0 are allowed. Default value is 0.15.|
+=== Rotation Sideways  ===
+By default we rotate the controller by moving the mouse to left or right.
+This will implicitly rotates the camera view too.
+You can disable this behaviour by setting the "RotateOnSideways" property to true.
+And as best practice it is recommended to also deactivate the "MoveSideways" property.
+Moving the camera up and down by mouse move will still be possible.
+^Property ^Description ^
+|RotateOnSideways|The left and right movement will be used to rotate the camera left to right, instead of strifing the character to the side.|
+|SidewayRotationSpeed|Get or set speed of sideway rotation. A basis speed value applied to direction vector. Default value is 1. This value will only be recognized, if RotateOnSideways is enabled.|
+|MoveSideways |Activate or deactivate to move character sideways on move-left/right hotkeys.|
+=== Movement Drag Mode ===
+We can also enable movement only when dragging is active.
+W-A-S-D or thumbstick movement behaviour will then no longer work.
+Only if left mouse button is dragged (MovementDragModeButton == LButtonDown) the camera will be moved
+into view direction.
+This behaviour is sometimes used in strategy games when moving along a map.
+And in case you want to invert the movement, you can use the "InvertMovementDragModeXAxis" and "InvertMovementDragModeYAxis" property.
+^Property^Description^
+|MovementDragMode|Get or set MovementDragMode value, which defines if camera movement is only been applied, if mouse-down button is active. Set MovementDragModeButton to define the mouse button to be used. Valid states are: LButtonDown, MButtonDown, RButtonDown|
+|MovementDragModeButton|Get or set mouse button to be used if MovementDragMode is enabled. Valid states are: LButtonDown, MButtonDown, RButtonDown|
+|InvertMovementDragModeXAxis|Invert the X-Axis direction value if MovementDragMode is enabled.|
+|InvertMovementDragModeYAxis|Invert the Y-Axis direction value if MovementDragMode is enabled.|
+=== Rotation Drag Mode ===
+We can also enable rotation only when dragging is active.
+It's then no longer possible to rotate the camera without holding the drag button.
+^Property^Description^
+|RotationDragMode|Get or set RotationDragMode value, which defines if camera rotation is only been applied, if mouse-down button is active. Set RotationDragModeButton to define the mouse button to be used. Valid states are: LButtonDown, MButtonDown, RButtonDown|
+|RotationDragModeButton|Get or set mouse button to be used if RotationDragMode is enabled. Valid states are: LButtonDown, MButtonDown, RButtonDown|
+=== Rotation Around Center ===
+In case you want to use the first person controller without a free camera rotation,
+but instead with a rotating first-person controller,
+use the "RotateAroundCenter" property.
+//__**WARNING:**__ This property is currently a little bit buggy!//
+=== Hide Cursor ===
+In many games you don't want to show the mouse cursor.
+On Windows platform we provide an easy to use property called "ShowCursor", which enables or disables the displayed mouse cursor.
+^Property^Description^
+|ShowCursor|You can show/hide mouse cursor while first person controller is running. It is recommended to disable it already at design time.|
+=== Size ===
+A character controller is not only a virtual component, it actually should have a size.
+Therefor it is important to define a Width, Height and Depth for you controller,
+suitable to the expected character size.
+It will be the basis for jumping, crawling, crouching and later for physics collision detection.
+^Property^Description^
+|Width|Width of the virtual character controller.|
+|Height|Height of the virtual character controller.|
+|Depth|Depth of the virtual character controller.|
+=== Jumping ===
+You can control the jumping height and the time it takes by the "JumpingAnimationTime" and the "JumpingHeight" property.
+JumpingHeight is a multiplier for the character height.
+So a value of 2 means it can jump up the double of its size.
+And the animation time is given in seconds and tells the controller how long it takes for jumping.
+^Property^Description^
+|JumpingHeight|Multiplier of peek jumping height for the virtual character controller.|
+|JumpingAnimationTime|Time in seconds the jumping up and down takes.|
+=== Crouching ===
+You can control switching to crouch-mode.
+While the "CrouchingAnimationTime" is the time it takes to enter or leave that mode, the "CrouchingHeight" is the final character size in that mode, based on it's original height.
+When crouching is active states should contain the **fpCrouching** state.
+CrouchingHeight is a multiplier for the character height.
+A value of 0.5 means, the character height in crouching is only half of it's full size.
+And the animation time is given in seconds and tells the controller how long it takes to get down to crouching or up from crouching.
+Internally an animation runs, that shrinks or grows the character size.
+^Property^Description^
+|CrouchingHeight|Multiplier for originl characters height. Will define the active crouching size.|
+|CrouchingAnimationTime|Time in seconds the animation takes to enter or leave the crouching state.|
+|CrouchingSpeedReduction|Multiplier to reduce regular speed while in crouching mode.|
+=== Crawling ===
+Besides the crouching mode, you can also control switching to crawling-mode.
+Crouching often is half of the size of the character, while crawling is less then a quater of it.
+While the "CrawlingAnimationTime" is the time it takes to enter or leave that mode, the "CrawlingHeight" is the final character size in that mode, based on it's original height.
+When crawling is active states should contain the **fpCrawling** state.
+CrawlingHeight is a multiplier for the character height.
+A value of 0.25 means, the character height in crawling is only a quater of it's full size.
+And the animation time is given in seconds and tells the controller how long it takes to get down to crawling or up from crawling.
+Internally an animation runs, that shrinks or grows the character size.
+^Property^Description^
+|CrawlingHeight|Multiplier for originl characters height. Will define the active crawling size.|
+|CrawlingAnimationTime|Time in seconds the animation takes to enter or leave the crawling state.|
+|CrawlingSpeedReduction|Multiplier to reduce regular speed while in crawling mode.|
+=== Default Behaviour ===
+Finally there are 2 important properties to deactivate default behaviour of  our character controllers.
+^Property^Description^
+|UseDefaultBehaviour |Will deactivate any automatic operation handling like jumping, crouching, crawling, moving and so on. But the user-specific callback events like OnMove, OnJump or OnCrawl and so on, are still getting called.|
+|UseDefaultMovement|Allows to disable default movement of the controller. This has no influence on camera rotation.|
+==== User-Friendly Events  ====
+For individual treatment you can disable or overwrite those predefined hotkeys.
+The basic character controller component catches all input events, handles them and throws back user-friendly events.
+^Event ^Callback^Description^
+|OnIdle|TOnCharacterControllerEvent|OnIdle event getting raised when first person controller switches to idle mode.|
+|OnMove|TOnCharacterControllerMoveEvent|OnMove event getting raised in doOnMoveForward, doOnMoveBackward, doOnMoveLeft, doOnMoveRight and DoOnGamePadThumbstickPos methods, used by keyboard hotkeys and gamepad thumbstick movement.|
+|OnRotate|TOnCharacterControllerRotateEvent|OnRotate event getting raised if the view was rotated by DoOnGamePadThumbstickPos or DoOnMouseMove.|
+|OnBoost|TOnCharacterControllerEvent|OnBoost event getting raised when boost mode was activated or deactivated.|
+|OnCrouch|TOnCharacterControllerEvent|OnCrouch event getting raised when crouching was activated or deactivated.|
+|OnCrawl|TOnCharacterControllerEvent|OnCrawl event getting raised when crawling was activated or deactivated.|
+|OnJump|TOnCharacterControllerEvent|OnJump event getting raised when first person controller is jumping.|
+|OnAim|TOnCharacterControllerEvent|OnAim event getting raised when aiming mode was activated or deactivated.|
+|OnPush|TOnCharacterControllerEvent|OnPush event getting raised when pushing mode was activated or deactivated|
+|OnPull|TOnCharacterControllerEvent|OnPull event getting raised when pulling mode was activated or deactivated.|
+|OnCustomAction|TOnCharacterControllerHotKeyTriggered|OnCustomAction event getting raised by keyboard custom action hotkeys and gamepad buttons.|
+|OnClick|TOnCharacterControllerHotKeyTriggered|OnClick event getting raised by clicking left, middle or right mouse button.|
+|OnStart|TOnCharacterControllerEvent|OnStart event getting raised when start hotkey was activated.|
+|OnMode|TOnCharacterControllerEvent|OnMode event getting raised when mode hotkey was activated.|
+|OnBack|TOnCharacterControllerEvent|OnBack event getting raised when back hotkey was activated.|
+|OnNavigate|TOnCharacterControllerHotKeyTriggered|OnNavigate event getting raised when menu navigation was triggered.|
+|OnChangeSize|TNotifyEvent|Getting called, when leaving crouching or crawling mode.|
+|OnHotKey|TOnCharacterControllerHotKeyTriggered|OnHotKey event getting raised when a registered hotkey was triggered. It's a central callback event for all hotkeys. Parallel to it hotkey specific events will be raised: OnIdle, OnMove, OnBoost, OnCrouch, OnJump, OnCustomAction, OnClick, OnStart, OnMode, OnBack and OnNavigate|
+|OnTriggerPoint|TOnCharacterControllerTriggerPoint|If a TGorillaTriggerPointManager component was linked to the first person controller, a trigger-point check will automatically be performed on movement. If then a trigger-point is in reach, the OnTriggerPoint event will be raised.|
+And the corresponding event method declarations look like:
+^Name^Declaration^
+|TOnCharacterControllerHotKeyTriggered|procedure(ASender : TObject; const AKind : TGorillaCharacterControllerHotKey; const AHotKey : TGorillaHotKeyItem; const AStates : TGorillaCharacterControllerStates; const AMode : TGorillaInputMode) of object;|
+|TOnCharacterControllerMoveEvent|procedure(ASender : TObject; AKind : TGorillaCharacterControllerHotKey; ADir : TPoint3D; ACurrentSpeed : Single) of object;|
+|TOnCharacterControllerRotateEvent|procedure(ASender : TObject; ACurrentRotation : TQuaternion3D; ANewRotation : TQuaternion3D; ADelta : TPointF) of object;|
+|TOnCharacterControllerEvent|procedure(ASender : TObject; AState : TGorillaCharacterControllerState; AMode : TGorillaInputMode) of object;|
+|TOnCharacterControllerTriggerPoint|procedure(ASender : TObject; AManager : TGorillaTriggerPointManager; APt : TGorillaTriggerPoint; ADist : Single) of object;|
 ===== FirstPerson Controller =====
@@ Line 141: / Line 300: @@
 FFirstPersonCtrl.Camera := FCamera;
 </file>
-You have some properties to optimize or configure your specific character movement:
-^Property ^Description ^
-|MouseControllerSpeed|Get or set mouse controller speed. The value reduces movement speed on mouse interaction. Default value is 0.075.|
-|GamePadThumbstickSpeed|Get or set gamepad controller speed, when using thumbsticks to move. The value reduces movement speed on gamepad interaction. Default value is 0.5.|
-|Speed |Get or set speed of movement. A basis speed value applied to direction vector. Default value is 1.0.|
-|CrouchingSpeedReduction|Factor of reduction on speed if state is fpCrouching. Values between 0.0 - 1.0 are allowed. Default value is 0.15.|
-|RunningSpeedBoost|Boost factor on speed if state is fpBoost. Values between 1-1000 are allowed. Default value is 2.0.|
-|JumpingHeight |Get or set jumping height value. The value defines the height of jumping. Default value is 4.0.|
-|CrouchingHeight |Get or set crouching height value. The value defines how deep the character getting down. Default value is 0.5.
-|ShowCursor |You can show/hide mouse cursor while first person controller is running. (not working properly)|
-|RotationDragMode |Get or set FRotationDragMode value, which defines if camera rotation is only been applied, if mouse down is active.|
-|UseDefaultBehaviour |Activate / Deactivate default behaviour on hotkeys triggered.|
-|UseDefaultMovement |Activate / Deactivate default movement behaviour. This flag allows to disable default HotKey (W-A-S-D keys) / Gamepad (thumbstick) movement. This has no influence on camera rotation.|
 ===== ThirdPerson Controller =====