[Ken] Design Version

Design Versions represent specific configurations or states of a Design Family. Each version contains 3D geometry (meshes) and material elements that make up the visual representation of the design.

What is a Design Version?

A Design Version is a specific configuration within a Design Family that includes:

• 3D Geometry - Associated to actual 3D mesh assets
• Material Elements - Associated to actual material assets
• Version State - Active version is the one that is currently available for use
• Debug mode - Version is in debug mode if it is not available for use in the catalog
• Material default configuration - These version will be used as the default material configuration while spawning the item without any default material configuration in a room
• Revision number - The revision number is the version number of the design version, it will increase when the meshes or materials are updated
• Chunk System - The chunk ID and chunk size of the design version

At the moment, only one active version is allowed per Design Family.

Attributes & Metadata

Design Versions contain metadata that controls their availability, asset management, and default material configurations.

Core Identification

Basic identifiers for the Design Version:

Example:

• id: a40OQ000001Q78XYAS
• name: "0.0"
• design_family_id: a4fOQ000000g8yrYAA (MALAGA Design Family)

Version State

Controls the availability and usage of this version:

Active Version Behavior:

• ✅ Only one active version allowed per Design Family at a time
• ✅ Active version is used when placing items in rooms
• ✅ Appears in catalog and search results

Debug Mode:

• 🔧 debug: true → Version only visible in debug/development mode
• 🔧 debug: false → Version available in production

Version State Scenarios:

Chunk System

Asset packaging and delivery management:

Purpose:

The chunk system optimizes asset delivery by:

• Grouping related assets together
• Enabling progressive loading
• Supporting delta updates
• Managing bandwidth efficiently

How It Works:

1. Chunk ID: Groups assets into downloadable packages

   • Example: chunk_id: 1234 → All meshes and materials in chunk 1234

2. Chunk Size: Tracks total asset size

   • Used for download progress indicators
   • Helps estimate bandwidth requirements
   • Example: chunk_size: 52428800 (50MB)

3. Revision Count: Tracks version updates

   • Increments when meshes or materials are updated
   • Triggers by Salesforce
   • Example: revision_count: 5 (5th revision)

Default Material Configuration

Flags indicating which default materials this version provides:

Purpose:

These flags determine which material configuration is used when spawning an item in a room without explicit material selection. When a Design Version doesn’t have a specific default material flag set to true, the system looks up other Design Versions within the same Design Family that have that flag enabled and uses their materials as defaults.

Example: Sofa with Material Lookup

Consider a Design Family “MODULAR SOFA” with two versions:

Version A: Base Configuration

Design Version A (id: a40OQ000001Q78XYAS)
├── default_fabric: false     ← No default fabric configured
├── default_wood: true         ← Has default wood for legs
├── default_leather: false
└── Design Version Elements:
    ├── Oak Natural (wood)
    └── Walnut Dark (wood)

Version B: Material Library

Design Version B (id: a40OQ000001Q78XYZB)
├── default_fabric: true       ← Provides default fabrics
├── default_wood: false
├── default_leather: false
└── Design Version Elements:
    ├── Beige Linen (fabric)
    ├── Gray Velvet (fabric)
    └── Navy Cotton (fabric)

Material Application Flow:

When spawning the sofa from Version A:

1. Legs: Version A has default_wood: true

   • ✅ Uses materials from Version A’s elements
   • Applies “Oak Natural” to the legs

2. Seat Cushions: Version A has default_fabric: false

   • 🔍 System looks up Design Versions with default_fabric: true
   • ✅ Finds Version B
   • Fetches materials from Version B’s elements
   • Applies “Beige Linen” (first fabric) to the seat cushions

Configuration Scenarios:

Single Version with All Defaults:

Design Version: Complete Configuration
├── default_fabric: true
├── default_wood: true
├── default_leather: false
└── default_metal: false

Result: All materials come from this version

Split Configuration (Material Lookup):

Design Version 1: Geometry Variant
├── default_fabric: false      → Looks up Version 2
├── default_wood: true          → Uses own materials
└── default_metal: false

Design Version 2: Material Library
├── default_fabric: true        → Provides fabrics for Version 1
├── default_wood: false
└── default_leather: true       → Provides leather options

Result: Version 1 uses Version 2's fabrics, own wood materials

Relationships

Links to associated assets:

Data Structure:

Design Version (a4010000000k3QLAAY)
├── Design Family (a4f100000000EvJAAU)
│   └── name: "DANISH SOFA"
│
├── Design Version Meshes []
│   ├── Mesh 1: 3 SEATER 180
│   ├── Mesh 2: 2 Seater 160
│   └── ...
│
└── Design Version Elements []
    ├── Element 1: Black Cherry
    ├── Element 2: Red Oak
    ├── Element 3: White Oak Light
    └── Element 4: Walnut

System Metadata

Audit trail and system information:

Uses:

• Track version lifecycle
• Cache invalidation triggers
• Sync with asset pipeline
• Audit logging

Version Lifecycle

Understanding how versions evolve over time:

Creating a New Version

1. Initial Creation

   • active: false, debug: true
   • Assets uploaded to chunk
   • revision_count: 1

2. Testing Phase

   • active: true, debug: true
   • Available to developers for testing
   • Material defaults configured

3. Production Release

   • Previous active version set to active: false
   • New version set to active: true, debug: false
   • Design Family’s released_on_production flag is set to true, if it is not set, the design family will not be shown in the catalog
   • Now available to all users

Updating a Version

When meshes or materials are updated:

1. Revision Increment

   • revision_count increases (e.g., 5 → 6)
   • updated_at timestamp updates
   • Revision count file is updated by trigger manually or trigger at 0h UTC automatically

2. Chunk Update

   • New assets uploaded to same chunk_id
   • chunk_size may change if assets grow/shrink

3. Cache Invalidation

   • Apps detect revision_count change
   • Re-download updated assets
   • Clear cached versions

Related Pages

Core Resources

• Design Family - Parent concept overview
• Category - Resource organization

Application Usage

• Items - Configurable - Working with configurable items
• Materials - Application - Applying materials
• Custom Items - Importing your own items

Technical Details

• 3D Model Import - Importing custom 3D models
• Performance Optimization - Asset optimization guide
• System Requirements - Hardware requirements