Troubleshooting

This section covers common issues and their solutions when working with the Assembly Spline Tool.

Kit Assembly Failures

Kit components not joining together

Problem: Assembly kits fail to construct properly or components don’t connect.

Cause: Kit validation rules not met or mesh problems.

Solution:

• Check the console for warnings or error messages
• Review the logs for specific validation failures
• Familiarize yourself with the kit rules (documented in the kit documentation section)
• Verify that all required components are present and properly named
• Check that anchor points are correctly positioned

Anchor Point Issues

Can’t find anchor points or connection points

Problem: Anchor points are missing or not visible.

Cause: Anchor points not properly named or positioned in the mesh.

Solution:

• Check the console for warnings about missing anchor points
• Verify anchor point naming conventions are followed
• Ensure anchor points are properly positioned in the source mesh
• Check that the mesh file contains the expected anchor point structure
• Review the kit documentation for specific anchor point requirements

COLLADA Import Problems

COLLADA (.dae) files won’t load

Problem: Mesh files fail to import or display incorrectly.

Cause: File corruption, unsupported features, or format issues.

Solution:

• Check the mesh file for corruption
• Verify the file is a valid COLLADA (.dae) format
• Look for geometry issues in Blender or other 3D software
• Check console for import warnings or errors
• Ensure mesh bounding box accurately represents the geometry
• This issue can also affect Mesh Spline Tool - check both tools

Molecule Spacing Issues

Molecules too close or far apart

Problem: Placement units are not properly spaced along the spline.

Cause: Spacing settings incorrect or component conflicts.

Solution:

• Adjust the spacing slider in the tool window
• Check that molecules are properly configured
• Verify that the main component is correctly identified
• Reorder components in the list if necessary

Last molecule extends past the final node

Problem: The final molecule in the spline extends beyond the last node.

Cause: Fixed-size molecules (TSStatics) don’t always divide evenly into the spline length, leaving a remainder.

Solution:

• This is normal behavior with fixed-size molecules
• The tool places molecules based on spacing, not exact spline length
• Adjust the spline length by moving the last node to better accommodate the molecule size
• Consider adjusting the spacing to minimize the remainder
• Use appropriate end caps or adjust the final molecule position manually

Bridge Component Problems

Bridge components not connecting between molecules

Problem: Spans between molecules are broken or not visible.

Cause: Molecule building issues or bridge components disabled.

Solution:

• Check the console for warnings or errors during molecule building
• Verify that bridge meshes are enabled in the components section
• Check that bridge components are properly configured
• Look for mesh problems that might prevent proper connections
• Ensure molecules are properly spaced for bridge components to work

Bridge Component Orientation Issues

Bridge components appear in wrong places or overlap

Problem: Bridge components start/end in incorrect positions, overlap, or look like artifacts.

Cause: Incorrect prerotation settings for the molecules.

Solution:

• Ensure the appropriate prerotation is selected with the radio button on the tool window
• Check that molecules are oriented correctly before bridge components are applied
• Verify that the prerotation matches the actual orientation of the source meshes

Mesh Quality Issues

Assembly components not displaying correctly

Problem: Kit components have visual artifacts or don’t render properly.

Cause: Mesh file problems or unsupported features.

Solution:

• Check the mesh file for corruption
• Verify the mesh is in a supported format
• Look for geometry issues in Blender or other 3D software
• Check console for import warnings or errors
• Ensure mesh bounding box accurately represents the geometry

Performance Issues

Tool becomes slow with complex assemblies

Problem: Tool becomes unresponsive when working with complex kits.

Cause: Too many components or very long splines.

Solution:

• Reduce the number of components in the assembly
• Break long splines into shorter segments
• Simplify complex kit geometries
• Reduce the number of different component types

Spline Visibility Issues

Assembly spline disappears

Problem: Spline becomes invisible or can’t be found.

Cause: Spline may be underground, off-screen, or have color/lighting conflicts.

Solution:

• Use the “Go To Spline” button to locate and focus on the spline
• Check if the spline is underground or positioned off-screen
• Adjust lighting or color settings if there are visibility conflicts

Session Management

Assembly splines disappear between sessions

Problem: Work is lost when restarting the tool.

Cause: Splines are designed not to persist between sessions by default.

Solution:

• Use the round-trip recovery system to import existing splines
• Select assembly objects in the scene tree to estimate spline parameters
• The tool can recover splines from scene meshes automatically

Kit Validation

Kit validation warnings or errors

Problem: Console shows validation failures or warnings.

Cause: Kit rules not followed or component configuration issues.

Solution:

• Read all console messages carefully
• Check the kit documentation for specific rules
• Verify component naming conventions
• Ensure all required components are present
• Check anchor point positioning and naming

When to Report Bugs

If you encounter any of these issues, they may indicate a bug:

• Tool window freezing without performance cause
• Kit validation completely failing without clear errors
• Undo/redo history not working properly
• File corruption or unreadable data

Recommendation: Reload the tool and try again. If the problem persists, check the console for error messages and report the issue with specific steps to reproduce.