Added an example about cancelling animations. (#171)

Author: paweljarosz

animation/cancel_animation/all.texture_profiles

@@ -0,0 +1,18 @@
+path_settings {
+  path: "**"
+  profile: "Default"
+}
+profiles {
+  name: "Default"
+  platforms {
+    os: OS_ID_GENERIC
+    formats {
+      format: TEXTURE_FORMAT_RGBA
+      compression_level: BEST
+      compression_type: COMPRESSION_TYPE_DEFAULT
+    }
+    mipmaps: false
+    max_texture_size: 0
+    premultiply_alpha: true
+  }
+}

animation/cancel_animation/assets/SourceSansPro-Semibold.ttf

@@ -0,0 +1,4 @@
+images {
+  image: "/assets/images/shipBlue_manned.png"
+}
+extrude_borders: 2

animation/cancel_animation/assets/images/shipBlue_manned.png

@@ -0,0 +1,5 @@
+font: "/assets/SourceSansPro-Semibold.ttf"
+material: "/builtins/fonts/font-df.material"
+size: 32
+output_format: TYPE_DISTANCE_FIELD
+characters: " !\"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~"

animation/cancel_animation/assets/sprites.atlas

@@ -0,0 +1,23 @@
+---
+tags: animation, input
+title: Cancel animation
+brief: This example shows how to use `go.cancel_animations()` to stop a running animation and start a new one.
+author: Defold Foundation
+scripts: cancel_animation.script
+---
+
+The collection contains two game objects:
+- `ship` with one sprite and one script.
+- `description` with a label for displaying the instructions text
+
+![setup](setup.png)
+
+## How It Works
+
+The script starts an animation of movement along the X axis in `init()`. The ship starts moving to the right and back. Then it listens for input so it can interrupt that animation.
+
+Clicking or tapping cancels the currently played animations immediately and starts a new one to move the ship toward the new x position instead.
+
+When the player presses the mouse button or touches the screen, the script first calls [`go.cancel_animations()`](https://defold.com/ref/go-lua/index.html#go.cancel_animations:url-property). Defold stops the running tween and leaves the game object's position exactly where it was at that moment.
+
+The script then calls [`go.animate()`](https://defold.com/ref/go-lua/index.html#go.animate:url-property-playback-to-easing-duration-delay-complete_function) again with the clicked x coordinate as the new target. Because the old animation was canceled first, the new tween starts from the ship's current position instead of jumping back to the original starting point.

animation/cancel_animation/assets/text32.font

@@ -0,0 +1,46 @@
+name: "default"
+scale_along_z: 0
+embedded_instances {
+  id: "ship"
+  data: "components {\n"
+  "  id: \"script\"\n"
+  "  component: \"/example/cancel_animation.script\"\n"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"sprite\"\n"
+  "  type: \"sprite\"\n"
+  "  data: \"default_animation: \\\"shipBlue_manned\\\"\\n"
+  "material: \\\"/builtins/materials/sprite.material\\\"\\n"
+  "textures {\\n"
+  "  sampler: \\\"texture_sampler\\\"\\n"
+  "  texture: \\\"/assets/sprites.atlas\\\"\\n"
+  "}\\n"
+  "\"\n"
+  "}\n"
+  ""
+  position {
+    x: 80.0
+    y: 360.0
+  }
+}
+embedded_instances {
+  id: "description"
+  data: "embedded_components {\n"
+  "  id: \"label\"\n"
+  "  type: \"label\"\n"
+  "  data: \"size {\\n"
+  "  x: 600.0\\n"
+  "  y: 32.0\\n"
+  "}\\n"
+  "line_break: true\\n"
+  "text: \\\"Click or touch anywhere to cancel current animation and move to the cursor position\\\"\\n"
+  "font: \\\"/assets/text32.font\\\"\\n"
+  "material: \\\"/builtins/fonts/label-df.material\\\"\\n"
+  "\"\n"
+  "  position {\n"
+  "    x: 360.0\n"
+  "    y: 60.0\n"
+  "  }\n"
+  "}\n"
+  ""
+}

animation/cancel_animation/example.md

@@ -0,0 +1,19 @@
+function init(self)
+	msg.post(".", "acquire_input_focus") -- <1>
+	go.animate(".", "position.x", go.PLAYBACK_ONCE_FORWARD, 600, go.EASING_INOUTSINE, 5.0) -- <2>
+end
+
+function on_input(self, action_id, action)
+	if (action_id == hash("mouse_button_left") or action_id == hash("touch")) and action.pressed then -- <3>
+		go.cancel_animations(".", "position") -- <4>
+		go.animate(".", "position.x", go.PLAYBACK_ONCE_FORWARD, action.x, go.EASING_INOUTSINE, 1.2) -- <5>
+	end
+end
+
+--[[
+1. Acquire input focus so the script receives mouse clicks and touch presses.
+2. Start with a long horizontal animation toward x = 600 so there is something to interrupt.
+3. React to either a left mouse click or a touch press.
+4. Cancel the running position animation. Defold keeps the property at its current value when the animation is canceled.
+5. Start a new animation from that current x position toward the clicked x coordinate.
+]]

animation/cancel_animation/example/cancel_animation.collection

@@ -0,0 +1,65 @@
+[project]
+title = Cancel Animation
+version = 0.1
+
+[bootstrap]
+main_collection = /example/cancel_animation.collectionc
+
+[input]
+game_binding = /builtins/input/all.input_bindingc
+repeat_interval = 0.05
+
+[display]
+width = 720
+height = 720
+high_dpi = 1
+
+[physics]
+scale = 0.02
+gravity_y = -500.0
+
+[script]
+shared_state = 1
+
+[collection_proxy]
+max_count = 256
+
+[label]
+subpixels = 1
+
+[sprite]
+subpixels = 1
+max_count = 32765
+
+[windows]
+iap_provider = 
+
+[android]
+package = com.defold.examples
+
+[ios]
+bundle_identifier = com.defold.examples
+
+[osx]
+bundle_identifier = com.defold.examples
+
+[html5]
+show_fullscreen_button = 0
+show_made_with_defold = 0
+scale_mode = no_scale
+heap_size = 64
+
+[graphics]
+texture_profiles = /all.texture_profiles
+
+[collection]
+max_instances = 32765
+
+[particle_fx]
+max_emitter_count = 1024
+
+[render]
+clear_color_blue = 0.183594
+clear_color_green = 0.164063
+clear_color_red = 0.160156
+