Tile Animation Support

[ShadowApex]

The latest versions of Tiled supports animated tiles. I've been doing some work for my personal project, Tuxemon, to make PyTMX work with animated tiles defined in Tiled, and I'd like to see if PyTMX is interested in adding this functionality.

Right now I am using PygAnim to optionally support animated tiles in Pygame with PyTMX. I was planning on checking to see if PygAnim is available, and if it is not, tile animations would be unavailable, in order to maintain compatibility. Is this something that PyTMX would be interested in including?

[TurBoss]

👍

[bitcraft]

Yeah, animation loading would be nice to have. I just looked over the specifications for it and it should be simple to implement it. Here's are my ideas for implementing it, let me know what you think:

#1

• When an animation is encountered in the cell, use the GID for the first frame of the animation
• This will simplify tile rendering for existing games, old code doesn't have to be rewritten.
• Animations won't break old renderers, but animations won't show
• Animations can be queried by map.get_animated_tiles(), or something to that effect
• Use the return value from the query to handle animated tiles somehow

#2

• When animations are encountered, return a sequence of tuples [(image, frame duration), ...]
• Tile rendering will check each cell returned by the API if it is a single image or multiple images
• This may slightly complicate existing code, but may be more intuitive for new projects

I don't like the idea of including PygAnim dependencies. Pytmx supports pygame, pyglet, and pysdl2, and even no graphics at all because it is written to have no dependencies, and I'd like to keep it that way. There are simple loaders that I've stuck in the 'utils' modules, but I'd like to keep them as simple as possible.

Btw, I've been watching the Tuxemon project and it's impressive what you've done with it. I know you've been using it for a long time since you have checks for the old API names (getTileByGID, etc). Sorry about the confusion! Anyway, let me know what you think.

[ShadowApex]

Btw, I've been watching the Tuxemon project and it's impressive what you've done with it. I know you've been using it for a long time since you have checks for the old API names (getTileByGID, etc). Sorry about the confusion! Anyway, let me know what you think.

Cool to know you've been following Tuxemon! Yeah, I remember having to implement those checks when the API changed. Some people had older versions of PyTMX and others had the newer version, so I tried to support both. I think it's been long enough now to remove those checks if I wanted to :).

I don't like the idea of including PygAnim dependencies. Pytmx supports pygame, pyglet, and pysdl2, and even no graphics at all because it is written to have no dependencies, and I'd like to keep it that way. There are simple loaders that I've stuck in the 'utils' modules, but I'd like to keep them as simple as possible.

I think you're right in not wanting to include PygAnim as a dependency. The leaner, the better. Having a method to return a sequence of tuples would be a perfect alternative though. PygAnim takes exactly that list of tuples data structure for its animation objects. PygAnim can accept either paths to an image to load, or Pygame surfaces:

# create the animation objects   ('filename of image',    duration_in_seconds)
boltAnim = pyganim.PygAnimation([('testimages/bolt_strike_0001.png', 0.1),
                                 (some_surface_obj, 0.1)])
boltAnim.play() # there is also a pause() and stop() method

Perhaps we could create a simple loader in utils could generate that sequence of tuples in that format with the surface or image for each frame?

#1

• When an animation is encountered in the cell, use the GID for the first frame of the animation
• This will simplify tile rendering for existing games, old code doesn't have to be rewritten.
• Animations won't break old renderers, but animations won't show
• Animations can be queried by map.get_animated_tiles(), or something to that effect
• Use the return value from the query to handle animated tiles somehow

I like maintaining compatibility for old renderers with this method. I also think that having a map.get_animated_tiles() method would be really helpful in many situations. I know currently in Tuxemon, I'm handling the drawing of animated tiles differently than with normal tiles, so having this kind of method would make it easy to iterate through just the animated tiles.

#2

• When animations are encountered, return a sequence of tuples [(image, frame duration), ...]
• Tile rendering will check each cell returned by the API if it is a single image or multiple images
• This may slightly complicate existing code, but may be more intuitive for new projects

If I understand this correctly, getting a tile surface with this idea would either return a single image/surface or a list of images/surfaces, correct? I also actually like this, but would break compatibility for projects that aren't expecting a list of images/surfaces, right? I do think that doing it this way would make it easier to draw animated tiles and normal tiles on the correct layers. Right now, the way it is in my project, animated tiles and normal tiles are handled in separate draw loops, which makes it hard for me to draw animated tiles and normal tiles on the same layer.

Honestly I think there's merit to both methods. Maybe we could add an optional argument to the get_tile, etc. methods to maintain backwards compatibility?

E.g.

def get_tile_image(self, x, y, layer, with_animation=False):

What do you think?

[bitcraft]

I've merged in the initial support for animations, but will keep this issue open for discussion, and also as a reminder to myself to document it. Thanks again for the pull request!

[bitcraft]

How about making the frames a named tuple? I don't think it needs to be a separate class, but I prefer the dotted attribute access. So instead of frame['duration'], frame.duration could be used instead.

[ShadowApex]

A named tuple would be great. I also think dotted access would be nice to use. So something like this?:

>>> Frame = namedtuple('Frame', 'gid duration')
>>> duration = int(frame.attrib['duration'])
>>> gid = self.parent.register_gid(int(frame.attrib['tileid']) + self.firstgid)
>>> f = Frame(gid, duration)
>>> p['frames'].append(f)

[bitcraft]

I've already got the changes made locally. I'll push them and then update
pypi. After that, I think it's a great start. I've even updated my
scrolling lib to use the animated tiles. Works pretty well.

On Mon, Nov 23, 2015 at 3:08 PM William Edwards notifications@github.com
wrote:

A named tuple would be great. I also think dotted access would be nice to
use. So something like this?:

Frame = namedtuple('Frame', 'gid duration')>>> duration = int(frame.attrib['duration'])>>> gid = self.parent.register_gid(int(frame.attrib['tileid']) + self.firstgid)>>> f = Frame(gid, duration)>>> p['frames'].append(f)

—
Reply to this email directly or view it on GitHub
#64 (comment).

[ShadowApex]

Awesome! Sounds great!

[bitcraft]

I'm pretty happy with the implementation of animation loading now. Thanks again for your contribution, I'll close this issue now.