2D Animated Sprite Sheet Parser

[johannhowitzer]

This code takes sprite sheets that contain marker pixels, and chops it up by storing a bunch of data in an array.  The indexes of the array can then be used to call upon the data to draw and animate sprites.  The sprite sheets can be changed dramatically, and the parsing routine will do all the work of detecting where things have moved.  Multiple sheets can be loaded one after another, and the new sprites from each sheet will be added to the array in order.

If you're confused about something, please bring it up so I can clarify, and if this post needs to be edited to be easier to understand, I'll gladly make the edits.


First, this stuff goes in the header:

Code: QB64: [Select]

1. type coordinate_int
2.    x as long
3.    y as long
4. end type
5.  
6. type sprite_structure
7.    ' Top-left position of the sprite's first animation frame in the sheet
8.    pos     as coordinate_int
9.  
10.    ' Size of sprite visually
11.    size    as coordinate_int
12.  
13.    ' Number of frames in animation
14.    frames  as integer
15.  
16.    ' "Frames-per-frame" - that is, the number of time units that will tick in your program
17.    ' per frame of animation.  If this has a value of 2, and your program runs at 60 FPS,
18.    ' the sprite will animate at 30 FPS.  This is done so that animations that do not update
19.    ' to the next frame every unit of time will not take up huge sections of the sprite sheet
20.    ' with duplicates.
21.    fpf     as _byte
22.  
23.    ' Offset from hitbox position to sprite's visual position.  Your program should be storing
24.    ' the position of an object mechanically, and then add this to the object's position
25.    ' to get the position that the sprite will be drawn.
26.    offset  as coordinate_int
27.  
28.    ' Size of hitbox, in my program I've copied this over to the object data
29.    hb_size as coordinate_int
30.  
31.    ' Image handle of the sheet this sprite is found in
32.    image   as _unsigned long
33. end type
34.  
35. dim shared sprite(1000) as sprite_structure
36. dim shared sprite_count as integer
37.  
38. call parse_sprites([first image handle])
39. call parse_sprites([second image handle])

The two routines below are the tools the parsing routine uses.  They take a starting position, handle of image to scan, and the color used for detection.  scan_right returns the x coordinate where the color was first found, while scan_down returns the y coordinate. These scans are noninclusive - they will not scan the pixel they start on.  To make them inclusive, move the loop condition in front of the do statement.

The preserve& handle is used to make sure these routines keep the same _source the program had going in, so you don't have to worry about that part.  I like to do that for most routines that will use _source or _dest in any way, saves headaches.

Code: QB64: [Select]

1. function scan_right(x1, y, i&, d~&)
2. x = x1
3. preserve& = _source
4. _source i&
5. w = _width(i&)
6. do
7.    x = x + 1
8.    ' if x > w then do something - you can error trap moving past the edge of the image here
9. loop until point(x, y) = d~& or x > w
10. scan_right = x
11. _source preserve&
12. end function
13.  
14.  
15. function scan_down(x, y1, i&, d~&)
16. y = y1
17. preserve& = _source
18. _source i&
19. h = _height(i&)
20. do
21.    y = y + 1
22.    ' if y > h then do something - you can error trap moving past the edge of the image here
23. loop until point(x, y) = d~& or y > h
24. scan_down = y
25. _source preserve&
26. end function

Now here's the star of the show, the parsing routine.  It uses the coordinates such as x1, y1, x2, y2, x_hb, y_hb as its scan locations - moving from x1 to x2 etc. when it needs to leave some information behind for later.  You can actually use this technique and restructure it as you see fit for your own purposes, this sprite sheet slicer is just the way I've used it, and seems like it would be the most likely use.

Code: QB64: [Select]

1. sub parse_sprites(i&)
2.  
3. preserve& = _source
4.  
5. _source i&
6. d~& = point(0, 0) ' Detection color
7. s  = sprite_count + 1
8. x1 = 1 ' Top left of first sprite in sheet
9. y1 = 2
10.  
11. do
12.    sprite(s).image = i&
13.  
14.    ' Source position
15.    sprite(s).pos.x = x1
16.    sprite(s).pos.y = y1
17.  
18.    ' #1 Sprite size
19.    x2 = scan_right(x1, y1, i&, d~&)
20.    y2 =  scan_down(x1, y1, i&, d~&)
21.    sprite(s).size.x = x2 - x1 - 1
22.    sprite(s).size.y = y2 - y1 - 1
23.  
24.    ' #2 Animation frame count
25.    x2 = scan_right(x2, y1, i&, d~&)
26.    sprite(s).frames = int( ((x2 + 1) - x1) / (sprite(s).size.x + 2) )
27.    if sprite(s).frames < 1 then sprite(s).frames = 1
28.  
29.    ' #3 Frame counter ticks per animation frame
30.    sprite(s).fpf = scan_right(x2, y1 - 1, i&, d~&) - x2
31.    if sprite(s).fpf < 1 then sprite(s).fpf = 1
32.    x2 = x2 + 1
33.  
34.    ' #4 Sprite display position - relative to hitbox position
35.    x_hb = scan_right(x2 - 1, y1, i&, d~&)
36.    y_hb =  scan_down(x2, y1 - 1, i&, d~&)
37.    sprite(s).offset.x = x2 - x_hb
38.    sprite(s).offset.y = y1 - y_hb
39.    ' NOTE If either offset is zero, this forces the other one to be zero as well
40.    '      Easy fix is to move the detection pixels outside the sprite area
41.  
42.    ' #5 Hitbox size
43.    sprite(s).hb_size.x = scan_right(x_hb, y1, i&, d~&) - x_hb
44.    sprite(s).hb_size.y =  scan_down(x2, y_hb, i&, d~&) - y_hb
45.  
46.    y1 = y2 + 1
47.    if point(x1 - 1, y1) = d~& then ' #6 End of column
48.       if point(x1, 0) = d~& then exit do ' No more columns
49.       y1 = 2
50.       x1 = scan_right(x1, 0, i&, d~&) + 1 ' Find new column
51.    end if
52.  
53.    s = s + 1
54. loop
55.  
56. sprite_count = s
57.  
58. _source preserve&
59.  
60. end sub

(Notice the minor issue with the flexibility of the hitbox detection pixels; I realized this quirk after fully coding this, and have had bigger fish to fry since then, so I haven't gone back and updated it.  All it really means is in some fringe cases, you will need to add a row and column of empty pixels at the top and left of a sprite.  If I do get around to updating this, I'll come back and post it here.)

Now, here's an example of using the sprite data in a _putimage statement:

Code: QB64: [Select]

1. 's = [sprite index, set through the object data somehow]
2. 'frame = [frame counter used by the program to mark time units]
3.  
4. w = sprite(s).size.x
5. h = sprite(s).size.y
6.  
7. ' Animation frame
8. fpf = sprite(s).fpf
9. if fpf = 0 then fpf = 1 ' prevent division by zero
10. f = int((frame - entity(n).spawn_f) / fpf) mod sprite(s).frames ' Sprite animation frame
11.  
12. x1 = [x of object] + sprite(s).offset.x ' Use hitbox offset to get sprite position on screen
13. y1 = [y of object] + sprite(s).offset.y
14. x2 = sprite(s).pos.x + (f * (w + 2)) ' Sprite position in source image, modified by animation frame
15. y2 = sprite(s).pos.y
16.  
17. _putimage(x1, y1)-step(w, h), sprite(s).image, [image handle to draw to], (x2, y2)-step(w, h)

The last thing is to describe how the image is set up for the purposes of this parsing process, so you can follow how the routine analyzes the image, and if you want to use this slicer directly, you can easily make your own sprite sheets by following this structure.  The detection pixel color is freely changeable, the parsing routine finds it at point(0, 0).

Now, you'll want to download the image attachment, open it and zoom in so you can see pixels clearly.  The grey borders are really just to keep you from getting confused, the parser doesn't care about them.  You don't have to keep the borders there, but you do need one pixel between each sprite-frame on the sheet, and the borders shouldn't be the same as the detection color.  Note that while I've colored the detection pixels for the purposes of this explanation, they need to all be the same color as point(0, 0) normally.


Here's a step-by-step of the parsing process.  I've marked the parsing routine with numbers so you can follow it more easily.

1. First, from the current position, the red pixels are located to determine the sprite's size, seen at #1 in the routine.  The y2 coordinate will be used again later.

2. The orange pixel far to the right is found by #2 in the routine to determine the number of animation frames.  Note that the animation frames are expected to be the same size, if they aren't, you will see some strange things.

3. The second orange pixel immediately to the right of it is found by #3 in the routine, the further to the right, the more frames-per-frame.  So if it's only one pixel to the right of the other orange pixel, it will parse to a value of 1, and the animation will advance every frame.

4. Re-using the x2 and y1 coordinates that were left behind, that last box is scanned for the green pixels in #4 and #5 of the routine, to get the hitbox offset and size.  This is very intuitive - this little box outlined by these pixels is the hitbox, within the sprite's rectangle.  You can even draw a box for yourself as a visual aid - like that light-blue box I've drawn - since this last section is not an animation frame, it only contains the hitbox data.

5. The parser continues down the column with each new sprite, until it detects the end of the column, by finding the blue pixel you see there, detected by #6 in the code.  This section also looks for a new column along the top of the image, finding the other blue pixel you see at the top of the second column.  If it finds TWO such pixels - the blue and red - it knows this is the last column, and will terminate instead of looking for another column.


Do be careful with the detection pixels - it's easy to forget one, which will cause the parser to slip through and make a mistake.  For every sprite, you need:

- First-frame sprite height and width (red)
- Animation count, at right side of last animation frame (orange)
- Frames-per-frame, to the right of the previous pixel (orange)
- Four pixels giving hitbox offset and size (green)

And then you also need column end (blue), new column (blue), and last column (red) pixels.  And remember, all of these must be the same color as point(0, 0), which in this case is actually purple, like all the key pixels in the image that I haven't mentioned.


I've done the same scanning thing here with text, in order to implement a text tag replacement routine.  In my program, I've used this to make sure if the user changes the keybinds, the program will update the dialogue text that contains the keybinds to reflect the change.  It's a pretty flexible routine and can be easily expanded to do all kinds of things to text, I'll post it here too if people are interested.