immersive2/docs/NAMING_CONVENTIONS.md

Naming Conventions

Tool and Material Naming

This document describes the naming conventions used for tools, materials, and related entities in the immersive WebXR application.

Material Naming

Materials follow a consistent naming pattern based on their color:

Format: material-{color}

Where:

• {color} is the hex string representation of the material's color (e.g., #ff0000 for red)

Examples:

• material-#ff0000 - Red material
• material-#00ff00 - Green material
• material-#222222 - Dark gray material

Implementation:

const material = new StandardMaterial("material-" + color.toHexString(), scene);

Location: Materials are created in:

• src/toolbox/functions/buildColor.ts - For toolbox color swatches
• src/diagram/functions/buildMeshFromDiagramEntity.ts - Fallback material creation via buildMissingMaterial()

Tool Mesh Naming

Tool meshes use a compound naming pattern that includes both the tool type and color:

Format: tool-{toolId}

Where:

• {toolId} = {toolType}-{color}
• {toolType} is a value from the ToolType enum (e.g., BOX, SPHERE, CYLINDER, CONE, PLANE, PERSON)
• {color} is the hex string representation of the tool's color

Examples:

• tool-BOX-#ff0000 - Red box tool
• tool-SPHERE-#00ff00 - Green sphere tool
• tool-CYLINDER-#0000ff - Blue cylinder tool
• tool-PLANE-#ffff00 - Yellow plane tool

Implementation:

function toolId(tool: ToolType, color: Color3) {
    return tool + "-" + color.toHexString();
}

const newItem = await buildMesh(tool, `tool-${id}`, colorParent.getScene());
// For example: `tool-BOX-#ff0000`

Location: Tool meshes are created in src/toolbox/functions/buildTool.ts

Tool Colors

The application uses 16 predefined colors for the toolbox:

const colors: string[] = [
    "#222222", "#8b4513", "#006400", "#778899",  // Row 1: Dark gray, Brown, Dark green, Light slate gray
    "#4b0082", "#ff0000", "#ffa500", "#ffff00",  // Row 2: Indigo, Red, Orange, Yellow
    "#00ff00", "#00ffff", "#0000ff", "#ff00ff",  // Row 3: Green, Cyan, Blue, Magenta
    "#1e90ff", "#98fb98", "#ffe4b5", "#ff69b4"   // Row 4: Dodger blue, Pale green, Moccasin, Hot pink
]

Tool Types

Available tool types from the ToolType enum:

• BOX - Cube mesh
• SPHERE - Sphere mesh
• CYLINDER - Cylinder mesh
• CONE - Cone mesh
• PLANE - Flat plane mesh
• PERSON - Person/avatar mesh

Material Color Access

When accessing material colors, use this priority order to handle both current and legacy materials:

// For StandardMaterial
const stdMat = material as StandardMaterial;
const materialColor = stdMat.emissiveColor || stdMat.diffuseColor;

// Current rendering uses emissiveColor
// Legacy materials may have diffuseColor instead

Rendering Modes

Materials can be rendered in three different modes, affecting how color properties are used:

1. Lightmap with Lighting

• Uses diffuseColor + lightmapTexture
• disableLighting = false
• Most expensive performance-wise
• Provides lighting illusion with actual lighting calculations

2. Unlit with Emissive Texture (Default)

• Uses emissiveColor + emissiveTexture (lightmap)
• disableLighting = true
• Best balance of visual quality and performance
• Provides lighting illusion without lighting calculations

3. Flat Emissive

• Uses only emissiveColor
• disableLighting = true
• Best performance
• No lighting illusion, flat shading

Instance Naming

Instanced meshes (created from tool templates) follow this pattern:

Format: tool-instance-{toolId}

Example:

const instance = new InstancedMesh("tool-instance-" + id, newItem);
// For example: `tool-instance-BOX-#ff0000`

These instances share materials with their source mesh and are used for visual feedback before creating actual diagram entities.

Related Files

• src/toolbox/functions/buildTool.ts - Tool mesh creation and naming
• src/toolbox/functions/buildColor.ts - Material creation and color management
• src/diagram/functions/buildMeshFromDiagramEntity.ts - Diagram entity instantiation
• src/toolbox/types/toolType.ts - ToolType enum definition
• src/util/lightmapGenerator.ts - Lightmap texture generation and caching
• src/util/renderingMode.ts - Rendering mode enum and labels