Path animation

[Alarantalara]

For the last couple months I've been slowly working on reducing the download size of inferno8's campaign To Lands Unknown.
My current project is to reduce the number of files needed for many of the animations seen in game by allowing movement without restricting it to hexes.
Since it's now at a point where it works for straight line paths (minus some error handling). I thought I'd post it to see if there are any flaws with how I am doing this.

Current plans for development include rewriting the path code to allow for more interesting paths - Complete, cubic uniform B-splines and parabolas added.

This code requires version 1.9.4 or later.

Edit: Replaced code with header comment from latest version.

Code: Select all

[animate_path]

animate_path is a new tag that allows for movement of an object along paths not restricted by the hex grid

Required keys:
x,y: a sequence of points relative to the center of the reference hex in pixels through which the animation will travel
hex_x, hex_y: a hex on the map for which all other coordinates will be relative to
image: the image to display. It should have a 72 pixel transparent border surrounding it
frames: the number of frames to display in the movement
frame_length: the amount of time each frame will be visible

Optional keys:
linger: if yes, then leave the final frame visible
transpose: if yes, then the interpolation methods marked function will calculate based on y-values rather than x-values
interpolation: (default: linear) The method used to travel between points. Allowed values are: linear, bspline, parabola
Method Details:
    linear:
    bspline: requires that at least 4 points be specified
    parabola (function): requires exactly 3 points be specified - the x-values must be sorted (increasing or decreasing)

Example:
[animate_path]
    x=0,100,1000
    y=0,0,1000
    hex_x=10
    hex_y=10
    image=the_image.png
    frames=20
    frame_length=20
[/animate_path]

Note for those who want more options:
This file exposes a global table: interpolation_methods
You can add an initialization function to it to provide your own path function.
The initialization function receives a list of x values, a list of y values and the total number of locations
The number of x and y values are guaranteed to be the same

Your initialization function must return 3 functions:

The first function returns the length of each segment of the path, the number of segments and the total length of the path
It takes no parameters
<lengths>, num_lengths, total_length = length_function()
<lengths> must be an array indexed from [1..n] where n is the number of lengths
All lengths must be positive

The second function is called for each point of the path specified by the user
It takes one parameter specifying which segment in the path was reached (0..n where n is number of segments)
There are no return values

The third function is called containing the distance travelled along the current segment
This value will be in the range [0..length[segment_number]]
The function must return the absolute x,y coordinates of the associated point
x, y = get_point_on_current_segment_from_offset( offset )

I originally tried attaching this, but the extension lua is not currently allowed. Is it possible to change this? (Edit: Yes it is. Thank-you shadowmaster!)

[doofus-01]

This sounds like a nice idea. It's mostly over my head, but:

I originally tried attaching this, but the extension lua is not currently allowed. Is it possible to change this?

You could just change the extension to .txt or .cfg with a note stating that it needed to be renamed.

[Anonymissimus]

Impressive.
Cubic splines, are you serious ?
Looks like a good candidate for the wesnoth lua pack. Note that you can define functions locally within other functions.

afaik shadowmaster sets the allowed extensions - so, no.

[AI]

Shadowmaster has just fixed the lua extension upload issue.

[Alarantalara]

I shall celebrate this new found ability by uploading the current version. Now with piecewise linear movement.

I am quite serious about doing cubic splines: I've implemented them before and the matrix math is simple enough that I can do it without a library.

Edit: removed file due to new version

[Anonymissimus]

Well, I may have misunderstood...was thinking about cubic splines such as these:
http://en.wikipedia.org/wiki/B-spline

[Alarantalara]

I was thinking of natural cubic splines, but I could also do cubic B-splines. They would default to uniform splines, with the knot vector for non-uniform splines being optional.
Natural cubic splines have the advantage that they work as long as two points are specified (and 1 point is no movement, so is easy). Also every point specified is actually passed through. Conversely, they don't allow for curves that aren't functions - a side effect of actually using derivatives for the calculation.
Cubic B-splines don't have the function limitation, but only the first and last point (at best) are actually touched by the curve and a minimum of four points must be specified.

[Alarantalara]

I found a bug due to a missing division.
I have corrected it and added uniform B-splines to the path options.
Edit: Added parabolas (x and y directions)

Update: Animation is now non-destructive: items passed over are not erased unless they happen to have identical names (unlikely given that the image includes a crop function)

Update 2: Natural cubic splines finally added. Also, I now return the list of interpolation methods rather than pollute the global namespace. This completes my initial list of features. However, there is an algorithm swap I can do to improve the runtime for cubic splines and I have a couple more ideas I'm thinking of trying, so this may not be the final version.

For those who are curious, things I am considering are:

• Hex based coordinates for those who just want a fancy way to move from one hex to another.
  Simultaneous animations.
  Alternate velocity functions for the existing methods (e.g. constant time between specified points rather than constant velocity for linear interpolation).
  Allowing user-defined paths to add their own attributes to the tag - will probably require a request first.

[Alarantalara]

Since I've had two instances of people reporting errors with the animation in To Lands Unknown because they were using a version of Wesnoth prior to 1.9.4, I've further modified the code to print a reasonable error message if get_image_size isn't available.

Since this doesn't actually affect the function, I've left the old one with its less friendly error available. Perhaps I can go back to it once 1.10 arrives.

[Anonymissimus]

It's possible to "throw a hard error", that is, exit the scenario/campaign with defeat instantly, if wesnoth.game_config.version doesn't fit the required one so you can make sure that people have the requirements. Look for the [check_version] tag in SoW.

[Alarantalara]

For something that just affects the appearance of the scenario, that seems rather harsh. Thanks for telling me, though. I'll keep it in mind in case I ever do something that does have permanent effects on game state.

Edit: at one point I considered trying to make it have a fallback of just placing the object in the center of each hex passed through for the correct duration. I decided people would complain that it looked ugly though.

[Alarantalara]

Update to handle the case when the path consists of only one point. You can now use it to handle a one time animation in place. Just list the images and the number of frames. No per image timing though.

[Anonymissimus]

Tried it a bit. Leaving away frames= gives an error.

Code: Select all

		wml_actions.animate_path({
			hex_x = 17,
			hex_y = 9,
			x = "0,100,200",
			y = "0,100,200",
			image = "units/trolls/grunt.png",
			frame_length = 2000,
			frames = 20
		})

animate.PNG (179.56 KiB) Viewed 5488 times

Either not the way to be used or not the way it's supposed to be I guess.
Some more examples or more comprehensive description may help.
Version in the wlp.

[Alarantalara]

I wrote a somewhat more complete version of the documentation for Elvish_Hunter's RTF file, but everything is working as intended.
image can be a comma separated list of images. When at least two images are listed, then the code either loops through them to allow for things like walk/run cycles or, if frames is not present, then it displays each image exactly once (allows for simple animation in place for example).
So,

Code: Select all

wml_actions.animate_path({
         hex_x = 17,
         hex_y = 9,
         x = "0,100,200",
         y = "0,100,200",
         image = "units/trolls/grunt.png,units/trolls/grunt.png",
         frame_length = 2000
      })

will run without displaying an error.

The cropped troll is currently unavoidable as my implementation assumes that there is a 72 pixel transparent border surrounding the image so that I can safely crop it to simulate image offsets. image and halo in the place item tag do not accommodate x and y offsets and it was easier to simply work around the issue through the ~CROP image path function and larger images than to submit a feature request.

I know I've mentioned the required border for the images in the documentation, but it could possibly be made more prominent. Perhaps I'll copy the documentation I wrote for Elvish_Hunter back into the Lua file, since I think it is somewhat more clear than what is there currently.

[pauxlo]

The cropped troll is currently unavoidable as my implementation assumes that there is a 72 pixel transparent border surrounding the image so that I can safely crop it to simulate image offsets. image and halo in the place item tag do not accommodate x and y offsets and it was easier to simply work around the issue through the ~CROP image path function and larger images than to submit a feature request.

I just had the idea that ~CROP could also work for rectangles outside of the original image, adding transparent space there. (This would be a feature request for ~CROP). Or would it better to have a new image path function which adds empty space outside the image to avoid confusion?