Skip to content

How to Contribute

Jump to bottom
Valentin Simonov edited this page Jul 30, 2017 · 17 revisions

Hello!

I am glad that you decided to contribute to TouchScript.

Even if you are here just to clone the library and use it from the source project, it's always the first step to a pull request!

This page contains everything you should know about TouchScript to start contributing.

How to Contribute?

TouchScript is an open source project, like all the other open source projects out there it needs your support!
You can contribute in several ways:

  • Fix bugs in code — if you found a bug and know how to fix it, it will be very helpful for the project if you fixed it and submitted a pull request;
  • Add features — if you need a specific feature for your project and think that it could be useful for others, feel free to submit a pull request;
  • Write tutorials — if you are not a developer or are not experienced enough to read TouchScript's code, you can still help by updating the docs and writing tutorials. Because good documentation is what makes an open source project alive;
  • Test it on devices — TouchScript can be used on various devices but I don't have all of them nor I have time to test the library everywhere, so I would be really glad if you could run examples or test your project using TouchScript on devices you have.

If you fixed a bug, added a feature or corrected a typo in comments and want to contribute this fix, before doing a pull request please do the following:

  • Read Main Ideas Behind TouchScript.
    Unfortunately, if your code conflicts with general vision of what TouchScript is and what it isn't, your code will not be accepted.
  • Read Code Conventions and make sure that your code follows them. I try to keep the repository clean and uniform.

With all these steps done your awesome new feature or fix of a hard-to-find bug is more than welcome!

Project Structure

The project is split into several sub-folders.

When you first clone the repository (and I recommend to use current develop branch to be up-to-date with ongoing development) you will see the following folder structure:

  • AssetStore — the project used to update TouchScript Asset Store page. You will not need this.
  • Build — build scripts to automatically generate TouchScript.unitypackage, build external libraries and synchronize modules.
  • Docs — Sandcastle Help File Builder project to generate online docs.
  • External — external projects which go to TouchScript as built assemblies. In the time of writing this folder contains: TUIO support source, Windows touch C++ plugin source.
  • Modules — Unity projects for 3rd party tools support. These projects require paid assets which have to be bought separately and can't be distributed with TouchScript. (It used to contain Playmaker and Scaleform integrations until they were removed)
  • Resources — sources for assets used in TouchScript.
  • Source — main TouchScript Unity project.

Starting with the Source project

  1. First, clone the project from Github.
  2. Make sure that you pulled all submodules.
  3. Use TouchScript.

To be able to use TUIO you will need to build TUIO DLLs or grab them from the latest release. To build the DLLs you either need to run Build/build_external.sh script which compiles the DLLs and copies them into the Source project; or manually compile the DLLs by opening the project in Visual Studio, it will put them into Source/Assets/TouchScript/Modules/TUIO/Libraries folder.

To be able to use Windows touch you will need to build WindowsTouch.dll or grab it from the latest release. To build the DLL you (once again) either need to run Build/build_external.sh script (but this time only on Windows); or manually compile the DLL by opening the project in Visual Studio, it will put the DLL to Source/Assets/TouchScript/Plugins/WindowsTouch folder (but don't forget that there is also a 64bit version in that folder).

Build scripts

There are few scripts in Build folder which might be useful for you:

  1. build_external.sh builds external libraries and was already mentioned. This script assumes that on Mac you have Unity installed in /Applications/Unity/Unity.app and on windows that you have .NET 4+ installed.
  2. sync_modules.sh backs up files added to git from TouchScript folders in all modules in Modules folder, copies TouchScript folder from the Source project to every module and restores backed files. Since TouchScript folder in Modules is not added to git this approach allows synchronizing source and modules development easy enough.
  3. package.sh refreshes everything and builds a unitypackage.

Source

TouchScript source is heavily documented. You can find the most up-to-date documentation here.

TouchScript uses preprocessor defines to enable some of it's functionality. Read more about it.

How does TouchScript Work?

If you want to know how TouchScript internals work please read the following documents:

Home

Help

Basic

Advanced

Contributing

Clone this wiki locally