Castle Game Engine

Class TCastleThirdPersonNavigation

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleThirdPersonNavigation

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 TCastleNavigation.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 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';

Methods

Protected procedure ProcessMouseLookDelta(const Delta: TVector2); override;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure Update(const SecondsPassed: Single; var HandleInput: Boolean); override;
Public function Press(const Event: TInputPressRelease): Boolean; override;
Public function PropertySections(const PropertyName: String): TPropertySections; override;
Public procedure Init;

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_CameraCloser: TInputShortcut read FInput_CameraCloser;
Public property Input_CameraFurther: TInputShortcut read FInput_CameraFurther;
Public property Input_Crouch: TInputShortcut read FInput_Crouch;
Public property Input_Run: TInputShortcut read FInput_Run;
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 RotationSpeed: Single read FRotationSpeed write FRotationSpeed default DefaultRotationSpeed;
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 Radius;
Published property AvatarTargetPersistent: TCastleVector3Persistent read FAvatarTargetPersistent ;

Description

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 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';
 

Methods

Protected procedure ProcessMouseLookDelta(const Delta: TVector2); override;
 
Public constructor Create(AOwner: TComponent); override;
 
Public destructor Destroy; override;
 
Public procedure Update(const SecondsPassed: Single; var HandleInput: Boolean); override;
 
Public function Press(const Event: TInputPressRelease): Boolean; override;
 
Public function PropertySections(const PropertyName: String): TPropertySections; override;
 
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.

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;
 
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_CameraCloser: TInputShortcut read FInput_CameraCloser;
 
Public property Input_CameraFurther: TInputShortcut read FInput_CameraFurther;
 
Public property Input_Crouch: TInputShortcut read FInput_Crouch;
 
Public property Input_Run: TInputShortcut read FInput_Run;
 
Published property MouseLookHorizontalSensitivity;
 
Published property MouseLookVerticalSensitivity;
 
Published property InvertVerticalMouseLook;
 
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_CameraCloser, Input_CameraFurther 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_CameraCloser, Input_CameraFurther 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;
 
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 RotationSpeed: Single read FRotationSpeed write FRotationSpeed default DefaultRotationSpeed;

Speed of rotating by keys, in radians per second.

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 Radius;

Camera will keep at least this distance from walls.

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.