SpriteHit - Learn To Code - PlayBASIC Documentation

SpriteHit

HitSpriteIndex = SpriteHit(CheckSprite, SpriteIndex, CollisionClass)

Parameters:

    CheckSprite = The Index of the sprite to check for collisions
    SpriteIndex = The Index of the sprite you wish to start checking from
    CollisionClass = The collision class to limited sprite collisions against

Returns:

HitSpriteIndex = The sprite index of the first sprite that has hit the source sprite

      The SpriteHit function checks a sprite for any collisions against the activate sprite list. It's important to understand that SpriteHit does not simply check a pair of sprites for a collision (see SpritesOverlap for that), rather it will automatically step through the internal sprite list for you.

      SpriteHit will start checking for collision at your selected starting sprite ( providing this sprite exists) and will continue until either an impact is found, or it reaches the end of the sprite list. Your starting sprite will generally be the first sprite in the sprite list. Which is obtained by calling the GetFirstSprite() function. When a collision is detected, the index of the hit sprite will be returned, if there was no collision, the function returns a zero.

      You can check for multiple impacts, by calling SpriteHit repeatedly, each time telling it to start checking at the next sprite after the previous hit sprite. Use the GetNextSprite() function for this.

      It's important to remember that sprites are stored internally in what is called a linked list. This means the sprite list isn't actually ordered based upon the sprites index numbers as you might expect, but rather, the order will follow when the sprites were created, regardless of their sprite index value.

      For example.

      If you create sprites 10,5,20,2 Then when SpriteHit steps through the sprite list, it'll check sprite 2 (the starting sprite), then 20, then 5, then 10. Please see GetFirstSprite() & GetNextSprite() about iterating through the sprite list correctly.

      Sprite collisions can also be selectively screened by using collision class parameter. This requires that you've previously assigned each sprite it's SpriteCollisionClass bit value. You can use these values to make a sprite belong to a particular group. More importantly, this will make SpriteHit ignore groups of sprite that it shouldn't bother return a collisions against. By default, all created sprites are assigned a collision class of 1.

FACTS:

      * SpriteHit returns the Index of the first sprite that impacts the check sprite.

      * If there was No collision SpriteHit returns a zero.

      * Sprite collisions occur when the collision regions of any two sprites overlap. See SpriteCollisionMode for the various collision modes.

      * Use SpriteHitMap or SpriteHitMapPixels when performing sprite to map level collisions

      * See the Sprite Tutorial for more information.

Mini Tutorial:

      This example is in 3 parts.

      Part 1 creates two coloured images.

      Part 2 then creates both out test sprite (sprite #1) and a group of randomly position sprites to check collisions again.

      Part 3 is the main loop, where it check for any collisions with sprite #1.

; ========================
; Part 1 - Create an image
; ========================

  Cls RGB(0,0,255)
  GetImage 1,0,0,32,32

  Cls RGB(0,255,00)
  GetImage 2,0,0,32,32

; =============================
; Part 2- Create some sprites
; =============================

; Create Sprite 1 and assign it image 1
  CreateSprite 1
  SpriteImage 1,1
  CenterSpriteHandle 1

; Enable Collision for Sprite #1
  SpriteCollision 1,on

; Set Sprite #1's collision Class to %0001 (1 in decimal)
  SpriteCollisionClass 1,%0001


; Create a bunch fo sprites to check collision against
  For Sprites=2 To 50

     CreateSprite Sprites
     SpriteImage Sprites,2
     x=Rnd(GetScreenWidth()-32)
     y=Rnd(GetScreenHeight()-32)
     PositionSprite sprites,x,y

   ; Enable Collision for this sprite
     SpriteCollision Sprites,on

   ; Set Sprites Collision Class to %0010  (2 in decimal)
     SpriteCollisionClass Sprites,%0010

  Next



; =============================
; Part 3- The Main Loop
; =============================

; Start a DO/Loop
  Do

   ; Clear the screen
     Cls RGB(0,0,0)

   ; Display a message
     Print "Checking for Collisions"

   ; Position the Sprite 1 at the mouses position
     PositionSprite 1,MouseX(),MouseY()

   ; Check if sprite #1 hit another sprite
   ; of this sprite class
     ThisSprite=SpriteHit(1,GetFirstSprite(),%0010)

   ; If there was impact, then we loop through and
   ; find any other sprites we might have hit also
     While ThisSprite>0
        Print "Hit Sprite:"+Str$(ThisSprite)

      ; Check if this sprite hit another sprite ?
     NextSprite=GetNextSprite(ThisSprite)
     ThisSprite=SpriteHit(1,NextSprite,%0010)
  EndWhile

; Draw All of the sprites
  DrawAllSprites

; Draw the screen
  Sync

; Loop back to the DO statement
  Loop

This example would output.

  no Text Ouput