Blitz3D+ Command Reference

FreeEntity entity

Parameters

entity - handle returned by an entity creating function such as CreateCube, CreateLight or LoadMesh

Description

Frees an entity, removing it from the scene and releasing its internal resources.

All child entities parented to the entity are freed along with it - free a vehicle and its wheels, turret and camera go too.

Gotcha: the variable holding the handle (and any variables referencing children) is not reset - it still holds the old number. Using it after FreeEntity causes a runtime error in debug mode, or worse in release mode. Set your variable to 0 after freeing so the rest of your code can test it.

If you only want an entity gone temporarily - a respawning pickup, say - use HideEntity instead and show it again later; hiding and showing is much cheaper than freeing and recreating.

See also: HideEntity, ClearWorld, CopyEntity.

Example

; FreeEntity Example
; ------------------

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

SeedRnd MilliSecs()

camera=CreateCamera()
PositionEntity camera,0,0,-8

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

; Up to 10 floating bubbles
Dim bubbles(10)
count=0

While Not KeyDown(1)

    ; Space spawns a bubble
    If KeyHit(57) And count<10
        count=count+1
        bubbles(count)=CreateSphere(16)
        ScaleEntity bubbles(count),0.5,0.5,0.5
        PositionEntity bubbles(count),Rand(-3,3),Rand(-2,2),Rand(0,3)
        EntityColor bubbles(count),Rand(50,255),Rand(50,255),Rand(50,255)
    EndIf

    ; Enter pops the newest bubble: FreeEntity removes it from the scene
    ; and frees its resources - the old handle must never be used again
    If KeyHit(28) And count>0
        FreeEntity bubbles(count)
        bubbles(count)=0
        count=count-1
    EndIf

    ; Spin the remaining bubbles
    For i=1 To count
        TurnEntity bubbles(i),0,2,0
    Next

    ; 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

    RenderWorld

    Text 0,0,"Space: spawn bubble   Enter: FreeEntity newest bubble   Esc: exit"
    Text 0,20,"Bubbles alive: "+count

    Flip

Wend

End

Index