Blitz3D+ Command Reference

CreateSprite ( [parent] )

Parameters

parent (optional) - entity to parent the sprite to; 0 (default) for none

Description

Creates a sprite entity and returns its handle.

A sprite is a flat rectangle made of two triangles that, by default, turns to face the camera wherever it goes. It is created at 0,0,0 and spans from -1,-1 to +1,+1, so a fresh sprite is two units across.

Two things make sprites worth reaching for. They are only two polygons each, so you can have thousands on screen - which is what makes them the backbone of particle effects, explosions, smoke, sparks, bullet trails and 2D-style games built in 3D. And because they turn to face the camera, a well-drawn sprite reads as a solid object from every angle without ever being one.

Sprites have no mesh you can get at, so the vertex and surface commands do not apply, and they have rotation and scaling commands of their own: RotateSprite and ScaleSprite work in the flat plane of the sprite, where RotateEntity and ScaleEntity would not do what you want. HandleSprite moves the pivot, and SpriteViewMode changes how the sprite turns.

A new sprite has no texture. Put one on with EntityTexture, or use LoadSprite, which creates the sprite and loads its texture in one step. For soft-edged effects, texture flag 2 with additive EntityBlend is the usual recipe.

The optional parent makes the sprite a child of another entity, so moving the parent moves the sprite; the relationship is one way, and the sprite still starts at 0,0,0 in the parent local space rather than at the parent position.

See also: LoadSprite, SpriteViewMode, ScaleSprite, RotateSprite, HandleSprite, EntityTexture.

Example

; CreateSprite Example
; --------------------

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

camera=CreateCamera()
PositionEntity camera,0,1,-5

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

ground=CreatePlane()
EntityTexture ground,LoadTexture("media/MossyGround.BMP")

SeedRnd MilliSecs()

; A campfire built from ember sprites. CreateSprite makes a flat
; two-triangle quad that always faces the camera - cheap enough
; to use by the dozen for particle effects like this.
Dim ember(15)
Dim rise#(15)
For i=0 To 15
    ember(i)=CreateSprite()
    ScaleSprite ember(i),0.15,0.15
    EntityColor ember(i),255,Rand(80,180),30
    ; Additive blending makes the embers glow
    EntityBlend ember(i),3
    rise(i)=Rnd(0.01,0.04)
    PositionEntity ember(i),Rnd(-0.5,0.5),Rnd(0,2.5),Rnd(-0.5,0.5)
Next

While Not KeyDown(1)

    ; Drift each ember upwards and recycle it at the top
    For i=0 To 15
        MoveEntity ember(i),Rnd(-0.01,0.01),rise(i),0
        If EntityY(ember(i))>2.5 Then PositionEntity ember(i),Rnd(-0.5,0.5),0,Rnd(-0.5,0.5)
    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,"Arrows: move camera   Esc: exit"
    Text 0,20,"CreateSprite made 16 ember particles - orbit them: they always face you"

    Flip

Wend

End

Index