GSoC-SpriteSheets Gabba

This page is related to Summer of Code 2010

See the list of Summer of Code 2010 Ideas

This is a Summer of Code 2010 student page

Description

Gabba - Sprite Sheets

I have a pretty concrete proposal of how I'd implement the idea from http://wiki.wesnoth.org/SoC_Ideas_SpriteSheets Details inside!

About Me

See http://wiki.wesnoth.org/User:Gabba.

Project

These are the essential points of what I plan to implement:

1. Keep individual pngs on svn. Makes it easier for artists. If some artists prefer to work directly with spritesheets, no problem, I'll accept that as input as well.
2. Keep WML .cfg files for unit animations as they are now, i.e. have them refer to individual .png files. (Artists can instead use a part of their own sprite sheet through the already implemented ~CROP() functor.) Makes it easier to create animations and see what are the frames of an animation.
3. Generate sprite sheets as part of the build process.
   • The size of the actual sprite sheets should be configurable as a build option, depending on the target platform memory capabilities.
   • There are several design choices to make here:
     1. do we mix all sprites from official content together? (Best for disk space, but wastes memory as you may load a whole sheet for a single image.)
     2. do we do per-campaign/per-faction sprite sheets? (Probably best for memory, still ok on disk space, and we're forced to do this for non-mainline content)
     3. we should probably allow a mix of both and let the packagers enter a set of directories with WML animation descriptions, and out come the corresponding sprite sheets.
   • If some artists are already using sprite sheets, I'll take them apart (treating each ~CROP as an individual image) and rebuild optimized spritesheets.
4. During this same build process generate new .cfg files for animations, that refer to positions within the new sprite sheets and use ~CROP(), instead of refering directly to the original .png. The new .cfg files will be identical to the old ones, except for the image references.
5. When distributing the game (except in source form), include only spritesheets and the generated .cfg files, not original .png or .cfg files.
6. Once the system is in place, work out the possible memory/display optimizations.

As far as generating the sprite sheets themselves, I'll borrow a maximum of code from the program below (licence is BSD) and adapt their GUI for wesnoth needs for testing and to complement the automated process:

ClanLib texture packer

   http://www.rtsoft.com/forums/showthread.php?t=2518
   http://www.clanlib.org/beta/index.php/Examples#Screenshots_from_ClanLib-2.0.2FUtilities

• This program takes .png with transparency as input and output, so no problem there.
• I'll modify the GUI and especially provide a command-line interface, to allow integration with the build process. Unless there's a very good case for introducing a new dependency, the modified program won't add any new dependencies to Wesnoth or its build process.
• The program currently outputs XML with info of where individual images ended up in the sprite sheets; I'll adapt this code to output modified WML .cfg files, as explained above.

I'll then spend any remaining time trying to improve the placement of images in the sprite sheets, which may seem to be nitpicking but could get crucial for low-memory devices. Misc research links about this:

   http://en.wikipedia.org/wiki/Bin_packing_problem
   http://code.google.com/p/caparf/
   http://scholar.google.com/scholar?q=%22Packing+Rectangular+Pieces+-+A+Heuristic+Approach.%22

Note: before picking the ClanLib tool as the base for my work, I evaluated the following ones:

   http://www.imagemagick.org/script/montage.php
   BlitzBasic ImagePacker - http://www.blitzbasic.com/Community/posts.php?topic=30518
   http://slick.cokeandcode.com/demos/packer.jnlp
   http://homepage.ntlworld.com/config/imagepacker/

Artists' workflow

So, how would implementing this system affect how artists work now? In short: not at all, as you can see below:

Concrete example from the drake glider (Glider.cfg):

• What it'll look like on svn (i.e., same as now):

  [attack_anim]
      (...)
       [frame]
           duration=100
           image="units/drakes/glider-kick-1.png"
       [/frame]
      (...)
  [/attack_anim]

• What it'll look like after processing through my system, and therefore in your packaged copy of the game:

  [attack_anim]
      (...)
       [frame]
           duration=100
           image="units/drakes/drakes_sprite_sheet.png~CROP(0,0,20,20)"
       [/frame]
      (...)
  [/attack_anim]

• What an artist can change it to (in either the svn source or the packaged version she downloaded from the http://www.wesnoth.org/ front page) in order to test a new image:

  [attack_anim]
      (...)
       [frame]
           duration=100
           image="units/drakes/My_New_Fancy_Glider_Kick_1.png"
       [/frame]
      (...)
  [/attack_anim]

• Or she could use this, too, to refer to her own image sheet or strip (this is already possible):

  [attack_anim]
      (...)
       [frame]
           duration=100
           image="MY_OWN_SPRITE_SHEET.png~CROP(10,10,30,30)"
       [/frame]
      (...)
  [/attack_anim]

Milestones and Calendar

Before GSoC, poke a bit more inside the code of ClanLib Texture Packer, and continue to evaluate alternate candidates. Do a few spritesheet tests to try and locate problems that could affect this project. GSoC start according to Google's calendar: May 24

• Add a commmand line interface to the ClanLib app, and test generations of sets of spritesheets of various sizes, using a list of image folders as input. Discuss design issues for the following milestones.
  • Deadline: June 7
• Integrate parsing of WML files with animation data to harvest the list of images (and parts of images) to use as input. Adapt the ClanLib app's current interface to my testing needs.
  • Deadline: June 21
• Output updated WML files with the new location of images within spritesheets.
  • Deadline: July 5
• Start integration of the tool with the Wesnoth build process.
  • Deadline: July 16 (Mid-term evaluation)
• Finish integration with the build process, do final adjustments to UI, do memory benchmarks and resolve caching issues, document stuff
  • Deadline: August 9
• If things go faster than planned, implement various bin-packing algorithms to try and do even better than the clanlib texture packer. Test them with various spritesheet sizes and various sets of images.