FlxTween: add cancelChain() (HaxeFlixel#1988)

flixel/tweens/FlxTween.hx

@@ -373,6 +373,7 @@ class FlxTween implements IFlxDestroyable
 	private var _running:Bool = false;
 	private var _waitingForRestart:Bool = false;
 	private var _chainedTweens:Array<FlxTween>;
+	private var _nextTweenInChain:FlxTween;
 
 	/**
 	 * This function is called when tween is created, or recycled.
@@ -409,6 +410,7 @@ class FlxTween implements IFlxDestroyable
 		ease = null;
 		manager = null;
 		_chainedTweens = null;
+		_nextTweenInChain = null;
 	}
 
 	/**
@@ -495,8 +497,10 @@ class FlxTween implements IFlxDestroyable
 	}
 
 	/**
-	 * Immediately stops the Tween and removes it from the 
-	 * TweenManager without calling the complete callback.
+	 * Immediately stops the Tween and removes it from its 
+	 * `manager` without calling the `onComplete` callback.
+	 *
+	 * Yields control to the next chained Tween if one exists.
 	 */
 	public function cancel():Void
 	{
@@ -505,6 +509,27 @@ class FlxTween implements IFlxDestroyable
 		if (manager != null)
 			manager.remove(this);
 	}
+
+	/**
+	 * Immediately stops the Tween and removes it from its
+	 * `manager` without calling the `onComplete` callback
+	 * or yielding control to the next chained Tween if one exists.
+	 *
+	 * If control has already been passed on, forwards the cancellation
+	 * request along the chain to the currently active Tween.
+	 */
+	public function cancelChain():Void
+	{
+		// Pass along the cancellation request.
+		if (_nextTweenInChain != null)
+			_nextTweenInChain.cancelChain();
+
+		// Prevent yielding control to any chained tweens.
+		if (_chainedTweens != null)
+			_chainedTweens = null;
+
+		cancel();
+	}
 
 	private function finish():Void
 	{
@@ -570,7 +595,10 @@ class FlxTween implements IFlxDestroyable
 		if (_chainedTweens == null || _chainedTweens.length <= 0)
 			return;
 
-		doNextTween(_chainedTweens.shift());
+		// Remember next tween to enable cancellation of the chain.
+		_nextTweenInChain = _chainedTweens.shift();
+
+		doNextTween(_nextTweenInChain);
 		_chainedTweens = null;
 	}
 

tests/unit/src/flixel/tweens/FlxTweenTest.hx

@@ -82,6 +82,66 @@ class FlxTweenTest extends FlxTest
 		step();
 	}
 
+	@Test
+	function testCancelChainFirstTweenUnfinished()
+	{
+		var chain = createChain(4);
+
+		while (!chain.updated[0])
+			step();
+
+		Assert.isFalse(chain.completed[0]);
+
+		chain.tweens[0].cancelChain();
+
+		for (i in 0...chain.count)
+			finishTween(chain.tweens[i]);
+
+		for (i in 1...chain.count)
+			Assert.isFalse(chain.updated[i] || chain.completed[i]);
+	}
+
+	@Test
+	function testCancelChainFirstTweenFinished()
+	{
+		var chain = createChain(4);
+
+		while (!chain.updated[1])
+			step();
+
+		Assert.isTrue(chain.updated[0] && chain.completed[0]);
+		Assert.isFalse(chain.completed[1]);
+
+		chain.tweens[0].cancelChain();
+
+		for (i in 1...chain.count)
+			finishTween(chain.tweens[i]);
+
+		for (i in 2...chain.count)
+			Assert.isFalse(chain.updated[i] || chain.completed[i]);
+	}
+
+	function createChain(count:Int)
+	{
+		var updated = [for (i in 0...count) false];
+		var completed = [for (i in 0...count) false];
+		var tweens = [for (i in 0...count)
+			makeTween(0.1,
+				function (_) completed[i] = true,
+				function (_) updated[i] = true
+		)];
+
+		for (i in 1...count)
+			tweens[0].wait(0.1).then(tweens[i]);
+
+		return {
+			count: count,
+			updated: updated,
+			completed: completed,
+			tweens: tweens
+		}
+	}
+
 	@Test
 	function testLinearChain()
 	{