aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
author Brendan Griffiths <96725360+Orwellian-225@users.noreply.github.com>2023-03-04 21:00:01 +0100
committer GitHub <noreply@github.com>2023-03-04 21:00:01 +0100
commit95173891f7c5eea7717a58ae4f1438fd09e0ee1f (patch)
tree953e73703b23ad00593ccce57ac5e9174c4ee16a /docs
parent028247a24866726b79c56cb2f266738a8a9abc70 (diff)
Modify Project Structure Documentation (#14)
* add: Asset and Data file structure add: Naming Conventions add: Clarification on asset file exporting * change: More relevant file structure examples Co-authored-by: ClarkeCode <33846391+ClarkeCode@users.noreply.github.com> * apply: Directory Naming Convention Changes Co-authored-by: ClarkeCode <33846391+ClarkeCode@users.noreply.github.com> * apply: Remove Prefixes for asset names Co-authored-by: ClarkeCode <33846391+ClarkeCode@users.noreply.github.com> * apply: Directory Naming Convention Changes to example --------- Co-authored-by: ClarkeCode <33846391+ClarkeCode@users.noreply.github.com>
Diffstat (limited to 'docs')
-rw-r--r--docs/project-file-structure.md133
1 files changed, 124 insertions, 9 deletions
diff --git a/docs/project-file-structure.md b/docs/project-file-structure.md
index ffad323..f69a372 100644
--- a/docs/project-file-structure.md
+++ b/docs/project-file-structure.md
@@ -10,17 +10,34 @@ Please see the [C++ Styleguide](./styleguide-cpp.md) for more details
All godot files are in the OpenVic2/game directory
+### Directories
+
+* r/, root/, res/, res://
+ * The root directory of the Godot Project
+* u/, user/, user://
+ * The user directory used by the project (Platform specific)
+ * Windows u/ - %APPDATA%/OpenVic2/
+ * MacOS u/ - ~/Library/Application Support/OpenVic2/
+ * Linux u/ - ~/.local/share/OpenVic2/
+* d/, data/, common/ - The data directory used to store data files
+ * can be a subdirectory of root/ - root/common/
+ * can be a subdirectory of user/ - user/common/
+ * files in this directory should not be included in the godot export, but as external files in the same directory as the executable
+
### Definitions
-* root/, res/, r/ -> The root directory of the Godot project (OpenVic2/game/)
-* user/, u/ -> The user directory used by the project (Platform specific)
-* core -> related to the functionality of OpenVic2 without modification
+* core - OpenVic2 without modification
+* mod - OpenVic2 with changes in files to modify the gameplay experience
+* scene - godot engine scene object
+* script - godot engine gdscript object
+* resource - godot engine resource object
+* asset - static file generally used as is within the project - art, music etc.
+* data file - static file that holds data or information that needs to be processed to be used - economy good information, province names etc.
+
+### OpenVic2 File Extensions
-> Windows u/ -> %APPDATA%/OpenVic2/
->
-> MacOS u/ -> ~/Library/Application Support/OpenVic2/
->
-> Linux u/ -> ~/.OpenVic2/
+* ov2d - OpenVic2 data file
+* ov2b - OpenVic2 binary file
### When to use root/
@@ -50,6 +67,16 @@ permissions issues. I.e. if the application writes to these files in any capacit
Files that are modified by the running application should be in user/
+### When to use data/
+
+* Any data file that gets read in by the program
+* Any data file that expresses game conditions
+* Can be used within both root/ and user/ - see above rules to know when
+
+#### Rule of thumb
+
+Any sort of modifiable data file should be in data/, core files will be in root/ and mod files will be in data/
+
### Scene, Scripts, and Resources Organization
No scene files should be in the root/src/ directory
@@ -64,6 +91,9 @@ to organize their structure
Resources, scenes, scripts etc. used exclusively within that scene should be stored in the scenes subdirectory
+A scene and its script should always be together within the directory i.e. no /scripts/ and /scenes/ directories should exist within
+the project somewhere.
+
Example:
```
root/
@@ -72,7 +102,7 @@ root/
| |- ButtonNormal.tres
| |- ButtonHover.tres
| |- ButtonDisabled.tres
- |- Scripts/
+ |- Utility/
| |- Math.gd
|- Menu/
| |- MenuManager.tscn
@@ -91,3 +121,88 @@ root/
| | | |- VolumeGrid.tscn
| | | |- VolumeGrid.gd
```
+
+#### Naming Convention
+
+Subdirectories for Godot files should be PascalCase.
+```
+root/src/GameSession/
+```
+
+File names should be PascalCase.
+```
+root/src/GameSession/Map.tscn
+```
+
+### Asset Organization
+
+Note: Asset files should not be exported with Godot in a pck file. They should be downloaded via an installer or handled in a similar
+fashion to the data files and their exclusion from the export
+
+Asset files should be organized within a relevant category from root/
+```
+root/images/
+root/audio/
+root/models/
+```
+
+Asset files should be organized in a subdirectory that specifies it's relevancy within the application.
+```
+root/art/economy/
+root/art/military/
+root/audio/sfx/
+root/audio/music/
+```
+
+
+#### Naming Convention
+
+Asset file subdirectories should be snake_case.
+```
+root/art/icons/goods/
+```
+
+Asset files should be PascalCase for their name.
+```
+TheCrown.mp3
+Coal.png
+```
+
+
+### Data File Organization
+
+All data files should be in the root/common/ directory.
+
+Data files should be organized by category.
+```
+root/common/map/
+root/common/technology/
+root/common/pop/
+```
+
+Data files that are plain text should have the ov2d file extension.
+```
+root/common/pop/soldier.ov2d
+```
+
+Data files that are complex data like a bitmap should make use of the standard file extension for that data
+```
+root/common/map/provinces.bmp
+```
+
+Data files can be further organized by subdirectory.
+```
+root/common/economy/goods/Coal.ov2d
+```
+
+#### Naming Convention
+
+Data file subdirectories should be snake_case.
+```
+root/common/economy/technology/
+```
+
+Data files should be PascalCase.
+```
+root/common/economy/goods/Coal.txt
+```