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

@@ -1,62 +1,117 @@
-# In-file Prefixes
+# Datablock names
 
 ::: warning Work in Progress
 30 Apr. 2023 - The content of this page is currently being edited/updated.
 :::
 
-## Collection names
+## Separators
+We only have 3 separators to work with, so we try to make the most of them and keep their meaning consistent across conventions:  
+`-` : Separates prefixes from each other and from the rest of the name.  
+`_` : Used instead of spacebar in composite words, eg. `eifel_tower_base`.  
+`.` : Suffixes, used only for symmetry sides, ie `.L`/`.R`, and for variations, `clock.normal`, `clock.broken`, `clock.destroyed`  
 
-We use prefixes only for top level collections of an asset. This is important to distinguish types of assets. The name of the asset itself should be lowercase.
+## Asset Mnemonic
+
+All local datablocks across all assets of a production must have a unique name. To faciliate this, each asset is assigned a mnemonic that must remain unique within a given production. For example, a character named "Elder Sprite" might get the mnemonic "ES". The max length of this mnemonic is not limited, but the shorter the better. If a minor prop in the production is called "Electric Switch", it can not have the mnemonic "ES", because it's already taken. So, "ELSW" would be fine.
+
+## Asset Collections
+
+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.
 
 - `CH` : Character
 - `PR` : Prop
-- `EN` : Environment asset
+- `EN` : Environment Prop
-- `SE` : set
+- `SE` : Set
-- `LG` : light rig
+- `LG` : Light Rig
+- `CAM`: Camera Rig
 
-Example: `CH-phileas`
+Example: `CH-elder_sprite`
 
-Sub-collections should start with the character's name and have dots as separators: `phileas.rig.widgets`
+Note that there's no technical distinction between different types of assets. This is purely for organizational purposes and comfort.
 
-## Object naming
+The immediate sub-collections of the root collection are strictly defined by our Asset Pipeline add-on, as being `{mnemonic}-{task_layer}`. Task Layers are the different data layers that make up an asset, such as Modeling, Rigging, and Shading. Beyond those two layers, any number of collections may be created according to the needs and wants of the person responsible for a given Task Layer. However, each sub-collection should still start with `{mnemonic}-{task_layer}-`.
+So, here's what an asset's collection hierarchy might look like:
+```txt
+CH-elder_sprite
+    ES-model
+        ES-model-head
+            ES-model-teeth_and_tongue
+    ES-rig
+        ES-rig-widgets
+        ES-rig-helpers
+            ES-rig-eye.L
+            ES-rig-eye.R
+    ES-shading
+        ES-shading-outlines
+```
+## Asset Datablocks
+- All local datablocks (Mesh, Material, Action, etc.) of an asset must start with or at least include the asset's mnemonic, eg `ES-eye.L`. This is automated by the Asset Pipeline add-on.
+- Object Data and Shape Keys should be named the same as the containing Object. This is automated by the Asset Pipeline add-on.
+- Object names must not end with a `.00x` suffix. This is enforced by the Asset Pipeline add-on.
+    - In some cases it may be truly unreasonable to expect an artist to give every object in an asset a unique, manually typed in name, like when building a house out of a hundred wooden slab objects. In these cases, the Batch Rename Datablocks built-in add-on should be used to give groups of objects the same name, then in a subsequent step replace the `.` in the `.00x` suffixes with an `_` instead.
+    - The purpose of this is so that, when there are >1 copies of this asset overridden in a file, every object in the same copy of the asset will have the same number suffix. This would not be the case if we didn't replace the `.` with an `_` before publishing the asset.
+    - Without this step, debugging shot files with multiple copies of an asset becomes an absolute nightmare, and if you add the occasional deletion of copies into the mix, it could even confuse Blender's Library Override system and break shots.
 
-All objects should have a prefix, followed by a dash that determines their type:
+It is advisable to give Objects an additional prefix to provide information about the object's purpose, especially when it is NOT part of an asset. This is purely for organizational and comfort purposes. Here are some recommendations:
 
-- `WGT` : bone shapes
+- `WGT` : Bone shapes
-- `LGT` : light objects and mesh-lights, also shadow casters
+- `LGT` : Light objects and mesh-lights, also shadow casters
 - `HLP` : Empties and other helper objects that are not rendered
 - `GEO` : Geometry, meshes, curves that contribute to the rendered appearance of the asset
 - `RIG` : Rig and rig specific objects that do not appear in rendering
-- `ENV` : matte paintings, sky-domes, fog volume objects
+- `ENV` : Matte paintings, sky-domes, fog volume objects
-- `GPL` : grease pencil stroke objects (need to differentiate from GEO because can not be rendered on the farm)
+- `GPL` : Grease pencil stroke objects (need to differentiate from GEO because can not be rendered on the farm)
 
-Use dot uppercase L or R for objects that belong to one side and are mirrored 
+Use `.L` or `.R` for objects that belong to one side and are symmetrical.
+On the other hand, avoid using `.L` and `.R` when similar objects exist on each side of an asset but aren't meant to be symmetrical.
 
-Example: `GEO-dresser_drawer.L`
+Example: `GEO-WRDB-drawer_knob.L` for the left-side drawer knob of a wardrobe prop.
 
-If a name contains a *of* relationship - in the above example the `drawer` of the `dresser` - these should not be separated by a dot, but rather with an underscore.
+If a name contains a *of* relationship - in the above example the `knob` of the `drawer` - these should NOT be separated by `.`, but rather with `_`.
 
-Another example: `GEO-ellie_watch_screw` and not `GEO-ellie_watch.screw`
+Another example:
+```
+Good: `GEO-ES-watch_screw`
+Bad:  `GEO-ES-watch.screw`
+```
 
-If the watch had a variant of type `clean` and `dirty`, these would be using a dot to express the nature of the variant: `GEO-ellie_watch.clean` and `GEO-ellie_watch.dirty` 
+If the watch had a variant of type `clean` and `dirty`, these would be using a `.` to express the nature of the variant:
+```
+`GEO-ES-watch.clean`
+`GEO-ES-watch.dirty` 
+```
 
 ## Actions
 
-### Prefixes
+### Pose Library
 
-Example: `PLB-spring.hand`
+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. Since the Pose Library doesn't have collections, use naming to make sure that poses for a given body part get sorted together alphabetically.
 
-- `PLB` Pose library actions to be linked into animation files
+Examples:
-- `RIG` Actions used by the rig's Action constraints
+```
-- `ANI` Animation to be used in a shot
+Hand_Fist
-
+Hand_Splayed
-More examples:
+Face_Happy
-
+Face_Surprised
-```txt
+Eyes_Blink
-- ANI-rex.140_0020_A.v001
+Eyes_Surprised
-- ANI-ellie.060_scratch.layout.v001
+```
-- ANI-sprite_A.110_0100_A.v001
+
-- PLB-rex_face.scared
+### Rig Constraints
-- PLB-rex_face.happy
+Rigs may use Actions for Action Constraint based control set-ups. Since these are asset datablocks, they must start with the asset mnemonic.
-- PLB-rex_hand.closed
+Corrective Actions are ones which are meant to activate when two other actions activate. These should use the name of the two trigger actions, separated by a "+".
+
+Examples: 
+- `RIG-ES-mouth_open`
+- `RIG-ES-lips_wide`
+- `RIG-ES-mouth_open+lips_wide`
+
+### Animations of Shots
+Actions created for shots should be named `ANI-{asset_mnemonic}-{scene_name}.{version}`
+
+Examples:
+```
+ANI-ES-060_scratch_layout.v001
+ANI-ES-110_0100_A.v001
+ANI-REX-140_0020_A.v001
 ```