Using project files



3,441 visits, 4,168 views



This tutorial hasn't been translated.


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.

Construct allows you to import external files to your project. For more information, see the manual entry on Project Files. This tutorial covers some useful workflows for using project files.

Using external image files

If your project has a lot of large detailed images which add a lot to the download size, you can make your game load quicker by adding them as project files instead. That way they won't need to be downloaded before the game starts running. You can then load them at runtime using Sprite or Tiled Background's Load image from URL actions - just enter the name of the image as the URL, e.g. "mylargeimage.jpg". The On image URL loaded trigger fires when they have finished loading. This means you can request large images on the start of each layout that needs them, and show some kind of "Please wait..." message until they've loaded.

Storing additional web pages with your project

You may want to have a few extra simple HTML pages stored with your project. You can import any necessary extra HTML, CSS and Javascript files to your project, and navigate to them with the Browser object. You can also edit the files within Construct 3 using the Text Editor.

Loading file data

If you want to read data from a file stored with the project, such as an XML file, you can use the AJAX object's Request project file action to download the file. Then the result can be loaded in to another object, in this case to the XML object. The events below show how this can be done.

Events to load XML data

You can use similar events to load dictionary or array JSON data in to the Dictionary or Array objects. The JSON data files can also be edited directly in Construct 3 using the Dictionary Editor and Array Editor.

Storing additional files to download

You can store documents or other files with your project, and use the Browser object to download them with the Invoke download action.

Making level editors

Perhaps the most advanced use of project files is the ability to support your own custom level editor. This can even include user-made levels, creating a community of additional level designers for your game, and increasing its longevity!

Making a level editor is complicated, and won't be covered in full detail here. However the principle is that using the Array, Dictionary or XML objects (or some combination of them), you can store data representing an entire level. If you've designed your level editor in Construct, you can use Array or Dictionary's Download action to download a .json file storing the data, or simply use their AsJSON expressions to get the data as a long JSON string. Once you have a file or files representing a level, you can import them as project files, e.g. level3.json.

Once you have all your levels imported, you can load them by requesting them with the AJAX object then loading the result in to the object, similar to how is done with the XML object in the above example. Then you are ready to load the level.

The cool thing about this is you can allow for user-made levels. If a user designs a level and uploads it somewhere like, you could have a text field in your game where you enter this URL and load their level.

You can also allow yourself to change or add new levels after the game is published, without re-uploading the entire game. For example if you load a list of available levels from an XML file, you only need to upload or change a few .json files then edit the .xml file in order to add or update levels.

Don't forget project files are available during preview, and are also cached for offline use, so it's easy to test and doesn't cause any trouble for offline players either.

One last tip: you can combine multiple arrays in to a single .json file using the Dictionary object. Simply store keys in the Dictionary object which store each array as JSON data, e.g.

Set "array1" to Array1.AsJSON

Set "array2" to Array2.AsJSON

Set "array3" to Array3.AsJSON

Then you can add a few extra keys (e.g. the name of the level) and download everything as a single .json file from the Dictionary object.


Project files are a very powerful feature of Construct with a lot of flexibility. It allows for a lot of interesting new capabilities, such as dynamic image loading, convenient handling of additional pages or documents, loading and using data files, and even making full blown level editors with support for user-made levels. There are doubtless other things you can use it for other than those listed here!


  • Order by
Want to leave a comment? Login or Register an account!