Michael Mainguy
bda0735c7f
Implemented a single button in the toolbox that cycles through four rendering modes: 1. Lightmap + Lighting - diffuseColor + lightmapTexture with lighting enabled 2. Emissive Texture - emissiveColor + emissiveTexture with lighting disabled (default) 3. Flat Color - emissiveColor only with lighting disabled 4. Diffuse + Lights - diffuseColor with two dynamic scene lights enabled Features: - Single clickable button displays current mode and cycles to next on click - Automatically manages two scene lights (HemisphericLight + PointLight) for Diffuse + Lights mode - UI materials (buttons, handles, labels) are excluded from mode changes to remain readable - Button positioned below color grid with user-adjusted scaling - Added comprehensive naming conventions documentation - Updated inspector hotkey to Ctrl+Shift+I 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
139 lines
4.3 KiB
Markdown
139 lines
4.3 KiB
Markdown
# 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:**
|
|
```typescript
|
|
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:**
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
// 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:**
|
|
```typescript
|
|
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
|