prime31 / touchkit

Gestures and input handling made sane for Unity

TouchKit

TouchKit aims to make touch handling in Unity more sane. Touches in TouchKit are actual objects as opposed to Structs like Unity uses by default. The advantage to this is that touch tracking becomes orders of magnitude more simple. You can retain a touch that began and since you are only holding on to a pointer (as opposed to a Struct) the properites of that touch will be updating as the touch changes. TouchKit doesn't save too much time for simple, single-tap processing. It's usefulness is in detecting and managing gestures (hence the original name before the lovely trademark owner complained: GestureKit).

TouchKit allows gesture recognizers to act on the entire screen or they can define a Rect in which to do detection. If a touch doesn't orginate in the Rect the touches won't be passed on to the recognizer (except for the Any Touch Recognizer).

Included Gesture Recognizers

TouchKit comes with a few built in recognizers to get you started and to serve as an example for how to make your own. Included are the following:

• Tap Recognizer: detects one or more taps from one or more fingers
• Long Press Recognizer: detects long-presses with configurable duration and allowed movement. Fires when the duration passes and when the gesture is complete.
• Button Recognizer: generic button recognizer designed to work with any 2D sprite system at all
• Pan Recognizer: detects a pan gesture (one or more fingers down and moving around the screen)
• TouchPad Recognizer: detects and tracks a touch in an area and maps the location from -1 to 1 on the x and y axis based on the touches distance from the center of the area
• Swipe Recognizer: detects swipes in the four cardinal directions
• Pinch Recognizer: detects pinches and reports back the delta scale
• Rotation Recognizer: detects two finger rotation and reports back the delta rotation
• One Finger Rotation Recognizer: pass it a target object's center position and it will report back the delta rotation of a single finger
• Any Touch Recognizer: fires enter/exit events whenever a touch enters/exist the boundary. the difference here is that it will allow a touch to begin outside of it's frame and then move into its frame. handy for directional buttons.

How Do I Use TouchKit?

If you are just using the built in recognizers, check out the demo scene which shows how to use them. You will want to use Unity's script execution order (Edit -> Project Settings -> Script Execution Order) to ensure that TouchKit executes before your other scripts. This is just to ensure you have your input when the Update method on your listening objects runs.

When working with recognizers that are not full screen, the TKRect class is used to define the rectangle. TouchKit has an automatic scaling system built in that is turned on by default. What that means is that you set your TKRect sizes only once for any screen size and density. By default, the design time resolution (TouchKit.designTimeResolution) that TouchKit uses is 320 x 180. You can change that to whatever you want. When you create your TKRects you set the size and origin based on that exact screen size. At runtime, TouchKit will scale the rects based on the actual screen resolution.

If you want to make your own (and feel free to send pull requests if you make any generic recognizers!) all you have to do is subclass TKAbstractGestureRecognizer and implement the three methods: touchesBegan, touchesMoved and touchesEnded. Recognizers can be discrete (they only complete once like a tap or long touch) or continous (they can fire continuously like a pan). Recognizers use the state variable to determine if they are still active, completed or failed. If you set the state to Recognized, the completion event is fired automatically for you and the recognizer is reset in preparation for the next set of touches.

Starting with touchesBegan, if you find a touch that look interesting you can add it to the _trackingTouches List and set the state to Began. By adding the touch to the _trackingTouches List you are telling TouchKit that you want to receive all future touch events that happen with that touch. As the touch moves, touchesMoved will be called where you can look at the touches and decide if the gesture is still possible. If it isn't, set the state to Failed and TouchKit will reset the recognizer for you.

Using the Tap recognizer as an example, the flow would be like the following:

• touchesBegan: add the touch to _trackingTouches signifying we are watching it. Set the state to Began and record the current time (we don't want a press that is too long to be considered a tap)
• touchesMoved: check the deltaMovement of the touch and if it moves too far set the state to Failed signifying the gesture failed and we are done with the touch
• touchesEnded: if not too much time has elapsed we successfully recognized the gesture so we set state to Recognized which will fire the event for us. If too much time elapsed we set state to Failed

UI Touch Handling Replacement

TouchKit can be used for any and all touch input in your game. The TKButtonRecognizer class has been designed to work with any sprite solution for button touch handling. This lets you keep your input totally separate from your rendering. It implements the same setup that iOS does: a highlighted button expands its hit rect for better useability.

License

For any developers just wanting to use TouchKit in their games go right ahead. You can use TouchKit in any and all games either modified or unmodified. In order to keep the spirit of this open source project it is expressly forbid to sell or commercially distribute TouchKit outside of your games. You can freely use it in as many games as you would like but you cannot commercially distribute the source code either directly or compiled into a library outside of your game.

Feel free to include a "prime31 inside" logo on your about page, web page, splash page or anywhere else your game might show up if you would like. medium huge

touchkit's Issues

TKTapRecognizer "numberOfTapsRequired" doesn't work

The class TKTap Recognizer doesn't actually do anything with the public int "numberOfTapsRequired", so when you try to adjust it to do a double tap or anything it just doesnt work. I looked for any references to it's usage in monodevelop and it found none.

public class TKTapRecognizer : TKAbstractGestureRecognizer
{
public int numberOfTapsRequired = 1;
public int numberOfTouchesRequired = 1;

...
}

Making TouchKit Package for the PackageManager

If this repo was set-up as a Unity package, it would be possible to add it as git url into the Unity Package Manager. This would make developers life easier. Also I think it could be possible to use it as dependency for other libraries, given the license.

Infos on how to use and implement:
https://docs.unity3d.com/Manual/upm-git.html
https://docs.unity3d.com/Manual/upm-manifestPkg.html

TKSwipeRecognizer also needs gestureCompleteEvent

TKSwipeRecognizer also needs to fire gestureCompleteEvent when the finger is lifted if the swipe was recognized. This will be very useful in games where swipe is the main control, where you can implement long presses with this. Without this functionality, players have to swipe constantly to move. which is cumbersome to say the least.

I will try to implement it by myself and will make a pull request after finishing it.

License

I'm no expert, but I suspect the current license makes it unusable for companies that make experts check their licenses. It would be nice to hear an expert. Maybe picking a license for "use in games" and prohibiting the "use in similar libraries" would be good?

Probably picking MIT for everything would be better.

With TKPinchRecognizer often get "found touch Unity forgot to end"

found touch Unity forgot to end with phase: Stationary
UnityEngine.Debug:LogWarning(Object)
TouchKit:addTouchesUnityForgotToEndToLiveTouchesList() (at Assets/Packages/TouchKit/Plugins/TouchKit/TouchKit.cs:65)
TouchKit:Update() (at Assets/Packages/TouchKit/Plugins/TouchKit/TouchKit.cs:142)

After getting this warning, recognizer will stop working. It will trigger inconsistently, sometimes during the first pinch, sometimes after a lot. The problem is it'll stop working once it happen.

TKLTouch instead of TKTouch in namespace Prime31

In file TouchKitLite every TKTouch should be changed with TKLTouch cos error is thown can't convert type TKTouch to TKLTouch. +1:

How to make just one gesture occur at a given time ?

When i add more gestures , like pan , swipe and pinch recognizer, when i just move the screen, swipe and pan gesture will be fired at the same time; when i pan screen , then don't lift one finger, then add another finger to pinch screen, then this will fire pinch event; but i just want fire one event at the same time and make one finger pan or two finger pan , how can i implement them ?

Add gesture to rotate the camera with two fingers around the scene

TKPinchRecognizer accidentally counts the first touch twice

I am not completely familiar with your codebase yet, but I have found a temporary solution to the problem, and the solution may help you pinpoint the problem.

It is occurring on a Windows 7 and a Windows 8 touchscreen device.

In the method touchesBegan, the line if( touches[i].phase == TouchPhase.Began ) is causing the problem. Touch 0 and touch 1 are identical (they have the same fingerID).

My temporary solution uses the following code inside the problematic if statement:

if (this.isUniqueID(_trackingTouches, touches[i])) {
    _trackingTouches.Add( touches[i] );
    // DebugConsole.Log(string.Format("Touch :: Pos: {1}, ID: {2}", i, touches[i].position, touches[i].fingerId));
}

// .... after the touchesBegan method
private bool isUniqueID(List<TKTouch> touches, TKTouch touch)
{
    for (int i = 0; i < touches.Count; i++) {
        if (touches[i].fingerId == touch.fingerId)
        {
            return false;
        }
    }
    return true;
}

Also, it is worth noting that because of this, the pinch gesture in the first demo scene does not work.

Pinch and Swipe together issues

I have added a swipe recognizer to my character, to move him around the screen.

I also added a pinch recognizer to zoom the camera in and out.

The problem I am running into is that occasionally, while zooming the camera, the character will recognize a swipe and start walking around. Any idea how to get the swipe recognizer to see that a pinch is in progress, and ignore any swipes it thinks it is detecting?

Any help is appreciated.
-Larry

TouchKit.removeAllGestureRecognizers(); error

if you execute this code

recognizer.onTouchUpInsideEvent += (r) =>
{
TouchKit.removeAllGestureRecognizers();
};

you get an InvalidOperationException

on line 157 in TouchKit.

Please change:

this

foreach (var recognizer in _gestureRecognizers)
{
recognizer.recognizeTouches(_liveTouches);
}

to this

foreach (var recognizer in _gestureRecognizers)
{
recognizer.recognizeTouches(_liveTouches);
if (_gestureRecognizers.Count == 0)
break;
}

TKTouchPadRecognizer doesn't call its gestureCompleteEvent

I'm leaving a note there as I'm investigating this problem myself.

It looks like the gestureCompleteEvent of TKTouchPadRecognizer is never being called.
I tried to debug the problem and it looks like the isTrackingTouch method returns false for the ending touch, which is kind of weird.

I'm registering the recognizer just like in the demo:

            AnimationCurve touchPadInputCurve = AnimationCurve.Linear( 0.0f, 0.0f, 1.0f, 1.0f );
            var recognizer = new TKTouchPadRecognizer( new TKRect( 0f, 50f, Game.DesignWidth, Game.DesignHeight-50 ) );
            recognizer.inputCurve = touchPadInputCurve;

            recognizer.gestureRecognizedEvent += ( r ) =>
            {
                //Camera.main.transform.position -= new Vector3( recognizer.deltaTranslation.x, recognizer.deltaTranslation.y ) / 100;
                Debug.Log( "touchpad recognizer fired: " + r );
            };

            // continuous gestures have a complete event so that we know when they are done recognizing
            recognizer.gestureCompleteEvent += r =>
            {
                Debug.Log( "touchpad gesture complete" );
            };
            TouchKit.addGestureRecognizer( recognizer );

If you put a breakpoint in isTrackingTouch you can see that _trackingTouches is empty, but I cannot find who's clearing it before it should be cleared.

I might need a hand with this. Cheers!

Simulating touches on editor not working

I have integrated touch kit into a game according to the docs, I was not able to test the simulate touches with mouse in the editor here is my touch kit component in editor

PopulateFromMouse is wrong with low-framerate and fast clicking

With a low framerate it is possible for Input.GetMouseButtonUp and Input.GetMouseButtonDown to be true for the same frame. This causes populateFromMouse to begin a new touch before the last one has ended. This ultimately ends up with gestures having the same touch (id=0) inserted into their _trackingTouches list.

Near the top of internalUpdateTouches right after this line:
_liveTouches.Add( _touchCache[0].populateFromMouse() );
I added the following code:
mu += Input.GetMouseButtonUp(0) ? "u" : "-";
m += Input.GetMouseButton(0) ? "m" : "-";
md += Input.GetMouseButtonDown(0) ? "d" : "-";
history += _liveTouches.Count != 0 ? ((int)_liveTouches[0].phase).ToString() : "-";
Debug.Log(history + "\n" + mu + "\n" + m + "\n" + md);

This prints:
----------0112223------02111301303013-03--0110
----------------u-----------u--u-u--u--u-----u
----------mmmmmm-------mmmmm-mm-m-mm--m---mmmm
----------d------------d-----d--d-d---d---d--d

As can be seen, at the end (0110 pattern) means you get "Begin Move Move Begin" for the fake touch which causes the issue.

Can't build for PC/Mac

line 58 in Assets/TouchKitLite/TKLTouch.cs will make a pc/mac build fail.

Two touches get counted as three on Windows Standalone

On a Surface with Windows 8 Pro TouchKit doesn't detect gestures properly because it counts the first touch as a touch and a mousclick.
Therefore, if you touch the screen with two fingers, three _liveTouches are counted.

I solved this problem in my case by removing UNITY_STANDALONE_WIN from the preprocessor directives in internalUpdateTouches.
However, this isn't a general solution because as to be expected the mouse input is ignored.

Not working after pressing Home button and resuming several times on Android device.

What happened?

Test it on Android device (Nexus S). After pressing the Home button to exit game and resume it several times, the game don't response any touch.

What lead this problem?

In TouchKit, new qualified touch reply on the figureId, and after resuming from background the Unity don't allocate figureId start with 0.

private void Update()
{
    ......
    //After resuming, the fingerId may start bigger than maxTouchesToProcess
    if( touch.fingerId < maxTouchesToProcess )
        _liveTouches.Add( _touchCache[touch.fingerId].populateWithTouch( touch ) );
    ......
}

[BUG] Horizontal swipe recognized without pointer up

Repro:

1. Create a scrollview
2. Init horizontal swipe (TKSwipeRecognizer)
3. Hold the left mouse button and start dragging the list fast
   Result:
   recognizer fires gestureRecognizedEvent while dragging.

Expected behaviour:
recognizer fires gestureRecognizedEvent only when was dragging fast and released the button

Possibly related to:
#52

Exceeding of maximumNumberOfTouches must finalise gesture

Exceeding of maximumNumberOfTouches must finalise gesture because now if you want implement different behaviour for singe and double pinch you will have conflict

TouchKit Lite Documentation

There is any kind of TouchKitLite documentation, I can't find it anywhere, it is kinda of different from standard touch and I can't find myself on code (even it beeing so small).

Help with custom script using Touchkit

I am creating a 2D game, and I am wanting to use touch screen gestures to change game cameras. I don't know if this is something that can be implemented easily. I have been working on this all afternoon, and I need some outside help. I am a complete noob to C#, so I may have a number of issues that would be problematic. I was thinking that I could use some code kinda like this to make this work:

public Camera camorig;
public Camera camleft;
public Camera camright;

void Update () {

		CameraTransition cameraTransition = GameObject.FindObjectOfType<CameraTransition>();
		if (cameraTransition == null)
			Debug.LogWarning(@"CameraTransition not found.");

		var recognizer = new TKSwipeRecognizer();
		recognizer.gestureRecognizedEvent += ( r ) =>
		{
			Debug.Log( "swipe recognizer fired: " + r );
		} ;
		TouchKit.addGestureRecognizer( recognizer );

		if (state == TKGestureRecognizerState.Recognized) {
			
			if (completedSwipeDirection == TKSwipeDirection.Left) {

				cameraTransition.DoTransition (CameraTransitionEffects.Fold, camorig, camleft, 1.0f);
				 
			} else if (completedSwipeDirection == TKSwipeDirection.Right) {

				cameraTransition.DoTransition (CameraTransitionEffects.Fold, camorig, camright, 1.0f);

			} else {

				Debug.Log (@"Swipe not successful");
			}
		}

		else {

			Debug.Log (@"Gesture not recognized");
		}
	}

You can see that I am using another addon to facilitate transitions between cameras. Would something like this work, or am I completely off? I didn't know if I could use variables like "state" and "completedSwipeDirection" from the swipe recognizer, so that might be an issue. Because of that, I duplicated the recognizer and simply added this code to it, intending to attach the recognizer to my game object, but I wasn't able to attach it because it didn't derive from MonoDevelop. Any help would be much appreciated!

cstobler

touchEnded event does not work properly

if one button is released touchEnded event is called on all of the buttons (same with touch moved)

How can I prevent TouchKit from dispatching an event when tapping on UI Elements?

Basically what the title says.

I'm using this in my game and it's working great. My game needs a tap recognizer, that wherever you tap, an action happens. But there are specific places of the UI that have UI Canvas Buttons. If I touch those, both their actions plus the tap recognizer fire. How can I prevent the Tap Recognizer from firing when tapping on Canvas elements?

Thanks!

Mac OS trackpad Gesture

I don't know if it can be seen as an issue but it seems to me that it is not possible to detect touches and gestures made on a Macbook trackpad

Can't use boundaryFrame or TKRect in 3D game

Either I'm missing something or TKRects don't work unless your game is setup for 2D.
I'd like my 3D game to only listen for touches in a particular area of the screen.

Example scenes do not work with newer versions of Unity

As someone just getting my head in to this library, it doesn't help that everything is built using some custom UI scripts rather than the Unity UI system introduced in Unity 5. This has rendered the examples almost entirely non-functional.

[BUG] Horizontal swipe not recognized if there was an arbitraty dragging before

Repro:

1. Create a scrollview
2. Init horizontal swipe (TKSwipeRecognizer)
3. Unset triggerWhenCriteriaMet (see details #66)
4. Hold the left mouse button and drag slowly from left to right, then from right to left (for example). Then make a fast drag and only now release the button.

Result:
recognizer do not fire gestureRecognizedEvent

Expected behaviour:
recognizer fires gestureRecognizedEvent. That's how it works in vkontakte app when watching photo album for example.

Why is that important:
User may just dragged a bit before swiping because he is inside the bus which makes him shake from time to time

Mouse Input - simulate Pinch and Rotate with separate modifier keys

I have pinch and rotate gestures set up which works excellently with touchscreens but I also need to build for desktop. When simulating multiple touches with the alt key, pinch and rotate happen at the same time- is it possible to split these out so pinch works when the ctrl key is pressed and rotate when the alt key is pressed..

TKLongPressRecognizer

In the constructor there is an error.

    this.allowableMovementCm = allowableMovementCm;

Should be...

    this.allowableMovementCm = allowableMovement;

How to use TouchkitLite

How should we use TouchkitLite? Can we use it as a standalone?