Blitz3D+ Command Reference

CopyEntity ( entity[,parent] )

Parameters

entity - entity handle

parent (optional) - entity that will act as parent to the copy

Description

Creates a copy of an entity and returns the handle of the new copy.

The copy is a new entity instance of an existing entity's mesh. Entity properties - position, rotation, colour, alpha and so on - are individual to each copy, but the mesh and surface data are shared. Mesh edits such as VertexCoords, RotateMesh or PaintSurface made through any copy affect every copy. Use CopyMesh when the new mesh needs independently editable geometry.

Because the geometry is shared, CopyEntity is the normal way to fill a scene with repeated objects - forests, rocks, crates, bullets - far more cheaply than loading or creating each one from scratch. In Extended mode, compatible opaque mesh copies are grouped automatically into GPU-instanced draws, so large numbers of copies render very quickly; no separate CreateInstance command is required. Grouping is an optimisation only, so copies with different materials or other incompatible state still render correctly as ordinary draws.

If a parent entity is specified, the copy is created at the parent entity's position; otherwise it is created at 0,0,0. The parent relationship is one way: moving the parent moves the copy, but moving the copy does not affect the parent.

See also: CopyMesh, LoadMesh, FreeEntity, EntityParent.

Example

; CopyEntity Example
; ------------------

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

SeedRnd MilliSecs()

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

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

; The original crate - every copy will share this entity's mesh
crate=CreateCube()
ScaleMesh crate,0.4,0.4,0.4

copies=0

While Not KeyDown(1)

    ; Space creates a copy of the crate at a random position
    If KeyHit(57)
        copy=CopyEntity(crate)
        ; Entity properties like colour and position are per-copy...
        EntityColor copy,Rand(50,255),Rand(50,255),Rand(50,255)
        PositionEntity copy,Rand(-2,2),Rand(-2,2),Rand(0,3)
        copies=copies+1
    EndIf

    ; ...but the MESH is shared, so rotating the original mesh spins every copy too
    RotateMesh crate,0.25,0.35,0.45

    ; 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: copy the crate   Arrow keys: move camera   Esc: exit"
    Text 0,20,"CopyEntity called "+copies+" times - all copies share one mesh"

    Flip

Wend

End

Index