CreateCapsule ( [radius#][,height#][,segments][,parent] )

Parameters

radius# (optional) - radius of the body and its rounded ends; 0.5 (default)

height# (optional) - full height from end to end, rounded ends included; at least twice the radius; 2 (default)

segments (optional) - segments round the capsule, from 3 to 256; 24 (default)

parent (optional) - parent entity for the new mesh; 0 for none (default)

Description

Creates an upright capsule - a cylinder with rounded ends - and returns its handle.

The capsule stands on the Y axis, centred on the origin. height# is the full end-to-end height with the ends included, the same measurement EntityCapsule and PhysicsBodyCapsule use, so a character's visible body and its collider can share the same two numbers: CreateCapsule(0.3,1.8) for a person 1.8 m tall. A height of exactly twice the radius gives a sphere.

Use it for characters, pills, rounded posts and limbs instead of a scaled cylinder or sphere. Scaling squashes or stretches the rounded ends, so give the size here and leave the entity's scale at 1.

The capsule is one surface, shaded smoothly. A texture wraps once round it, and V follows the distance down the outline from 0 at the top to 1 at the bottom, so the image is not squeezed onto the ends.

Automatic EntityPhysics gives it an exact capsule collider, static or moving, so a dropped capsule topples and rolls as it should. PositionMesh, RotateMesh, ScaleMesh and FitMesh keep this, so a shape you have turned or resized with them keeps its collider. Editing its vertex positions or triangles, AddMesh or FlipMesh makes it an ordinary mesh again, and an explicit EntityPhysics shape, EntityBox, EntityRadius, EntityCapsule or EntityConvex always wins. A capsule laid on its side with RotateMesh is therefore still a capsule. It is a closed solid, so it works with the CSG commands.

Arguments are checked in release builds too: a radius or height that is not a positive number, a height less than twice the radius, or segments outside 3 to 256 stops the program with a runtime error naming the argument.

See also: EntityCapsule, PhysicsBodyCapsule, CreateCylinder, CreateSphere, EntityPhysics.

Example

; CreateCapsule Example
; ---------------------

Graphics3D 640,480,0,2
SetBuffer BackBuffer()

; Automatic entity physics runs on the Box3D collision backend
SetCollisionBackend 1

Const SCENERY=1
Const PROPS=2

camera=CreateCamera()
PositionEntity camera,0,3,-9
RotateEntity camera,15,0,0

light=CreateLight()
RotateEntity light,45,-25,0

; A static floor for the capsules to land on
ground=CreateCube()
ScaleEntity ground,5,0.5,5
PositionEntity ground,0,-0.5,0
EntityColor ground,65,85,100
EntityType ground,SCENERY
EntityPhysics ground,0

; Capsules hit the floor and each other
Physics PROPS,SCENERY
Physics PROPS,PROPS

SeedRnd MilliSecs()
Dim capsules(20)
count=0

; Sizes are kept in steps: radius in 5 cm, height in 25 cm
radius_steps=6
height_steps=7

; The first three drop by themselves, a moment apart
auto_drops=3
next_drop=MilliSecs()

timer=CreateTimer(60)

While Not KeyDown(1)

    ; - / + change the radius, [ / ] the height; a capsule is never shorter than it is wide
    If KeyHit(12) And radius_steps>2 Then radius_steps=radius_steps-1
    If KeyHit(13) And radius_steps<12 Then radius_steps=radius_steps+1
    If KeyHit(26) And height_steps>1 Then height_steps=height_steps-1
    If KeyHit(27) And height_steps<12 Then height_steps=height_steps+1
    radius#=radius_steps*0.05
    height#=height_steps*0.25
    If height<radius*2 Then height=radius*2

    ; Space drops a capsule of the chosen size
    If (KeyHit(57) Or (auto_drops>0 And MilliSecs()>next_drop)) And count<20 Then
        auto_drops=auto_drops-1
        next_drop=MilliSecs()+700
        capsule=CreateCapsule(radius,height)
        EntityColor capsule,Rand(100,255),Rand(100,255),Rand(100,255)
        PositionEntity capsule,Rnd(-1,1),5,Rnd(-1,1)
        RotateEntity capsule,Rnd(360),0,Rnd(-60,60)
        EntityType capsule,PROPS
        ; Automatic physics recognises the capsule and gives it a capsule collider
        EntityPhysics capsule
        capsules(count)=capsule
        count=count+1
    EndIf

    ; R clears the floor
    If KeyHit(19) Then
        For index=0 To count-1
            FreeEntity capsules(index)
        Next
        count=0
    EndIf

    ; Arrow keys move the camera
    If KeyDown(200) Then MoveEntity camera,0,0,0.1
    If KeyDown(208) Then MoveEntity camera,0,0,-0.1
    If KeyDown(203) Then TurnEntity camera,0,1,0
    If KeyDown(205) Then TurnEntity camera,0,-1,0

    UpdateWorld
    RenderWorld

    Text 0,0,"Arrows: camera   - / + : radius   [ / ] : height   Space: drop   R: clear   Esc: exit"
    Text 0,20,"CreateCapsule("+radius+","+height+")   capsules: "+count+" of 20"
    Text 0,40,"The height includes both rounded ends, as in EntityCapsule"

    Flip
    WaitTimer timer

Wend

End

Index