GetFirstSprite - Learn To Code - PlayBASIC Documentation

GetFirstSprite

FirstSpriteIndex = GetFirstSprite()

Parameters: NONE

Returns:

FirstSpriteIndex = The Index of the First sprite in the sprite list

      The GetFirstSprite function returns the Index of the last created Sprite in the internal sprite list.

      Active sprites, like all resources in PlayBasic are internally managed through a linked list. Each time a new sprite is created (regardless of it's sprite index) , it's placed at the head of the list. What GetFirstSprite does, is grabs the sprite index from the head of the list, whatever it might be.

      Once we have the first sprite in the list, we can then step through all the created sprites using GetNextSprite.

      I.e This sample code steps through the entire sprite list.

; Grab the first Sprite Index from the head
; of the sprite link list and place it in the
; variable ThisSprite
  ThisSprite=GetFirstSprite()

; Start of While/EndWhile loop. The loop will continue
; until "ThisSprite" variable is equal to or lower than zero
; (end of list)
  While ThisSprite>0
   ; << Do something with This Sprite here >>


   ; Get the next sprite  in the List
     ThisSprite=GetNextSprite(ThisSprite)

   ; Continue the While loop
  EndWhile

PlayBasic uses the linked list in everything from rendering to collsion (ie. DrawAllSprites, DrawOrderedSprites, SpriteHit)

While we could also step through the sprite list and render them using DrawSprite, We'll most commonly be using GetFirstSprite,GetNextSprite commands in conjunction with the sprite collision. (SeeSpriteHit).

FACTS:

* GetFirstSprite() will return a ZERO if the sprite list is empty.

* The sprite list will be in order the sprites were created, and not the sprites index numbers.

Mini Tutorial:

This first part of example creates 10 sprites. The sprite indexes will be between 100 and 110. Then in the second part, we use the GetFirstSprite and GetNextSprite functions to step through our list of created sprites.

; =============================
; Part #1
; =============================

; Create 10 sprites randomly
  For lp =1 To 10
   ; Create the sprite
     CreateSprite 100+lp
  Next

; =============================
; Part #2
; =============================

; Display a Heading Message
  Print "============================"
  Print "List Created Sprites:"
  Print "============================"

; Get the First Created Sprite.
  ThisSprite=GetFirstSprite()

; While ThisSprite index is NOT 0, then run the loop
  While ThisSprite<>0
   ; Display this sprite index
     Print "Sprite :"+Str$(ThisSprite)
   ;Read what sprite is after this one
     ThisSprite=GetNextSprite(ThisSprite)
  EndWhile

; Display the screen and wait for key press
  Sync
  WaitKey

This example would output.

  ============================
List Created Sprites:
  ============================
  Sprite :110
  Sprite :109
  Sprite :108
  Sprite :107
  Sprite :106
  Sprite :105
  Sprite :104
  Sprite :103
  Sprite :102
  Sprite :101


Related Info:	CreateSprite \| DeleteSprite \| GetFreeSprite \| GetNextSprite \| NewSprite \| SpriteHit :