Advanced Usage

Assembly Kit Conventions

The Assembly Spline Tool uses a “molecule” system where rigid meshes are connected together to form a single rigid unit. The molecule is built by placing the root mesh first, then adding other rigid meshes one by one to create a rigid assembly (a cluster of meshes which all stick together). The entire molecule can be rotated as one unit by rotating the root. Bridges are then used to connect one molecule to the next, allowing the assembly to populate along the spline. Understanding the naming conventions and anchor point standards is essential for creating functional assembly kits.

Core Architecture

The system creates complex assemblies by building rigid molecules and connecting them with bridges:

• Molecule: A rigid unit composed of multiple connected rigid meshes
• Rigid Meshes: Individual components within each molecule which form the structural backbone
• Bridge Meshes: Stretchable connector components which span between different molecules
• Root Mesh: The starting point for each molecule which controls the entire unit’s rotation
• Variations: Alternative versions of meshes for visual variety

File Naming Conventions

Required Filename Strings

Root Mesh

• Format: [name]_root.dae or root_[name].dae
• Example: ak_wood_pole_old_001_root.dae
• Purpose: Defines the primary mesh which serves as the starting point
• Fallback: If no root mesh is found, the first rigid mesh (by array index order) becomes the root

Bridge Meshes

• Format: [name]_bridge.dae or bridge_[name].dae
• Example: ak_wood_pole_old_001_bridge.dae
• Purpose: Connect consecutive rigid meshes in the assembly
• Requirements: Must have exactly 2 attachment points (source and target)
• Attachment Point Positioning: Source should be near the +X edge, target should be near the -X edge

Sag-Enabled Bridges

• Format: [name]_bridge_sag.dae or sag_[name]_bridge.dae
• Example: ak_wood_pole_old_001_bridge_sag.dae
• Purpose: Bridges which support vertical sag/deflection along the spline (telephone wires, cables, etc)
• Behavior: Automatically scales in Z-direction based on spline elevation changes
• Sag Factor: Applied as 1.0 + sag * 0.1 for vertical stretching

Variations

• Format: [baseName]_var_[variantName].dae
• Example: ak_wood_pole_old_001_var_damaged.dae
• Purpose: Alternative versions of base meshes for visual variety
• Behavior: Can be enabled/disabled individually, support random distribution
• Base Name Requirement: The base filename must be identical to the mesh it varies (e.g., ak_wood_pole_old_001.dae and ak_wood_pole_old_001_var_damaged.dae)

Rigid Meshes

• Format: [name].dae (any mesh without special identifiers)
• Example: ak_wood_pole_old_001.dae
• Purpose: Main structural components of the assembly
• Behavior: Placed sequentially along the spline path as part of the molecule

Anchor Point Naming Standards

Anchor Point Structure

• Format: nail.[joinName].[pointType].[aliasName]
• Examples:
  • nail.connection1.point.main
  • nail.connection1.head.primary
  • nail.connection1.aux.support

Point Types and Degrees of Freedom

1. Nail Joint (1 DOF) - Most Common (90% use case)

• Format: nail.[joinName].point + nail.[joinName].head
• Example: nail.connection1.point, nail.connection1.head
• Behavior: Allows rotation around the nail axis (head - point vector)
• Use Case: Hinged connections, rotating components, bridge connections
• Joining Requirement: The same join name must appear on both meshes to be joined, with corresponding anchor points

2. Fixed Joint (0 DOF)

• Format: nail.[joinName].point + nail.[joinName].head + nail.[joinName].aux
• Example: nail.connection1.point, nail.connection1.head, nail.connection1.aux
• Behavior: Completely rigid connection with no movement
• Use Case: Welded connections, solid structural joints
• Joining Requirement: The same join name must appear on both meshes to be joined, with corresponding anchor points

3. Ball Joint (3 DOF)

• Format: nail.[joinName].point only
• Example: nail.connection1.point
• Behavior: Full rotational freedom in all directions
• Use Case: Universal joints, flexible connections
• Joining Requirement: The same join name must appear on both meshes to be joined, with corresponding anchor points

Alias System

• Format: nail.[joinName].[pointType].[aliasName]
• Example: nail.connection1.point.main, nail.connection1.point.alternate
• Purpose: Multiple instances of the same join type with different names
• Behavior: Allows complex assemblies with multiple connection points
• Use Case: When a single mesh (e.g., bridge) needs to connect to multiple attachment points with the same join name, aliases distinguish between them
• UI Control: Each alias can be individually enabled/disabled in the interface

Mesh Distribution

The tool offers three distribution methods for placing assemblies along the spline:

Single Distribution

When only one component group is enabled, there is only one distribution possible - the same assembly is placed at every mesh placement position along the spline.

Round Robin Distribution

Cycles through available component groups in sequence, ensuring even distribution. This creates repeating patterns such as:

• Pole, wire, pole, wire for telephone infrastructure
• Post, board, post, board for fence assemblies
• Clean, dirty, clean, dirty for varied fence posts

The pattern repeats consistently from start to end of the spline.

Random Distribution

Uses weight sliders and a random seed for probabilistic placement:

• Weight Normalization: The weights of each component group’s weight slider are normalized to determine the probability of appearing
• Probability Calculation: Each component group gets a chance to appear based on its normalized weight
• Random Seed: The random seed ensures reproducible patterns - the same seed will always generate the same distribution
• Sequential Population: Assemblies are populated along the spline from start to end using the calculated probabilities

Example: With 3 component groups and weights of 0.8, 0.4, and 0.1:

• Component Group A (weight 0.8): ~62% chance, appears most frequently
• Component Group B (weight 0.4): ~31% chance, appears moderately
• Component Group C (weight 0.1): ~7% chance, appears rarely

In a spline with 100 mesh placement positions, you might see approximately 62 instances of Component Group A, 31 instances of Component Group B, and 7 instances of Component Group C, creating natural variation while maintaining the desired proportions.

Component Groups and Variations

In the Assembly Spline Tool, each component group has its own distribution choice:

• Component Groups: A base mesh and its variations form a group (e.g., fence posts)
• Variations: Meshes of the same type but with different appearances (e.g., clean, dirty, rotten fence posts)
• Artistic Variation: Allows for natural-looking assemblies with varied appearances while maintaining structural consistency

This method is ideal for creating natural, varied arrangements while maintaining artistic control through weights and ensuring consistency through the random seed. The random seed slider can be used to quickly audition different variations very quickly.

Jitter Controls

The Assembly Spline Tool includes tri-axial jitter controls (roll/pitch/yaw) for adding natural variation to assembly placement:

Jitter Workflow Approaches

Approach 1: Set Jitter Amplitude First

• Set Jitter Amplitude: Adjust the roll, pitch, and yaw sliders to set the overall amplitude of variation
• Fine-tune with Random Seed: Use the random seed slider to cycle through different variations without changing the amplitude
• Iterative Refinement: This approach allows the user to establish the “character” of the variation with the jitter sliders, then find the perfect variation using the random seed

Approach 2: Fix Random Seed First

• Set Random Seed: Choose a specific random seed value to lock in a particular variation pattern
• Adjust Individual Jitter: Fine-tune individual roll, pitch, or yaw sliders to achieve the desired effect
• Precise Control: Useful when the user wants to maintain a specific variation pattern while adjusting only certain aspects

Jitter Applications

• Small Values: Subtle natural variation for realistic placement
• Large Values: Dramatic variation for artistic or stylized effects
• Combined Approach: Mix different amplitudes across axes for complex variation patterns
• Selective Jitter: Use only specific axes (e.g., roll only) for targeted variation

Terraforming

The Assembly Spline Tool includes terraforming capabilities which automatically adjust the surrounding terrain to match the user’s spline design. This is useful for creating realistic infrastructure installations which properly integrate with the landscape.

How Terraforming Works

• Create and Edit the Spline: Design the spline with the desired elevation, banking, and width variations
• Access Terraforming Options: Go to the Terrain tab to find all terraforming controls
• Configure Parameters: Set the terraforming parameters to control how the terrain is modified
• Execute Terraforming: Click the “Terraform” button to perform the operation

Terraforming Parameters

Domain of Influence (DOI)

• Range: 0 to 500 meters
• Purpose: Defines how far away from the spline the terraforming operation will affect the terrain
• Usage: Larger values create wider terraforming areas, smaller values keep changes more localized

Terraform Margin

• Range: 1 to 20 meters
• Purpose: Creates a flat, smooth area around the spline edges before the terrain begins to fall off
• Behavior: The margin follows the plane of the spline, including banking and slope variations
• Effect: Ensures the immediate area around the spline has a clean, flat surface

Terraform Falloff

• Range: 1 to 5
• Purpose: Controls how quickly the modified terrain blends into the surrounding landscape
• Values:
  • 1: Very gradual, gentle blending
  • 3: Balanced falloff (recommended for most situations)
  • 5: Steep, abrupt blending for sharp terrain transitions

Noise Parameters

Noise Roughness

• Range: 0 to 1
• Purpose: Controls the amplitude of terrain variations (bump size)
• Usage:
  • 0: Smooth, clean terrain
  • 0.5: Moderate surface variation
  • 1: Maximum roughness with large bumps

Noise Scale

• Range: 0 to 1
• Purpose: Controls the frequency of terrain variations (bump density)
• Usage:
  • 0: Very fine, detailed surface texture
  • 0.5: Balanced surface detail
  • 1: Large, sparse surface variations

Note: The noise system automatically generates multiple layers of detail for natural-looking terrain variation.

Terraforming Process

• Terrain Analysis: The system analyzes the spline’s elevation, banking, and width
• Margin Creation: Creates a flat margin around the spline following the spline’s plane
• Falloff Application: Applies gradual terrain blending from the margin to the DOI boundary
• Noise Integration: Adds surface variations for realistic terrain appearance
• Final Blending: Smoothly integrates the modified terrain with the existing landscape

Performance Considerations

• Execution Time: Typically takes 2-7 seconds depending on spline length and DOI size
• Operation Type: Blocking operation - the interface will be unresponsive during execution
• Memory Usage: Larger DOI values require more memory for terrain calculations

Best Practices

• Iterative Workflow: Terraforming supports undo/redo, allowing the user to experiment and refine results
• Start with DOI: Begin by adjusting the Domain of Influence to get the overall terraforming area right
• Refine Margin: Once DOI is set, adjust the margin to ensure it doesn’t undercut the spline surface (this can happen with high falloff values)
• Margin Guidance: A margin value of 1m does not guarantee exactly 1m around the spline everywhere - it’s just a guide
• Add Detail: Finally, use noise parameters to add surface detail and variation
• Falloff Balance: Avoid values of 1 (too shallow) - 3-4 usually provides good results
• Noise Integration: Use noise for natural terrain features and realistic ground variation

Assembly Kit Creation

Creating functional assembly kits requires careful attention to file organization, naming conventions, and anchor point setup. The system automatically analyzes the kit structure and builds molecules based on the connections it finds.

Kit Folder Structure

Organize the assembly kit files in a dedicated folder:

• Mesh Files: All .dae files for the assembly components
• Naming Consistency: Follow the exact naming conventions for root, bridge, and variation meshes
• File Format: Use Collada (.dae) format only
• Anchor Points: Ensure all meshes have properly named and consistant anchor points

Assembly Construction Process

1. Molecule Building

• Root Selection: System identifies the root mesh by filename, or falls back to first rigid mesh
• Attachment Analysis: Parses all anchor points and determines join types automatically
• Connection Mapping: Maps bridge meshes to rigid mesh connections based on anchor point names
• Placement Order: Determines assembly sequence through connection analysis

2. Attachment Point Processing

• Boundary Correction: Moves bridge attachment points to mesh boundaries for proper alignment
• Alignment Calculation: Computes proper orientation for connections based on join types
• Join Validation: Ensures all connections are properly formed before assembly

3. Spline Population

• Molecule Placement: Places complete assemblies along the spline path
• Bridge Scaling: Automatically scales bridges in local X-axis to span between molecules
• Variation Selection: Chooses appropriate variations based on distribution settings
• Jitter Application: Adds controlled randomness to placements using jitter controls

Component Properties

Each component in the assembly kit has configurable properties:

Rigid Meshes

• isRandom: Choose between round-robin vs random placement
• randomWeight: Probability weight (0.0 to 1.0) for random selection
• isEnabled: Whether the component is active in the assembly

Bridge Meshes

• isRandom: Distribution mode for bridge placement
• randomWeight: Selection probability for random distribution
• isSag: Whether sag is supported (requires _sag in filename)

Variations

• isRandom: Distribution mode for variation selection
• randomWeight: Individual random weights for fine-tuned control
• isEnabled: Whether the variation is active

Assembly Kit Troubleshooting

The Assembly Spline Tool includes a robust validation system which ensures assembly kits are properly constructed. When validation fails, the system provides some technical information in the console for debugging.

Validation System Overview

The system prioritizes robustness:

• Fast Failure: Validation failures result in immediate build failure
• Console Logging: All validation issues use warning level ('W') logging
• Technical Details: Error information is written to console
• Silent Fallbacks: Automatic fallbacks may happen, with console warnings

Required Validations

Join Completeness

• Requirement: All join points must have matching counterparts on other meshes
• Validation: System checks for complete join pairs before assembly
• Failure: Entire molecule build fails if joins are incomplete

Bridge Connectivity

• Requirement: Bridges must connect exactly two rigid meshes (can be different rigid meshes in the molecule)
• Validation: Source and target join count must be equal
• Failure: Build fails with specific error message

Attachment Points

• Requirement: Valid anchor point naming and positioning
• Validation: All anchor points must follow nail.[joinName].[pointType].[aliasName] format (aliasName is optional)
• Failure: Invalid naming causes build failure

Common Error Cases

Missing Root Mesh

• Symptom: No mesh with root in filename
• Behavior: System automatically uses first rigid mesh (by array index order)
• Notification: Silent fallback with console warning
• Action: Check console for warning message

Invalid Joins

• Symptom: Malformed anchor point names or incomplete join pairs
• Behavior: Logs warnings for malformed anchor points
• Notification: Console warnings only
• Action: Review anchor point naming conventions

Unconnected Meshes

• Symptom: Meshes with anchor points which don’t connect to anything
• Behavior: Entire molecule build fails
• Notification: Console error message
• Action: Ensure all meshes have proper connections

Bridge Mismatch

• Symptom: Bridges with incorrect number of attachment points
• Behavior: Build fails with specific error message
• Notification: Console error message
• Action: Verify bridges have exactly 2 attachment points

Debugging Workflow

1. Check Console Output

• Location: All validation errors use log('W', logtag, ...) format
• Content: Detailed technical information about validation failures
• Level: Warning level, not error level

2. Verify File Naming

• Root Mesh: Ensure one mesh has root in filename
• Bridge Meshes: Verify bridge naming and sag variants
• Variations: Check var naming convention for any variations

3. Validate Anchor Points

• Format: Confirm nail.[joinName].[pointType].[aliasName] structure (aliasName is optional)
• Completeness: Ensure all joins have required anchor points
• Connections: Verify anchor points connect properly between meshes

4. Test Incrementally

• Start Simple: Begin with basic rigid mesh connections, introducing joins onw by one
• Add Complexity: Gradually add bridges and variations
• Validate Each Step: Check console after each addition

Best Practices for Kit Creation

• Plan Connections: Design the assembly structure before creating meshes
• Follow Conventions: Use exact naming conventions for all components
• Test Early: Validate basic connections before adding complexity
• Monitor Console: Check console output for warnings and errors
• Use Examples: Reference working kits for naming and structure guidance