How to collaborate on Construct projects with GitHub




6,163 visits, 19,349 views


This tutorial hasn't been translated.


Some useful tools

For full documentation on all the tools provided by the GitHub website and GitHub Desktop, see GitHub's help. Some useful tools you may want to explore include:

  • Reverting changes: you can change your mind about something you committed, and revert it to undo it. (Note this will create another commit that reverts an earlier commit.)
  • Rolling back to earlier versions: you can roll back your working copy to an older version of your project at any point from the past. For example if you can go back to how your project looked 3 months ago and compare how it looks and works. It's also useful in case anything is accidentally broken, since you can roll back to the last known good version.
  • Viewing history: you can see a log of changes to each individual file, with the time they were changed, the commit messages and descriptions for every change, who was changing the file, and so on.
  • Blame: the name is a bit unfortunate since hopefully you won't want to use this for accusing people, but Blame breaks down the contents of a file and shows when each part of that file was last changed and by whom. Basically it's just another useful way to look at the history, since you can see when each part of a file was last changed.
  • Create branches: a branch is like a variant of your project. For example you could make a branch, and change the menu system. If you don't like it, you can throw away the branch and keep using the old one. If you do like it, you can merge the branch over to the main one (the master branch). This is good for long-term experimental changes, since your in-progress work won't mess up the main branch that everyone else is working on.
  • Use other GitHub features like issues, project boards, the wiki and more to help your team work together effectively.

Some Construct specific quirks

Construct assigns UIDs to objects in the editor. These are saved in the layout files for each instance. Construct will assign a newly placed instance the lowest unused UID. This means if two clients who both place a new instance then merge their projects, it's possible the layout file uses the same UID for two objects. Luckily Construct handles this gracefully: if it reads a project which specifies two objects with the same UID, it will simply assign one of the objects a different UID. This will show up next time you commit - you might notice an object you didn't think you modified got a new UID, but it's just Construct making sure that it really is a unique ID! Also watch out for this in case you have any events referring to specific UIDs.

Construct uses several other kinds of internal IDs, but for these it generally uses large random numbers. This is specifically to help make merging changes easy, since as noted above, incrementing IDs can easily end up conflicting when using source control. With random IDs, in practice there is never a conflict between two people adding the same kind of item - both will still get unique IDs and they will merge just fine.

Also, avoid making manual edits to JSON files in your project. You can edit things like image and sound files outside of Construct and it should use the changes when you next open the project. However if you do something like rename an object by editing the object's JSON file directly, you will most likely corrupt the project. This is because renaming an object actually involves updating a wide range of other references across the project. Construct takes care of this for you when you rename an object from the editor, but if you do this outside of the editor it will create inconsistent references and break the project. When resolving conflicts you may be forced to edit JSON files, and in other cases you might not break anything (like changing the list of instances on a layer). But in general wherever possible you should make changes using the Construct editor to avoid breaking things.

Also note that when Construct updates, make sure everyone on your team updates at the same time. Construct project files are not backwards compatible - i.e. you can't open a project saved in r200 in r100. Similarly, while using source control, you cannot merge changes made in r200 back in to a project saved in r100 and keep using it in r100. Since the file format is not backwards compatible, you may corrupt the project. If everyone on the team updates at the same time, you'll avoid this problem.


Source control software tools like GitHub are mature and advanced tools for effectively collaborating on a project. They are widespread in traditional software development, but source control tools are general-purpose enough that teams using Construct can take advantage of them as well. Since these tools are so well-established and thorough, there should be little need for any specific collaboration features in Construct.

Source control is widely regarded as mandatory for any kind of professional development. Merging by hand is so slow, difficult and error-prone that it is well worth your time to learn source-control tools, even if it seems difficult at first. It's even handy for individual developers for all the additional tools it provides. If you're working in a team, get everyone on source control, and I'm sure before long you'll wonder how you got by without it!


  • Order by
Want to leave a comment? Login or Register an account!
  • I've been waiting for this. Thank you finally!!

  • Thanks for sharing this tutorial 👍

    It helps to solve my current problem.

  • After you invite people to join the repository, how do they acccess the construct project?

  • Very cool, when using this though, if I modify the position of an object or add new object etc, changes appear in my GIT commit list. However if I change a tilemap, adding or removing tiles, those changes do not appear in the commit list.

      • [-] [+]
      • 2
      • Ashley's avatar
      • Ashley
      • Construct Team Founder
      • 2 points
      • (3 children)

      All changes should appear in your commit list. If changes do not appear, then you have not saved the project, and the changes won't be there when you next open the project either.

      • Recorded a quick video showing the issue:

      • I've tested a few times, certainly saving the project - if I move an object and save, it appears. If I modify a tilemap and save then nothing appears in the commit list.

        What's interesting is if I edit the tile map and then do something like move an objects position, when I commit the changes the tile map edits are saved. So that data is being captured, its just if I edit the tilemap and do nothing else, git thinks I've made no edits to the project and nothing appears in the commit list.

          • [-] [+]
          • 1
          • Ashley's avatar
          • Ashley
          • Construct Team Founder
          • 1 points
          • *
          • (0 children)

          Tilemap data is saved in the corresponding layout JSON file, so check for changes there. Maybe GitHub Desktop isn't checking there or something, or perhaps you forgot to add the files in the first place.

  • wow. That's a great resource. I haven't used that yet but I really like it