125 lines
4.7 KiB
ReStructuredText
125 lines
4.7 KiB
ReStructuredText
.. _doc_project_organization:
|
|
|
|
Project organization
|
|
====================
|
|
|
|
Introduction
|
|
------------
|
|
|
|
Since Godot has no restrictions on project structure or filesystem usage,
|
|
organizing files when learning the engine can seem challenging. This
|
|
tutorial suggests a workflow which should be a good starting point.
|
|
We will also cover using version control with Godot.
|
|
|
|
Organization
|
|
------------
|
|
|
|
Godot is scene-based in nature, and uses the filesystem as-is,
|
|
without metadata or an asset database.
|
|
|
|
Unlike other engines, many resources are contained within the scene
|
|
itself, so the amount of files in the filesystem is considerably lower.
|
|
|
|
Considering that, the most common approach is to group assets as close
|
|
to scenes as possible; when a project grows, it makes it more
|
|
maintainable.
|
|
|
|
As an example, one can usually place into a single folder their basic assets,
|
|
such as sprite images, 3D model meshes, materials, and music, etc.
|
|
They can then use a separate folder to store built levels that use them.
|
|
|
|
.. code-block:: none
|
|
|
|
/project.godot
|
|
/docs/.gdignore # See "Ignoring specific folders" below
|
|
/docs/learning.html
|
|
/models/town/house/house.dae
|
|
/models/town/house/window.png
|
|
/models/town/house/door.png
|
|
/characters/player/cubio.dae
|
|
/characters/player/cubio.png
|
|
/characters/enemies/goblin/goblin.dae
|
|
/characters/enemies/goblin/goblin.png
|
|
/characters/npcs/suzanne/suzanne.dae
|
|
/characters/npcs/suzanne/suzanne.png
|
|
/levels/riverdale/riverdale.scn
|
|
|
|
Style guide
|
|
-----------
|
|
|
|
For consistency across projects, we recommend following these guidelines:
|
|
|
|
- Use **snake_case** for folder and file names (with the exception of C#
|
|
scripts). This sidesteps case sensitivity issues that can crop up after
|
|
exporting a project on Windows. C# scripts are an exception to this rule,
|
|
as the convention is to name them after the class name which should be
|
|
in PascalCase.
|
|
- Use **PascalCase** for node names, as this matches built-in node casing.
|
|
- In general, keep third-party resources in a top-level ``addons/`` folder, even
|
|
if they aren't editor plugins. This makes it easier to track which files are
|
|
third-party. There are some exceptions to this rule; for instance, if you use
|
|
third-party game assets for a character, it makes more sense to include them
|
|
within the same folder as the character scenes and scripts.
|
|
|
|
Importing
|
|
---------
|
|
|
|
Godot versions prior to 3.0 did the import process from files outside
|
|
the project. While this can be useful in large projects, it
|
|
resulted in an organization hassle for most developers.
|
|
|
|
Because of this, assets are now transparently imported from within the project
|
|
folder.
|
|
|
|
Ignoring specific folders
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To prevent Godot from importing files contained in a specific folder, create
|
|
an empty file called ``.gdignore`` in the folder (the leading ``.`` is required).
|
|
This can be useful to speed up the initial project importing.
|
|
|
|
.. note::
|
|
|
|
To create a file whose name starts with a dot on Windows, you can use a
|
|
text editor such as Notepad++ or use the following command in a
|
|
command prompt: ``type nul > .gdignore``
|
|
|
|
Once the folder is ignored, resources in that folder can't be loaded anymore
|
|
using the ``load()`` and ``preload()`` methods. Ignoring a folder will also
|
|
automatically hide it from the FileSystem dock, which can be useful to reduce clutter.
|
|
|
|
Note that the ``.gdignore`` file's contents are ignored, which is why the file
|
|
should be empty. It does not support patterns like ``.gitignore`` files do.
|
|
|
|
.. _doc_project_organization_case_sensitivity:
|
|
|
|
Case sensitivity
|
|
----------------
|
|
|
|
Windows and recent macOS versions use case-insensitive filesystems by default,
|
|
whereas Linux distributions use a case-sensitive filesystem by default.
|
|
This can cause issues after exporting a project, since Godot's PCK virtual
|
|
filesystem is case-sensitive. To avoid this, it's recommended to stick to
|
|
``snake_case`` naming for all files in the project (and lowercase characters
|
|
in general).
|
|
|
|
.. note::
|
|
|
|
You can break this rule when style guides say otherwise (such as the
|
|
C# style guide). Still, be consistent to avoid mistakes.
|
|
|
|
On Windows 10, to further avoid mistakes related to case sensitivity,
|
|
you can also make the project folder case-sensitive. After enabling the Windows
|
|
Subsystem for Linux feature, run the following command in a PowerShell window::
|
|
|
|
# To enable case-sensitivity:
|
|
fsutil file setcasesensitiveinfo <path to project folder> enable
|
|
|
|
# To disable case-sensitivity:
|
|
fsutil file setcasesensitiveinfo <path to project folder> disable
|
|
|
|
If you haven't enabled the Windows Subsystem for Linux, you can enter the
|
|
following line in a PowerShell window *running as Administrator* then reboot
|
|
when asked::
|
|
|
|
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
|