docs/naming-conventions/in-file-prefixes.md

@@ -1,47 +1,53 @@
 # Datablock names
 
+Naming objects in a Blender production can be quite non-trivial when trying to achieve stability, clarity, and the ability to easily make shot files fully local at the end of production, to create fully interactive demo files that can be shared with the world.
+
 ## Separators
-We only have 3 separators to work with, so we try keep their meaning consistent across conventions:  
+We try keep their meaning consistent across conventions:
-`-` : Separates prefixes (including the Asset Identifier) from each other and from the rest of the name.
+`-` : Separates prefixes (including the Namespace Identifier) from each other and from the rest of the name, eg. `GEO-esprite-head`. Also should be used for naming objects in a hierarchical way when possible, see "Indicating a hierarchy" below.
-`.` : Separates suffixes, currently only for symmetry sides, ie `.L`/`.R`.
+`.` : Separates suffixes for symmetry sides, eg. `GEO-esprite-eye.L`, as well as asset variants, see below.
-`_` : Used to separate parts of the base name, eg. `console_button_032`. The base name of an ID never has any technical significance.
+`_` : Used to separate parts of the base name, eg. `wooden_wardrobe_032`. The base name of an ID never has any technical significance.
-`:` : Separator for variations of an object, eg. `clock:normal`, `clock:broken`, `clock:destroyed`.
 
-## Asset Identifier
+## Namespace Identifier
 
-All local datablocks across all assets of a production must have a unique name. To faciliate this, each asset's name, or a shortened version of it, should be present in all ID names of that asset. For example, the character "Elder Sprite" might have a full-length unique identifier of `elder_sprite`, along with an optional shortened (but still unique) version, eg. `esprite`.
+All datablocks across the entire production must have a unique name. To faciliate this, each asset's name, or a shortened version of it, should be present in all datablock names of that asset. This should be enforced by add-ons wherever possible. For example, the character "Elder Sprite" might have a full-length unique identifier of `elder_sprite`, along with an optional shortened (but still unique) version, eg. `esprite`. You should use the short version most of the time, eg. `GEO-esprite-head`, but the longer version when the name doesn't have a lot of other information, eg. the asset's root collection (`CH-elder_sprite`) or the rig object (`RIG-elder_sprite`).
+
+This also applies to datablocks which are not part of an asset, for example pose library poses and shared node groups that get linked into assets. Their namespace identifier should simply be the name of the .blend file that they're in, or a shortened version of it.
 
 This identifier will be present among the prefixes in the names of datablocks, to make sure all names are unique, not just in a single file, but across the whole production. This is necessary because Blender's Library Override system relies on making local copies of linked object hierarchies, meaning all assets need to be able to exist in the same namespace without name collisions.
 
+The identifier can also have underscores and numbers in it, which may be the case for library assets, eg. `LI-tree_birch_001`.
+
 ## Asset Collection Hierarchy
 
-We use prefixes for the root collections of assets to help distinguish different types of assets in the Outliner of a complex shot file. The name of the asset itself should be lowercase.
+We use prefixes for the root collections (and only the root) of assets to help distinguish different types of assets in the Outliner of a complex shot file. The name of the asset itself should be lowercase.
 
 - `CH` : Character
-- `PR` : Prop
+- `PR` : Rigger Prop
-- `EN` : Environment Prop
+- `LI` : Library/Environment Asset
 - `SE` : Set
 - `LG` : Light Rig
-- `CAM`: Camera Rig
+- `CA`: Camera Rig
 
-Example root collection name: `CH-elder_sprite`
+Example root collection names: `CH-elder_sprite`, `LI-rock_large_013`
 
 Note that there's no technical distinction between different types of assets. This is purely for organizational purposes and comfort.
 
-The immediate sub-collections of the root collection are strictly defined by our Asset Pipeline add-on, as being `{identifier}-{task layer}`. Task Layers are the different data layers that make up an asset, such as Modeling, Rigging, and Shading. Inside these Task Layer Collections, each artist responsible for their own Task Layer may create sub-collections freely, as long as each sub-collection still starts with `{identifier}-{task layer}-`.
+The immediate sub-collections of the root collection should be named according to the Task Layers configured in our Asset Pipeline add-on, but this is not strictly required. Task Layers are the different data layers that make up an asset, such as Modeling, Rigging, and Shading. Collections nested beyond this can be named freely, as long as they still start with the namespace identifier.
+
 So, here's what an asset's collection hierarchy might look like:
 ```txt
 CH-elder_sprite
     esprite-model
-        esprite-model-head
+        esprite-head
-            esprite-model-teeth_and_tongue
+            esprite-teeth_and_tongue
     esprite-rig
-        esprite-rig-widgets
+        esprite-widgets
-        esprite-rig-helpers
+        esprite-helpers
-            esprite-rig-eye.L
+            esprite-eye.L
-            esprite-rig-eye.R
+            esprite-eye.R
     esprite-shading
-        esprite-shading-outlines
+        esprite-outlines
 ```
 
 ## Name Prefixes
@@ -62,36 +68,58 @@ All local datablocks of an asset (Object, Mesh, Material, Action, etc.) must als
 - Object Data and Shape Keys should be named the same as the containing Object. This is automated by the Asset Pipeline add-on.
 - Words in all base names should be lower-case and separated by `_`.
 - All datablock names must not end with a `.00x` suffix. This is enforced by the Asset Pipeline add-on.
-    - When there's too many objects to manually name, like when building a house out of a hundred wooden plank objects, the **Batch Rename Datablocks** built-in add-on should be used to give groups of objects the same name. Then replace the `.` in the `.00x` suffixes with an `_` instead, so `GEO-house-wooden_plank.023` becomes `GEO-house-wooden_plank_023`, making the number a part of the base name for the purposes of Library Overrides and duplication.
+    - When there's too many objects to manually name, like when building a house out of a hundred wooden plank objects, the **Batch Rename Datablocks Operator** should be used to give groups of objects the same name. Then replace the `.` in the `.00x` suffixes with an `_` instead, so `GEO-house-wooden_plank.023` becomes `GEO-house-wooden_plank_023`, making the number a part of the base name for the purposes of Library Overrides and duplication.
-    - This makes it so that when an asset is duplicated in a shot, every object in the same copy of the asset will have the same number suffix. The first copy will have no suffix, the second copy will have .001, etc. Without this step, this object would instead end up getting named `GEO-HS-wooden_plank.024`, which would mean the suffix number has no correlation with which overridden copy of the asset this object belongs to. This could break Library Overrides.
+    - This makes it so that when an asset is duplicated in a shot, every object in the same copy of the asset will have the same number suffix. The first copy will have no suffix, the second copy will have .001, etc. Without this step, this object would instead end up getting named `GEO-house-wooden_plank.024`, which would mean the suffix number has no correlation with which overridden copy of the asset this object belongs to. This could break Library Overrides.
-- "Of" relationships should be part of the base name, as there is nothing special about them from a technical sense, so they are not a suffix or a prefix. Example: `GEO-wardrobe-drawer_knob.L` for the knob of a drawer on the Wardrobe prop.
 
-
+## Indicating Hierarchy
-## Name Suffixes
+For complex assets, try to use dashes to indicate a nested hierarchy of objects, eg:
-Use `.L`/`.R` suffixes for objects that belong to one side and are symmetrical.
-On the other hand, avoid using `.L`/`.R` when similar objects exist on each side of an asset but aren't meant to be symmetrical.
-
-
-If the watch had a variant of type `clean` and `dirty`, these would be using a `:` to express the nature of the variant:
 ```
-`GEO-watch:clean`
+PR-wardrobe
-`GEO-watch:dirty`
+    wardrobe.model
+        GEO-wardrobe-base
+        GEO-wardrobe-drawer_01
+        GEO-wardrobe-drawer_01-knob
+        GEO-wardrobe-drawer_02
+        GEO-wardrobe-drawer_02-knob
 ```
 
+
+## Indicating Asset Variants
+The `.` is also used for indicating asset variants, which is when an asset has multiple states or versions in the production.
+The variant indicator can be placed anywhere in the name hierarchy:
+`GEO-wardrobe:burned-shelf-book` indicates that the whole wardrobe has a burned variant. Perhaps there was a house fire in the film.
+`GEO-wardrobe-shelf-book:burned` indicates that only the book is burned, perhaps because a candle fell over in the film.
+
+
+## Symmetry Suffixes
+Use exactly `.L`/`.R` suffixes for objects that belong to one side and are symmetrical.
+On the other hand, avoid using `.L`/`.R` when similar objects exist on each side of an asset but aren't meant to be symmetrical, and use a different side indicator if necessary, such as `_left`.
+
+
+## Node Trees
+Node Trees (aka Node Groups) in Blender are unfortunately all stored in one location, which is inconvenient when trying to browse them, which we frequently do. To remedy this, node groups should be prefixed with what type of node group they are.
+```
+`GN` : Geometry Nodes
+`SH` : Shading Nodes
+`CM` : Compositing Nodes
+```
+
+And as always, the namespace identifier must be included, eg. `GN-esprite-procedural_beard`.
+
 ## Actions
 
 ### Pose Library
 
-Pose Library actions are in their own files, and marked as assets, so they show up in the Asset Browser and therefore the built-in Pose Library add-on. Due to frequent use, limited UI space in the Pose Library UI, and the fact that these assets are never duplicated or made local in a shot file (therefore unique naming across the procution isn't important), their names should be kept very simple. No need for any prefix, just simply describe the pose. For easy consistency, lowercase words separated by underscores is recommended.
+Pose Library actions also need a namespace identifier. For easy consistency, use lowercase words separated by underscores, as usual.
 
 Examples:
 ```
-hand_fist
+rex-hand_fist
-hand_splayed
+rex-hand_splayed
-face_happy
+rex-face_happy
-face_surprised
+rex-face_surprised
-eyes_blink
+rex-eyes_blink
-eyes_surprised
+rex-eyes_surprised
 ```
 
 ### Rig Actions
@@ -106,13 +134,13 @@ RIG-esprite-mouth_open+lips_wide
 ```
 
 ### Animations of Shots
-Actions created for shots should be named `ANI-{asset_identifier}-{scene_name}.{version}`
+Actions created for shots should be named `ANI-{asset_identifier}-{scene_name}-{version}`
 
 Examples:
 ```
-ANI-esprite-060_scratch_layout.v001
+ANI-esprite-060_scratch_layout-v001
-ANI-esprite-110_0100_A.v001
+ANI-esprite-110_0100_A-v001
-ANI-rex-140_0020_A.v001
+ANI-rex-140_0020_A-v001
 ```
 
 ### Bone Names