SpriteMaster Pro

This command needs to be called BEFORE loading/creating sprites, loading packs, or displaying sprites.

Once this command is called you can use the following two global variables to access the sprite camera and sprite pivot used by SpriteMaster:

spritecamera - points to the 3D camera
spritepivot - points to a sprite pivot which all created/loaded sprites are attached to by default

Normally, this pivot is created by using the SpriteGraphics command. You can however use this function to create additional pivots to attach sprites to. Handy for hiding/showing a bunch of sprites simultaneously.

This function needs to be called BEFORE loading/creating sprites, or loading packs.

NOTE: Only positive values can be used for zooming.

The sprites texture size is set to the next 'power of 2' value. Some examples here:

sprite.smSprite=CreateSprite(28,60) ; texture size will be 32x64
sprite.smSprite=CreateSprite(120,160) ; texture size will be 128x256

To set up animation frames for the sprite just supply values in the columns and rows parameters. Then, use the frame parameter in PositionSprite to show a particular frame in the sprite.

Example
create a sprite with a size of 28x30 which has 5 frames across and 4 frames down:

sprite.smSprite=CreateSprite(28,30,5,4)
PostionSprite sprite,40,70,7 ; show frame 7

The sprites default texture will be empty. Use SpriteTexture and GetSpriteTexture() to change this.

You can use GetPackedSprite() and CopySprite() with created sprites. Doing so makes the newly created sprite share the mesh in which the referenced sprite is using.

If you wish to find the new pack associated with the sprite then use the GetPack() function.

You should load images which have sizes using a 'power of 2' where possible. Otherwise the sprites image will appear blurred due to internal scaling of the texture.
Example width/height sizes are:

8 , 16 , 32 , 64 , 128 , 256 , 512 , 1024 , etc...

You can use GetPackedSprite() and CopySprite() with created sprites. Doing so makes the copied sprite share the pack/surface/mesh in which the referenced sprite is using.

If you wish to find the new pack associated with the sprite then use the GetPack() function.

Text sprites are created by extracting an exsiting font image from within the specified pack. This font image needs to be set up using a particular sequence of characters.

Example:

The frame layout can be anything but the characters should use this string sequence (same as above):

Normally, using AddText, the first character in the font layout is a ! (exclamation mark). You can however use an charoffest parameter to tell SpriteMaster whereabouts the exclamation mark is. For example, your font layout might start with a SPACE followed by the exclamation mark. In which case you use an offset of 1:

mytext.smSprite=CreateTextSprite("textpack.png",1)

Use the animation settings in Image Packer to set up the appropriate frames for the font.

To add text/characters use AddText
To remove all text/characters use ClearText

If you wish to find the new pack associated with the text sprite then use the GetPack() function.

A text sprite is a special kind of quad sprite set up to display a string of font characters. See the CreateTextSprite() function for details on how to set up a text sprite.

The textstring$ parameter can contain any valid character values.
There are a couple of control characters which can be passed to the AddText command:

So, AddText txt,3,8,"Hello"+Chr$(10)+"World" produces:

NOTE2: There are a quite a few commands/functions which do not work with text sprites. Here is a list:

RotateSprite , ResizeSprite, FlipSprite , SetSprite ,
SpritesOverlap() , CopySprite()

You can see how many sprites are associated with a pack with the CountSpritesUsingPack() function.

If you have several hundred sprites in a surface you may wish to use this command outside of a loop.

The pack needs an associated *.def file to work correctly. See the Image Packer tool.

Once the pack is loaded you can extract as many sprites/images/textures as required using these functions:

GetPackedSprite()
GetPackedImage()
GetPackedTexture()

To free the pack (and associated sprites) use FreePack.

You can use CountPackedImages() to return the number of individual sprites/images in the pack. Alternatively, CountSpritesUsingPack() can be used to return the number of sprites using the pack.

Sprites created or loaded with CreateSprite() / LoadSprite() have their own pack. If you use CopySprite() on these sprites then the copies will share the pack/surface. By using GetPack() to retrieve the pack you can then free up the original sprite as well as the copies by using via the FreePack command.

coin=LoadSprite("coin.png")
Dim c(5)
For n=1 to 5
c(n)=CopySprite(coin)
Next
coinpack=GetPack(coin)
FreePack coinpack ; free pack and coin/copies of coin

1) Sprites index number:
sprite.smSprite=GetPackedSprite(4,pack)
Gets the 4th sprite in the pack.
This is useful if you wish to extract all sprites into an array.
One thing to bear in mind is though, if you use Image Packer to modify the pack then the images in the pack are likely to be jumbled. This will cause the index numbers to refer to different images.
You can use SpriteName$() to find the name of the sprite if using the index method.

2) Sprites name:
sprite.smSprite=GetPackedSprite("car",pack)
Gets the sprite called car from the pack. This name is set within Image Packer. The name is always lowercase and without spaces.

You can free up individually extracted sprites by using FreeSprite. Alternatively, use FreePack to clear ALL sprites associated with a pack (as well as the pack itself).

The optional rX,rY,rW,rH parameters are used to grab a region of the sprite image instead.
The rX and rY values are offsets from the top/left of the sprite image. rW and rH determine the width and height of the region.

1) Images by index number:
myimage=GetPackedImage(4,pack)
Gets the 4th image in the pack.
This is useful if you wish to extract all images into an array.
One thing to bear in mind though, if you use Image Packer to modify the pack then the images in the pack are likely to be jumbled. This will cause the index numbers to refer to different images.

2) Images name:
image=GetPackedImage("car",pack)
Gets the image called car from the pack. This name is set within Image Packer. The name is always lowercase and without spaces.

Once you have your extracted the image the sprite pack can be freed up with FreePack.

The def$ value which can be used in 2 ways:

1) Textures by index number:
mytexture=GetPackedTexture(4,pack)
Gets the 4th texture in the pack.
This is useful if you wish to extract all textures into an array.
One thing to bear in mind though, if you use Image Packer to modify the pack then the textures in the pack are likely to be jumbled. This will cause the index numbers to refer to different textures.

2) Textures name:
mytexture=GetPackedTexture("brick",pack)
Gets the texture called brick from the pack. This name is set within Image Packer. The name is always lowercase and without spaces.

Once you have your extracted the texture the pack can be freed up with FreePack.

Dim s(100)
num=Rand(100)
For n=1 to num
s(n)=GetPackedSprite(Rand(1,numimages),pack)
Next

numsprites=CountSpritesUsingPack(pack)

For i=1 to num
DebugLog PackedImageName$(i,pack)
Next

If the image has no animation then a value of 1 is returned.

If the optional frames parameter is used, the frame of the (animated) sprite is changed to the number supplied.

TIP: Unlike 2D images you do not need to call this every loop. Only when you wish to re-position the sprite.

Note: The 'frame' value supplied to PositionSprite automatically wraps around in both directions if the value is out of bounds. This helps to avoid incorrect animation frames being shown.

The sprite is rotated around it's anchor point which can be changed with the HandleSprite command.

The optional movedistance# parameter can be used to move the sprite in the direction it is facing. You should design your sprites so that they face to the right by default.
Giving the movedistance# a negative value moves the sprite in the opposite direction.

Ommitting the angle# parameter rotates the sprite to its default orientation.

Unlike GetPackedSprite(), the CopySprite() function copies every attribute of the sprite including size, color, alpha, rotation, and flip status.

The new sprites name is the same as the copied sprite but with an underscore and new value appended.

NOTE: Resizing sprites causes them to blur. This is down the sprites texture being scaled and thereby losing the pixel<>texel match.

If the horizontally and vertically parameters are omitted the sprites flip status is reset to default.

Postive values in handleX# and handleY# moves the hotspot right and down.
Negative values in handleX# and handleY# moves the hotspot left and up.

The hotspot is set by default to the top/left corner of a sprite which gives both handles a value of 0.

Ommiting the handleX# parameter centers handle horizontally.
Ommiting the handleY# parameter centers handle vertically.

With this command you can set the sprites frame, position, size, rotation, color, and alpha all within one call.

You can use 0 for the width/height which will leave the size of the sprite unchanged.

If you use negative values for red/green/blue/alpha then the current settings remain.

Changing the sprite image still keeps the axis/handle position relative to it's current setting. So, if the handle is centred it will remain so on the newly chosen image.

Also, if the current sprite is flipped horizontally and/or vertically this will also be applied to the new sprite image.

Note: You can only change the image to another from inside the pack used by the current sprite.

For a description of the ref$ parameter see GetPackedSprite()

The optional rX,rY,rW,rH parameters are used to grab a region of a sprite image instead.
The rX and rY values are offsets from the top/left of the sprite image. rW and rH determine the width and height of the region.

If the red / green / blue / alpha parameters are ommitted then the sprite is reset to it's default values of white and opaque.

If the alpha parameter is ommitted then the sprite is reset to it's default alpha value of 1.0 (opaque).

PositionSprite sprite1,Rand(100),Rand(100)
PositionSprite sprite2,Rand(100),Rand(100)

DebugLog SpritesCollide(sprite1,sprite2)

Note: This will affect any sprites sharing the texture such as those created with:

CopySprite()
GetPackedSprite()