SpriteSheetApplicationSAB

This page is related to Summer of Code 2014

See the list of Summer of Code 2014 Ideas

This is a Summer of Code 2014 student page

Description

Aishiko GSOC 2014 SpriteSheets

My proposal is to take the current functions for drawing sprites and move it to allow for spritesheets, while hiding any of the changes from campaign designers. It should allow for the seemless intergration of spritesheets and allow for a period of conversion from multiple files to sheets.

IRC

Aishiko, Aishiko_laptop

Prelim Implementation Ideas

Goals

Eliminate as many small single images as possible from the program. Enable Sprite Sheets to be used in;

1. Gameplay
   • Units
   • Terrain
   • etc
2. Menus, mouse pointers, etc. Optional Goal I doubt at this point that I'll make it this far.
3. Reuse as much as the existing syntax as possible
4. Create Unit Tests to make sure that the areas modified are as good as I can make them.
5. Make it easy for the artists to add sprites to a sprite sheet:

Problems

• Not all units and terrain are 72x72
• Adding a boarder around each image to make it easier for the artists to see what sort of space they have to work with will make taking the current images and converting them a bit harder as well as creating a script to convert them (which remains a soft goal, ie if I have to do it AFTER the summer, I'll do that.) Stupid perfectionist leanings, at least for what I think of to get the project ready!
• Syntax making sure that its easy to use and understand for the average user

First Steps

At this point I think I would take 1 sprite (character) and create a spritesheet of it, and then test with that one. To allow testing I'd likely have it check for a spritesheet if it finds one it uses that, otherwise it uses the individual sprite images, in this way the game still works, until all the sprites have been turned into spritesheets.

Through this whole process if it breaks it should only break on the sprite sheets until then it shouldn't break at all.

How This Will Work

The way this will work is each sheet will be a grid of one colour that is not used in any of the sprites (say a shade of pink) this RGBA colour is a Primary Key, it will lay out a grid of equal sized areas within our spritesheet. Then each of those grid squares (or rectangles) each frame/image has a second border of colour, say a different shade of pink. Each unit's spritesheet will then be read at loading into the cache, each grid square will be searched for an image if found it will be loaded into an object that will contain the following information:

• SpriteSheetName
• Row
• Column
• Upper Y
• Upper X
• Lower Y
• Lower X

So each Spritesheet will generate a SpriteAddress Object and will have objects in it that give the information about each frame (given above we'll call it a SpriteFrameAddress Object). The Spritesheet and its SpriteAddress and its SpriteFrameAddress Objects will be stored in the same cache as the spritesheet itself (so we won't have to refind each frame.

Current WML modification language will be largely untouched. If feasiable each sheet will be called in WML by someting like:

image=<Female_Elvish_Archer>,[4.1~4.4]:[75*2,100,130]

which would translate out to: row 4, columns 1-4, with times of 5ms, 75ms, 100ms, and then 130ms for the images in order. This should take the current markup language and merely extand it to allow for rows and columns be the callers for an image. The <sheetName> will either relate to a memory address of the sheet or to an image under units/ like units/Elvish_Sorceress.png

SpriteSheets Phase One

would be getting something like:

image="units/elves-wood/sorceress-melee-attack-[1~10,1,2].png:[80*5,100*2,80*5]"

to work as a spritesheet with something like:

image="units/Elvish_Sorceress[2.1~2.10,2.1~2.2].png:[80*5,100*2,80*5]"

or

image="units/elves-wood/Elvish_Sorceress[2.1~2.10,2.1~2.2].png:[80*5,100*2,80*5]"

When the WML goes for the individual images that create that animation it'll look at the generated SpriteAddressObject for the needed SpriteFrameAddresses This could be extended to so there is a SpriteAnimation object that will read the configs for the unit and have say the Attack Animation instead of calling each image seperately (perhaps as a later extention?)

The ojbects might not be needed and just a config file generated that holds all the Row, Column, and X,Y data for each image might be all that is needed and will work fine.

SpriteSheets Phase Two

At this point, I'll work on getting rid of file path names in the config files, or add it in as an optional short cut way of declaring a spritesheet, something like units/elves-wood/Elvish_Sorceress.png will become Elvish_Sorceress

Cache Phase One

In cache the spritesheets would be loaded at game start and parsed as above using the scenario recruitment lists for all sides, and any recall lists. When an image is needed from a spritesheet it will gotten out of the sheet and then passed into the cache that will using and holding that image such as the scaled_to_zoom_ or tod_colored_images_. The sheets will remained cached until the game is exited completely.

Cache Phase Two

At the end of the scenario one of three things will happen, A) all the spritesheets and accomping addressing data will be dumped. Such as returning to the main menu. B) Each Spritesheet currently loaded will be compared to the next scenario loaded and any that are not needed are dropped. These 2 options should help in loading and playing on devices with limited resources to devote to a cache. C) The sheets will remained cached until the game is exited completely.

Testing

In addition to creating unit tests, I'll try out various hardware to see what sort of performance changes I can detect during the course of getting things working. I'll test on a Quad-core with 8 or more GB RAM, a Dual-core with 4GB RAM, and a 32bit single core with 1-4 GB RAM (I don't have any Macs so I can not test on that and I only have Windows in a VM, so most testing will be done under Linux I'll depend on the various developers that use windows to let me know how it is affecting the running under Windows)

Deliverables

1. Properly working Spritesheet cache to speed up loading and elimnate glithy and laging animations do to disk access times.
   1. dynamic so that low mem devices are not adversely effected. (Likely by implementing option A above).
2. Properly parse spritesheets and quickly be able to pass that information on for each frame.
3. Spritesheets that are flexible and easy for artists and WML users to implement.
   1. Spritesheets that do not have a fixed size for every frame they hold.
   2. Nor a Fixed grid size that holds each frame in its borderl.
   3. Not require to have the gridlines or the borders be a particular width (optional, could be axed for performance reasons).
4. WML syntax for Spritesheets that is not long, complex, hard to understand, or prone to errors.
5. No negative or negible impact on loading times

Packages Required

SDL:    Needed for getting the colour information
Boost:  Might be able to provide a performance boost (no pun intended)

13 Week Timeline

March 20 - April 20:

• Get more details and further flesh out the details of proposal. Create more patches (at least one every 1-2 weeks that is some bug or feature request, something not trival).
• Get more familiar with Git and GitHub. Be active in the community and encouraging to others that want to create a patch.

April 21 - May 18:

• More details hammered out and continue doing what I'd been doing during Mar 20 - April 20. Perhaps begin a little pre-coding to test theories.

May 19-June 1:

• Add a cache for just the spritesheets
  • Here in gl I'll add a spritesheets cache it will be the cache that will hold all the sprite sheets once loaded. It will have to be felxible (in size and what's loaded) and perstant. Ideally, I'd have it keep everything stored that has been stored there already, but perhaps, look at what's on the map and if say orcs are not going to be in this scenario but were in the last dropping the orc spritesheet from the cache. This would help in running wesnoth on such devices as tablets and phones with limited resources.

June 1-15:

• Add a get_spritesheet_frame function to get the image of the sprite we need right now.
  • At this point I'll create the basic get an image out of a spritesheet function. Ideally, at this point we'll know its a spritesheet and just have to send it the sheet and the information about the images in the sheet. This information would be what image we want, and what size the image is. From there the function should grab the right image and send it through the rest of the processes with nothing else having to be done to make it work.

June 16-29:

• Implement a way to determine if its a sheet or not.
  • This will require modifying the existing snytax for the WML or the way it is parsed.

June 23-27:

• Mid-term evaluation, I would like to receive feedback before this point so that if I'm not performing up to par I can work harder/longer.

June 30-July 13:

• Modify any existing functions that need to be modified to handle sheets
  • Here is where I'd need to update things that I didn't think about during the application process. I'll also use this time to further intergrate the gl::spritesheets cache into the memory management, and hopefully discover any issues at this point and can fix them/address them before the end.

July 14-27:

• Run tests and see what breaks and fix what broke
  • Unit tests would have to be added and commited to keep this up and make sure its as robust as I can make it in the timeframe allotted to make it all work.

July 28-Aug 10:

• Pad time in case something takes longer then expected
  • Something ALWAYS takes longer then expected or breaks in ways that we didn't expect and only a fool doesn't plan for the worst, so that is what this is, this is my, "OH CRAP" time. Where I have some time to address the parts that take longer or where I work on optional extended tasks like writing a shell/pythonn script to convert all the images to spritesheets.

Aug 3:

• End of all major code additions/changes, begin of code clean-up and Minor fixes begin.

Aug 11-17:

• Documentation and clean up anything that hasn't yet be done.

Aug 22:

• Final evaluation and send the required code snippets to Google.

The Weeks in the Program

Week 1: May 19 to May 25

Week 2: May 26 to June 1

Week 3: June 2 to June 8

Week 4: June 9 to June 15

Week 5: June 16 to June 22

Week 6: June 23 to June 29

Week 7: June 30 to July 6

Week 8: July 6 to July 13

Week 9: July 14 to July 20

Week 10: July 21 to July 27

Week 11: July 28 to August 3

Week 12: August 4 to August 10

Week 13: August 11 to August 17

Optional tasks if everything goes smoother and easier then planed in no particular order:

• Convert all the sprites, update all the .cfg for the base units
• Create script to allow Addon Artists convert their sprites

Artists Weigh In

OK, not just for artists, go to http://forums.wesnoth.org/viewtopic.php?f=9&t=40191 and weigh in on the details that effect you as an user! And only those details, and thank you for helping me make Wesnoth a little bit better.