Class TCastleCollider

Unit

Declaration

type TCastleCollider = class(TCastleBehavior)

Description

Abstract collider that determines the shape used to determine collisions with physics bodies.

Hierarchy

Overview

Fields

Public nested const DefaultDensity = 1.0;
Public nested const DefaultMass = 0.0;
Public nested const DefaultRestitution = 0.0;
Public nested const DefaultFriction = 0.5;
Public class var AutoSizeMinThickness: Single;
Public AutoSizeMinThickness2D: Single;

Methods

Protected function TotalScale: Single;
Protected function CreateKraftShape(const APhysics: TKraft; const ARigidBody: TKraftRigidBody): TKraftShape; virtual; abstract;
Protected procedure ShapeChangedNotifyRigidBody;
Protected procedure UpdateVisualization; virtual;
Protected procedure WorldAfterAttach; override;
Protected procedure WorldBeforeDetach; override;
Protected function CanAttachToParent(const NewParent: TCastleTransform; out ReasonWhyCannot: String): Boolean; override;
Protected procedure DisableAutoSize;
Protected procedure CalculateSizeCore; virtual;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public function PropertySections(const PropertyName: String): TPropertySections; override;
Public procedure CustomSerialization(const SerializationProcess: TSerializationProcess); override;
Public procedure InternalTransformChanged(const TransformChanged: TCastleTransform); virtual;
Public procedure InternalDesigningBegin; virtual;
Public procedure InternalDesigningEnd; virtual;
Public procedure ParentBeforeDetach; override;
Public procedure InternalAutoSize;
Public procedure CalculateSize;

Properties

Public property Translation: TVector3 read FTranslation write SetTranslation;
Public property Rotation: TVector4 read FRotation write SetRotation;
Published property AutoSize: Boolean read FAutoSize write SetAutoSize default true;
Published property Density: Single read FDensity write SetDensity default DefaultDensity;
Published property Mass: Single read FMass write SetMass default DefaultMass;
Published property Restitution: Single read FRestitution write SetRestitution default DefaultRestitution;
Published property Friction: Single read FFriction write SetFriction default DefaultFriction;
Published property SizeScale: Single read FSizeScale write SetSizeScale default 1.0;
Published property Mode2D: Boolean read FMode2D write SetMode2D default false;
Published property TranslationPersistent: TCastleVector3Persistent read FTranslationPersistent stored StoredWithAutoSize;
Published property RotationPersistent: TCastleVector4RotationPersistent read FRotationPersistent stored StoredWithAutoSize;

Description

Fields

Public nested const DefaultDensity = 1.0;

Default for Density.

Public nested const DefaultMass = 0.0;

Default for Mass, zero means "use Density instead".

Public nested const DefaultRestitution = 0.0;

Default for Restitution.

Public nested const DefaultFriction = 0.5;

Default for Friction.

Public class var AutoSizeMinThickness: Single;

Minimum collider thickness used by AutoSize in 3D mode (when Mode2D = False). Changing this only affects new size calculations.

Public AutoSizeMinThickness2D: Single;

Minimum collider thickness used by AutoSize in 2D mode (when Mode2D = True). Changing this only affects new size calculations.

Methods

Protected function TotalScale: Single;

Total scale, accumulated from all parents TCastleTransform.Scale (converted to scalar following Mode2D) and collider SizeScale.

Protected function CreateKraftShape(const APhysics: TKraft; const ARigidBody: TKraftRigidBody): TKraftShape; virtual; abstract;

This item has no description.

Protected procedure ShapeChangedNotifyRigidBody;

Notify associated TCastleRigidBody that Kraft shape needs to be recreated. This may in turn call TCastleCollider.InitializeKraft and TCastleCollider.CreateKraftShape.

Protected procedure UpdateVisualization; virtual;

Called when the collider size has changed and needs to be updated.

Protected procedure WorldAfterAttach; override;

This item has no description. Showing description inherited from TCastleBehavior.WorldAfterAttach.

Called after Parent became part of World. Called only if ListenWorldChange is True.

Protected procedure WorldBeforeDetach; override;

This item has no description. Showing description inherited from TCastleBehavior.WorldBeforeDetach.

Called before Parent stops being part of World. Called only if ListenWorldChange is True.

This is also called at the destruction of behavior (more precisely from BeforeDestruction now). Even in this case, we guarantee that Parent is still valid during this call, and not in half-destroyed state. Before the actual destructor of TCastleBehavior we do BeforeParentDetach and BeforeWorldDetach and set Parent to Nil.

Protected function CanAttachToParent(const NewParent: TCastleTransform; out ReasonWhyCannot: String): Boolean; override;

Only one TCastleCollider behavior can be added to a given TCastleTransform so we check that here.

Protected procedure DisableAutoSize;

Sets AutoSize = False, unless this is called inside InternalAutoSize or at loading. Call this when something changes collider size explicitly, e.g. TCastleSphereCollider.Radius changes.

Protected procedure CalculateSizeCore; virtual;

Recalculate collider size. Do not be concerned about AutoSize here, just update collider properties. The default implementation resets Translation and Rotation.

Public constructor Create(AOwner: TComponent); override;

This item has no description.

Public destructor Destroy; override;

This item has no description.

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 CustomSerialization(const SerializationProcess: TSerializationProcess); override;

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

Override this method to call various methods of SerializationProcess, which in turn allows to serialize/deserialize things that are not published. This allows to serialize/deserialize with more freedom, e.g. to serialize/deserialize some private field.

Public procedure InternalTransformChanged(const TransformChanged: TCastleTransform); virtual;

Notify this collider that given TCastleTransform changed. It can provoke AutoSize recalculation (if Parent changed) or other reactions (e.g. mesh update, if TransformChanged corresponds to Mesh).

Public procedure InternalDesigningBegin; virtual;

Create collider visualization.

Public procedure InternalDesigningEnd; virtual;

Destroy collider visualization.

Public procedure ParentBeforeDetach; override;

This item has no description. Showing description inherited from TCastleBehavior.ParentBeforeDetach.

Called before Parent changed, e.g. at the beginning of TCastleTransform.RemoveBehavior.

This is also called at the destruction of behavior (more precisely from BeforeDestruction now). Even in this case, we guarantee that Parent is still valid during this call, and not in half-destroyed state. Before the actual destructor of TCastleBehavior we do BeforeParentDetach and BeforeWorldDetach and set Parent to Nil.

Public procedure InternalAutoSize;

Recalculate collider size using parent bounding box, only if AutoSize says we should recalculate. Ignored if not AutoSize.

Public procedure CalculateSize;

Calculate collider size to reflect parent bounding box now. This works regardless of AutoSize value, and doesn't change AutoSize value. The idea is that you can call it when

  1. You have AutoSize = False and want to adjust size to bounding box at specific moment.

  2. You have AutoSize = True but still want to force recalculation right now, because AutoSize doesn't do it too eagerly (see AutoSize description).

See also
AutoSize
Automatically calculate collider properties that determine collider size based on the parent transformation bounding box.

Properties

Public property Translation: TVector3 read FTranslation write SetTranslation;

Local collider translation, relative to parent TCastleTransform. Note that CalculateSize and AutoSize mechanisms set it automatically.

Public property Rotation: TVector4 read FRotation write SetRotation;

Local collider rotation, relative to parent TCastleTransform. Note that CalculateSize and AutoSize mechanisms set it automatically.

Published property AutoSize: Boolean read FAutoSize write SetAutoSize default true;

Automatically calculate collider properties that determine collider size based on the parent transformation bounding box.

When this is set, properties like TCastleSphereCollider.Radius or TCastleBoxCollider.Size are automatically updated to the best values to match collider size with the parent TCastleTransform.LocalBoundingBox.

Note that even when this is True, the collider size recalculation is not done too "eagerly", i.e. the collider size is not recalculated on every possible change. For example, if you animate a TCastleScene, then bounding box may change every frame (note: it depends on the technique; e.g. glTF models with skinned animation have a complete bounding box of the animation precalculated and constant; but X3D models morphed using CoordinateInterpolator have bounding box changing every frame).

But it would be bad to change the collider size (even at design-time) every frame. That's because changing the collider size may imply (for the underlying physics engine) recreation of internal srtuctures and reinitialization of the collision state. So in the ideal case, the collider size should just stay constant once the object has been added to some TCastleViewport and it may interact with other physics bodies.

You can always manually force recalculation of the collider size using the CalculateSize method.

Published property Density: Single read FDensity write SetDensity default DefaultDensity;

Density (per volume) in kg, this implicitly determines mass (volume is automatically calculated by the physics engine). If you instead prefer to explicitly set mass, set Mass property to something non-zero.

Published property Mass: Single read FMass write SetMass default DefaultMass;

Mass in kg. When non-zero, this overrides the automatically calculated mass from the volume and Density.

Published property Restitution: Single read FRestitution write SetRestitution default DefaultRestitution;

Larger restitution means that on collision, this object behaves more elastic. Reasonable values are between 0 (inelastic) and 1 (elastic). See https://en.wikipedia.org/wiki/Coefficient_of_restitution .

Published property Friction: Single read FFriction write SetFriction default DefaultFriction;

Larger friction means that it is harder for body to slide alongside another object.

Published property SizeScale: Single read FSizeScale write SetSizeScale default 1.0;

Local collider size scale.

This is particularly useful if AutoSize mechanism calculated too large box. For collision purposes, you sometimes want a collider that is a bit smaller than the bounding box/sphere around the object. Maybe it should even be too small at certain places, but then it will make a better fit overall.

You can achieve this (and still keep using AutoSize) by adjusting this property e.g. to 0.9 to have collider be 90% of what AutoSize calculated.

This is not reset by CalculateSize and AutoSize mechanisms (in contrast to Translation, Rotation) because the idea is that user adjusts the auto-calculated size this way.

Published property Mode2D: Boolean read FMode2D write SetMode2D default false;

Make various features (in particular automatic size calculation caused by AutoSize) better adjusted to 2D models, where the user-visible shape is in XY and the Z coordinate (position in Z, thickness in Z) should have little or no effect on the result.

More precisely, when this is True:

  1. AutoSize estimates collider 3D sizes (because internally Kraft colliders are always in 3D) based on geometry sizes only in XY dimensions. So it ignores how thin or thick is you geometry along the Z axis.

  2. AutoSize assumes a bit larger "minimum thickness" for 2D, because typical 2D worlds use larger units. See AutoSizeMinThickness vs AutoSizeMinThickness2D.

  3. Non-uniform scale (coming from accumulated TCastleTransform.Scale on all our parents) is handled differently. When Mode2D = True, the non-uniform scale is converted into a scalar using Approximate2DScale, so it only looks at XY coordinates. When Mode2D = False, the non-uniform scale is converted using Approximate3DScale, so it looks at all coordinates.

  4. In the future, esp. if we integrate with other physics engines like Box2D, it is possible that some colliders in 2D mode will have a shape much more suitable in 2D. "Suitable in 2D" ideally means "Z coordinate is ignored". This means that a 2D collider should (ideally) behave as if it is infinite in Z.

    For example a 2D sphere collider may effectively be an infinite cylinder. That is: it should be a circle in XY, but extruded into infinity in -Z and +Z. This is not right now how the TCastleSphereCollider behaves with Mode2D = True, but it may be in the future.

Published property TranslationPersistent: TCastleVector3Persistent read FTranslationPersistent stored StoredWithAutoSize;

Translation 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 Translation directly.

See also
Translation
Local collider translation, relative to parent TCastleTransform.
Published property RotationPersistent: TCastleVector4RotationPersistent read FRotationPersistent stored StoredWithAutoSize;

Rotation 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 Rotation directly.

See also
Rotation
Local collider rotation, relative to parent TCastleTransform.

Generated by PasDoc 0.16.0.