Class TCastleThirdPersonNavigation

Unit

Declaration

type TCastleThirdPersonNavigation = class(TCastleMouseLookNavigation)

Description

3rd-person camera navigation. Create an instance of this and assign it to TCastleViewport.Navigation to use. Be sure to also assign Avatar. Call Init once the parameters that determine initial camera location are all set.

Turn on MouseLook to allow user to move the mouse to orbit with the camera around the avatar. When AimAvatar is aaNone (default), it allows to look at the avatar easily from any side (e.g. you can then see avatar's face easily). When AimAvatar is aaHorizontal or aaFlying, rotating allows to point the avatar at the appropriate direction.

Using keys AWSD and arrows you can move and rotate the avatar, and the camera will follow.

Using the mouse wheel you can get closer / further to the avatar.

See also the news post with demo movie about this component: https://castle-engine.io/wp/2020/06/29/third-person-navigation-with-avatar-component-in-castle-game-engine/

Hierarchy

Overview

Fields

Public nested const DefaultInitialHeightAboveTarget = 1.0;
Public nested const DefaultDistanceToAvatarTarget = 4.0;
Public nested const DefaultAvatarRotationSpeed = 10;
Public nested const DefaultAvatarTarget: TVector3 = (X: 0; Y: 2; Z: 0);
Public nested const DefaultCameraSpeed = 10;
Public nested const DefaultMoveSpeed = 1.0;
Public nested const DefaultCrouchSpeed = 0.5;
Public nested const DefaultRunSpeed = 2.0;
Public nested const DefaultJumpSpeed = 5.0;
Public nested const DefaultRotationSpeed = Pi * 150 / 180;
Public nested const DefaultCameraDistanceChangeSpeed = 1;
Public nested const DefaultMinDistanceToAvatarTarget = 0.5;
Public nested const DefaultMaxDistanceToAvatarTarget = 10;
Public nested const DefaultAnimationIdle = 'idle';
Public nested const DefaultAnimationRotate = 'rotate';
Public nested const DefaultAnimationWalk = 'walk';
Public nested const DefaultAnimationRun = 'run';
Public nested const DefaultAnimationCrouch = 'crouch';
Public nested const DefaultAnimationCrouchIdle = 'crouch_idle';
Public nested const DefaultAnimationCrouchRotate = 'crouch_rotate';
Public nested const DefaultAnimationJump = 'jump';
Public nested const DefaultAnimationFall = 'fall';
Public nested const DefaultAirMovementControl = 0.5;
Public nested const DefaultAirRotationControl = 0.5;

Methods

Protected procedure ProcessMouseLookDelta(const Delta: TVector2); override;
Protected function Zoom(const Factor: Single): Boolean; override;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure Update(const SecondsPassed: Single; var HandleInput: Boolean); override;
Public function PropertySections(const PropertyName: String): TPropertySections; override;
Public procedure Init;
Public function Input_CameraCloser: TInputShortcut; deprecated 'use Input_ZoomIn';
Public function Input_CameraFurther: TInputShortcut; deprecated 'use Input_ZoomOut';

Properties

Public property AvatarTarget: TVector3 read FAvatarTarget write FAvatarTarget;
Public property Input_Forward: TInputShortcut read FInput_Forward;
Public property Input_Backward: TInputShortcut read FInput_Backward;
Public property Input_LeftRotate: TInputShortcut read FInput_LeftRotate;
Public property Input_RightRotate: TInputShortcut read FInput_RightRotate;
Public property Input_LeftStrafe: TInputShortcut read FInput_LeftStrafe;
Public property Input_RightStrafe: TInputShortcut read FInput_RightStrafe;
Public property Input_Crouch: TInputShortcut read FInput_Crouch;
Public property Input_Run: TInputShortcut read FInput_Run;
Public property Input_Jump: TInputShortcut read FInput_Jump;
Published property ZoomEnabled default true;
Published property MouseLookHorizontalSensitivity;
Published property MouseLookVerticalSensitivity;
Published property InvertVerticalMouseLook;
Published property CameraFollows: Boolean read FCameraFollows write SetCameraFollows default true;
Published property Avatar: TCastleScene read FAvatar write SetAvatar;
Published property AvatarHierarchy: TCastleTransform read FAvatarHierarchy write SetAvatarHierarchy;
Published property AvatarRotationSpeed: Single read FAvatarRotationSpeed write FAvatarRotationSpeed default DefaultAvatarRotationSpeed;
Published property CameraSpeed: Single read FCameraSpeed write FCameraSpeed default DefaultCameraSpeed;
Published property AimAvatar: TAimAvatar read FAimAvatar write FAimAvatar default aaNone;
Published property InitialHeightAboveTarget: Single read FInitialHeightAboveTarget write SetInitialHeightAboveTarget default DefaultInitialHeightAboveTarget;
Published property ImmediatelyFixBlockedCamera: Boolean read FImmediatelyFixBlockedCamera write FImmediatelyFixBlockedCamera default false;
Published property DistanceToAvatarTarget: Single read FDistanceToAvatarTarget write SetDistanceToAvatarTarget default DefaultDistanceToAvatarTarget;
Published property CameraDistanceChangeSpeed: Single read FCameraDistanceChangeSpeed write FCameraDistanceChangeSpeed default DefaultCameraDistanceChangeSpeed;
Published property MinDistanceToAvatarTarget: Single read FMinDistanceToAvatarTarget write FMinDistanceToAvatarTarget default DefaultMinDistanceToAvatarTarget;
Published property MaxDistanceToAvatarTarget: Single read FMaxDistanceToAvatarTarget write FMaxDistanceToAvatarTarget default DefaultMaxDistanceToAvatarTarget;
Published property MoveSpeed: Single read FMoveSpeed write FMoveSpeed default DefaultMoveSpeed;
Published property CrouchSpeed: Single read FCrouchSpeed write FCrouchSpeed default DefaultCrouchSpeed;
Published property RunSpeed: Single read FRunSpeed write FRunSpeed default DefaultRunSpeed;
Published property JumpSpeed: Single read FJumpSpeed write FJumpSpeed default DefaultJumpSpeed;
Published property RotationSpeed: Single read FRotationSpeed write FRotationSpeed default DefaultRotationSpeed;
Published property AirMovementControl: Single read FAirMovementControl write FAirMovementControl default DefaultAirMovementControl;
Published property AirRotationControl: Single read FAirRotationControl write FAirRotationControl default DefaultAirRotationControl;
Published property AnimationIdle: String read FAnimationIdle write FAnimationIdle stored AnimationIdleStored nodefault;
Published property AnimationRotate: String read FAnimationRotate write FAnimationRotate stored AnimationRotateStored nodefault;
Published property AnimationWalk: String read FAnimationWalk write FAnimationWalk stored AnimationWalkStored nodefault;
Published property AnimationRun: String read FAnimationRun write FAnimationRun stored AnimationRunStored nodefault;
Published property AnimationCrouch: String read FAnimationCrouch write FAnimationCrouch stored AnimationCrouchStored nodefault;
Published property AnimationCrouchIdle: String read FAnimationCrouchIdle write FAnimationCrouchIdle stored AnimationCrouchIdleStored nodefault;
Published property AnimationCrouchRotate: String read FAnimationCrouchRotate write FAnimationCrouchRotate stored AnimationCrouchRotateStored nodefault;
Published property AnimationJump: String read FAnimationJump write FAnimationJump stored AnimationJumpStored nodefault;
Published property AnimationFall: String read FAnimationFall write FAnimationFall stored AnimationFallStored nodefault;
Published property Radius;
Published property ChangeTransformation: TChangeTransformation read FChangeTransformation write FChangeTransformation default ctAuto;
Published property AvatarTargetPersistent: TCastleVector3Persistent read FAvatarTargetPersistent ;

Description

Fields

Public nested const DefaultInitialHeightAboveTarget = 1.0;

This item has no description.

Public nested const DefaultDistanceToAvatarTarget = 4.0;

This item has no description.

Public nested const DefaultAvatarRotationSpeed = 10;

This item has no description.

Public nested const DefaultAvatarTarget: TVector3 = (X: 0; Y: 2; Z: 0);

This item has no description.

Public nested const DefaultCameraSpeed = 10;

This item has no description.

Public nested const DefaultMoveSpeed = 1.0;

This item has no description.

Public nested const DefaultCrouchSpeed = 0.5;

This item has no description.

Public nested const DefaultRunSpeed = 2.0;

This item has no description.

Public nested const DefaultJumpSpeed = 5.0;

This item has no description.

Public nested const DefaultRotationSpeed = Pi * 150 / 180;

This item has no description.

Public nested const DefaultCameraDistanceChangeSpeed = 1;

This item has no description.

Public nested const DefaultMinDistanceToAvatarTarget = 0.5;

This item has no description.

Public nested const DefaultMaxDistanceToAvatarTarget = 10;

This item has no description.

Public nested const DefaultAnimationIdle = 'idle';

This item has no description.

Public nested const DefaultAnimationRotate = 'rotate';

This item has no description.

Public nested const DefaultAnimationWalk = 'walk';

This item has no description.

Public nested const DefaultAnimationRun = 'run';

This item has no description.

Public nested const DefaultAnimationCrouch = 'crouch';

This item has no description.

Public nested const DefaultAnimationCrouchIdle = 'crouch_idle';

This item has no description.

Public nested const DefaultAnimationCrouchRotate = 'crouch_rotate';

This item has no description.

Public nested const DefaultAnimationJump = 'jump';

This item has no description.

Public nested const DefaultAnimationFall = 'fall';

This item has no description.

Public nested const DefaultAirMovementControl = 0.5;

This item has no description.

Public nested const DefaultAirRotationControl = 0.5;

This item has no description.

Methods

Protected procedure ProcessMouseLookDelta(const Delta: TVector2); override;

This item has no description.

Protected function Zoom(const Factor: Single): Boolean; override;

This item has no description. Showing description inherited from TCastleNavigation.Zoom.

Zoom in / out. Negative Factor makes "zoom out", positive makes "zoom in" (zero makes nothing).

Called only if ZoomEnabled, so no need to check it within implementation.

Factor values correspond to TInputPressRelease.MouseWheelScroll values, so 1.0 should be treated like a "one operation" and some systems only generate values -1 or +1 (and never fractions).

Public constructor Create(AOwner: TComponent); override;

This item has no description.

Public destructor Destroy; override;

This item has no description.

Public procedure Update(const SecondsPassed: Single; var HandleInput: Boolean); override;

This item has no description. Showing description inherited from TCastleUserInterface.Update.

Control may do here anything that must be continuously repeated. E.g. camera handles here falling down due to gravity, rotating model in Examine mode, and many more.

This method may be used, among many other things, to continuously react to the fact that user pressed some key (or mouse button). For example, if holding some key should move some 3D object, you should do something like:

if HandleInput then
begin
  if Container.Pressed[keyArrowRight] then
    Transform.Position := Transform.Position + Vector3(SecondsPassed * 10, 0, 0);
  HandleInput := not ExclusiveEvents;
end;

Instead of directly using a key code, consider also using TInputShortcut that makes the input key nicely configurable. See engine tutorial about handling inputs.

Multiplying movement by SecondsPassed makes your operation frame-rate independent. Object will move by 10 units in a second, regardless of how many FPS your game has.

The code related to HandleInput is important if you write a generally-useful control that should nicely cooperate with all other controls, even when placed on top of them or under them. The correct approach is to only look at pressed keys/mouse buttons if HandleInput is True. Moreover, if you did check that HandleInput is True, and you did actually handle some keys, then you have to set HandleInput := not ExclusiveEvents. As ExclusiveEvents is True in normal circumstances, this will prevent the other controls (behind the current control) from handling the keys (they will get HandleInput = False). And this is important to avoid doubly-processing the same key press, e.g. if two controls react to the same key, only the one on top should process it.

Note that to handle a single press / release (like "switch light on when pressing a key") you should rather use Press and Release methods. Use this method only for continuous handling (like "holding this key makes the light brighter and brighter").

To understand why such HandleInput approach is needed, realize that the "Update" events are called differently than simple mouse and key events like "Press" and "Release". "Press" and "Release" events return whether the event was somehow "handled", and the container passes them only to the controls under the mouse (decided by TCastleUserInterface.CapturesEventsAtPosition). And as soon as some control says it "handled" the event, other controls (even if under the mouse) will not receive the event.

This approach is not suitable for Update events. Some controls need to do the Update job all the time, regardless of whether the control is under the mouse and regardless of what other controls already did. So all controls (well, all controls that exist, in case of TCastleUserInterface, see TCastleUserInterface.Exists) receive Update calls.

So the "handled" status is passed through HandleInput. If a control is not under the mouse, it will receive HandleInput = False. If a control is under the mouse, it will receive HandleInput = True as long as no other control on top of it didn't already change it to False.

Public function PropertySections(const PropertyName: String): TPropertySections; override;

This item has no description. Showing description inherited from TCastleComponent.PropertySections.

Section where to show property in the editor.

Public procedure Init;

Makes camera be positioned with respect to the current properties and avatar. Always call this explicitly once. Use this after setting properties like Avatar, AvatarHierarchy, DistanceToAvatarTarget, InitialHeightAboveTarget.

At design-time (in CGE editor), this is automatically called after changing relevant properties of this navigation.

Public function Input_CameraCloser: TInputShortcut; deprecated 'use Input_ZoomIn';

Warning: this symbol is deprecated: use Input_ZoomIn

This item has no description.

Public function Input_CameraFurther: TInputShortcut; deprecated 'use Input_ZoomOut';

Warning: this symbol is deprecated: use Input_ZoomOut

This item has no description.

Properties

Public property AvatarTarget: TVector3 read FAvatarTarget write FAvatarTarget;

Translation, from the avatar origin, to the "target" of the avatar where camera looks at. This is usually head, and this vector should just describe the height of head above the ground. By default this is DefaultAvatarTarget = (0, 2, 0).

Public property Input_Forward: TInputShortcut read FInput_Forward;

This item has no description.

Public property Input_Backward: TInputShortcut read FInput_Backward;

This item has no description.

Public property Input_LeftRotate: TInputShortcut read FInput_LeftRotate;

This item has no description.

Public property Input_RightRotate: TInputShortcut read FInput_RightRotate;

This item has no description.

Public property Input_LeftStrafe: TInputShortcut read FInput_LeftStrafe;

This item has no description.

Public property Input_RightStrafe: TInputShortcut read FInput_RightStrafe;

This item has no description.

Public property Input_Crouch: TInputShortcut read FInput_Crouch;

This item has no description.

Public property Input_Run: TInputShortcut read FInput_Run;

This item has no description.

Public property Input_Jump: TInputShortcut read FInput_Jump;

This item has no description.

Published property ZoomEnabled default true;

Zooming in this navigation mode makes camera move closer/further from avatar.

Published property MouseLookHorizontalSensitivity;

This item has no description. Showing description inherited from TCastleMouseLookNavigation.MouseLookHorizontalSensitivity.

Mouse look sensitivity, if MouseLook is working. These properties specify how much angle change is produced by moving mouse by 1 pixel.

Published property MouseLookVerticalSensitivity;

This item has no description.

Published property InvertVerticalMouseLook;

This item has no description. Showing description inherited from TCastleMouseLookNavigation.InvertVerticalMouseLook.

If this is True and MouseLook works, then the meaning of vertical mouse movement is inverted: when user moves mouse up, he looks down. Some players are more comfortable with such configuration.

Published property CameraFollows: Boolean read FCameraFollows write SetCameraFollows default true;

Does camera follow the avatar, by default yes.

When this is False, camera remains unchanged by anything here (avatar movement/rotations, mouse look, even by calling Init). Some properties of this then are meaningless (e.g. DistanceToAvatarTarget).

However, all the inputs to control the avatar continue to work.

Published property Avatar: TCastleScene read FAvatar write SetAvatar;

Avatar scene, that is animated, moved and rotated when this navigation changes. This navigation component will just call Avatar.AutoAnimation := 'xxx' when necessary. Currently we require the following animations to exist: walk, idle.

When AvatarHierarchy is Nil, then Avatar is directly moved and rotated to move avatar. Otherwise, AvatarHierarchy is moved, and Avatar should be inside AvatarHierarchy.

This scene should be part of TCastleViewport.Items to make this navigation work, in particular when you call Init.

Published property AvatarHierarchy: TCastleTransform read FAvatarHierarchy write SetAvatarHierarchy;

Optional avatar hierarchy that is moved and rotated when this navigation changes. When this is Nil, we just move and rotate the Avatar. When this is non-nil, then we only move and rotate this AvatarHierarchy.

If AvatarHierarchy is non-nil, then it should contain Avatar as a child. AvatarHierarchy can even be equal to Avatar (it is equivalent to just leaving AvatarHierarchy as Nil).

This object should be part of TCastleViewport.Items to make this navigation work, in particular when you call Init.

Published property AvatarRotationSpeed: Single read FAvatarRotationSpeed write FAvatarRotationSpeed default DefaultAvatarRotationSpeed;

When AimAvatar, this is avatar's rotation speed (in radians per second). Should make avatar rotation "catch up" (with some delay after camera rotation.

Published property CameraSpeed: Single read FCameraSpeed write FCameraSpeed default DefaultCameraSpeed;

Camera position tracks the desired position with given speed (in units per second). This makes camera adjust to avatar moving (because of input, or because of gravity or other external code) and to not being blocked by the collider.

Published property AimAvatar: TAimAvatar read FAimAvatar write FAimAvatar default aaNone;

If not aaNone then rotating the camera also rotates (with some delay) the avatar, to face the same direction as the camera. This allows to rotate the avatar with mouse look (which is comfortable), on the other hand it takes away some flexibility, e.g. you cannot look at avatar's face for a long time anymore.

Published property InitialHeightAboveTarget: Single read FInitialHeightAboveTarget write SetInitialHeightAboveTarget default DefaultInitialHeightAboveTarget;

Initial height of camera above the AvatarTarget. Together with DistanceToAvatarTarget this determines the initial camera position, set by Init. It is not used outside of Init.

Published property ImmediatelyFixBlockedCamera: Boolean read FImmediatelyFixBlockedCamera write FImmediatelyFixBlockedCamera default false;

Immediately (not with delay of CameraSpeed) update camera to never block avatar view by a wall, enemy etc. When it is True, we avoid seeing an invalid geometry (e.g. from the wrong side of the wall or inside a creature) ever, but in exchange the camera sometimes has to be adjusted very abrtupty (testcase: third_person_navigation demo, stand in the middle of moving enemies, and look around).

Published property DistanceToAvatarTarget: Single read FDistanceToAvatarTarget write SetDistanceToAvatarTarget default DefaultDistanceToAvatarTarget;

Preferred distance from camera to the avatar target (head). User can change it with Input_ZoomIn, Input_ZoomOut if you set these inputs to some key/mouse button/mouse wheel.

Published property CameraDistanceChangeSpeed: Single read FCameraDistanceChangeSpeed write FCameraDistanceChangeSpeed default DefaultCameraDistanceChangeSpeed;

Speed with which Input_ZoomIn, Input_ZoomOut can change DistanceToAvatarTarget.

Published property MinDistanceToAvatarTarget: Single read FMinDistanceToAvatarTarget write FMinDistanceToAvatarTarget default DefaultMinDistanceToAvatarTarget;

Limit of the distance to avatar, used when changing DistanceToAvatarTarget, and also when deciding how to adjust camera to avoid collisions.

Published property MaxDistanceToAvatarTarget: Single read FMaxDistanceToAvatarTarget write FMaxDistanceToAvatarTarget default DefaultMaxDistanceToAvatarTarget;

This item has no description.

Published property MoveSpeed: Single read FMoveSpeed write FMoveSpeed default DefaultMoveSpeed;

Speed of movement by keys.

Published property CrouchSpeed: Single read FCrouchSpeed write FCrouchSpeed default DefaultCrouchSpeed;

Speed of movement by keys, when crouching.

Published property RunSpeed: Single read FRunSpeed write FRunSpeed default DefaultRunSpeed;

Speed of movement by keys, when running.

Published property JumpSpeed: Single read FJumpSpeed write FJumpSpeed default DefaultJumpSpeed;

Speed of jump by keys.

Published property RotationSpeed: Single read FRotationSpeed write FRotationSpeed default DefaultRotationSpeed;

Speed of rotating by keys, in radians per second.

Published property AirMovementControl: Single read FAirMovementControl write FAirMovementControl default DefaultAirMovementControl;

Should we have control on the avatar movement in the air. Must be >= 0.

  • 0 -> no control in the air

  • 1 -> full control in the air, just like on the ground

  • between 0 and 1 -> limited control, smoothly changes between no control and full control

  • above 1 -> in the air you move even faster than on the ground

Published property AirRotationControl: Single read FAirRotationControl write FAirRotationControl default DefaultAirRotationControl;

Should we have control on the avatar rotation in the air.

  • 0 -> no control in the air

  • 1 -> full control in the air, just like on the ground

  • between 0 and 1 -> limited control, smoothly changes between no control and full control

  • above 1 -> in the air you rotate even faster than on the ground

Published property AnimationIdle: String read FAnimationIdle write FAnimationIdle stored AnimationIdleStored nodefault;

Animation when character is not moving, not rotating and not crouching. Default 'idle'.

Published property AnimationRotate: String read FAnimationRotate write FAnimationRotate stored AnimationRotateStored nodefault;

Animation when character is rotating, but otherwise remains in place (not moving) and it is not crouching. Default 'rotate'.

Published property AnimationWalk: String read FAnimationWalk write FAnimationWalk stored AnimationWalkStored nodefault;

Animation when character is walking. Default 'walk'.

Published property AnimationRun: String read FAnimationRun write FAnimationRun stored AnimationRunStored nodefault;

Animation when character is running. Default 'run'.

Published property AnimationCrouch: String read FAnimationCrouch write FAnimationCrouch stored AnimationCrouchStored nodefault;

Animation when character is moving while crouching. Default 'crouch'.

Published property AnimationCrouchIdle: String read FAnimationCrouchIdle write FAnimationCrouchIdle stored AnimationCrouchIdleStored nodefault;

Animation when character is crouching (Input_Crouch is pressed) but not moving or rotating. Default 'crouch_idle'.

Published property AnimationCrouchRotate: String read FAnimationCrouchRotate write FAnimationCrouchRotate stored AnimationCrouchRotateStored nodefault;

Animation when character is crouching (Input_Crouch is pressed) and rotating, but not moving. Default 'crouch_rotate'.

Published property AnimationJump: String read FAnimationJump write FAnimationJump stored AnimationJumpStored nodefault;

Animation when character is jumping (Input_Jump is pressed). Default 'jump'.

Published property AnimationFall: String read FAnimationFall write FAnimationFall stored AnimationFallStored nodefault;

Animation when character is fall. Default 'fall'.

Published property Radius;

Camera will keep at least this distance from walls.

Published property ChangeTransformation: TChangeTransformation read FChangeTransformation write FChangeTransformation default ctAuto;

How does the avatar change transformation (for movement and rotations). This determines whether we update TCastleTransform.Translation, TCastleTransform.Rotation directly or use physics (TCastleRigidBody) velocities or forces.

See TChangeTransformation for possible values are their meaning.

By default, this is ctAuto, which means that we detect whether you have physics behaviors (TCastleRigidBody, TCastleCollider, with TCastleRigidBody.Exists) set up on the avatar.

Published property AvatarTargetPersistent: TCastleVector3Persistent read FAvatarTargetPersistent ;

AvatarTarget that can be visually edited in Castle Game Engine Editor, Lazarus and Delphi. Normal user code does not need to deal with this, instead read or write AvatarTarget directly.

See also
AvatarTarget
Translation, from the avatar origin, to the "target" of the avatar where camera looks at.

Generated by PasDoc 0.16.0.