How to collaborate on Construct projects with GitHub

56

Index

Stats

22,001 visits, 63,347 views

Tools

Translations

This tutorial hasn't been translated.

License

This tutorial is licensed under CC BY 4.0. Please refer to the license text if you wish to reuse, share or remix the content contained within this tutorial.

Published on 1 Apr, 2020. Last updated 12 Sep, 2024

Construct's project folder structure

In Chrome (and other Chromium-based browsers like Edge and Opera), you can save projects to a local folder. It's necessary to use this option when using source control like Git, since it allows you to work with a range of individual files, instead of a single .c3p file.

Since you'll be dealing with individual files in the project folder, it's worth knowing how it's structured and what each folder and file is for. This is the overall project folder structure as saved from the Space Blaster demo project:

First, the main project file is a .c3proj file (really just a JSON file) in the root. This stores all the project settings and a list of everything used in the project. Other parts of the project are saved in subfolders as follows:

  • eventSheets stores all the event sheets used in your project in JSON format.
  • objectTypes and families store data for all the object types and families added to your project in JSON format.
  • images stores all the images used in your project by all objects in PNG format. The image filenames are either the name of the object for non-animated objects (e.g. tiledbackground.png), or the object name, animation name and frame number for animated objects (e.g. player-default-000.png).
  • layouts stores all the layouts used in your project, including the layers and where all objects are placed, in JSON format.
  • Other folders like icons, music and sounds store project files from their corresponding folders in the Project Bar.

Some folders may be missing if a project does not have any content for them. For example a project with no families may omit the families folder. However it will be created if any families are added to the project.

UI state files

There are also several .uistate.json files in both the root and some of the subfolders. These are JSON files that separately store the user interface state, like which tabs are currently open. This is stored in a separate file because typically you do not want to share it. Having to log a change for the rest of the team just because you switched a tab is unnecessary and a possible source of problems, so Construct deliberately saves this separately so you can exclude it. Basically, the file is for you only and is of no interest to the rest of the team.

Source control basics

The image below shows the basic architecture of a source control system:

The server has the master copy of the project. This is the version with everyone's changes merged in to one place.

The clients have their own independent copies of the project, called their working copy. This means each team member's changes don't immediately affect the server, nor can other team members immediately see what others have changed. If a team member has finished a unit of work and wants to merge their changes in, they push the changes to the server and their work is merged in. Once the changes are in the server's copy of the project, other team members can pull to download any new changes to their own working copy.

A typical workflow in a single work session might be:

  1. First pull so you have the latest version of the project
  2. Make some changes
  3. When done, push the changes to the server to submit them

After pushing, the next time each team member pulls from the server, they will receive those changes.

If you make changes then pull without committing, any changes from the server should be merged with your local changes. Usually the source control system can do this for you automatically.

The main problem with this process is conflicts: when two people change the same part of a project then try to push those changes at the same time. The first person can submit the changes OK, but when the second person pushes, the server will notice they haven't pulled in the other changes yet, and will make them do that before they push. Then they will have to manually merge in the other changes then push again. This will be described in more detail later on. If everyone only works on separate parts of the project, or at least co-ordinates to ensure two people don't change the same thing at the same time, you should be able to avoid most conflicts.

In some source control systems, the server can be on a team member's computer. However this is more complex to set up. Using a web-based service like GitHub means their service acts as the server.

  • 19 Comments

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

  • As a solo dev hesitant to jump into source control, your tutorial was a game-changer! Now I'm excited to finally integrate it into my workflow and open the door to future collaboration. Thanks for making it so approachable!

  • Very useful and succinct tutorial on using source control via GitHub. thank you.

  • 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.

      • 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.

          • [-] [+]
          • 0
          • Ashley's avatar
          • Ashley
          • Construct Team Founder
          • 0 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.

      • Recorded a quick video showing the issue: youtu.be/QRjykEozW-U

  • Scirra has since enforced updates upon any user.

    This breaks version control more often than not, and leads to losing time and resources.

    I tried reasoning with them on a thread to no use, even though any other user agreed a toggle in options or at the very least an advanced Chrome parameter was necessary.

    There is a workaround I discovered recently:

    1. Go to the editor version url (editor.construct.com/rXXX)

    2. Three dots Chrome menu -> More tools -> Create Shortcut (open as new window)

    3. Pin this window to your taskbar.

    This way, you can actually control when you want your team to upgrade.

    In case anyone at Scirra cares, the same issues I talked about in the thread you dismissed are still ongoing and affect Github workflows.

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

      You can choose which version of Construct you use on our releases page.

      Everyone on the team needs to be on the same version of Construct, because save files are not backwards compatible. So make sure if you upgrade, everyone does it at the same time. Even if something goes wrong, source control lets you roll back to a working version at any time.

      FWIW I'm using GitHub with my own game project and so far it's working out great.

      • For anyone reading this reply, my workaround fixes the known "Stuck in old version" bug which annoys a lot of people around the discord at the very least (PWA c3 gets stuck to the version you install it as, and inconsistently prompts you with an update on launch which leads to members sometimes doing commits in an older version) and also lets you actually stick to a version in case some custom functionality breaks without your consent.

        Additionally those using custom engine launchers or edits were in a disadvantage as it was impossible to choose when to upgrade your team to a new version. I still lost time because of the devs not implementing a basic software QOL option before finding this workaround. The original post has everything noted.

        Your work is awesome, Ashley, but you are ignoring a lot of paying customers by not even adding an advanced option like a Chrome parameter for disabling the enforced updates which have consistently broken workflows.

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

          Updates are not mandatory - you can choose whichever release you want to use on the releases page. If you work in a team, your whole team need to upgrade at the same time. That's a part of project management that your team will need to handle - software can't handle that for you.

          If you install the stable version, then the installed version will always update to the latest stable release, and if you install a beta version, then the installed version will always update to the latest beta release. That should always work consistently, and if it doesn't, please file an issue.

          • If anyone wants to work consistently and freely using Github, currently the PWA is not the way to go. Shortcutting an editor version works exactly as it was before you enforced updates, and has never given me any issues since. I just click c3 on my taskbar, and the correct version is displayed for everyone.

            If anyone wants extra steps and the risk of losing progress, that's cool. Tried reasoning on the forums a long time ago, to everyone's frustration on the dev's responses. I still respect his stance, and his work is absolutely incredible (has been my main professional engine for too long to remember).

  • Load more comments (6 replies)