Class TCastleCapsuleCollider

Description

Hierarchy

Unit

CastleTransform

Declaration

type TCastleCapsuleCollider = class(TCastleCollider)

Description

Collide as a capsule. Add this collider to TCastleTransform behaviors, along with a TCastleRigidBody, to make the given TCastleTransform be affected by physics and collide with other physics bodies.

Source: transform/castletransform_physics.inc (line 580).

Hierarchy

TObject
TPersistent
TComponent
TCastleComponent
TCastleBehavior
TCastleCollider
TCastleCapsuleCollider

Show Additional Members: Inherited Protected

Overview

Constants

Public	`DefaultDensity = 1.0;`
Public	`DefaultMass = 0.0;`
Public	`DefaultRestitution = 0.0;`
Public	`DefaultFriction = 0.5;`

Fields

Public	`class var AutoSizeMinThickness: Single;`
Public	`AutoSizeMinThickness2D: Single;`
Public	`AutoSizeMinThickness2DDepth: Single;`

Methods

Protected	`function GetInternalText: String; virtual;`
Protected	`procedure SetInternalText(const Value: String); virtual;`
Protected	`procedure SetName(const Value: TComponentName); override;`
Protected	`procedure TranslateProperties(const TranslatePropertyEvent: TTranslatePropertyEvent); virtual;`
Public	`procedure SetTransient;`
Public	`procedure AddNonVisualComponent(const NonVisualComponent: TComponent);`
Public	`procedure InsertNonVisualComponent(const Index: Integer; const NonVisualComponent: TComponent);`
Public	`procedure RemoveNonVisualComponent(const NonVisualComponent: TComponent);`
Public	`function NonVisualComponentsIndexOf(const NonVisualComponent: TComponent): Integer;`
Public	`function NonVisualComponentsCount: Integer;`
Public	`function NonVisualComponentsEnumerate: TNonVisualComponentsEnumerator;`
Public	`function ValueIsStreamed: Boolean; virtual;`
Public	`procedure DesignerInfo(const SList: TStrings); virtual;`
Public	`procedure DesignerWarnings(const SList: TStrings); virtual;`
Protected	`procedure Update(const SecondsPassed: Single; var RemoveMe: TRemoveType); virtual;`
Protected	`procedure BeforeRender( const CameraView: TViewVectors; const ParentParentWorldTransformation: TTransformation); virtual;`
Protected	`procedure ParentChanged; virtual; deprecated 'Use ParentAfterAttach / ParentBeforeDetach or WorldAfterAttach / WorldBeforeDetach';`
Protected	`procedure ParentAfterAttach; virtual;`
Public	`procedure BeforeDestruction; override;`
Public	`function World: TCastleAbstractRootTransform;`
Protected	`function StoredWithAutoSize: Boolean;`
Protected	`function TotalScale: Single;`
Protected	`procedure DeinitializePhysicsEngineObjects; virtual;`
Protected	`procedure ShapeChangedNotifyRigidBody;`
Protected	`procedure WorldAfterAttach; override;`
Protected	`procedure WorldBeforeDetach; override;`
Protected	`function CanAttachToParent(const NewParent: TCastleTransform; out ReasonWhyCannot: String): Boolean; override;`
Protected	`procedure DisableAutoSize;`
Public	`destructor Destroy; override;`
Public	`procedure CustomSerialization(const SerializationProcess: TSerializationProcess); override;`
Public	`procedure InternalTransformChanged(const TransformChanged: TCastleTransform); virtual;`
Public	`procedure ParentBeforeDetach; override;`
Public	`procedure InternalAutoSize;`
Public	`procedure CalculateSize;`
Protected	`function CreateKraftShape(const APhysics: TKraft; const ARigidBody: TKraftRigidBody): TKraftShape; override;`
Protected	`procedure CalculateSizeCore; override;`
Protected	`procedure UpdateVisualization; override;`
Public	`constructor Create(AOwner: TComponent); override;`
Public	`function PropertySections(const PropertyName: String): TPropertySections; override;`
Public	`procedure InternalDesigningBegin; override;`
Public	`procedure InternalDesigningEnd; override;`

Properties

Public	`property NonVisualComponents [const Index: Integer]: TComponent read GetNonVisualComponents;`
Public	`property IsLoading: Boolean read FIsLoading;`
Public	`property Parent: TCastleTransform read FParent;`
Public	`property ListenWorldChange: Boolean read FListenWorldChange write SetListenWorldChange;`
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;`
Published	`property Radius: Single read FRadius write SetRadius stored StoredWithAutoSize;`
Published	`property Height: Single read FHeight write SetHeight stored StoredWithAutoSize;`

Description

Constants

Public DefaultDensity = 1.0;

This item is declared in ancestor TCastleCollider.

Default for Density.

Source: transform/castletransform_physics.inc (line 292).

Public DefaultMass = 0.0;

This item is declared in ancestor TCastleCollider.

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

Source: transform/castletransform_physics.inc (line 295).

Public DefaultRestitution = 0.0;

This item is declared in ancestor TCastleCollider.

Default for Restitution.

Source: transform/castletransform_physics.inc (line 298).

Public DefaultFriction = 0.5;

This item is declared in ancestor TCastleCollider.

Default for Friction.

Source: transform/castletransform_physics.inc (line 301).

Fields

Public class var AutoSizeMinThickness: Single;

This item is declared in ancestor TCastleCollider.

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

Source: transform/castletransform_physics.inc (line 305).

Public AutoSizeMinThickness2D: Single;

This item is declared in ancestor TCastleCollider.

Minimum collider thickness used by AutoSize in 2D mode (when Mode2D = True). This is used for axis other than Z (like X, Y, or collider radiuses that affect size in a few axis). Changing this only affects new size calculations.

Source: transform/castletransform_physics.inc (line 311).

Public AutoSizeMinThickness2DDepth: Single;

This item is declared in ancestor TCastleCollider.

Minimum collider thickness used by AutoSize in 2D mode (when Mode2D = True) for Z. This is used only by TCastleBoxCollider now, as only that collider has specific size in Z. Changing this only affects new size calculations.

Source: transform/castletransform_physics.inc (line 316).

Methods

Protected function GetInternalText: String; virtual;

This item is declared in ancestor TCastleComponent.

This item has no description.

Source: base/castleclassutils.pas (line 575).

Protected procedure SetInternalText(const Value: String); virtual;

This item is declared in ancestor TCastleComponent.

This item has no description.

Source: base/castleclassutils.pas (line 576).

Protected procedure SetName(const Value: TComponentName); override;

This item is declared in ancestor TCastleComponent.

This item has no description.

Source: base/castleclassutils.pas (line 577).

Protected procedure TranslateProperties(const TranslatePropertyEvent: TTranslatePropertyEvent); virtual;

This item is declared in ancestor TCastleComponent.

Enumerate all properties that are possible to translate in this component. E.g. in TCastleLabel it will return TCastleLabel.Caption, in TCastleEdit it will return TCastleEdit.Text and TCastleEdit.Placeholder.

Returns only non-empty properties, thus assuming that if current (by convention, English) text is empty, then there is no point in translating it. Moreover descendants may define boolean properties to exclude particular text from translating, e.g. TCastleLabel.CaptionTranslate, TCastleEdit.TextTranslate, TCastleEdit.PlaceholderTranslate.

It is not recursive (it doesn't enumerate children properties). Use global TranslateProperties procedure to call this on a hierarchy of TComponent.

You usually don't want to call this method (it is called by other engine routines). But you may find it useful to override this, if you define new component.

Source: base/castleclassutils.pas (line 598).

Public procedure SetTransient;

This item is declared in ancestor TCastleComponent.

Ignore this component when serializing parent's TCastleUserInterface.Controls list or TCastleTransform.List, and do not show this component in CGE editor. This simply sets csTransient flag in ComponentStyle.

This is useful for children that are automatically managed by the parent, and should not be modified by user code. For example, TCastleCheckbox is internally composed from TCastleImageControl and TCastleLabel children, but we don't want to serialize or even show these children to user.

Note that if you want to prevent this component from serializing as part of TCastleUserInterface.Controls list or TCastleTransform.List, but you still want it to be visible in CGE editor, then make it a "subcomponent" instead, by SetSubComponent(true).

Note that both csSubComponent and csTransient only disable the component serialization as part of parent's lists enumerated by CustomSerialization (see internal TCastleUserInterface.SerializeChildrenEnumerate , TCastleTransform.SerializeChildrenEnumerate, TCastleTransform.SerializeBehaviorsEnumerate).

If you will make the component published in its own property (which is normal for "subcomponents") then it will be serialized anyway, just as part of it's own property (like TCastleScrollView.ScrollArea). So to really avoid serializing a children component make it csSubComponent and/or csTransient, and do not publish it.

Source: base/castleclassutils.pas (line 663).

Public procedure AddNonVisualComponent(const NonVisualComponent: TComponent);

This item is declared in ancestor TCastleComponent.

Add non-visual component to this component. This is used to organize non-visual components in a tree hierarchy, in CGE designs and editor.

Parameters

RemoveMe: Set this to rtRemove or rtRemoveAndFree to remove this component from Parent after this call finished. rtRemoveAndFree additionally will free this item. Initially it's rtNone when this method is called.

Source: transform/castletransform_behavior.inc (line 52).

Protected procedure BeforeRender( const CameraView: TViewVectors; const ParentParentWorldTransformation: TTransformation); virtual;

This item is declared in ancestor TCastleBehavior.

Event called right before rendering the parent TCastleTransform. Override this if you have to adjust the parent transformation strictly before the rendering.

Compared to adjusting the parent transformation in e.g. Update, adjusting the parent transformation here has advantages:

There's no 1-frame delay between moving the thing that causes the change (like camera) and updating the thing that reacts to it (like a transformation with a billboard).
We adjust transformation before rendering each occurrence of TCastleTransform in the viewport tree. This matters if given TCastleTransform may occur multiple times in the viewport tree, directly or through TCastleTransformReference.
We adjust transformation before each render, so things are OK if given TCastleTransform is present in multiple viewports (see https://castle-engine.io/multiple_viewports_to_display_one_world).

For example, adjusting the TCastleTransform done by the TCastleBillboard is done using this method. The transformation in this case is determined by the camera and parent's parent transformation. The transformation has to be applied without any delay (even a 1-frame delay would be visible, as artifacts caused by billboard not perfectly aligned with the camera would be visible – blending sort along camera direction in sort3D is not perfect if billboard doesn't exactly match camera direction). And the transformation with billboard may be present in multiple viewports and/or multiple times in the same viewport tree.

Parameters

CameraView: Current camera vectors, in world coordinates, used to render the scene now.
ParentParentWorldTransformation: World transformation of the parent of the parent of this behavior. The name is kind of convoluted, but consistent: When the parent of this behavior has exactly one parent TCastleTransform (not zero, not more) then ParentParentWorldTransformation.Transform is equivalent to Parent.Parent.WorldTransform.

Source: transform/castletransform_behavior.inc (line 103).

Protected procedure ParentChanged; virtual; deprecated 'Use ParentAfterAttach / ParentBeforeDetach or WorldAfterAttach / WorldBeforeDetach';

This item is declared in ancestor TCastleBehavior.

Warning: this symbol is deprecated: Use ParentAfterAttach / ParentBeforeDetach or WorldAfterAttach / WorldBeforeDetach

Called after Parent changed, at the end of TCastleTransform.AddBehavior, TCastleTransform.RemoveBehavior.

Source: transform/castletransform_behavior.inc (line 109).

Protected procedure ParentAfterAttach; virtual;

This item is declared in ancestor TCastleBehavior.

Called after Parent changed, e.g. at the end of TCastleTransform.AddBehavior.

Source: transform/castletransform_behavior.inc (line 113).

Public procedure BeforeDestruction; override;

This item is declared in ancestor TCastleBehavior.

This item has no description.

Source: transform/castletransform_behavior.inc (line 161).

Public function World: TCastleAbstractRootTransform;

This item is declared in ancestor TCastleBehavior.

Reference to the root transformation (typically matching the TCastleViewport.Items value) corresponding to the parent of this behavior.

May be Nil if the behavior is not yet added to the parent TCastleTransform, or when the TCastleTransform is not yet part of the TCastleAbstractRootTransform (which means that TCastleTransform is not added to the viewport yet). You can use ListenWorldChange and override WorldBeforeDetach, WorldAfterAttach to be notified when this changes.

Source: transform/castletransform_behavior.inc (line 184).

Protected function StoredWithAutoSize: Boolean;

This item is declared in ancestor TCastleCollider.

Use this for "stored" for properties that are auto-calculated when AutoSize.

Source: transform/castletransform_physics.inc (line 253).

Protected function TotalScale: Single;

This item is declared in ancestor TCastleCollider.

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

Source: transform/castletransform_physics.inc (line 257).

Protected procedure DeinitializePhysicsEngineObjects; virtual;

This item is declared in ancestor TCastleCollider.

This item has no description.

Source: transform/castletransform_physics.inc (line 262).

Protected procedure ShapeChangedNotifyRigidBody;

This item is declared in ancestor TCastleCollider.

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

Source: transform/castletransform_physics.inc (line 267).

Protected procedure WorldAfterAttach; override;

This item is declared in ancestor TCastleCollider.

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

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

Source: transform/castletransform_physics.inc (line 271).

Protected procedure WorldBeforeDetach; override;

This item is declared in ancestor TCastleCollider.

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.

Source: transform/castletransform_physics.inc (line 272).

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

This item is declared in ancestor TCastleCollider.

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

Source: transform/castletransform_physics.inc (line 276).

Protected procedure DisableAutoSize;

This item is declared in ancestor TCastleCollider.

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.

Source: transform/castletransform_physics.inc (line 283).

Public destructor Destroy; override;

This item is declared in ancestor TCastleCollider.

This item has no description.

Source: transform/castletransform_physics.inc (line 319).

Public procedure CustomSerialization(const SerializationProcess: TSerializationProcess); override;

This item is declared in ancestor TCastleCollider.

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.

Source: transform/castletransform_physics.inc (line 321).

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

This item is declared in ancestor TCastleCollider.

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).

Source: transform/castletransform_physics.inc (line 326).

Public procedure ParentBeforeDetach; override;

This item is declared in ancestor TCastleCollider.

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

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

Source: transform/castletransform_physics.inc (line 333).

Public procedure InternalAutoSize;

This item is declared in ancestor TCastleCollider.

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

Source: transform/castletransform_physics.inc (line 337).

Public procedure CalculateSize;

This item is declared in ancestor TCastleCollider.

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

You have AutoSize = False and want to adjust size to bounding box at specific moment.
You have AutoSize = True but still want to force recalculation right now, because AutoSize doesn't do it too eagerly (see AutoSize description).

Properties

Public property NonVisualComponents [const Index: Integer]: TComponent read GetNonVisualComponents;

This item is declared in ancestor TCastleComponent.

Components added by AddNonVisualComponent.

Source: base/castleclassutils.pas (line 698).

Public property IsLoading: Boolean read FIsLoading;

This item is declared in ancestor TCastleComponent.

Is the component during deserialization now.

Note: We can't use csLoading in ComponentState because in Delphi it is not possible to control it from CastleComponentSerialize.

Source: base/castleclassutils.pas (line 711).

Public property Parent: TCastleTransform read FParent;

This item is declared in ancestor TCastleBehavior.

Parent TCastleTransform of this behavior. Change it by doing TCastleTransform.AddBehavior, TCastleTransform.RemoveBehavior.

Nil if this behavior is not yet added to a parent.

Source: transform/castletransform_behavior.inc (line 191).

Public property ListenWorldChange: Boolean read FListenWorldChange write SetListenWorldChange;

This item is declared in ancestor TCastleBehavior.

Set this to True to receive WorldBeforeDetach, WorldAfterAttach calls.

Source: transform/castletransform_behavior.inc (line 194).

Public property Translation: TVector3 read FTranslation write SetTranslation;

This item is declared in ancestor TCastleCollider.

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

Source: transform/castletransform_physics.inc (line 357).

Public property Rotation: TVector4 read FRotation write SetRotation;

This item is declared in ancestor TCastleCollider.

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

Source: transform/castletransform_physics.inc (line 361).

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

This item is declared in ancestor TCastleCollider.

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.

Source: transform/castletransform_physics.inc (line 387).

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

This item is declared in ancestor TCastleCollider.

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.

Source: transform/castletransform_physics.inc (line 393).

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

This item is declared in ancestor TCastleCollider.

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

Source: transform/castletransform_physics.inc (line 398).

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

This item is declared in ancestor TCastleCollider.

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 .

Source: transform/castletransform_physics.inc (line 404).

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

This item is declared in ancestor TCastleCollider.

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

Source: transform/castletransform_physics.inc (line 408).

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

This item is declared in ancestor TCastleCollider.

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.

Source: transform/castletransform_physics.inc (line 426).

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

This item is declared in ancestor TCastleCollider.

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:

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.
AutoSize assumes a bit larger "minimum thickness" for 2D, because typical 2D worlds use larger units. Moreover, it assumes even larger thickness in Z, to avoid too thin boxes (that would not be detected as collidable). See AutoSizeMinThickness, AutoSizeMinThickness2D, AutoSizeMinThickness2DDepth.
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.
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.

Source: transform/castletransform_physics.inc (line 463).

Published property TranslationPersistent: TCastleVector3Persistent read FTranslationPersistent stored StoredWithAutoSize;

This item is declared in ancestor TCastleCollider.

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.

Castle Game Engine

API Reference

Class TCastleCapsuleCollider

Unit

Declaration

Description

Hierarchy

Overview

Constants

Fields

Methods

Properties

Description

Constants

Fields

Methods

See also

See also

See also

See also

Parameters

Parameters

See also

Properties

See also

See also