animation
Sprite-sheet animation, cutting frames from a grid and playing them over time.
A sprite sheet packs an animation's frames into one image, laid out in a grid.
A SpriteSheet wraps that image and the frame size and hands you any cell as a
Quad. An Animation is a list of those cells played in order, each held for a
while, which you advance from your update and draw each frame. One sheet can
feed several animations, which is how a character keeps a separate walk cycle
for each way it faces.
You build a sheet with newSpriteSheet, then an animation with newAnimation
(frames given as (column, row) cells) or rowAnimation (a whole row, left to
right). update moves it along by the current frame's time, draw paints the
frame where you ask, and quad hands you that frame if you would rather draw
it yourself. Frames can share one duration or each carry their own.
This is an opt-in module, imported on its own with import nim2d/animation.
The core engine does not pull it in.
type SpriteSheet = ref object
An image cut into a grid of equal cells. cols and
rows are worked out from the image and the frame
size.
Fields
-
imageImage -
frameWidthint -
frameHeightint -
colsint -
rowsint
type Animation = ref object
A run of frames from a sheet, each shown for its duration. Advance it with
update and show it with draw. Build one with newAnimation or
rowAnimation.
newSpriteSheet ¶
proc newSpriteSheet(image: Image; frameWidth, frameHeight: int): SpriteSheet
Wrap image as a grid of frameWidth by frameHeight cells. The number of
columns and rows comes from the image size, so a 96 by 144 image cut into 32 by 36 cells is 3 columns and 4 rows.
Parameters
-
image(Image) -
frameWidth(int) -
frameHeight(int)
Returns
SpriteSheet
frameCount ¶
proc frameCount(sheet: SpriteSheet): int
How many cells the sheet holds, columns times rows.
Parameters
-
sheet(SpriteSheet)
Returns
int
quad ¶
proc quad(sheet: SpriteSheet; col, row: int): Quad
The cell at (col, row) as a Quad, ready to hand to a texture's draw.
Columns and rows count from zero, left to right and top to bottom.
Parameters
-
sheet(SpriteSheet) -
col(int) -
row(int)
Returns
Quad
newAnimation ¶
proc newAnimation(sheet: SpriteSheet; frames: openArray[(int, int)]; frameTime: float; loop = true): Animation
An animation over the given frames, each a (column, row) cell of sheet,
every frame held for frameTime seconds. With loop it runs forever,
otherwise it stops and holds on the last frame. Raises ValueError with no
frames or a frameTime that is not positive.
Parameters
-
sheet(SpriteSheet) -
frames(openArray[(int, int)]) -
frameTime(float) -
loop(auto)
Returns
Animation
newAnimation ¶
proc newAnimation(sheet: SpriteSheet; frames: openArray[(int, int)]; durations: openArray[float]; loop = true): Animation
An animation whose frames each carry their own duration, so a pose can linger
while others flick past. durations must be the same length as frames, and
every duration must be positive. Raises ValueError otherwise.
Parameters
-
sheet(SpriteSheet) -
frames(openArray[(int, int)]) -
durations(openArray[float]) -
loop(auto)
Returns
Animation
rowAnimation ¶
proc rowAnimation(sheet: SpriteSheet; row: int; frameTime: float; loop = true): Animation
An animation of a whole row, every column left to right, each frame held for
frameTime. Handy when a sheet puts one cycle per row.
Parameters
-
sheet(SpriteSheet) -
row(int) -
frameTime(float) -
loop(auto)
Returns
Animation
update ¶
proc update(anim: Animation; dt: float)
Advance the animation by dt seconds, stepping to later frames as their
time runs out and wrapping around when it loops. A paused or finished
animation does not advance, and a non-looping one stops on its last frame and
then reports done. A single-frame animation holds that frame, so it only
moves once it has more than one. Frame durations are positive by
construction, so the time always drains.
Parameters
-
anim(Animation) -
dt(float)
quad ¶
proc quad(anim: Animation): Quad
The current frame as a Quad.
Parameters
-
anim(Animation)
Returns
Quad
draw ¶
proc draw(anim: Animation; nim2d: Nim2d; x, y: float; scale = 1.0; angle = 0.0; ox = 0.0; oy = 0.0)
Draw the current frame at (x, y), scaled uniformly by scale, turned by
angle radians about the origin (ox, oy) given in unscaled frame pixels.
Parameters
-
anim(Animation) -
nim2d(Nim2d) -
x(float) -
y(float) -
scale(auto) -
angle(auto) -
ox(auto) -
oy(auto)
currentFrame ¶
proc currentFrame(anim: Animation): int
The index of the frame showing now, counting from zero.
Parameters
-
anim(Animation)
Returns
int
frameCount ¶
proc frameCount(anim: Animation): int
How many frames the animation runs through.
Parameters
-
anim(Animation)
Returns
int
done ¶
proc done(anim: Animation): bool
True once a non-looping animation has reached and stopped on its last frame.
Parameters
-
anim(Animation)
Returns
bool
reset ¶
proc reset(anim: Animation)
Send the animation back to its first frame so it plays again from the start.
Parameters
-
anim(Animation)
setFrame ¶
proc setFrame(anim: Animation; i: int)
Jump straight to frame i, clamped to the range, and clear the elapsed time
on it. Useful to park an animation on a resting pose.
Parameters
-
anim(Animation) -
i(int)
pause ¶
proc pause(anim: Animation)
Stop advancing on update, holding the current frame.
Parameters
-
anim(Animation)
resume ¶
proc resume(anim: Animation)
Start advancing again after a pause.
Parameters
-
anim(Animation)