Update install and animation docs

Author: parashivbrl

docs/animation_settings.md

@@ -2,26 +2,29 @@
 
 When importing GLTF/GLB files, you can configure animation settings to control how animations are processed and displayed.
 
-## Import Animations
-
-Controls whether animations are imported from the GLTF/GLB file:
-
-- When enabled (default), creates Maya keyframes for translation, rotation, and scale animations
-
-- Imports all animation data from the file, including bone animations, object transformations, and camera animations
+> **Note:** Before previewing imported animation, set Maya's Time Slider playback speed to **Real-time** (`Playback Speed > Real-time`). The other options—**Play Every Frame, Free** and **Play Every Frame, Max Real-time**—ignore the FPS chosen below and can make animation appear too fast or too slow.
 
-- When disabled, animation data is ignored and only static geometry is imported
+## Animation FPS
 
-- Useful when you only need the static model without animation data
+- Choose the playback rate for imported animations from the dropdown
+- Default is **30 fps (NTSC)**, but presets such as 15 fps (Game), 24 fps (Film), 25 fps (PAL), 48 fps (Show), 50 fps (PAL Field), and 60 fps (NTSC Field) are available
+- **24 fps** and **30 fps** cover most use cases
+- Use this setting to match the project frame rate before importing
 
-## Open Time Editor Window
+## Import Animations
 
-Controls whether the Time Editor window opens automatically after import:
+- When enabled (default), brings in all animation data, including skeletal motion, object transforms, and camera animation, creating the corresponding Maya keyframes
+- Disable if you only need static meshes and want to avoid adding keys to the scene
+- Helpful to leave off when you plan to author new animation in Maya and only use the imported geometry
 
-- When enabled, the Maya Time Editor window automatically opens when importing animated GLTF/GLB files
+## Import Blendshape Animations
 
-- Provides immediate access to view and edit the imported animation clips
+- When enabled (default), imports blendshape weight keyframes from the GLTF/GLB file
+- Required for facial animation or any deformation driven by blendshape curves
+- Disable if you only need static blendshape targets without animation to reduce scene keyframe data
 
-- Useful for quickly reviewing and editing imported animations
+## Open Time Editor Window
 
-- When disabled (default), animations are imported but the Time Editor window does not open automatically
+- When enabled, launches the Maya Time Editor immediately after import so you can inspect and tweak the new animation clips
+- Helpful when you expect to edit or retime the imported animation right away
+- Disabled by default to avoid interrupting the workflow if you only need the animation loaded into the scene

docs/dependencies_installation.md

@@ -8,7 +8,7 @@ This guide will help you install the required dependencies for the glTF/GLB impo
 
 | Requirement | Details |
 |-------------|---------|
-| **Maya Version** | Maya 2024 or later|
+| **Maya Version** | Maya 2022 or later|
 | **Operating System** | Windows, macOS, or Linux |
 | **Python** | Python 3.7+ (automatically included with Maya 2022+) |
 
@@ -18,7 +18,7 @@ This guide will help you install the required dependencies for the glTF/GLB impo
 
 The plugin requires the following Python packages:
 
-- **[numpy](https://pypi.org/project/numpy/)** - Required for Maya 2024
+- **[numpy](https://pypi.org/project/numpy/)** - Required for Maya 2024 and below
 
 > **Note:** Maya 2025+ includes numpy by default.
 

docs/faq.md

@@ -22,7 +22,7 @@
     **For Maya 2024**: Yes, you need to install numpy. **For Maya 2025+**: No additional dependencies are required as numpy is included by default. Please follow the complete guide in [Dependencies Installation](dependencies_installation.md) for installation instructions.
 
 ??? question "Where should I install the plugin files?"
-    The plugin should be installed in ApplicationPlugins directory. Detailed installation paths and instructions are provided in the [Plugin Installation](plugin_installation.md) guide.
+    Extract the downloaded zip and copy the contents of the `scripts` folder to your user-specific Maya `.../scripts` directory, and the contents of the `plug-ins` folder to the matching `.../plug-ins` directory (create it if it does not exist). Refer to the platform-specific steps in [Plugin Installation](plugin_installation.md) for exact paths on Windows, macOS, and Linux.
 
 ## Import Questions
 
@@ -125,11 +125,13 @@
 ??? question "My animations aren't playing correctly"
     Animation issues can often be resolved by:
 
-    1. Checking [Animation Settings](animation_settings.md) configuration - Ensure "Import Animations" is enabled
-    2. Enabling "Open Time Editor Window" in [Animation Settings](animation_settings.md) to automatically open the Time Editor after import for easier access to animation clips
-    3. Using [Show Animation Clips](show_animation_clips.md) to manage multiple animations - All clips are organized in Maya's Time Editor
-    4. Verifying timeline settings in Maya
-    5. Note: Transform-based animations work better than joint-based animations - Sketchfab assets with rigged animations may require preprocessing (see [Asset Compatibility and Workarounds](compatibility_and_workarounds.md))
+    1. Checking [Animation Settings](animation_settings.md) configuration — ensure "Import Animations" (and "Import Blendshape Animations" if needed) is enabled
+    2. Setting Maya's playback speed to **Real-time** in the Time Slider options so imported FPS is respected
+    3. Enabling "Open Time Editor Window" in [Animation Settings](animation_settings.md) to automatically open the Time Editor after import for easier access to animation clips
+    4. Using [Show Animation Clips](show_animation_clips.md) to manage multiple animations — all clips are organized in Maya's Time Editor
+    5. If you're on Maya 2023 or earlier and blendshape animations don't play, bake the clips via the Time Editor's **Bake** menu as described in the [Asset Compatibility and Workarounds](compatibility_and_workarounds.md#for-assets-with-animation-clips) guide
+    6. Verifying timeline settings in Maya
+    7. Note: Sketchfab assets with rigged animations may require preprocessing (see [Asset Compatibility and Workarounds](compatibility_and_workarounds.md))
 
 ## Advanced Usage
 
@@ -166,7 +168,15 @@
     Detailed technical information is available in the [Technical Details](technical_details.md) section, including programmatic import using MEL and Python commands with all available import options.
 
 ??? question "How do I report bugs or request features?"
-    Please refer to the project repository for information on reporting issues and requesting new features.
+    You can report bugs or request features through the [GitHub Issues page](https://github.com/parashivbrl/gltf-glb-importer-for-maya-docs/issues). When reporting issues, please include:
+    
+    1. Maya version and operating system
+    2. Asset source (Sketchfab, custom export, etc.)
+    3. File size and complexity details
+    4. Specific error messages or unexpected behavior
+    5. Sample files (when possible and appropriate)
+    6. Output logs from the Maya Script Editor
+    7. Steps to reproduce the issue
 
 ??? question "Are there example files I can use for testing?"
     The [Khronos glTF Sample Assets repository](https://github.com/KhronosGroup/glTF-Sample-Assets) provides official test assets that work well with the plugin. These are recommended for testing your installation and understanding the import process. Assets exported from Maya using Babylon exporter or from Blender using the built-in glTF 2.0 addon also work reliably.

docs/file_type_specific_options.md

@@ -20,13 +20,15 @@ The right side of the import dialog contains various import settings organized i
 - **No merging**: Discontinuous geometry along the UV boundary/seams (default option)
 - **Merge Vertices**: Combines duplicate vertices
 - **Import Skin Binding**: Imports skin binding data from the GLB/GLTF file (enabled by default)
+- **Import Blendshapes**: Imports blendshape targets from the GLB/GLTF file (enabled by default)
 
 ---
 
 ### Animation Settings
 
-- **Animation FPS**: Set the frame rate for imported animations (default: **"24 fps (Film)"**)
+- **Animation FPS**: Set the frame rate for imported animations (default: **"30 fps (NTSC)"**)
 - **Import Animations**: Creates Maya keyframes for translation, rotation, and scale animations
+- **Import Blendshape Animations**: Imports keyframes for blendshape weights (enabled by default)
 - **Open Time Editor Window**: Opens Time Editor window for animation playback and editing
 
 ---
@@ -35,7 +37,6 @@ The right side of the import dialog contains various import settings organized i
 
 - **Focus view on imported objects**: Automatically focuses the viewport camera on imported objects
 - **Animate framing**: Animates the camera framing to focus on imported objects
-- **Center view**: Centers the viewport view on imported objects
 
 ---
 

docs/geometry_options.md

@@ -9,17 +9,17 @@ Controls how geometry vertices are processed during import:
 **Merge Vertices**
 
 - Uses an algorithm to merge vertices automatically
-
 - Combines vertices that share the same position
-
 - Suitable for most static geometry imports
 
 **Import Skin Binding**
 
-- When disabled, skin binding data is ignored and geometry is imported without skeleton/deformation setup
-
-- Useful when you only need the static geometry without animation or deformation capabilities
+- When enabled (default), skin binding data is imported and applied to meshes that include skeleton/deformation data in the GLTF/GLB file
+- Required for animated, skinned, or deformable meshes to behave correctly in Maya
+- Disable if you only need static geometry without any skeleton-driven deformation, which can reduce scene complexity
 
-- When enabled (default), skin binding is imported and applied to geometry that has skeleton/deformation data in the GLTF/GLB file
+**Import Blendshapes**
 
-- Required for animated or skinned meshes to work correctly in Maya
+- When enabled (default), imports blendshape targets contained in the GLTF/GLB file
+- Needed for facial rigs or any deformation driven by blendshape weights
+- Disable if you only require static meshes or want to minimize scene data

docs/index.md

@@ -22,7 +22,7 @@ Easily bring .gltf and .glb assets into Maya, enabling you to work with modern 3
 ## Quick Start Guide
 
 1. **[Install Dependencies](dependencies_installation.md)** - Set up required Python packages
-2. **[Install Plugin](plugin_installation.md)** - Add the plugin to your **ApplicationPlugins** folder
+2. **[Install Plugin](plugin_installation.md)** - Copy the plugin files into your Maya documents plug-ins folder
 3. **[Import Files](importing_gltf_glb_file.md)** - Start importing glTF/glb content
 4. **[Configure Options](file_type_specific_options.md)** - Customize import settings
 

docs/limitations.md

@@ -8,53 +8,46 @@ While the glTF/GLB Importer for Maya successfully handles most files that adhere
 
 ---
 
-## Sketchfab Asset Import Issues
-
-Sketchfab assets, particularly those that are **automatically generated**, present specific challenges:
-
-### Hierarchical Structure Problems
-- **Different Node Hierarchy**: Sketchfab's auto-generated files follow a different hierarchical structure than standard glTF exporters
-- **Rigged Asset Import Issues**: Due to the non-standard hierarchy, rigged characters and animated objects may not import properly
-- **Bone/Joint Mapping**: The bone structure may not translate correctly to Maya's joint system
-
-### Orientation and Positioning Issues
-- **Incorrect Asset Orientation**: Even assets without animation data may be **incorrectly oriented** upon import
-- **Coordinate System Differences**: Sketchfab's coordinate system transformations may not align with Maya's expectations
-- **Scale Inconsistencies**: Assets may import at unexpected scales due to different unit interpretations
-
-### Animation-Specific Problems
-- **Joint-based Animations**: Assets with animations applied directly to joints often encounter import issues
-- **Skinning Data**: Vertex skinning information may not transfer correctly from Sketchfab's format
-- **Animation Curves**: Complex animation curves may be simplified or corrupted during the conversion process
-
----
-
 ## General Plugin Limitations
 
+### Geometry Processing
+- **Merge Vertices Side Effects**: When **Merge Vertices** is enabled during import, UVs can fail or distort because vertices that share the same position are de-duplicated, removing the seams needed to keep separate UV shells.
+### Blendshape Animations (Maya 2023 and below)
+- Blendshape targets and animation curves import, but in Maya 2023 and earlier they may not play back automatically.
+- Open the **Time Editor** and use the **Bake** menu options (e.g., *Bake to New Clip*, *Bake to Scene*, *Bake to Scene and Delete*, or *Flatten Layers*) to bake the clips back to standard curves so playback works.
+- Maya 2024+ plays the imported blendshape animation without baking.
+- For a detailed baking workflow, see **For Assets with Animation Clips** in the [Asset Compatibility and Workarounds guide](compatibility_and_workarounds.md#for-assets-with-animation-clips).
 ### File Format Constraints
 - **glTF Extensions**: Not all Khronos extensions are fully supported
 - **Vendor Extensions**: Limited support for vendor-specific extensions
-- **Binary Embedded Data**: Large embedded textures in GLB files may cause memory issues
 
 ### Maya Integration Limitations
-- **Scene Scale**: Very large or very small assets may not import with appropriate scale
 - **Viewport Performance**: Complex scenes with many materials may impact Maya's viewport performance
 
 ### Material and Texture Limitations
 - **Texture Format Support**: Some texture formats such as .webp and Compressed BasisU images may not be supported
 - **Material Complexity**: Advanced PBR features may not have direct Maya equivalents
-- **UV Mapping**: Complex UV layouts may not preserve perfectly
 
-### Animation and Rigging Constraints
-- **Morph Targets**: Blend shape/morph target support may be limited
-- **Complex Rigs**: Multi-layered rigging systems may not import completely
-- **Animation Sampling**: High-frequency animations may be resampled during import
+
+---
+
+## Sketchfab Asset Import Issues
+
+Sketchfab assets, particularly those that are **automatically generated**, present specific challenges:
+
+### Hierarchical Structure Problems
+- **Different Node Hierarchy**: Sketchfab's auto-generated files follow a different hierarchical structure than standard glTF exporters
+- **Rigged Asset Import Issues**: Due to the non-standard hierarchy, rigged characters and animated objects may not import properly
+
+### Animation-Specific Problems
+- **Skinning Data**: Vertex skinning information may not transfer correctly from Sketchfab's format
+- **Animation Curves**: Complex animation curves may be simplified or corrupted during the conversion process
 
 ---
 
 ## Reporting Issues
 
-If you encounter limitations not listed here, please provide:
+If you encounter limitations not listed here, please report them through the [GitHub Issues page](https://github.com/parashivbrl/gltf-glb-importer-for-maya-docs/issues) and provide:
 
 - Maya version and operating system