Castle Game Engine

Class TRigidBody

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleTransform

Declaration

type TRigidBody = class(TComponent)

Description

Rigid body properties for the physics engine, see TCastleTransform.RigidBody.

TODO: For now all the properties of this class, including the Collider and all properties of Collider, must be assigned before setting TCastleTransform.RigidBody .

Hierarchy

Overview

Methods

Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure Setup2D;
Public procedure InitializeTransform(const Transform: TCastleTransform);
Public procedure DeinitializeTransform(const Transform: TCastleTransform);
Public procedure Update(const Transform: TCastleTransform; const SecondsPassed: Single);
Public function GetCollidingTransforms: TCastleTransformList;
Public function PhysicsRayCast(const RayOrigin, RayDirection: TVector3; const MaxDistance: Single): TCastleTransform; overload;
Public function PhysicsRayCast(const RayOrigin, RayDirection: TVector3; const MaxDistance: Single; out Distance: Single): TCastleTransform; overload;

Properties

Public property AngularVelocity: TVector3 read FAngularVelocity write SetAngularVelocity;
Public property AngularVelocityDamp: Single read FAngularVelocityDamp write SetAngularVelocityDamp;
Public property MaximalAngularVelocity: Single read FMaximalAngularVelocity write SetMaximalAngularVelocity;
Public property LinearVelocity: TVector3 read FLinearVelocity write SetLinearVelocity;
Public property LinearVelocityDamp: Single read FLinearVelocityDamp write SetLinearVelocityDamp;
Public property MaximalLinearVelocity: Single read FMaximalLinearVelocity write SetMaximalLinearVelocity;
Public property InitialAngularVelocity: TVector3 read FAngularVelocity write SetAngularVelocity; deprecated 'use AngularVelocity';
Public property InitialLinearVelocity: TVector3 read FLinearVelocity write SetLinearVelocity; deprecated 'use LinearVelocity';
Public property OnCollisionEnter: TCollisionEvent read FOnCollisionEnter write SetOnCollisionEnter;
Public property OnCollisionExit: TCollisionEvent read FOnCollisionExit write SetOnCollisionExit;
Public property OnCollisionStay: TCollisionEvent read FOnCollisionStay write SetOnCollisionStay;
Published property Dynamic: Boolean read FDynamic write FDynamic default true;
Published property Animated: Boolean read FAnimated write FAnimated default false;
Published property Trigger: Boolean read FTrigger write SetTrigger default false;
Published property Collider: TCollider read FCollider;
Published property Gravity: Boolean read FGravity write FGravity default true;
Published property LockTranslation: T3DCoords read FLockTranslation write FLockTranslation;
Published property LockRotation: T3DCoords read FLockRotation write FLockRotation;
Published property Exists: Boolean read FExists write SetExists default true;

Description

Methods

Public constructor Create(AOwner: TComponent); override;
 
Public destructor Destroy; override;
 
Public procedure Setup2D;

Utility function to set common values for physics in 2D games. Locks moving along the Z axis, locks rotating along the X and Y axes.

Public procedure InitializeTransform(const Transform: TCastleTransform);

Connect this rigid body with Transform and Transform.World.

Public procedure DeinitializeTransform(const Transform: TCastleTransform);

Disconnect from Transform.World, if was connected.

Public procedure Update(const Transform: TCastleTransform; const SecondsPassed: Single);
 
Public function GetCollidingTransforms: TCastleTransformList;

Transformations that we collide with currently.

Public function PhysicsRayCast(const RayOrigin, RayDirection: TVector3; const MaxDistance: Single): TCastleTransform; overload;

Cast a ray using physics engine, see what is hit.

The given RayOrigin, RayDirection are in the parent coordinate system of this TCastleTransform. So for example query like this works naturally: MyTransform.RayCast(MyTransform.Translation, MyTransform.Direction, MaxDistance). In case of the overloaded version with Distance parameter, the Distance is consistently in the same, parent coordinate system.

This ignores the collider of this rigid body (to not accidentally collide with your own collider), and checks collisions with the rest of the world in given max distance. Only collisions with the physics colliders (defined inside TRigidBody.Collider) are considered.

The TCastleTransform.Pickable property is ignored by this method, i.e. it considers all colliders regardless of their TCastleTransform.Pickable value. This is in contrast to TCastleTransform.RayCast. In the future this method will become the basis of a new TCastleTransform.RayCast implementation and the concept of "pickable" flag will change into collision layers.

This returns the TCastleTransform that is hit and a distance from RayOrigin to the hit point. Returns Nil (Distance is undefined in this case) if nothing was hit.

Public function PhysicsRayCast(const RayOrigin, RayDirection: TVector3; const MaxDistance: Single; out Distance: Single): TCastleTransform; overload;
 

Properties

Public property AngularVelocity: TVector3 read FAngularVelocity write SetAngularVelocity;
 
Public property AngularVelocityDamp: Single read FAngularVelocityDamp write SetAngularVelocityDamp;
 
Public property MaximalAngularVelocity: Single read FMaximalAngularVelocity write SetMaximalAngularVelocity;
 
Public property LinearVelocity: TVector3 read FLinearVelocity write SetLinearVelocity;
 
Public property LinearVelocityDamp: Single read FLinearVelocityDamp write SetLinearVelocityDamp;
 
Public property MaximalLinearVelocity: Single read FMaximalLinearVelocity write SetMaximalLinearVelocity;
 
Public property InitialAngularVelocity: TVector3 read FAngularVelocity write SetAngularVelocity; deprecated 'use AngularVelocity';

Warning: this symbol is deprecated: use AngularVelocity

 
Public property InitialLinearVelocity: TVector3 read FLinearVelocity write SetLinearVelocity; deprecated 'use LinearVelocity';

Warning: this symbol is deprecated: use LinearVelocity

 
Public property OnCollisionEnter: TCollisionEvent read FOnCollisionEnter write SetOnCollisionEnter;

Occurs when TRigidBody starts colliding with another TRigidBody.

It can occur repeatedly for the same body (in the same time instant) if the collision has many points of contact.

Warning: Do not free the TCastleTransform instances that collide during this event. It would free the rigid body instance, which will crash the physics engine for now. Instead, you can set TCastleTransform.Exists to False (you can free it later, e.g. during TCastleUserInterface.OnUpdate).

Public property OnCollisionExit: TCollisionEvent read FOnCollisionExit write SetOnCollisionExit;

Occurs when TRigidBody stops colliding with another TRigidBody.

Warning: Do not free the TCastleTransform instances that collide during this event. It would free the rigid body instance, which will crash the physics engine for now. Instead, you can set TCastleTransform.Exists to False (you can free it later, e.g. during TCastleUserInterface.OnUpdate).

Public property OnCollisionStay: TCollisionEvent read FOnCollisionStay write SetOnCollisionStay;

Occurs when TRigidBody still collides with another TRigidBody.

Warning: Do not free the TCastleTransform instances that collide during this event. It would free the rigid body instance, which will crash the physics engine for now. Instead, you can set TCastleTransform.Exists to False (you can free it later, e.g. during TCastleUserInterface.OnUpdate).

Published property Dynamic: Boolean read FDynamic write FDynamic default true;

Does the physics simulation move and rotate this object (because of gravity, or because it collides with others).

true (dynamic object, the default)

In this case you cannot change the TCastleTransform.Translation and other transformation properties of the related TCastleTransform after assigning TCastleTransform.RigidBody. They are under the control of the physics engine. You can still reliably read them.

Keep Animated as False in this case. Right now, Animated doesn't actually matter when Dynamic is True, but don't depend on it. In the future, we may enable to set Animated to True, to allow you to explicitly transform objects that are still under control of physics.

false

In this case object is not transformed by the physics simulation. It still collides with other physical objects.

You can change the TCastleTransform.Translation and other transformation properties by your own code. But if you plan to change them very often (e.g. every frame), then set the Animated property to True.

Published property Animated: Boolean read FAnimated write FAnimated default false;

Is the transformation of this object updated often (relevant only when Dynamic = False).

This property is taken into account only if Dynamic = False. When Dynamic = False, you can change the TCastleTransform.Translation and other transformation properties of the related TCastleTransform. This property is an optimization hint to the physics engine, it says how often you will change the transformation.

true (animated object, also known as "kinematic")

The physics engine is prepared that this object can move often, e.g. every frame, so you can animate the related TCastleTransform using any technique.

false (static object)

Changing the transformation properties is costly, it may even be like destroying this object and creating a new one from the point of view of the physics engine, so do not change them often, e.g. every frame.

The upside is that collisions with static objects may be much more optimized, since the physics engine can assume that all the static objects form a completely frozen unmovable geometry in the world.

Published property Trigger: Boolean read FTrigger write SetTrigger default false;

Triggers report when other object collides with them, but still allow the other object to pass through. In other words, colliding with a trigger will not cause the collider to stop or "bounce off" the trigger.

They are useful as sensors. E.g. a trigger may be a coin (like in "Mario") that the player can "consume" by colliding with it.

Triggers report collisions through the same events as other rigid bodies: (TRigidBody.OnCollisionEnter, TRigidBody.OnCollisionStay, TRigidBody.OnCollisionExit).

Published property Collider: TCollider read FCollider;

Shape used for collisions with this object. You cannot assign this property directly, it is automatically assigned when you create a TCollider specifying this TRigidBody as it's parent.

Published property Gravity: Boolean read FGravity write FGravity default true;

Is this object affected by gravity.

Published property LockTranslation: T3DCoords read FLockTranslation write FLockTranslation;

Disable motion (TCastleTransform.Translation change) along the particular (world) axis.

For 2D games, you will usually want to disable motion along the Z axis. Instead of directly changing this property, you can achieve this by calling Setup2D.

Published property LockRotation: T3DCoords read FLockRotation write FLockRotation;

Disable rotation (TCastleTransform.Rotation change) along the particular (world) axis.

For 2D games, you will usually want to disable rotation along the X and Y axes. Instead of directly changing this property, you can achieve this by calling Setup2D.

Published property Exists: Boolean read FExists write SetExists default true;

Controls whether the rigid body is actually processed by the physics engine. When this is False, the rigid body is not updated by the physics engine, and it does not cause collisions with other rigid bodies.

Generated by PasDoc 0.16.0.