From 434a0d5e5192042b1a89bca2d2285899a900a3e5 Mon Sep 17 00:00:00 2001 From: "demeterdzadik@gmail.com" Date: Fri, 15 Sep 2023 21:54:00 +0200 Subject: [PATCH 01/11] New naming convention proposal A major overhaul of our in-blend naming conventions. Goals: - Every asset datablock must have a unique name to avoid Override issues - Separators could be more consistent and meaningful - No unnecessary strictness, eg. for Pose Library --- docs/naming-conventions/in-file-prefixes.md | 123 ++++++++++++++------ 1 file changed, 89 insertions(+), 34 deletions(-) diff --git a/docs/naming-conventions/in-file-prefixes.md b/docs/naming-conventions/in-file-prefixes.md index eae1c6a0..47240dd3 100644 --- a/docs/naming-conventions/in-file-prefixes.md +++ b/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 -- `SE` : set -- `LG` : light rig +- `EN` : Environment Prop +- `SE` : Set +- `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 -- `LGT` : light objects and mesh-lights, also shadow casters +- `WGT` : Bone shapes +- `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 -- `GPL` : grease pencil stroke objects (need to differentiate from GEO because can not be rendered on the farm) +- `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) -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 -- `RIG` Actions used by the rig's Action constraints -- `ANI` Animation to be used in a shot - -More examples: - -```txt -- ANI-rex.140_0020_A.v001 -- ANI-ellie.060_scratch.layout.v001 -- ANI-sprite_A.110_0100_A.v001 -- PLB-rex_face.scared -- PLB-rex_face.happy -- PLB-rex_hand.closed +Examples: +``` +Hand_Fist +Hand_Splayed +Face_Happy +Face_Surprised +Eyes_Blink +Eyes_Surprised +``` + +### Rig Constraints +Rigs may use Actions for Action Constraint based control set-ups. Since these are asset datablocks, they must start with the asset mnemonic. +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 ``` -- 2.30.2 From d5140afb7f749ce8b467df443d4f4ca051a37565 Mon Sep 17 00:00:00 2001 From: "demeterdzadik@gmail.com" Date: Fri, 15 Sep 2023 22:30:25 +0200 Subject: [PATCH 02/11] Small tweak --- docs/naming-conventions/in-file-prefixes.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/naming-conventions/in-file-prefixes.md b/docs/naming-conventions/in-file-prefixes.md index 47240dd3..710aa323 100644 --- a/docs/naming-conventions/in-file-prefixes.md +++ b/docs/naming-conventions/in-file-prefixes.md @@ -102,9 +102,11 @@ Rigs may use Actions for Action Constraint based control set-ups. Since these ar 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` +``` +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}` -- 2.30.2 From e1dad148895fd5bbbf35bafd65fd5ab51e41d07a Mon Sep 17 00:00:00 2001 From: "demeterdzadik@gmail.com" Date: Fri, 15 Sep 2023 22:33:01 +0200 Subject: [PATCH 03/11] Remove WIP warning notice --- docs/naming-conventions/in-file-prefixes.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/naming-conventions/in-file-prefixes.md b/docs/naming-conventions/in-file-prefixes.md index 710aa323..97c48c8e 100644 --- a/docs/naming-conventions/in-file-prefixes.md +++ b/docs/naming-conventions/in-file-prefixes.md @@ -1,9 +1,5 @@ # Datablock names -::: warning Work in Progress -30 Apr. 2023 - The content of this page is currently being edited/updated. -::: - ## 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. -- 2.30.2 From 27188bc437cd5adf64df4ae48036adb77ff9b166 Mon Sep 17 00:00:00 2001 From: "demeterdzadik@gmail.com" Date: Mon, 18 Sep 2023 11:01:39 +0200 Subject: [PATCH 04/11] More tweaks and clarifications - Make it explicit that if a name includes the full name of the asset, using the mnemonic is not necessary. - Add `TMP` name prefix suggestion - Add more detailed but less wordy explanation about why unique ID names are important. --- docs/naming-conventions/in-file-prefixes.md | 27 ++++++++++++--------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/docs/naming-conventions/in-file-prefixes.md b/docs/naming-conventions/in-file-prefixes.md index 97c48c8e..3eaf7510 100644 --- a/docs/naming-conventions/in-file-prefixes.md +++ b/docs/naming-conventions/in-file-prefixes.md @@ -1,14 +1,16 @@ # Datablock 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: +We only have 3 separators to work with, so we try 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` ## 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. +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. + +This mnemonic will be used in the names of datablocks, to make sure all names are unique, not just in a single file, but the whole production. This is useful/necessary because of the way Blender's Override system works, which relies on making local copies of linked object hierarchies, meaning all assets need to be able to exist in the same namespace without collisions. ## Asset Collections @@ -25,7 +27,7 @@ Example: `CH-elder_sprite` 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 `{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}-`. +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. 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 `{mnemonic}-{task_layer}-`. So, here's what an asset's collection hierarchy might look like: ```txt CH-elder_sprite @@ -40,13 +42,15 @@ CH-elder_sprite 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. +- All local datablocks of an asset (Object, Mesh, Material, Action, etc.) must include either the asset's mnemonic or full name (both is not necessary). Eg., `RIG-elder_sprite` or `GEO-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. +- 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-HS-wooden_plank.023` becomes `GEO-HS-wooden_plank_023`. + - The purpose of this is that when there are >1 copies of this asset overridden (and therefore local) in a file, 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 of the asset will have object names like `GEO-HS-wooden_plank_023.001`, which is fine. If we didn't do this step, this object would instead end up getting named `GEO-HS-wooden_plank.024`, which is not fine because now the suffix number has no correlation with which overridden copy of the asset this object belongs to. + - Without this step, debugging shot files with multiple copies of an asset becomes a nightmare, and it could even confuse the Library Override system and break shots. + 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: @@ -57,13 +61,14 @@ It is advisable to give Objects an additional prefix to provide information abou - `RIG` : Rig and rig specific objects that do not appear in rendering - `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) +- `TMP` : Any object used in pre-viz that should be replaced with final assets over the course of the production. -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. +Use `.L`/`.R` suffices 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. 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 `knob` of the `drawer` - these should NOT be separated by `.`, but rather with `_`. +If a name contains an "*of*" relationship - in the above example the `knob` *of* the `drawer` - these should NOT be separated by `.`, but rather with `_`. Another example: ``` -- 2.30.2 From 2435c664be919e94963c201e33bd09dae0f7458a Mon Sep 17 00:00:00 2001 From: "demeterdzadik@gmail.com" Date: Mon, 18 Sep 2023 14:43:24 +0200 Subject: [PATCH 05/11] Replace "mnemonic" with "identifier" Based on feedback from Simon. --- docs/naming-conventions/in-file-prefixes.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/naming-conventions/in-file-prefixes.md b/docs/naming-conventions/in-file-prefixes.md index 3eaf7510..de1a12ce 100644 --- a/docs/naming-conventions/in-file-prefixes.md +++ b/docs/naming-conventions/in-file-prefixes.md @@ -6,11 +6,11 @@ We only have 3 separators to work with, so we try keep their meaning consistent `_` : 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` -## Asset Mnemonic +## Asset Identifier -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. +All local datablocks across all assets of a production must have a unique name. To faciliate this, each asset is assigned an identifier that must remain unique within a given production. For example, a character named "Elder Sprite" might get the identifier "ES". The max length of this identifier is not limited, but the shorter the better. If a minor prop in the production is called "Electric Switch", it can not have the identifier "ES", because it's already taken. So, "ELSW" would be fine. -This mnemonic will be used in the names of datablocks, to make sure all names are unique, not just in a single file, but the whole production. This is useful/necessary because of the way Blender's Override system works, which relies on making local copies of linked object hierarchies, meaning all assets need to be able to exist in the same namespace without collisions. +This identifier will be used in the names of datablocks, to make sure all names are unique, not just in a single file, but the whole production. This is useful/necessary because of the way Blender's Override system works, which relies on making local copies of linked object hierarchies, meaning all assets need to be able to exist in the same namespace without collisions. ## Asset Collections @@ -27,7 +27,7 @@ Example: `CH-elder_sprite` 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 `{mnemonic}-{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 `{mnemonic}-{task_layer}-`. +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}-`. So, here's what an asset's collection hierarchy might look like: ```txt CH-elder_sprite @@ -44,7 +44,7 @@ CH-elder_sprite ``` ## Asset Datablocks -- All local datablocks of an asset (Object, Mesh, Material, Action, etc.) must include either the asset's mnemonic or full name (both is not necessary). Eg., `RIG-elder_sprite` or `GEO-ES-eye.L`. This is automated by the Asset Pipeline add-on. +- All local datablocks of an asset (Object, Mesh, Material, Action, etc.) must include either the asset's identifier or full name (both is not necessary). Eg., `RIG-elder_sprite` or `GEO-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. - 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-HS-wooden_plank.023` becomes `GEO-HS-wooden_plank_023`. @@ -99,7 +99,7 @@ Eyes_Surprised ``` ### Rig Constraints -Rigs may use Actions for Action Constraint based control set-ups. Since these are asset datablocks, they must start with the asset mnemonic. +Rigs may use Actions for Action Constraint based control set-ups. Since these are asset datablocks, they must start with the asset identifier. 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: @@ -110,7 +110,7 @@ RIG-ES-mouth_open+lips_wide ``` ### Animations of Shots -Actions created for shots should be named `ANI-{asset_mnemonic}-{scene_name}.{version}` +Actions created for shots should be named `ANI-{asset_identifier}-{scene_name}.{version}` Examples: ``` -- 2.30.2 From 7960580c1646053b21df5ed424b2bc997efb14ee Mon Sep 17 00:00:00 2001 From: "demeterdzadik@gmail.com" Date: Tue, 19 Sep 2023 15:41:17 +0200 Subject: [PATCH 06/11] Address feedback, add bone naming --- docs/naming-conventions/in-file-prefixes.md | 123 +++++++++++--------- 1 file changed, 71 insertions(+), 52 deletions(-) diff --git a/docs/naming-conventions/in-file-prefixes.md b/docs/naming-conventions/in-file-prefixes.md index de1a12ce..8f42db99 100644 --- a/docs/naming-conventions/in-file-prefixes.md +++ b/docs/naming-conventions/in-file-prefixes.md @@ -2,17 +2,18 @@ ## Separators We only have 3 separators to work with, so we try 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` +`-` : Separates prefixes (including the Asset Identifier) from each other and from the rest of the name. +`.` : Separates suffixes, currently only for symmetry sides, ie `.L`/`.R`. +`_` : Used to separate parts of the base name, eg. `console_button_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 -All local datablocks across all assets of a production must have a unique name. To faciliate this, each asset is assigned an identifier that must remain unique within a given production. For example, a character named "Elder Sprite" might get the identifier "ES". The max length of this identifier is not limited, but the shorter the better. If a minor prop in the production is called "Electric Switch", it can not have the identifier "ES", because it's already taken. So, "ELSW" would be fine. +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`. -This identifier will be used in the names of datablocks, to make sure all names are unique, not just in a single file, but the whole production. This is useful/necessary because of the way Blender's Override system works, which relies on making local copies of linked object hierarchies, meaning all assets need to be able to exist in the same namespace without collisions. +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 useful/necessary because of the way Blender's Override system works, which 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. -## Asset Collections +## 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. @@ -27,59 +28,55 @@ Example: `CH-elder_sprite` 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 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}-`. 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 + esprite-model + esprite-model-head + esprite-model-teeth_and_tongue + esprite-rig + esprite-rig-widgets + esprite-rig-helpers + esprite-rig-eye.L + esprite-rig-eye.R + esprite-shading + esprite-shading-outlines ``` -## Asset Datablocks -- All local datablocks of an asset (Object, Mesh, Material, Action, etc.) must include either the asset's identifier or full name (both is not necessary). Eg., `RIG-elder_sprite` or `GEO-ES-eye.L`. This is automated by the Asset Pipeline add-on. +## Name Prefixes +All Object names (not just in Assets) must start with a prefix describing the object's purpose: + +- `LGT` : Light objects and mesh-lights, also shadow casters +- `ENV` : Matte paintings, sky-domes, fog volume objects +- `GEO` : Geometry, meshes, curves that contribute to the rendered appearance of the asset +- `GPL` : Grease pencil stroke objects (need to differentiate from GEO because can not be rendered on the farm) +- `RIG` : Rig and rig specific objects that do not appear in rendering +- `WGT` : Bone shapes +- `HLP` : Empties and other helper objects that are not rendered +- `TMP` : Any object used in pre-viz that should be replaced with final assets over the course of the production. + +All local datablocks of an asset (Object, Mesh, Material, Action, etc.) must also include either the asset's shortened or full name. Eg., `RIG-elder_sprite` or `GEO-elder-eye.L`. This is enforced by the Asset Pipeline add-on. + +## Base Names - Object Data and Shape Keys should be named the same as the containing Object. This is automated by the Asset Pipeline add-on. -- 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-HS-wooden_plank.023` becomes `GEO-HS-wooden_plank_023`. +- 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-HS-wooden_plank.023` becomes `GEO-HS-wooden_plank_023`, making the number a part of the base name. - The purpose of this is that when there are >1 copies of this asset overridden (and therefore local) in a file, 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 of the asset will have object names like `GEO-HS-wooden_plank_023.001`, which is fine. If we didn't do this step, this object would instead end up getting named `GEO-HS-wooden_plank.024`, which is not fine because now the suffix number has no correlation with which overridden copy of the asset this object belongs to. - Without this step, debugging shot files with multiple copies of an asset becomes a nightmare, and it could even confuse the Library Override system and break shots. -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 -- `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 -- `GPL` : Grease pencil stroke objects (need to differentiate from GEO because can not be rendered on the farm) -- `TMP` : Any object used in pre-viz that should be replaced with final assets over the course of the production. - -Use `.L`/`.R` suffices for objects that belong to one side and are symmetrical. +## Name Suffixes +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. -Example: `GEO-WRDB-drawer_knob.L` for the left-side drawer knob of a wardrobe prop. +"Of" relationships should be part of the base name, and not a suffix. Example: `GEO-wardrobe-drawer_knob.L` for the left-side drawer knob of the Wardrobe prop. -If a name contains an "*of*" relationship - in the above example the `knob` *of* the `drawer` - these should NOT be separated by `.`, but rather with `_`. - -Another example: +If the watch had a variant of type `clean` and `dirty`, these would be using a `:` to express the nature of the variant: ``` -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 `.` to express the nature of the variant: -``` -`GEO-ES-watch.clean` -`GEO-ES-watch.dirty` +`GEO-watch.clean` +`GEO-watch.dirty` ``` ## Actions @@ -90,15 +87,15 @@ Pose Library actions are in their own files, and marked as assets, so they show Examples: ``` -Hand_Fist -Hand_Splayed -Face_Happy -Face_Surprised -Eyes_Blink -Eyes_Surprised +hand_fist +hand_splayed +face_happy +face_surprised +eyes_blink +eyes_surprised ``` -### Rig Constraints +### Rig Actions Rigs may use Actions for Action Constraint based control set-ups. Since these are asset datablocks, they must start with the asset identifier. 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 "+". @@ -118,3 +115,25 @@ ANI-ES-060_scratch_layout.v001 ANI-ES-110_0100_A.v001 ANI-REX-140_0020_A.v001 ``` + +### Bone Names +Making rigs as easy to learn and work with as possible is the most important thing when naming bones. +Every bone name should be named properly (never `Bone.023`), avoid ugly number suffixes, and avoid unnecessary padding in numbers. +Controls that are exposed to animators should ideally have max one prefix, with an intuitive acronym. +Examples: +``` +Bad: STR-TIP-Finger_04_003.L +Good: STR-Finger_Pinky_4.L +``` + +Numbering should start from 1, but if a bone gets inserted at the start of the chain, it's better to just number it 0 rather than change all the pre-existing bones' names, to not break any existing animations. + +Symmetry sides should be indicated by `.L`/`.R`. + +Other prefixes and their meaning: +- `IK` : Control body parts in Inverse Kinematics mode +- `FK` : Control body parts in Forward Kinematics mode +- `STR` : Squash and stretch body parts +- `ROOT` : Control a cohesive area of the rig (often detachable) +- `TGT` : Control the target of a Look-At rig set-up +- `P` : Parent of another control \ No newline at end of file -- 2.30.2 From 288d604bda83ab1c804197537daf96758320961d Mon Sep 17 00:00:00 2001 From: "demeterdzadik@gmail.com" Date: Wed, 20 Sep 2023 15:44:50 +0200 Subject: [PATCH 07/11] Small clarification for the "Of" relationships --- docs/naming-conventions/in-file-prefixes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/naming-conventions/in-file-prefixes.md b/docs/naming-conventions/in-file-prefixes.md index 8f42db99..a13d9cf0 100644 --- a/docs/naming-conventions/in-file-prefixes.md +++ b/docs/naming-conventions/in-file-prefixes.md @@ -65,13 +65,13 @@ All local datablocks of an asset (Object, Mesh, Material, Action, etc.) must als - 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-HS-wooden_plank.023` becomes `GEO-HS-wooden_plank_023`, making the number a part of the base name. - The purpose of this is that when there are >1 copies of this asset overridden (and therefore local) in a file, 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 of the asset will have object names like `GEO-HS-wooden_plank_023.001`, which is fine. If we didn't do this step, this object would instead end up getting named `GEO-HS-wooden_plank.024`, which is not fine because now the suffix number has no correlation with which overridden copy of the asset this object belongs to. - Without this step, debugging shot files with multiple copies of an asset becomes a nightmare, and it could even confuse the Library Override system and break shots. +- "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. ## Name Suffixes 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. -"Of" relationships should be part of the base name, and not a suffix. Example: `GEO-wardrobe-drawer_knob.L` for the left-side drawer knob of the Wardrobe prop. If the watch had a variant of type `clean` and `dirty`, these would be using a `:` to express the nature of the variant: ``` -- 2.30.2 From 2ec549e247c991bbf3e8c54c37be90773230224b Mon Sep 17 00:00:00 2001 From: "demeterdzadik@gmail.com" Date: Tue, 7 Nov 2023 17:12:30 +0100 Subject: [PATCH 08/11] Update in-file naming conventions for consistency --- docs/naming-conventions/in-file-prefixes.md | 35 ++++++++++----------- 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/docs/naming-conventions/in-file-prefixes.md b/docs/naming-conventions/in-file-prefixes.md index a13d9cf0..e6f1fb7e 100644 --- a/docs/naming-conventions/in-file-prefixes.md +++ b/docs/naming-conventions/in-file-prefixes.md @@ -11,7 +11,7 @@ We only have 3 separators to work with, so we try keep their meaning consistent 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`. -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 useful/necessary because of the way Blender's Override system works, which 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. +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. ## Asset Collection Hierarchy @@ -24,7 +24,7 @@ We use prefixes for the root collections of assets to help distinguish different - `LG` : Light Rig - `CAM`: Camera Rig -Example: `CH-elder_sprite` +Example root collection name: `CH-elder_sprite` Note that there's no technical distinction between different types of assets. This is purely for organizational purposes and comfort. @@ -49,22 +49,21 @@ All Object names (not just in Assets) must start with a prefix describing the ob - `LGT` : Light objects and mesh-lights, also shadow casters - `ENV` : Matte paintings, sky-domes, fog volume objects -- `GEO` : Geometry, meshes, curves that contribute to the rendered appearance of the asset +- `GEO` : Geometry, meshes, curves that contribute to the rendered appearance of an asset +- `RIG` : Armatures of an asset - `GPL` : Grease pencil stroke objects (need to differentiate from GEO because can not be rendered on the farm) -- `RIG` : Rig and rig specific objects that do not appear in rendering - `WGT` : Bone shapes - `HLP` : Empties and other helper objects that are not rendered - `TMP` : Any object used in pre-viz that should be replaced with final assets over the course of the production. -All local datablocks of an asset (Object, Mesh, Material, Action, etc.) must also include either the asset's shortened or full name. Eg., `RIG-elder_sprite` or `GEO-elder-eye.L`. This is enforced by the Asset Pipeline add-on. +All local datablocks of an asset (Object, Mesh, Material, Action, etc.) must also include either the asset's shortened or full name. Eg., `RIG-elder_sprite` or `GEO-esprite-eye.L`. This is enforced by the Asset Pipeline add-on. ## Base Names - 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-HS-wooden_plank.023` becomes `GEO-HS-wooden_plank_023`, making the number a part of the base name. - - The purpose of this is that when there are >1 copies of this asset overridden (and therefore local) in a file, 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 of the asset will have object names like `GEO-HS-wooden_plank_023.001`, which is fine. If we didn't do this step, this object would instead end up getting named `GEO-HS-wooden_plank.024`, which is not fine because now the suffix number has no correlation with which overridden copy of the asset this object belongs to. - - Without this step, debugging shot files with multiple copies of an asset becomes a nightmare, and it could even confuse the Library Override system and break shots. + - 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. + - 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. - "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. @@ -75,15 +74,15 @@ On the other hand, avoid using `.L`/`.R` when similar objects exist on each side 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` -`GEO-watch.dirty` +`GEO-watch:clean` +`GEO-watch:dirty` ``` ## 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. Since the Pose Library doesn't have collections, use naming to make sure that poses for a given body part get sorted together alphabetically. +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. Examples: ``` @@ -96,14 +95,14 @@ eyes_surprised ``` ### Rig Actions -Rigs may use Actions for Action Constraint based control set-ups. Since these are asset datablocks, they must start with the asset identifier. +Rigs may use Actions for Action Constraint based control set-ups. Since these are datablocks and part of the character asset, they must start with the asset identifier. 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 +RIG-esprite-mouth_open +RIG-esprite-lips_wide +RIG-esprite-mouth_open+lips_wide ``` ### Animations of Shots @@ -111,9 +110,9 @@ Actions created for shots should be named `ANI-{asset_identifier}-{scene_name}.{ Examples: ``` -ANI-ES-060_scratch_layout.v001 -ANI-ES-110_0100_A.v001 -ANI-REX-140_0020_A.v001 +ANI-esprite-060_scratch_layout.v001 +ANI-esprite-110_0100_A.v001 +ANI-rex-140_0020_A.v001 ``` ### Bone Names -- 2.30.2 From 69e1a19eec8d75251676014f45ed212412733f3d Mon Sep 17 00:00:00 2001 From: "demeterdzadik@gmail.com" Date: Wed, 15 Nov 2023 18:42:03 +0100 Subject: [PATCH 09/11] Update based on meeting with Simon and Andy - Dashes can be used to signify a sort of hierarchy - Variants are still separated by : but in a way that sort of merges into the hierarchy defined by the dashes, eg. `wardrobe:burned-shelf-book` - Asset identifier mostly non-controversial; Shortened name is optional, but try to use it. Asset identifiers can have underscores and numbers, no problem. (coral_001) - Collection prefixes should only be used for root collection. (Put this right after the Asset Collection Hierarchy header!) - Task layer names no longer have to be included in collection names. - Expand the concept of "Asset Identifier" to be more like a "Namespace Identifier", and mention that it should also be used for library IDs that aren't part of an (Asset Pipeline) asset. (instead of the asset's name, use the file's name, for example.) - Add SH-, GN-, CM- prefix conventions for node groups. - Small correction: Batch Rename Datablocks is not an addon. - Small correction: `GEO-house-wooden_plank.023` had inconsistent names - "Of" relationships should no longer be part of the base name. Recommended hierarchy based naming using dashes. - Variants are now a bit more complex, try to explain that properly. - Pose library poses should also have the asset identifier. - Animation versions now separated by dash instead of dot. - Change camera rig prefix from CAM to CA. - Only one prefix, still separated by dash. --- docs/naming-conventions/in-file-prefixes.md | 114 ++++++++++++-------- 1 file changed, 71 insertions(+), 43 deletions(-) diff --git a/docs/naming-conventions/in-file-prefixes.md b/docs/naming-conventions/in-file-prefixes.md index e6f1fb7e..b167e337 100644 --- a/docs/naming-conventions/in-file-prefixes.md +++ b/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: -`-` : Separates prefixes (including the Asset Identifier) from each other and from the rest of the name. -`.` : Separates suffixes, currently only for symmetry sides, ie `.L`/`.R`. -`_` : Used to separate parts of the base name, eg. `console_button_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`. +We try keep their meaning consistent across conventions: +`-` : 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 for symmetry sides, eg. `GEO-esprite-eye.L`, as well as asset variants, see below. +`_` : Used to separate parts of the base name, eg. `wooden_wardrobe_032`. The base name of an ID never has any technical significance. -## 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 -- `EN` : Environment Prop +- `PR` : Rigger 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-model-teeth_and_tongue + esprite-head + esprite-teeth_and_tongue esprite-rig - esprite-rig-widgets - esprite-rig-helpers - esprite-rig-eye.L - esprite-rig-eye.R + esprite-widgets + esprite-helpers + esprite-eye.L + 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. - - 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. -- "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. + - 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-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. - -## Name Suffixes -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: +## Indicating Hierarchy +For complex assets, try to use dashes to indicate a nested hierarchy of objects, eg: ``` -`GEO-watch:clean` -`GEO-watch:dirty` +PR-wardrobe + 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 -hand_splayed -face_happy -face_surprised -eyes_blink -eyes_surprised +rex-hand_fist +rex-hand_splayed +rex-face_happy +rex-face_surprised +rex-eyes_blink +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-110_0100_A.v001 -ANI-rex-140_0020_A.v001 +ANI-esprite-060_scratch_layout-v001 +ANI-esprite-110_0100_A-v001 +ANI-rex-140_0020_A-v001 ``` ### Bone Names -- 2.30.2 From 523bac7ffc667df7b56b5d0370dda2d4435eeaee Mon Sep 17 00:00:00 2001 From: "demeterdzadik@gmail.com" Date: Thu, 16 Nov 2023 14:45:53 +0100 Subject: [PATCH 10/11] Fix variant examples using : instead of . --- docs/naming-conventions/in-file-prefixes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/naming-conventions/in-file-prefixes.md b/docs/naming-conventions/in-file-prefixes.md index b167e337..8e27cac0 100644 --- a/docs/naming-conventions/in-file-prefixes.md +++ b/docs/naming-conventions/in-file-prefixes.md @@ -87,8 +87,8 @@ PR-wardrobe ## 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. +`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 -- 2.30.2 From 44c9a38e76dbae1d2bb4f6edfc9b83d4bbba94a0 Mon Sep 17 00:00:00 2001 From: "demeterdzadik@gmail.com" Date: Thu, 23 Nov 2023 16:45:32 +0100 Subject: [PATCH 11/11] Final touch-ups & some imgs for visual aid --- .../collection_hierarchy_naming_example.png | 3 ++ .../hierarchy_name_example.png | 3 ++ docs/naming-conventions/in-file-prefixes.md | 31 ++++--------------- 3 files changed, 12 insertions(+), 25 deletions(-) create mode 100644 docs/media/naming-conventions/collection_hierarchy_naming_example.png create mode 100644 docs/media/naming-conventions/hierarchy_name_example.png diff --git a/docs/media/naming-conventions/collection_hierarchy_naming_example.png b/docs/media/naming-conventions/collection_hierarchy_naming_example.png new file mode 100644 index 00000000..a707ef52 --- /dev/null +++ b/docs/media/naming-conventions/collection_hierarchy_naming_example.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d0c43b3b2ee7778bcbcad1f4484117ba6f5f9c395dde42a8dd3d69c6e3ebba42 +size 28948 diff --git a/docs/media/naming-conventions/hierarchy_name_example.png b/docs/media/naming-conventions/hierarchy_name_example.png new file mode 100644 index 00000000..21031ec1 --- /dev/null +++ b/docs/media/naming-conventions/hierarchy_name_example.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:716d5db90eedba01d9662174444ceca273090297aa8ccd7ee6d85fcb072b0bca +size 27514 diff --git a/docs/naming-conventions/in-file-prefixes.md b/docs/naming-conventions/in-file-prefixes.md index 8e27cac0..4a031f98 100644 --- a/docs/naming-conventions/in-file-prefixes.md +++ b/docs/naming-conventions/in-file-prefixes.md @@ -36,19 +36,8 @@ Note that there's no technical distinction between different types of assets. Th 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-head - esprite-teeth_and_tongue - esprite-rig - esprite-widgets - esprite-helpers - esprite-eye.L - esprite-eye.R - esprite-shading - esprite-outlines -``` +![Collection Hierarchy Naming Example](/media/naming-conventions/collection_hierarchy_naming_example.png) + ## Name Prefixes All Object names (not just in Assets) must start with a prefix describing the object's purpose: @@ -73,15 +62,7 @@ All local datablocks of an asset (Object, Mesh, Material, Action, etc.) must als ## Indicating Hierarchy For complex assets, try to use dashes to indicate a nested hierarchy of objects, eg: -``` -PR-wardrobe - wardrobe.model - GEO-wardrobe-base - GEO-wardrobe-drawer_01 - GEO-wardrobe-drawer_01-knob - GEO-wardrobe-drawer_02 - GEO-wardrobe-drawer_02-knob -``` +![Indicating Hierarchy in names](/media/naming-conventions/hierarchy_name_example.png) ## Indicating Asset Variants @@ -110,7 +91,7 @@ And as always, the namespace identifier must be included, eg. `GN-esprite-proced ### Pose Library -Pose Library actions also need a namespace identifier. For easy consistency, use lowercase words separated by underscores, as usual. +Pose Library actions also need a namespace identifier. Other than that, stick to lowercase and underscores. Examples: ``` @@ -123,7 +104,7 @@ rex-eyes_surprised ``` ### Rig Actions -Rigs may use Actions for Action Constraint based control set-ups. Since these are datablocks and part of the character asset, they must start with the asset identifier. +Rigs may use Actions for Action Constraint based control set-ups. Since these are datablocks and part of the character asset, they must include the namespace identifier. 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: @@ -134,7 +115,7 @@ 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-{namespace_identifier}-{scene_name}-{version}` Examples: ``` -- 2.30.2