Castle Game Engine

Class TPlayer

Description
Hierarchy
Fields
Methods
Properties

Unit

CastlePlayer

Declaration

type TPlayer = class(TAliveWithInventory)

Description

Player, 3D object controlling the camera, main enemy of hostile creatures, carries a backpack, may cause fadeout effects on screen and such.

Note that you can operate on player even before level is loaded, before TLevel or TCastleViewport are initialized. This allows to create player before level is started (create it from scratch, or by loading from save game), and "carry" the same player instance across various loaded levels.

Dead or Blocked player behaves much like alive and normal player. For example, it still has an associated Navigation that can be affected by physics (e.g. to apply physics to the dead player body, because player was killed when he was flying, or it's corpse lays on some moving object of the level — like elevator). However, input shortcuts will be cleared, to prevent user from directly moving the player.

Do not do some stuff when player is dead:

Note that a player has an associated and synchronized Navigation instance. See UseThirdPerson.

Hierarchy

Overview

Fields

Public var DefaultMoveHorizontalSpeed: Single;
Public DefaultMoveVerticalSpeed: Single;
Public DefaultPreferredHeight: Single;
Public nested const DefaultLife = 100;
Public nested const DefaultSickProjectionSpeed = 2.0;
Public nested const DefaultRenderOnTop = true;
Public nested const DefaultPlayerKnockBackSpeed = 20.0;
Public nested const DefaultSwimBreath = 30.0;
Public nested const DefaultDrownPause = 5.0;
Public nested const DefaultDrownDamageConst = 5.0;
Public nested const DefaultDrownDamageRandom = 10.0;
Public nested const DefaultSwimSoundPause = 3.11111111;
Public nested const DefaultFallMinHeightToSound = 4.0;
Public nested const DefaultFallSoundName = 'player_fall';

Methods

Protected procedure SetLife(const Value: Single); override;
Protected procedure Notification(AComponent: TComponent; Operation: TOperation); override;
Protected function LocalHeightCollision(const APosition, GravityUp: TVector3; const TrianglesToIgnoreFunc: TTriangleIgnoreFunc; out AboveHeight: Single; out AboveGround: PTriangle): Boolean; override;
Protected function LocalSegmentCollision(const Pos1, Pos2: TVector3; const TrianglesToIgnoreFunc: TTriangleIgnoreFunc; const ALineOfSight: Boolean): Boolean; override;
Protected procedure LocalRender(const Params: TRenderParams); override;
Protected procedure Fall(const FallHeight: Single); override;
Protected procedure ChangedTransform; override;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure Render(const Params: TRenderParams); override;
Public function Press(const Event: TInputPressRelease): Boolean; override;
Public function PickItemUpdate(var Item: TInventoryItem): Integer; override;
Public function DropItem(const Index: Integer): TItemOnWorld; override;
Public function DropCurrentItem: TItemOnWorld;
Public procedure UseItem(const Index: Integer); override;
Public procedure UseCurrentItem;
Public procedure ChangeInventoryCurrentItem(Change: Integer);
Public procedure Update(const SecondsPassed: Single; var RemoveMe: TRemoveType); override;
Public function Middle: TVector3; override;
Public procedure FadeOut(const Color: TCastleColor);
Public procedure Attack; virtual;
Public procedure LoadFromFile;
Public procedure LoadFromFile(const URL: string);
Public function Ground: PTriangle;
Public procedure LevelChanged;
Public function Sphere(out Radius: Single): boolean; override;
Public function Navigation: TCastleMouseLookNavigation;

Properties

Public property ListenPressRelease default true;
Public property Flying: boolean read FFlying write SetFlying;
Public property FlyingTimeOut: TFloatTime read FFlyingTimeOut write SetFlyingTimeOut;
Public property EquippedWeapon: TItemWeapon read FEquippedWeapon write SetEquippedWeapon;
Public property FadeOutColor: TCastleColor read FFadeOutColor;
Public property FadeOutIntensity: Single read FFadeOutIntensity;
Public property InventoryCurrentItem: Integer read FInventoryCurrentItem write FInventoryCurrentItem default -1;
Public property InventoryVisible: boolean read FInventoryVisible write FInventoryVisible default false;
Public property SickProjectionSpeed: Single read FSickProjectionSpeed write FSickProjectionSpeed default DefaultSickProjectionSpeed;
Public property CollidesWithMoving default true;
Public property Blocked: boolean read FBlocked write FBlocked;
Public property RenderOnTop: boolean read FRenderOnTop write FRenderOnTop default DefaultRenderOnTop;
Public property FallMinHeightToSound: Single read FFallMinHeightToSound write FFallMinHeightToSound default DefaultFallMinHeightToSound;
Public property FallMinHeightToDamage: Single read FFallMinHeightToDamage write FFallMinHeightToDamage default DefaultFallMinHeightToDamage;
Public property FallDamageScaleMin: Single read FFallDamageScaleMin write FFallDamageScaleMin default DefaultFallDamageScaleMin;
Public property FallDamageScaleMax: Single read FFallDamageScaleMax write FFallDamageScaleMax default DefaultFallDamageScaleMax;
Public property FallSound: TSoundType read FFallSound write FFallSound;
Public property HeadBobbing: Single read FHeadBobbing write FHeadBobbing default TCastleWalkNavigation.DefaultHeadBobbing;
Public property SwimBreath: Single read FSwimBreath write FSwimBreath default DefaultSwimBreath;
Public property DrownPause: Single read FDrownPause write FDrownPause default DefaultDrownPause;
Public property DrownDamageConst: Single read FDrownDamageConst write FDrownDamageConst default DefaultDrownDamageConst;
Public property DrownDamageRandom: Single read FDrownDamageRandom write FDrownDamageRandom default DefaultDrownDamageRandom;
Public property SwimSoundPause: Single read FSwimSoundPause write FSwimSoundPause default DefaultSwimSoundPause;
Public property FallingEffect: boolean read FFallingEffect write FFallingEffect default true;
Public property WalkNavigation: TCastleWalkNavigation read FWalkNavigation;
Public property Camera: TCastleWalkNavigation read FWalkNavigation; deprecated 'use WalkNavigation';
Public property ThirdPersonNavigation: TCastleThirdPersonNavigation read FThirdPersonNavigation;
Public property UseThirdPerson: Boolean read FUseThirdPerson write SetUseThirdPerson default false;
Public property KnockBackSpeed default DefaultPlayerKnockBackSpeed;
Public property EnableNavigationDragging: boolean read FEnableNavigationDragging write SetEnableNavigationDragging default true;
Public property EnableCameraDragging: boolean read FEnableNavigationDragging write SetEnableNavigationDragging default true; deprecated 'use EnableNavigationDragging';
Public property RenderDebug: boolean read FRenderDebug write FRenderDebug default false;

Description

Fields

Public var DefaultMoveHorizontalSpeed: Single;

Various navigation properties that may depend on loaded level.

Public DefaultMoveVerticalSpeed: Single;
 
Public DefaultPreferredHeight: Single;
 
Public nested const DefaultLife = 100;
 
Public nested const DefaultSickProjectionSpeed = 2.0;
 
Public nested const DefaultRenderOnTop = true;
 
Public nested const DefaultPlayerKnockBackSpeed = 20.0;
 
Public nested const DefaultSwimBreath = 30.0;
 
Public nested const DefaultDrownPause = 5.0;
 
Public nested const DefaultDrownDamageConst = 5.0;
 
Public nested const DefaultDrownDamageRandom = 10.0;
 
Public nested const DefaultSwimSoundPause = 3.11111111;
 
Public nested const DefaultFallMinHeightToSound = 4.0;

TPlayer.FallMinHeightToSound is larger than TCreature.FallMinHeightToSound, to avoid making "fall" sound when player merely jumps or walks down a steep hill. No such need for creature.

Public nested const DefaultFallSoundName = 'player_fall';
 

Methods

Protected procedure SetLife(const Value: Single); override;
 
Protected procedure Notification(AComponent: TComponent; Operation: TOperation); override;
 
Protected function LocalHeightCollision(const APosition, GravityUp: TVector3; const TrianglesToIgnoreFunc: TTriangleIgnoreFunc; out AboveHeight: Single; out AboveGround: PTriangle): Boolean; override;
 
Protected function LocalSegmentCollision(const Pos1, Pos2: TVector3; const TrianglesToIgnoreFunc: TTriangleIgnoreFunc; const ALineOfSight: Boolean): Boolean; override;
 
Protected procedure LocalRender(const Params: TRenderParams); override;
 
Protected procedure Fall(const FallHeight: Single); override;
 
Protected procedure ChangedTransform; override;
 
Public constructor Create(AOwner: TComponent); override;
 
Public destructor Destroy; override;
 
Public procedure Render(const Params: TRenderParams); override;
 
Public function Press(const Event: TInputPressRelease): Boolean; override;
 
Public function PickItemUpdate(var Item: TInventoryItem): Integer; override;

Add Item to inventory, updating player InventoryCurrentItem, making suitable notification and sound.

Public function DropItem(const Index: Integer): TItemOnWorld; override;

Drop item from inventory, updating player InventoryCurrentItem, making suitable notification and sound.

Public function DropCurrentItem: TItemOnWorld;
 
Public procedure UseItem(const Index: Integer); override;

Use an item from inventory. You can pass Index that is out of range (or call UseCurrentItem when InventoryCurrentItem = -1), it will then show a notification (by CastleGameNotifications unit) that nothing is selected.

Public procedure UseCurrentItem;
 
Public procedure ChangeInventoryCurrentItem(Change: Integer);

Change InventoryCurrentItem, cycling, and automatically showing the inventory afterwards (if it's not empty). Note that you can also always directly change InventoryCurrentItem property.

Public procedure Update(const SecondsPassed: Single; var RemoveMe: TRemoveType); override;
 
Public function Middle: TVector3; override;
 
Public procedure FadeOut(const Color: TCastleColor);

Cause a fade-out effect on the screen, tinting the screen to the given Color. The TPlayer class doesn't do the actual drawing of the fade-out effect on the screen, we merely store and animate the FadeOutColor and FadeOutIntensity properties. To draw the effect, use a procedure like GLFadeRectangle inside your 2D controls drawing code, see engine tutorial for example.

Public procedure Attack; virtual;
 
Public procedure LoadFromFile;

Load various player properties from an XML file. Properties not specified in the indicated file will be reset to their default values. This is handy to use in a game to allow to configure player behavior by simply editing an XML file (instead of hacking code).

Overloaded parameterless version reads from file 'castle-data:/player.xml'.

Note that the indicated file may not exist, and it will not cause errors. Not existing file is equivalent to a file with everything set at default values.

It is Ok to call this multiple times, at any moment. This way you can make some debug command to reload player.xml file, very useful to test various player properties without restarting the game.

Public procedure LoadFromFile(const URL: string);
 
Public function Ground: PTriangle;
 
Public procedure LevelChanged;
 
Public function Sphere(out Radius: Single): boolean; override;
 
Public function Navigation: TCastleMouseLookNavigation;

Navigation synchronized with this player instance. This is either WalkNavigation or ThirdPersonNavigation, depending on UseThirdPerson.

You can use this navigation as TCastleViewport.Navigation to allow user to directly control this player in first-person game. TLevel.Load sets this automatically.

The view vectors (position, direction and up), TCastleWalkNavigation.Gravity, and various navigation inputs are automatically adjusted based on the current player state (Dead, Blocked) and global PlayerInput_Xxx values, like PlayerInput_Forward. The outside code may still directly access and change some navigation properties like TCastleWalkNavigation.PreferredHeight, TCastleWalkNavigation.RotationHorizontalSpeed TCastleWalkNavigation.RotationVerticalSpeed. In fact, it's Ok to call TCastleWalkNavigation.Init.

Properties

Public property ListenPressRelease default true;
 
Public property Flying: boolean read FFlying write SetFlying;

Flying. How it interacts with FlyingTimeout: Setting this property to any value removes any timeout set by FlyingTimeout. That is, setting this to True makes player fly indefinitely, and setting this to False makes player stop flying (regardless if flying was initialized by Flying := true or FlyingTimeout).

Public property FlyingTimeOut: TFloatTime read FFlyingTimeOut write SetFlyingTimeOut;

Set this to something > 0 to start flying for a given number of seconds. The Flying property will also change to True for this time. It will automatically change back to False after given number of seconds (you can also always just manually switch Flying back to False).

Set this only with value > 0.

When this is > 0 it means flying with a timeout (always Flying = True then), otherwise it's = 0 (which means were not flying, or flying indefinitely long, depending on Flying).

Public property EquippedWeapon: TItemWeapon read FEquippedWeapon write SetEquippedWeapon;

Weapon the player is using right now, or nil if none.

You can set this property only to some item existing on Inventory. When you drop the current weapon, DeleteItem will automatically set this to Nil.

When setting this property (to nil or non-nil) player may get GameMessage about using/not using a weapon.

Public property FadeOutColor: TCastleColor read FFadeOutColor;
 
Public property FadeOutIntensity: Single read FFadeOutIntensity;
 
Public property InventoryCurrentItem: Integer read FInventoryCurrentItem write FInventoryCurrentItem default -1;

Currently selected inventory item.

Note: while we try to always sensibly update InventoryCurrentItem, to keep the assumptions that

  1. Inventory.Count = 0 => InventoryCurrentItem = -1

  2. Inventory.Count > 0 => InventoryCurrentItem between 0 and Inventory.Count - 1

but you should nowhere depend on these assuptions. That's because I want to allow myself freedom to modify Inventory in various situations, so InventoryCurrentItem can become invalid in many situations.

So every code should check that

  • If InventoryCurrentItem between 0 and Inventory.Count - 1 then InventoryCurrentItem is selected

  • Else no item is selected (possibly Inventory.Count = 0, possibly not)

Public property InventoryVisible: boolean read FInventoryVisible write FInventoryVisible default false;
 
Public property SickProjectionSpeed: Single read FSickProjectionSpeed write FSickProjectionSpeed default DefaultSickProjectionSpeed;
 
Public property CollidesWithMoving default true;
 
Public property Blocked: boolean read FBlocked write FBlocked;

Disables changing the camera by user. It's useful when you want to temporarily force camera to some specific setting (you can even use handy Player.Navigation.AnimateTo method to do this easily, see TCastleWalkNavigation.AnimateTo).

Public property RenderOnTop: boolean read FRenderOnTop write FRenderOnTop default DefaultRenderOnTop;

Render 3D children (like EquippedWeapon) on top of everything else.

Public property FallMinHeightToSound: Single read FFallMinHeightToSound write FFallMinHeightToSound default DefaultFallMinHeightToSound;
 
Public property FallMinHeightToDamage: Single read FFallMinHeightToDamage write FFallMinHeightToDamage default DefaultFallMinHeightToDamage;
 
Public property FallDamageScaleMin: Single read FFallDamageScaleMin write FFallDamageScaleMin default DefaultFallDamageScaleMin;
 
Public property FallDamageScaleMax: Single read FFallDamageScaleMax write FFallDamageScaleMax default DefaultFallDamageScaleMax;
 
Public property FallSound: TSoundType read FFallSound write FFallSound;

Sound when falling. The default is the sound named 'player_fall'.

Public property HeadBobbing: Single read FHeadBobbing write FHeadBobbing default TCastleWalkNavigation.DefaultHeadBobbing;

Controls head bobbing, but only when player is walking. See TCastleWalkNavigation.HeadBobbing for exact meaning of this. TPlayer.Navigation.HeadBobbing is automatically updated as necessary.

Note that when using CastleLevels, then the headBobbing defined inside VRML/X3D file (see https://castle-engine.io/x3d_extensions.php#section_ext_head_bobbing ) is ignored. Instead, Player properties control TCastleWalkNavigation.HeadBobbing and TCastleWalkNavigation.HeadBobbingTime.

Public property SwimBreath: Single read FSwimBreath write FSwimBreath default DefaultSwimBreath;

How many seconds you can swin before you start to drown.

Public property DrownPause: Single read FDrownPause write FDrownPause default DefaultDrownPause;

How many seconds between each drown event. Drown event makes stPlayerDrowning sound and causes damage DrownDamageConst + Random * DrownDamageRandom.

Public property DrownDamageConst: Single read FDrownDamageConst write FDrownDamageConst default DefaultDrownDamageConst;
 
Public property DrownDamageRandom: Single read FDrownDamageRandom write FDrownDamageRandom default DefaultDrownDamageRandom;
 
Public property SwimSoundPause: Single read FSwimSoundPause write FSwimSoundPause default DefaultSwimSoundPause;

Pause, in seconds, between playing stPlayerSwimming sound. This should be something that is not easily synchronized with SwimDrownPause.

Public property FallingEffect: boolean read FFallingEffect write FFallingEffect default true;

Enable navigation falling down effect due to gravity. This indirectly controls TCastleWalkNavigation.FallingEffect underneath.

Note: do not set Navigation.FallingEffect, as it will be overridden in our update. Use only this property to turn on/off the effect.

Public property WalkNavigation: TCastleWalkNavigation read FWalkNavigation;

Navigation synchronized with this player instance, when UseThirdPerson is False.

Public property Camera: TCastleWalkNavigation read FWalkNavigation; deprecated 'use WalkNavigation';

Warning: this symbol is deprecated: use WalkNavigation

 
Public property ThirdPersonNavigation: TCastleThirdPersonNavigation read FThirdPersonNavigation;

Navigation synchronized with this player instance, when UseThirdPerson is True.

The TCastleThirdPersonNavigation.AvatarHierarchy inside is initialized, don't touch it.

The TCastleThirdPersonNavigation.Avatar inside is created, you can further configure it if you want to use UseThirdPerson. Most of all, you can load some model there, like ThirdPersonNavigation.Avatar.Load('castle-data:/avatar.gltf').

Public property UseThirdPerson: Boolean read FUseThirdPerson write SetUseThirdPerson default false;

Whether to use 1st-person WalkNavigation or 3rd-person ThirdPersonNavigation. You have to set this before calling TLevel.Load.

Public property KnockBackSpeed default DefaultPlayerKnockBackSpeed;
 
Public property EnableNavigationDragging: boolean read FEnableNavigationDragging write SetEnableNavigationDragging default true;

Enable navigation by dragging. This results in including niMouseDragging in TCastleNavigation.Input (when player is not Dead or Blocked).

Public property EnableCameraDragging: boolean read FEnableNavigationDragging write SetEnableNavigationDragging default true; deprecated 'use EnableNavigationDragging';

Warning: this symbol is deprecated: use EnableNavigationDragging

 
Public property RenderDebug: boolean read FRenderDebug write FRenderDebug default false;

Show the debug bounding box of the player. Warning: It looks a little confusing (since it's a box around camera).

Generated by PasDoc 0.16.0.