|
|
@@ -1,79 +1,73 @@
|
|
|
---
|
|
|
title: Workflows in Defold
|
|
|
-brief: This manual covers how assets are handled in Defold, how you can change the structure of your project easily with the help of powerful refactoring, how collaboration works and advanced topics like external editors and the underlying Git tools.
|
|
|
+brief: This manual covers how you collaborate in teams and change the structure of your project easily with the help of powerful refactoring. The manual also covers topics like external editors and the underlying Git tools.
|
|
|
---
|
|
|
|
|
|
# Workflow
|
|
|
|
|
|
-A game project usually consists of a large number of external assets that are produced in various specialized programs for producing graphics, 3D models, sound files, animations and so forth. Defold is by default set up for a workflow that encourages you to work separately with your external tools, store the working files for those tools separately and then import the assets into Defold and the project file structure as they are finalized.
|
|
|
+A game project usually consists of a large number of external assets that are produced in various specialized programs for producing graphics, 3D models, sound files, animations and so forth. Defold is builit for a workflow where you to work in your external tools and then import the assets into Defold as they are finalized.
|
|
|
|
|
|
-Git is built primarily to handle source code and text files and stores those types of files with a very low footprint. Only the changes between each version are stored, which means that you can keep an extensive history of changes to all your project files to a relatively small cost. Binary files such as image or sound files, however, does not benefit from Git's storage scheme. Each new version you check in and synchronize takes about the same space. That is usually not a major issue with the final project assets (JPEG or PNG images, OGG sound files etc) but it can quickly become an issue with working project files (PSD files, Protools projects etc). These types of files or projects often grow very large since you usually work in much higher resolution than the target assets.
|
|
|
+Defold is built intended for small teams that work in intense collaboration to create games. Team members can work in parallel on the same content with very little friction. Defold is built upon [Git](https://git-scm.com) that is designed for distributed collaborative work. Git is an extremely powerful tool that allows for a wide range of workflows and Defold uses it to provide built in simple and powerful functionality.
|
|
|
|
|
|
-It is generally considered best to avoid putting large working files under the control of Git and instead use a separate solution for keeping backups. If you do large scale processing or generation of asset files from a working project it is usually easy to write simple scripts that copy the final files into the proper place in the Defold project hierarchy.
|
|
|
+## Your local working copy
|
|
|
|
|
|
-## Refactoring
|
|
|
+Before you can start working on a new project you need to get it to your local disk so the Defold editor can open it.
|
|
|
|
|
|
-Refactoring refers to the process of restructuring existing code and assets to improve the design. During the development of a project, the need to change or move things around often surfaces:
|
|
|
+
|
|
|
|
|
|
-* Names need to change to adhere to naming conventions or to improve clarity.
|
|
|
-* Code or asset files need to move to a more logical place in the project hierarchy.
|
|
|
-* New code and/or assets with better functionality are built to replace old ones, that are deleted.
|
|
|
+Click to open project <kbd>From Dashboard</kbd> to bring up a list of Defold hosted projects that you have access to. Specify a location on your hard drive where the project files will be stored. If you already have a folder on your hard drive containing a Defold project you can open it by clicking open project <kbd>From Disk</kbd>.
|
|
|
|
|
|
-Defold helps you refactor efficiently by keeping track of how assets are used and automatically updating references to assets that are renamed and/or moved. As a developer, you should feel free in your work. Your project is a flexible structure that you can change at will without fearing that everything will break and fall to pieces. Defold will help you in your refactoring work making the process as effortless as possible.
|
|
|
+When you save changes in your local working copy, Defold tracks all changes in the *Changed Files* editor pane, listing each file that has either been added, deleted or modified.
|
|
|
|
|
|
-That said, there are cases where Defold is unable to automatically update references when you are doing refactoring work. In those cases, the editor can't solve the problem, but will provide helpful error signals.
|
|
|
+
|
|
|
|
|
|
-For instance, if you add a Tilemap component to a Game Object and then delete the component file, the Defold compiler will signal an error when you try to start the game. The editor will also add error badges to all relevant icons in the Project View and in the Game Object or Collection hierarchy to help you quickly locate the problem:
|
|
|
+Select a file in the list and click <kbd>Diff</kbd> to view the changes that you have done to the file or <kbd>Revert</kbd> to undo all changes and restore the file to the state it had after the last synchronization.
|
|
|
|
|
|
-
|
|
|
-
|
|
|
-Some of these error signals Defold can add instantly as you make a change, provided that you have the relevant asset open. Badges in the Project View, however, are only added when the compiler is run (i.e. when you try to run your game).
|
|
|
-
|
|
|
-::: important
|
|
|
-If you move or rename files outside of the editor (i.e. in the OS X Finder, Windows Explorer or shell) the automatic refactoring mechanisms will not work. If you do file operations outside of the Defold editor, be aware that file references in your project assets might break.
|
|
|
-:::
|
|
|
+## Synchronizing
|
|
|
|
|
|
-## Collaboration
|
|
|
+To synchronize your project means that the project files are brought into sync with the project as it looks on the server. You should synchronize if:
|
|
|
|
|
|
-Defold is built on a foundation intended for intense collaboration. Multiple team members can work in parallel on the same content with very little friction. Defold is built upon Git that is designed for distributed collaborative work. Git is an extremely powerful tool that allows for a wide range of workflows and Defold uses it to provide simple and powerful functionality.
|
|
|
+1. You want to bring your project up to speed with what is stored on the server.
|
|
|
+2. You want to share your local project changes with other team members by committing and pushing your changes to the server.
|
|
|
|
|
|
-When you start working on a project for the first time (by selecting <kbd>File ▸ Open Project</kbd>), Defold will ask you to create a new local branch for the project.
|
|
|
+To start synchronizing, select <kbd>File ▸ Synchronize</kbd> in the menu.
|
|
|
|
|
|
-
|
|
|
+This brings up a window where you can inspect your changes and write a _useful_ commit message:
|
|
|
|
|
|
-Click *New branch* and name the branch. Defold then creates a complete local clone of the project structure, as it exists on the project server. The branches that you create only exist on your computer. You can have as many or as few of them as you like, and you can create new ones and delete old ones at will.
|
|
|
+
|
|
|
|
|
|
-When you start working and save changes you made to the project, these changes will be stored inside the current branch. No one else sees them until you _Synchronize_ your branch with the server repository.
|
|
|
|
|
|
-## Synchronizing
|
|
|
+To inspect the changes that have been done to a file, simply double click the file in the commit-list to open the Compare window:
|
|
|
|
|
|
-Synchronizing your project branch means that it is brought in sync with the project as it looks on the master branch on the server. Any changes that have been made on the server are pulled to your branch and any changes that you have made to your local branch are pushed to the server repository.
|
|
|
+
|
|
|
|
|
|
-When you have done some work in your current branch that you wish to share with the rest of the project team, you select <kbd>File ▸ Synchronize</kbd>. This brings up a window where you can inspect your changes and write a _useful_ commit message:
|
|
|
+The window shows two versions of the file (in case of a modified file; added or deleted files are shown differently). On the left hand side is the file as it looked on the server _when you last synchronized_. The right hand side shows your local version. Any differences are clearly highlighted so you can quickly review them.
|
|
|
|
|
|
-
|
|
|
+The built in file comparison tool works on text files only. However, since Defold stores all working files (game objects, collections, atlases, etc etc) in easily understandable JSON files, you can often figure out the meaning of the changes that have been made to such files:
|
|
|
|
|
|
-All files that are either changed, added or deleted from the project are listed in the top pane of the window. Each file carries an annotation:
|
|
|
+
|
|
|
|
|
|
-[M]
|
|
|
-: The file has been modified in your branch.
|
|
|
+## Refactoring
|
|
|
|
|
|
-[A]
|
|
|
-: The file has been added to your branch.
|
|
|
+Refactoring refers to the process of restructuring existing code and assets to improve the design. During the development of a project, the need to change or move things around often surfaces:
|
|
|
|
|
|
-[D]
|
|
|
-: The file has been deleted from your branch.
|
|
|
+* Names need to change to adhere to naming conventions or to improve clarity.
|
|
|
+* Code or asset files need to move to a more logical place in the project hierarchy.
|
|
|
+* New code and/or assets with better functionality are built to replace old ones, that are deleted.
|
|
|
|
|
|
+Defold helps you refactor efficiently by keeping track of how assets are used and automatically updating references to assets that are renamed and/or moved. As a developer, you should feel free in your work. Your project is a flexible structure that you can change at will without fearing that everything will break and fall to pieces. Defold will help you in your refactoring work making the process as effortless as possible.
|
|
|
|
|
|
-To inspect the changes that have been done to a file, simply double click the file in the commit-list to open the Compare window:
|
|
|
+That said, there are cases where Defold is unable to automatically update references when you are doing refactoring work. In those cases, the editor can't solve the problem, but will provide helpful error signals.
|
|
|
|
|
|
-
|
|
|
+For instance, if you add a Tilemap component to a Game Object and then delete the component file, the Defold compiler will signal an error when you try to start the game. The editor will also add error badges to all relevant icons in the Project View and in the Game Object or Collection hierarchy to help you quickly locate the problem:
|
|
|
|
|
|
-The window shows two versions of the file (in case of a modified file; added or deleted files are shown differently). On the left hand side is the file as it looked on the server _when you last synchronized_. The right hand side shows your local version. Any differences are clearly highlighted so you can quickly review them.
|
|
|
+
|
|
|
|
|
|
-The built in file comparison tool works on text files only. However, since Defold stores all working files (game objects, collections, atlases, etc etc) in easily understandable JSON files, you can often figure out the meaning of the changes that have been made to such files:
|
|
|
+Some of these error signals Defold can add instantly as you make a change, provided that you have the relevant asset open. Badges in the Project View, however, are only added when the compiler is run (i.e. when you try to run your game).
|
|
|
|
|
|
-
|
|
|
+::: important
|
|
|
+If you move or rename files outside of the editor (i.e. in the OS X Finder, Windows Explorer or shell) the automatic refactoring mechanisms will not work. If you do file operations outside of the Defold editor, be aware that file references in your project assets might break.
|
|
|
+:::
|
|
|
|
|
|
## Resolving conflicts
|
|
|
|
|
|
@@ -93,63 +87,27 @@ The editor does not allow you to pick changes from the two conflicting files. If
|
|
|
|
|
|
## External editors and tools
|
|
|
|
|
|
-Defold does not provide editing tools for creating images, sound files or bone animations. Such assets need to be created outside of Defold in specialized tools. Defold is agnostic when it comes to what tools it prefers. Any image program that can produce PNG files will do, any sound program that can save WAV files will do and any program that can save or export Spine JSON files will do (refer to the [Spine documentation](/manuals/spine) for details).
|
|
|
-
|
|
|
-Defold automatically detects changes to any assets that are in the project hierarchy and updates the editor view accordingly. The update cycle is not instant so you might have to wait a second or two to see your changes in the editor.
|
|
|
-
|
|
|
-The automatic asset tracking allows you to customize your work flow according to your needs.
|
|
|
-
|
|
|
-Shell scripts / batch files
|
|
|
-: You can use external scripts to automatically rebuild assets. For instance, if your source materials are of higher resolution or in a different format you can run a script or batch file that resizes or converts the files before copying them into the proper place in the project hierarchy.
|
|
|
-
|
|
|
-Data generation
|
|
|
-: You can use custom tools to create specialized data and write it into Lua script files (as table structures)
|
|
|
-
|
|
|
-## Opening assets in the text editor
|
|
|
-
|
|
|
-Defold automatically chooses the appropriate editor for the item you are trying to edit. However, it is also possible to open any project file in the Defold text editor. In some situations this possibility is extremely useful and it's use is advisable to, at least, familiarize yourself with the file formats, which helps when resolving conflicts.
|
|
|
-
|
|
|
-To open a file in the text editor, right-click the file in the Project view and select <kbd>Open With ▸ Text Editor</kbd>:
|
|
|
-
|
|
|
-
|
|
|
-
|
|
|
-Note that Defold remembers the choice of editor for the particular file. If you open a file with the Text Editor, subsequent double clicks on the file in the Project view will automatically open the file in the Text Editor. To reset the selected editor for the file, simply right-click the file and select <kbd>Open With ▸ [Filetype Editor]</kbd> where [Filetype Editor] is the type of editor used for the file type (e.g. Scene Editor for Game Objects, Tile Source Editor for Tile Sources and so forth).
|
|
|
+Defold does not provide editing tools for creating images, sound files, models or animations. Such assets need to be created outside of Defold in specialized tools and imported into Defold. Defold automatically detects changes to any asset in the project hierarchy and updates the editor view accordingly.
|
|
|
|
|
|
-Extra care should be taken when working with files through the Text Editor. Easy-to-make errors can prevent the file from being possible to open in the designated editor. For instance, suppose you edit a Game Object file and omit an end-quote character in one of the names:
|
|
|
+There is currently no way to hook custom build steps into the in-editor builder, but we provide a stand-alone build pipeline (see [Bob the builder](/manuals/bob)) that can be incorporated in any pipeline.
|
|
|
|
|
|
-
|
|
|
+The editor saves all Defold assets in text based files that are merge friendly. They are also easy to create and modify with simple scripts. See [this forum thread](https://forum.defold.com/t/deftree-a-python-module-for-editing-defold-files/15210) for more information. Note though that we do not publish our file format details since they do change once in a while.
|
|
|
|
|
|
-If you save this file from the Text Editor and then try to open it in the Scene Editor, Defold will signal an error and you will have to manually fix the error (either by re-editing the file, or by reverting your changes):
|
|
|
-
|
|
|
-
|
|
|
-
|
|
|
-Defold tries to provide helpful error messages and it is often easy to track down the error. If you need further aid, double-click the file in the Changed Files pane to bring up a window with all changes since your last Synchronize.
|
|
|
+Extra care should be taken when working with Defold asset files through a text editor or external tool. If you introduce errors those can prevent the file from opening in the Defold editor.
|
|
|
|
|
|
## Git
|
|
|
|
|
|
-Defold uses Git to do version tracking on all files in a simple and easily understandable manner.
|
|
|
-
|
|
|
-* Each branch you create in the editor is a clone of the remote project repository, stored in a separate folder.
|
|
|
-* Any changes you do locally are saved in the cloned repository.
|
|
|
-* When you Synchronize your project, the following happens:
|
|
|
- 1. Your changes are committed to the local repository.
|
|
|
- 2. The editor pulls any changes from the remote repository and merges it with your local repository.
|
|
|
- 3. If there are merge conflicts, you are asked to resolve them.
|
|
|
- 4. Finally, your changes are pushed to the remote repo.
|
|
|
+Git is built primarily to handle source code and text files and stores those types of files with a very low footprint. Only the changes between each version are stored, which means that you can keep an extensive history of changes to all your project files to a relatively small cost. Binary files such as image or sound files, however, does not benefit from Git's storage scheme. Each new version you check in and synchronize takes about the same space. That is usually not a major issue with final project assets (JPEG or PNG images, OGG sound files etc) but it can quickly become an issue with working project files (PSD files, Protools projects etc). These types of files often grow very large since you usually work in much higher resolution than the target assets. It is generally considered best to avoid putting large working files under the control of Git and instead use a separate storage and backup solution for those.
|
|
|
|
|
|
-The Git command line tool can be used to perform manual operations that the editor does not support. For instance, you can inspect the commit history of the repository:
|
|
|
+There are many ways you can use Git in a team workflow. The one Defold uses is as follows. When you synchronize, the following happens:
|
|
|
|
|
|
-```sh
|
|
|
-$ git log
|
|
|
-```
|
|
|
-
|
|
|
-and then do a checkout from a specific commit:
|
|
|
-
|
|
|
-```sh
|
|
|
-$ git checkout <commit-hash> <file path>
|
|
|
-```
|
|
|
+1. Any local changes are stashed so they can be restored if something fails later in the sync process.
|
|
|
+2. Server changes are pulled.
|
|
|
+3. The stash is applied (the local changes are restored), this may result in merge conflicts that need to be resolved.
|
|
|
+4. The user gets the option to commit any local file changes.
|
|
|
+5. If there are local commits, the user may choose to push these to the server. Again, it is possible that this leads to conflicts that need to be resolved.
|
|
|
|
|
|
-You can also set up a more advanced workflow if you want, allowing you to pull changes directly between team members. If you run into situations where more than one person works on an experimental branch, you might want to consider using Git for that. Please visit http://git-scm.com to learn more about Git.
|
|
|
+If you prefer a different workflow you can run Git from command line or through a third party application to perform pulls, pushes, commits and merges, working on several branches and so on.
|
|
|
|
|
|
## Line endings and Windows
|
|
|
|
|
|
@@ -178,18 +136,6 @@ Meanwhile, a second team member who works on a Mac OS X machine does some editin
|
|
|
|
|
|
This happened because the two files actually differ in how they encode the line endings. Since one file uses the *LF* character at the end of each line and the other uses the characters *CR*+*LF*, there is a legitimate conflict on each line and you will have to resolve it. If you have team members that work a lot with external tools, line endings will cause merge conflicts all the time.
|
|
|
|
|
|
-## Line endings in Defold
|
|
|
-
|
|
|
-Defold has some built in tools for seeing and changing line endings. You can turn on visible whitespace in the preferences (select <kbd>File ▸ Preferences...</kbd>):
|
|
|
-
|
|
|
-
|
|
|
-
|
|
|
-This setting makes the editor deliberately show all whitespace characters like *LF*, *CR*, *Space* and *Tab*:
|
|
|
-
|
|
|
-
|
|
|
-
|
|
|
-There is also a menu option <kbd>File ▸ Convert Line Delimiters To ▸ ...</kbd> where you can select which type of delimiter you want to set for the currently open file.
|
|
|
-
|
|
|
## Make Git deal with line endings properly
|
|
|
|
|
|
Git can be configured to specifically deal with line endings in a number of different ways:
|
|
|
@@ -207,11 +153,9 @@ false
|
|
|
true
|
|
|
: Git will process all text files and turn all *LF* line endings to *CR*+*LF* when writing them into the working directory and back to *LF* when they are checked into the repository again. This is a good setting on Windows machines.
|
|
|
|
|
|
-
|
|
|
input
|
|
|
: Git will process all files and turn all *CR*+*LF* into *LF* line endings when checking files into the repository. When checking files out, the files are untouched. This is a good setting on Unix and OS X machines.
|
|
|
|
|
|
-
|
|
|
You can configure Git with more fine grained control on how it should deal with line endings by creating a *.gitattributes* file in your repository:
|
|
|
|
|
|
```txt
|
Mikael Säker
