├── .gitignore
├── README.md
├── index.html
└── styles.css
/.gitignore:
--------------------------------------------------------------------------------
1 | *.meta
2 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | The Ramen Unity Style Guide
2 | ===========================
3 |
4 | ### For file structure, naming conventions and other things
5 |
6 | These are guidelines for keeping your project organized and allow your team to quickly find the assets they need. Games are large projects that span several months, thus having standardized conventions that make sense will avoid headaches in the long run.
7 |
8 | Note that your team and project might have different needs, use different software, etc. Use this guide only as a base to decide on what works for your team. Every project should have its own, easy to find, style guide, so everyone in the team is up to date in the project's conventions.
9 |
10 | # Table of Contents
11 |
12 | - [Asset Naming](#asset-naming)
13 | - [Folders](#folders)
14 | - [Source code](#source-code)
15 | - [Non-code assets](#non-code-assets)
16 | - [Directory/File structure](#directory-file-structure)
17 | - [Assets](#assets)
18 | - [Scripts](#scripts)
19 | - [Models](#models)
20 | - [Workflow](#workflow)
21 | - [Models](#models)
22 | - [Textures](#textures)
23 | - [Configuration files](#configuration-files)
24 | - [Localization](#localization)
25 | - [Audio](#audio)
26 | - [Be Consistent](#be-consistent)
27 |
28 | # Asset Naming
29 |
30 | First of all, no\ spaces\ on file or directory names.
31 |
32 | ## Folders
33 |
34 | `PascalCase`
35 |
36 | Prefer a deep folder structure over having long asset names.
37 |
38 | Directory names should be as concise as possible, prefer one or two words. If a directory name is too long, it probably makes sense to split it into sub directories.
39 |
40 | Try to have only one file type per folder. Use `Textures/Trees`, `Models/Trees` and not `Trees/Textures`, `Trees/Models`. That way its easy to set up root directories for the different software involved, for example, Substance Painter would always be set to save to the Textures directory.
41 |
42 | If your project contains multiple environments or art sets, use the asset type for the parent directory: `Trees/Jungle`, `Trees/City` not `Jungle/Trees`, `City/Trees`. Since it makes it easier to compare similar assets from different art sets to ensure continuity across art sets.
43 |
44 | ### Debug Folders
45 |
46 | `[PascalCase]`
47 |
48 | This signifies that the folder only contains assets that are not ready for production. For example, having an `[Assets]` and `Assets` folder.
49 |
50 | ## Source Code
51 |
52 | Use the naming convention of the programming language. For C# and shader files use `PascalCase`, as per C# convention.
53 |
54 | ## Non-Code Assets
55 |
56 | Use `tree_small` not `small_tree`. While the latter sound better in English, it is much more effective to group all tree objects together instead of all small objects.
57 |
58 | `camelCase` where necessary. Use `weapon_miniGun` instead of `weapon_gun_mini`. Avoid this if possible, for example, `vehicles_fighterJet` should be `vehicles_jet_fighter` if you plan to have multiple types of jets.
59 |
60 | Prefer using descriptive suffixes instead of iterative: `vehicle_truck_damaged` not `vehicle_truck_01`. If using numbers as a suffix, always use 2 digits. And **do not** use it as a versioning system! Use `git` or something similar.
61 |
62 | ### Persistent/Important GameObjects
63 |
64 | `_snake_case`
65 |
66 | Use a leading underscore to make object instances that are not specific to the current scene stand out.
67 |
68 | ### Debug Objects
69 |
70 | `[SNAKE_CASE]`
71 |
72 | Enclose objects that are only being used for debugging/testing and are not part of the release with brackets.
73 |
74 | # Directory/File Structure
75 |
76 | ```
77 | Root
78 | +---Assets
79 | +---Build
80 | \---Tools # Programs to aid development: compilers, asset managers etc.
81 | ```
82 |
83 | ## Assets
84 |
85 | ```
86 | Assets
87 | +---Art
88 | | +---Materials
89 | | +---Models # FBX and BLEND files
90 | | +---Textures # PNG files
91 | +---Audio
92 | | +---Music
93 | | \---Sound # Samples and sound effects
94 | +---Code
95 | | +---Scripts # C# scripts
96 | | \---Shaders # Shader files and shader graphs
97 | +---Docs # Wiki, concept art, marketing material
98 | +---Level # Anything related to game design in Unity
99 | | +---Prefabs
100 | | +---Scenes
101 | | \---UI
102 | \---Resources # Configuration files, localization text and other user files.
103 | ```
104 |
105 | ## Assets (alternative)
106 |
107 | ```
108 | Assets
109 | +---Art
110 | | +---Materials
111 | | +---Models # FBX and BLEND files
112 | | +---Music
113 | | +---Prefabs
114 | | +---Sound # Samples and sound effects
115 | | +---Textures
116 | | +---UI
117 | +---Levels # Unity scene files
118 | +---Src # C# scripts and shaders
119 | | +---Framework
120 | | \---Shaders
121 | ```
122 |
123 | ## Scripts
124 |
125 | Use namespaces that match your directory structure.
126 |
127 | A Framework directory is great for having code that can be reused across projects.
128 |
129 | The Scripts folder varies depending on the project, however, `Environment`, `Framework`, `Tools` and `UI` should be consistent across projects.
130 |
131 | ```
132 | Scripts
133 | +---Environment
134 | +---Framework
135 | +---NPC
136 | +---Player
137 | +---Tools
138 | \---UI
139 | ```
140 |
141 | ## Models
142 |
143 | Separate files from the modelling program and ready to use, exported models.
144 |
145 | ```
146 | Models
147 | +---Blend
148 | \---FBX
149 | ```
150 |
151 | # Workflow
152 |
153 | ## Models
154 |
155 | File extension: `FBX`
156 |
157 | Even though Unity supports Blender files by default, it is better to keep what is being worked on and what is a complete, exported model separate. This is also a must when using other software, such as Substance for texturing.
158 |
159 | Use `Y up`, `-Z forward` and `uniform scale` when exporting.
160 |
161 | ## Textures
162 |
163 | File extension: `PNG`, `TIFF` or `HDR`
164 |
165 | Choose either a `Specularity/Glossiness` or `Roughness/Metallic` workflow. This depends on the software being used and what your artists are more comfortable with. Specularity maps have the advantage of being having the possibility to be RGB maps instead of grayscale (useful for tinted metals), apart from that there is little difference between the result from either workflow.
166 |
167 | ### Texture Suffixes
168 |
169 | Suffix | Texture
170 | :------|:-----------------
171 | `_AL` | Albedo
172 | `_SP` | Specular
173 | `_R` | Roughness
174 | `_MT` | Metallic
175 | `_GL` | Glossiness
176 | `_N` | Normal
177 | `_H` | Height
178 | `_DP` | Displacement
179 | `_EM` | Emission
180 | `_AO` | Ambient Occlusion
181 | `_M` | Mask
182 |
183 | ### RGB Masks
184 |
185 | It is good practice to use a single texture to combine black and white masks in a single texture split by each RGB channel. Using this, most textures should have:
186 |
187 | ```
188 | texture_AL.png # Albedo
189 | texture_N.png # Normal Map
190 | texture_M.png # Mask
191 | ```
192 |
193 | Channel | Spec/Gloss | Rough/Metal
194 | :-------|:------------------|:-----------
195 | R | Specularity | Roughness
196 | G | Glossiness | Metallic
197 | B | Ambient Occlusion | Ambient Occlusion
198 |
199 | #### The blue channel can vary depending on the type of material:
200 |
201 | - For character materials use the `B` channel for *subsurface opacity/strength*
202 | - For anisotropic materials use the `B` channel for the *anisotropic direction map*
203 |
204 | ## Configuration Files
205 |
206 | File extension: `INI`
207 |
208 | Fast and easy to parse, clean and easy to tweak.
209 |
210 | `XML`, `JSON`, and `YAML` are also good alternatives, pick one and be consistent.
211 |
212 | Use binary file formats for files that should not be changed by the player. For multiplayer games store configuration data on a secure server.
213 |
214 | ## Localization
215 |
216 | File extension: `CSV`
217 |
218 | Widely used by localization software, makes it trivial to edit strings using spreadsheets.
219 |
220 | ## Audio
221 |
222 | File extension: `WAV` while mixing, `OGG` in game.
223 |
224 | Preload small sound clips to memory, load on the fly for longer music and less frequent ambient noise files.
225 |
226 | # Be Consistent
227 |
228 | > The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you're saying rather than on how you're saying it. We present global style rules here so people know the vocabulary, but local style is also important. If code you add to a file looks drastically different from the existing code around it, it throws readers out of their rhythm when they go to read it. Avoid this.
229 |
230 | -- [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html)
231 |
232 | ---
233 |
--------------------------------------------------------------------------------
/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | README.md
6 |
7 |
8 |
9 |
The Ramen Unity Style Guide
For file structure, naming conventions and other things
These are guidelines for keeping your project organized and allow your team to quickly find the assets they need. Games are large projects that span several months, thus having standardized conventions that make sense will avoid headaches in the long run.
Note that your team and project might have different needs, use different software, etc. Use this guide only as a base to decide on what works for your team. Every project should have its own, easy to find, style guide, so everyone in the team is up to date in the project's conventions.
First of all, no\ spaces\ on file or directory names.
Folders
PascalCase
Prefer a deep folder structure over having long asset names.
Directory names should be as concise as possible, prefer one or two words. If a directory name is too long, it probably makes sense to split it into sub directories.
Try to have only one file type per folder. Use Textures/Trees, Models/Trees and not Trees/Textures, Trees/Models. That way its easy to set up root directories for the different software involved, for example, Substance Painter would always be set to save to the Textures directory.
If your project contains multiple environments or art sets, use the asset type for the parent directory: Trees/Jungle, Trees/City not Jungle/Trees, City/Trees. Since it makes it easier to compare similar assets from different art sets to ensure continuity across art sets.
Debug Folders
[PascalCase]
This signifies that the folder only contains assets that are not ready for production. For example, having an [Assets] and Assets folder.
Source Code
Use the naming convention of the programming language. For C# and shader files use PascalCase, as per C# convention.
Non-Code Assets
Use tree_small not small_tree. While the latter sound better in English, it is much more effective to group all tree objects together instead of all small objects.
camelCase where necessary. Use weapon_miniGun instead of weapon_gun_mini. Avoid this if possible, for example, vehicles_fighterJet should be vehicles_jet_fighter if you plan to have multiple types of jets.
Prefer using descriptive suffixes instead of iterative: vehicle_truck_damaged not vehicle_truck_01. If using numbers as a suffix, always use 2 digits. And do not use it as a versioning system! Use git or something similar.
Persistent/Important GameObjects
_snake_case
Use a leading underscore to make object instances that are not specific to the current scene stand out.
Debug Objects
[SNAKE_CASE]
Enclose objects that are only being used for debugging/testing and are not part of the release with brackets.
Directory/File Structure
x
Root
+---Assets
+---Build
\---Tools # Programs to aid development: compilers, asset managers etc.
Assets
x
Assets
+---Art
| +---Materials
| +---Models # FBX and BLEND files
| +---Textures # PNG files
+---Audio
| +---Music
| \---Sound # Samples and sound effects
+---Code
| +---Scripts # C# scripts
| \---Shaders # Shader files and shader graphs
+---Docs # Wiki, concept art, marketing material
+---Level # Anything related to game design in Unity
| +---Prefabs
| +---Scenes
| \---UI
\---Resources # Configuration files, localization text and other user files.
Assets (alternative)
x
Assets
+---Art
| +---Materials
| +---Models # FBX and BLEND files
| +---Music
| +---Prefabs
| +---Sound # Samples and sound effects
| +---Textures
| +---UI
+---Levels # Unity scene files
+---Src # C# scripts and shaders
| +---Framework
| \---Shaders
Scripts
Use namespaces that match your directory structure.
A Framework directory is great for having code that can be reused across projects.
The Scripts folder varies depending on the project, however, Environment, Framework, Tools and UI should be consistent across projects.
xxxxxxxxxx
Scripts
+---Environment
+---Framework
+---NPC
+---Player
+---Tools
\---UI
Models
Separate files from the modelling program and ready to use, exported models.
xxxxxxxxxx
Models
+---Blend
\---FBX
Workflow
Models
File extension: FBX
Even though Unity supports Blender files by default, it is better to keep what is being worked on and what is a complete, exported model separate. This is also a must when using other software, such as Substance for texturing.
Use Y up, -Z forward and uniform scale when exporting.
Textures
File extension: PNG, TIFF or HDR
Choose either a Specularity/Glossiness or Roughness/Metallic workflow. This depends on the software being used and what your artists are more comfortable with. Specularity maps have the advantage of being having the possibility to be RGB maps instead of grayscale (useful for tinted metals), apart from that there is little difference between the result from either workflow.
Texture Suffixes
Suffix
Texture
_AL
Albedo
_SP
Specular
_R
Roughness
_MT
Metallic
_GL
Glossiness
_N
Normal
_H
Height
_DP
Displacement
_EM
Emission
_AO
Ambient Occlusion
_M
Mask
RGB Masks
It is good practice to use a single texture to combine black and white masks in a single texture split by each RGB channel. Using this, most textures should have:
xxxxxxxxxx
texture_AL.png # Albedo
texture_N.png # Normal Map
texture_M.png # Mask
Channel
Spec/Gloss
Rough/Metal
R
Specularity
Roughness
G
Glossiness
Metallic
B
Ambient Occlusion
Ambient Occlusion
The blue channel can vary depending on the type of material:
For character materials use the B channel for subsurface opacity/strength
For anisotropic materials use the B channel for the anisotropic direction map
Configuration Files
File extension: INI
Fast and easy to parse, clean and easy to tweak.
XML, JSON, and YAML are also good alternatives, pick one and be consistent.
Use binary file formats for files that should not be changed by the player. For multiplayer games store configuration data on a secure server.
Localization
File extension: CSV
Widely used by localization software, makes it trivial to edit strings using spreadsheets.
Audio
File extension: WAV while mixing, OGG in game.
Preload small sound clips to memory, load on the fly for longer music and less frequent ambient noise files.
Be Consistent
The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you're saying rather than on how you're saying it. We present global style rules here so people know the vocabulary, but local style is also important. If code you add to a file looks drastically different from the existing code around it, it throws readers out of their rhythm when they go to read it. Avoid this.