SpriteSheetBuilder Class
The SpriteSheetBuilder allows you to generate sprite sheets at run time from any display object. This can allow you to maintain your assets as vector graphics (for low file size), and render them at run time as sprite sheets for better performance.
Sprite sheets can be built either synchronously, or asynchronously, so that large sprite sheets can be generated without locking the UI.
Note that the "images" used in the generated sprite sheet are actually canvas elements, and that they will be sized
to the nearest power of 2 up to the value of maxWidth
or maxHeight
.
Constructor
SpriteSheetBuilder
()
Item Index
Methods
Properties
Methods
_drawNext
()
protected
Returns:
_endBuild
()
protected
_run
()
protected
_startBuild
()
protected
addAnimation
-
name
-
frames
-
[next]
-
[frequency]
Adds an animation that will be included in the created sprite sheet.
Parameters:
-
name
StringThe name for the animation.
-
frames
ArrayAn array of frame indexes that comprise the animation. Ex. [3,6,5] would describe an animation that played frame indexes 3, 6, and 5 in that order.
-
[next]
String optionalSpecifies the name of the animation to continue to after this animation ends. You can also pass false to have the animation stop when it ends. By default it will loop to the start of the same animation.
-
[frequency]
Number optionalSpecifies a frame advance frequency for this animation. For example, a value of 2 would cause the animation to advance every second tick.
addEventListener
-
type
-
listener
Adds the specified event listener. Note that adding multiple listeners to the same function will result in multiple callbacks getting fired.
Example
displayObject.addEventListener("click", handleClick);
function handleClick(event) {
// Click happened.
}
Parameters:
addFrame
-
source
-
[sourceRect]
-
[scale=1]
-
[setupFunction]
-
[setupParams]
-
[setupScope]
Adds a frame to the SpriteSheet. Note that the frame will not be drawn until you call build method. The optional setup params allow you to have a function run immediately before the draw occurs. For example, this allows you to add a single source multiple times, but manipulate it or it's children to change it to generate different frames.
Note that the source's transformations (x, y, scale, rotate, alpha) will be ignored, except for regX/Y. To apply transforms to a source object and have them captured in the sprite sheet, simply place it into a Container and pass in the Container as the source.
Parameters:
-
source
DisplayObjectThe source DisplayObject to draw as the frame.
-
[sourceRect]
Rectangle optionalA Rectangle defining the portion of the source to draw to the frame. If not specified, it will look for a
getBounds
method, bounds property, ornominalBounds
property on the source to use. If one is not found, the frame will be skipped. -
[scale=1]
Number optionalOptional. The scale to draw this frame at. Default is 1.
-
[setupFunction]
Function optionalOptional. A function to call immediately before drawing this frame.
-
[setupParams]
Array optionalParameters to pass to the setup function.
-
[setupScope]
Object optionalThe scope to call the setupFunction in.
Returns:
addMovieClip
-
source
-
[sourceRect]
-
[scale=1]
This will take a MovieClip, and add its frames and labels to this builder. Labels will be added as an animation running from the label index to the next label. For example, if there is a label named "foo" at frame 0 and a label named "bar" at frame 10, in a MovieClip with 15 frames, it will add an animation named "foo" that runs from frame index 0 to 9, and an animation named "bar" that runs from frame index 10 to 14.
Note that this will iterate through the full MovieClip with actionsEnabled set to false, ending on the last frame.
Parameters:
-
source
MovieClipThe source MovieClip to add to the sprite sheet.
-
[sourceRect]
Rectangle optionalA Rectangle defining the portion of the source to draw to the frame. If not specified, it will look for a
getBounds
method,frameBounds
Array,bounds
property, ornominalBounds
property on the source to use. If one is not found, the MovieClip will be skipped. -
[scale=1]
Number optionalThe scale to draw the movie clip at.
build
()
Builds a SpriteSheet instance based on the current frames.
Returns:
buildAsync
-
[timeSlice]
Asynchronously builds a SpriteSheet instance based on the current frames. It will
run 20 times per second, using an amount of time defined by timeSlice
. When it is complete it will
call the specified callback.
Parameters:
-
[timeSlice]
Number optionalSets the timeSlice property on this instance.
clone
()
SpriteSheetBuilder instances cannot be cloned.
dispatchEvent
-
eventObj
-
[target]
Dispatches the specified event to all listeners.
Example
// Use a string event
this.dispatchEvent("complete");
// Use an object
var event = {
type: "complete",
foo: "bar"
};
this.dispatchEvent(event);
Parameters:
-
eventObj
Object | StringAn object with a "type" property, or a string type. If a string is used, dispatchEvent will construct a generic event object with the specified type.
-
[target]
Object optionalThe object to use as the target property of the event object. This will default to the dispatching object.
Returns:
hasEventListener
-
type
Indicates whether there is at least one listener for the specified event type.
Parameters:
-
type
StringThe string type of the event.
Returns:
initialize
()
protected
Initialization method.
removeAllEventListeners
-
[type]
Removes all listeners for the specified type, or all listeners of all types.
Example
// Remove all listeners
displayObject.removeAllEvenListeners();
// Remove all click listeners
displayObject.removeAllEventListeners("click");
Parameters:
-
[type]
String optionalThe string type of the event. If omitted, all listeners for all types will be removed.
removeEventListener
-
type
-
listener
Removes the specified event listener.
Important Note: that you must pass the exact function reference used when the event was added. If a proxy function, or function closure is used as the callback, the proxy/closure reference must be used - a new proxy or closure will not work.
Example
displayObject.removeEventListener("click", handleClick);
stopAsync
()
Stops the current asynchronous build.
Properties
defaultScale
Number
The scale to apply when drawing all frames to the sprite sheet. This is multiplied against any scale specified in the addFrame call. This can be used, for example, to generate a sprite sheet at run time that is tailored to the a specific device resolution (ex. tablet vs mobile).
Default: 1
maxHeight
Number
The maximum height for the images (not individual frames) in the generated sprite sheet. It is recommended to use a power of 2 for this value (ex. 1024, 2048, 4096). If the frames cannot all fit within the max dimensions, then additional images will be created as needed.
Default: 2048
maxWidth
Number
The maximum width for the images (not individual frames) in the generated sprite sheet. It is recommended to use a power of 2 for this value (ex. 1024, 2048, 4096). If the frames cannot all fit within the max dimensions, then additional images will be created as needed.
Default: 2048
onComplete
Function
deprecated
Callback function to call when a build completes. Called with a single parameter pointing back to this instance.
onProgress
Function
deprecated
Callback to call when an asynchronous build has progress. Called with two parameters, a reference back to this instance, and the current progress value (0-1).
padding
Number
The padding to use between frames. This is helpful to preserve antialiasing on drawn vector content.
Default: 1
progress
Number
Read-only. A value between 0 and 1 that indicates the progress of a build, or -1 if a build has not been initiated.
Default: -1
spriteSheet
SpriteSheet
The sprite sheet that was generated. This will be null before a build is completed successfully.
timeSlice
Number
A number from 0.01 to 0.99 that indicates what percentage of time the builder can use. This can be thought of as the number of seconds per second the builder will use. For example, with a timeSlice value of 0.3, the builder will run 20 times per second, using approximately 15ms per build (30% of available time, or 0.3s per second). Defaults to 0.3.
Default: 0.3
Events
complete
Dispatched when a build completes.