Sprite Plug-in Scripting Reference

Overview

The sprite plugin implements masked, animated, scalable, and transparent sprites.

The sprites can be imported from various image file formats. Importing may be slow due to the massive compression and mask calculations, but then playback is extremely fast.

Image files with an alpha channel will automatically generate a mask, files with no alpha will see pure white as clear.

Sprites are organized into rows and columns and can be animated by time or frame on this basis.

Messages: nodemove, nodechange

Nodemove is sent when the position of the sprite changes.

Nodechange is sent when the sprite's data changes.

Commands and Functions

binaryget, binaryset

binary data $ = binaryget(node name $, col #, row #)
binaryset(node name $, col #, row #, binary data $)

Get or set binary data for any sprite.

This routine is useful for serialization into xml and trading data between sprites.

boundsget, boundsset

rectangle $ = boundsget(node name $)
boundsset(node name $, rectangle $)

Get or set the boundary rectangle of the sprite.

colget, colrow, colset, rowget, rowset

col # = colget(node name $)
colrow(node name $, col #, row #)
colset(node name $, col #)
row # = rowget(node name $)
rowset(node name $, row #)

These functions force the sprite to a certain row and/or column image, and stop automatic animation. This is for scripted (not automatic) animation.

colmax, rowmax

col # = colmax(node name $)
row # = rowmax(node name $)

These functions return the maximum extent of the sprites row or column data. If either function returns zero, the sprite has no data.

colorderget, colorderset, currentorder, roworderget, roworderset

current order $ = colorderget(node name $)
colorderset(node name $, col order $, row #)
current order $ = currentorder(node name $)
current order $ = roworderget(node name $)
roworderset(node name $, row order $, col #)

These routines set the row or column animation order.

Currentorder returns the current row order or col order, whichever was set last. Example:

sprite.roworderset("mysprite", "1, 2, 3", 1)

See: msperframeset, msperframeget

deletedata

deletedata(node name $, col #, row #)

Deletes the sprite at the given position, if any.
See: isloaded

exportseries, exportsingle

exportseries(node name $, file name $)
exportsingle(node name $, file name $, col #, row #)

Export one or all of the images in the sprite. Export types supported are JPEG, GIF, PHOTOSHOP 3, and PICT for the Mac and BMAP for Windows.
See: importseries, importsingle

fliphorget, fliphorset, fliphorver, flipverget, flipverset

hor flip TF = fliphorget(node name $)
fliphorset(node name $, hor flip TF)
fliphorver(node name $, flip hor TF, flip ver TF)
ver flip TF = flipverget(node name $)
flipverset(node name $, ver flip TF)

Get or set the horizontal and/or vertical flip of the sprite.

fullget, fullset, infoget, infoset

full $ = fullget(node name $)
fullset(node name $, full $)
info $ = infoget(node name $)
infoset(node name $, info $)

Get or set XML data that describes all the settings for this node.

The fullget and fullset routines have a header element with appropriate namespaces, infoget and infoset are an XML snippet for access as a property. Example:

mynode.info.title = "new title"

handlesget, handlesset

handles TF = handlesget(node name $)
handlesset(node name $, handles TF)

Turn on or off dragable handles for reshaping the node.

This routine is used by the system tool palettes for manual positioning.
See: markersget, markersset, partget, partset

heightget, heightset, widthget, widthheight, widthset

height # = heightget(node name $)
heightset(node name $, height #)
width # = widthget(node name $)
widthheight(node name $, width #, height #)
widthset(node name $, width #)

Get or set the width and/or height of the sprite.
See: scaleset

hittest

hit TF = hittest(node name $, hor #, ver #)

Returns true if the point is in the sprite.

importseries, importsingle

importseries(node name $, file name $, max col #, max row #, percent reduce #)
importsingle(node name $, file name $, col #, row #, percent reduce #)

Import one or all of the images in the sprite. Import types supported are JPEG, GIF, PHOTOSHOP 3, and PICT for the Mac and BMAP for Windows.

The last parameter is the percentage to reduce sprite size. Use zero for no reduction, or 50% for a small sacrifice in image quality. Negative one will dither for maximum quality.
See: exportseries, exportsingle

inkget, inkset

ink # = inkget(node name $)
inkset(node name $, ink #)

Get or set the ink transparency of the sprite. Values range from 1 (very transparent) to 7 (almost opaque). A value of 8 is copy (fast) and 9 will invert.

isloaded

is loaded TF = isloaded(node name $, col #, row #)

Returns true if the col and row have sprite data, false if there is no data there.

ismoving

is moving TF = ismoving(node name $)

Returns true if the sprite is animating, or false if it is stationary.

markersget, markersset

markers TF = markersget(node name $)
markersset(node name $, markers TF)

Turn on or off the node outline to show selection.

This routine is used by the system tool palettes to show that a node is selected.
See: handlesset, handlesget, partget, partset

msperframeget, msperframeset

ms per frame # = msperframeget(node name $)
msperframeset(node name $, ms per frame #)

Declare milliseconds per frame for automatic animation. Use negative one for frame based animation.
See: roworderset, colorderset, currentorder, roworderget, colorderget

partget, partset

part # = partget(node name $, hor #, ver #)
partset(node name $, hor #, ver #, part #)

Get or set the points for an individual handle.
See: markersget, markersset, handlesset, handlesget

pointhorget, pointhorset, pointhorver, pointverget, pointverset

hor # = pointhorget(node name $)
pointhorset(node name $, hor #)
pointhorver(node name $, hor #, ver #)
ver # = pointverget(node name $)
pointverset(node name $, ver #)

Get or set the horizontal and vertical position of the sprite.

scaleget, scaleset

scale percent #.# = scaleget(node name $)
scaleset(node name $, scale percent #.#)

Get or set the sprite scale with a floating point number. Use 100.0 for no scaling and fastest drawing.
See: widthheight, widthset, heightset