PS.spriteSolid ( width, height )

PS.spriteSolid() creates a solid sprite of the specified dimensions.

The required width and height parameters specify the dimensions of the sprite. They can be any positive integers. Values less than one (1) are clamped to 1. Non-integral values are floored. If either parameter is PS.DEFAULT, the value one (1) is used.

Usage notes

1. Newly created sprites are not located anywhere. Call PS.spriteMove() to position a sprite on the current grid plane.

2. By default, solid sprites are PS.COLOR_BLACK and PS.ALPHA_OPAQUE. You can change the color with PS.spriteSolidColor(), and the alpha transparency with PS.spriteSolidAlpha().

3. By default, the positional axis of a sprite created with PS.spriteSolid() is set to the top left corner of the sprite's rectangle (0, 0). You can change this with PS.spriteAxis().

Return value

PS.spriteSolid() returns a string that uniquely identifies the new solid sprite. It can be passed into any Perlenspiel function expecting a sprite identifier.

PS.ERROR is returned if an error occurs.

See below for an example of how to use PS.spriteSolid().

PS.spriteSolidColor ( sprite, color )

PS.spriteSolidColor() inspects and changes the color of a solid sprite.

The required sprite parameter should be unique sprite identifier of the type returned by PS.spriteSolid().

The optional color parameter can be supplied in any of the four Perlenspiel color expression formats.

If color is PS.DEFAULT, the default color (PS.COLOR_BLACK) is applied. If color is PS.CURRENT or not supplied, the color is not changed.

Usage notes

1. Only sprites created with PS.spriteSolid() can have their color changed or inspected. An error occurs if you call PS.spriteSolidColor() on a sprite created with PS.spriteImage().

Return value

PS.spriteSolidColor() returns a RGB triplet integer indicating the current color of the sprite.

PS.ERROR is returned if an error occurs.

PS.spriteSolidAlpha ( sprite, alpha )

PS.spriteSolidAlpha() inspects and changes the alpha transparency of a solid sprite.

The required sprite parameter should be unique sprite identifier of the type returned by PS.spriteSolid().

The optional alpha parameter specifies the alpha transparency of the sprite. It should be an integer between 0 (completely transparent) and 255 (fully opaque) inclusive. Values outside this range are clamped. Non-integral values are floored.

If alpha is PS.DEFAULT, the default alpha (PS.ALPHA_OPAQUE) is applied. If alpha is PS.CURRENT or not supplied, the alpha is not changed.

Usage notes

1. Only sprites created with PS.spriteSolid() can have their alpha changed or inspected. An error occurs if you call PS.spriteSolidAlpha() on a sprite created with PS.spriteImage().

Return value

PS.spriteSolidAlpha() returns an integer in the range 0-255 inclusive indicating the current alpha transparency of the sprite.

PS.ERROR is returned if an error occurs.

PS.spriteImage ( image, region )

PS.spriteImage() creates a sprite from an image object.

The required image parameter specifies the image object that is used to create the sprite.

The optional region parameter specifies a zero-based rectangular region inside the image that will be included in the sprite. It should be an object containing any of the following properties:

• .left : integer or PS.DEFAULT
• .top : integer or PS.DEFAULT
• .width : integer or PS.DEFAULT
• .height : integer or PS.DEFAULT

The .left property should be an integer between zero (0) and (image.width - 1), inclusive. Non-integral values are floored. An error occurs if .left is greater than or equal to image.width. If .left is less than one (1), PS.DEFAULT or not supplied, the value zero (0) is used.

The .top property should be an integer between zero (0) and (image.height - 1), inclusive. Non-integral values are floored. An error occurs if .top is greater than or equal to image.height. If .top is less than one (1), PS.DEFAULT or not supplied, the value zero (0) is used.

The .width property should be an integer between one (1) and image.width, inclusive. Non-integral values are floored. If .width is less than one (1), PS.DEFAULT, not supplied, or (.width - .left) is greater than image.width, the value (image.width - .left) is used.

The .height property should be an integer between one (1) and image.height, inclusive. Non-integral values are floored. If .height is less than one (1), PS.DEFAULT, not supplied, or (.height - .top) is greater than image.height, the value (image.height - .top) is used.

If region is PS.DEFAULT or not supplied, the entire image is used for the sprite.

Usage notes

1. Any alpha information present in the image passed into PS.spriteImage() will be preserved in the new sprite.

2. Newly created sprites are not located anywhere. Call PS.spriteMove() to position a sprite on the current grid plane.

3. By default, the positional axis of a sprite created with PS.spriteImage() is set to the top left corner of the sprite (0, 0). You can change this with a call to PS.spriteAxis().

Return value

PS.spriteImage() returns a string that uniquely identifies the new image sprite. It can be passed into any Perlenspiel function expecting a sprite identifier except PS.spriteSolidColor() or PS.spriteSolidAlpha(), which can only be used with solid sprites.

PS.ERROR is returned if an error occurs.

See below for an example of how to use PS.spriteRect().

PS.spritePlane ( sprite, plane )

PS.spritePlane() inspects or changes the color plane of a sprite.

The required sprite parameter should be unique sprite identifier of the type returned by PS.spriteSolid() or PS.spriteImage().

The optional plane parameter can be any positive integer. Values less than one (1) are clamped to zero. Non-integral values are floored.

If plane is PS.DEFAULT, the default plane (0) is used. If plane is PS.CURRENT or not supplied, the plane is not changed.

Usage notes

1. Calls to PS.spritePlane() do not trigger collision events.

2. If you change the plane of an invisible sprite, or a sprite that has never been placed on the grid with PS.spriteMove(), there is no visible effect.

Return value

PS.spritePlane() returns an integer indicating the current sprite plane.

PS.ERROR is returned if an error occurs.

PS.spriteShow ( sprite, show )

PS.spriteShow() inspects or changes the visibility of a sprite.

The required sprite parameter should be unique sprite identifier of the type returned by PS.spriteSolid() or PS.spriteImage().

If the optional show parameter is false or the number zero (0), the specified sprite becomes invisible:

• The beads occupied by the sprite on the current grid plane become transparent.
• Subsequent changes to any visual attribute of the sprite, such as its position or axis, have no visible effect. However, the specified attributes are still modified, and any changes will become evident if the sprite is made visible later.
• The sprite no longer collides with other sprites.

If show is true or any nonzero number, the sprite becomes visible again. If no visual attributes were changed while it was invisible, it assumes its previous state.

Calling PS.spriteShow( sprite, true ) on a visible sprite has no effect. Similarly, calling PS.spriteShow( sprite, false ) on an invisible sprite has no effect.

If show is PS.DEFAULT, the default visibility (true, visible) is assigned to the sprite. If show is PS.CURRENT or not supplied, the visibility is not changed.

Usage notes

1. Calling PS.spriteShow() on an invisible sprite will trigger a collision event if that sprite is touching or overlapping any other visible sprite.

Return value

PS.spriteShow() returns true if the specified sprite is visible, else false.

PS.ERROR is returned if an error occurs.

PS.spriteAxis ( sprite, x, y )

PS.spriteAxis() inspects or changes the positional axis of a sprite.

The required sprite parameter should be unique sprite identifier of the type returned by PS.spriteSolid() or PS.spriteImage().

The optional x and y parameters specify the location of the sprite's positional axis relative to the top left corner of the sprite. They can be any positive or negative integers. Non-integral values are floored.

If x or y are PS.DEFAULT, the default value zero (0) is used.

If x or y are PS.CURRENT or not supplied, the positional axis is not changed.

Usage notes

1. The axis of a sprite can placed anywhere, even outside the boundaries of the sprite. However, it's possible that some or all of the sprite may not be visible when the sprite is subsequently moved.

2. Changing the axis of a visible sprite will trigger a collision event if the repositioned sprite touches or overlaps any other visible sprite.

Return value

PS.spriteAxis() returns an object containing the following properties:

• .x : integer
• .y : integer

The .x and .y properties specify the location of the sprite's positional axis, relative to the top left corner of the sprite (0, 0).

PS.ERROR is returned if an error occurs.

PS.spriteMove ( sprite, x, y )

PS.spriteMove() inspects or changes the location of a sprite on the current grid plane.

The required sprite parameter should be unique sprite identifier of the type returned by PS.spriteSolid() or PS.spriteImage().

The optional x and y parameters specify the zero-based location of the sprite's positional axis on the current grid plane. They can be any positive or negative integers. Non-intergral values are floored.

If x or y are PS.DEFAULT, the default value (0) is used for the corresponding coordinate.

If x or y are PS.CURRENT or not supplied, the corresponding coordinate is not changed.

Usage notes

1. When a sprite is moved, the beads it previously occupied on the current grid plane become transparent (alpha = 0), and their color is set to PS.COLOR_WHITE.

2. The values of x and y can be set outside the boundaries of the grid if desired. However, it's possible that some or all of the sprite may not be visible.

3. Moving a visible sprite will cause a collision event if the moved sprite touches or overlaps any other visible sprite.

4. If an invisible sprite is moved, its coordinates are still updated, and it will appear at the new position when subsequently made visible.

Return value

PS.spriteMove() returns an object containing the following properties:

• .x : integer
• .y : integer

The .x and .y properties specify the current coordinates of the sprite's positional axis on the grid.

PS.ERROR is returned if an error occurs.

PS.spriteCollide ( sprite, exec )

PS.spriteCollide() inspects or changes the function that is called when a sprite collides with another.

The required sprite parameter should be unique sprite identifier of the type returned by PS.spriteSolid() or PS.spriteImage().

The optional exec parameter specifies a function that will be called when any call to PS.spriteMove(), PS.spriteShow() or PS.spriteAxis() causes the specified sprite to touch or collide with any other visible sprite, whether or not the sprites occupy the same grid plane.

The exec function should expect at least five arguments, as follows:

The first argument, s1, is set to sprite.

The second argument, p1, is set to the grid plane currently occupied by sprite.

The third argument, s2, is set to the unique identifier of the colliding sprite.

The fourth argument, p2, is set to the grid plane currently occupied by the colliding sprite.

The fifth argument, type, is set to the constant PS.SPRITE_TOUCH if any edge of the colliding sprite is immediately adjacent to any edge of sprite, or PS.SPRITE_OVERLAP if any region of the colliding sprite overlaps any region of sprite.

If exec is null or PS.DEFAULT, the default value (null, no collision function) is used.

If exec is PS.CURRENT or not supplied, the collision function is not changed.

Usage notes

1. If any call to PS.spriteMove(), PS.spriteShow() or PS.spriteAxis() results in a sprite collision, every sprite involved in the collision that has a collision function assigned to it will have that function called once for each colliding sprite.

2. When you change a visible sprite's collision function, that function is called immediately if the sprite is currently in a collision state with any other visible sprite.

Return value

PS.spriteCollide() returns the collision function currently assigned to sprite, or null if no function is assigned.

PS.ERROR is returned if an error occurs.

PS.spriteDelete ( sprite )

PS.spriteDelete() deletes a previously created sprite.

The required sprite parameter should be unique sprite identifier of the type returned by PS.spriteSolid() or PS.spriteImage().

The specified sprite is deleted from the engine, and its sprite identifier becomes invalid. Subsequent use of the identifier with any sprite command will cause an error.

Return value

PS.spriteDelete() returns PS.DONE on success, else PS.ERROR.