@holoscript/core 1.0.0-alpha.2 → 2.0.1

package/src/traits/LightingTrait.ts

@@ -0,0 +1,505 @@
+/**
+ * @holoscript/core Lighting Trait
+ *
+ * Enables dynamic lighting with support for multiple light types,
+ * shadows, and global illumination
+ */
+
+export type LightType = 'directional' | 'point' | 'spot' | 'area' | 'probe';
+export type ShadowType = 'none' | 'hard' | 'soft' | 'raytraced';
+
+/**
+ * Color definition
+ */
+export interface Color {
+  r: number;
+  g: number;
+  b: number;
+  a?: number;
+}
+
+/**
+ * Vector3 position or direction
+ */
+export interface Vector3 {
+  x: number;
+  y: number;
+  z: number;
+}
+
+/**
+ * Shadow configuration
+ */
+export interface ShadowConfig {
+  /** Shadow type */
+  type: ShadowType;
+  
+  /** Shadow map resolution */
+  resolution?: number;
+  
+  /** Shadow bias to prevent artifacts */
+  bias?: number;
+  
+  /** Softness/blur radius */
+  softness?: number;
+  
+  /** Max shadow distance */
+  maxDistance?: number;
+  
+  /** Cascade levels for directional lights */
+  cascades?: number;
+}
+
+/**
+ * Light source definition
+ */
+export interface LightSource {
+  /** Light type */
+  type: LightType;
+  
+  /** Light name */
+  name?: string;
+  
+  /** Position in world space */
+  position?: Vector3;
+  
+  /** Direction (for directional/spot) */
+  direction?: Vector3;
+  
+  /** Color */
+  color: Color;
+  
+  /** Intensity/brightness 0-1+ */
+  intensity: number;
+  
+  /** Attenuation range (point/spot) */
+  range?: number;
+  
+  /** Spot angle in degrees */
+  spotAngle?: number;
+  
+  /** Inner spot angle */
+  innerSpotAngle?: number;
+  
+  /** Shadow configuration */
+  shadow?: ShadowConfig;
+  
+  /** Light cookie/projection */
+  cookie?: string;
+  
+  /** Enable volumetric fog interaction */
+  volumetric?: boolean;
+  
+  /** Light priority for batching */
+  priority?: number;
+}
+
+/**
+ * Global illumination configuration
+ */
+export interface GlobalIlluminationConfig {
+  /** Enable global illumination */
+  enabled: boolean;
+  
+  /** Intensity multiplier */
+  intensity?: number;
+  
+  /** Sky color for ambient light */
+  skyColor?: Color;
+  
+  /** Sky intensity */
+  skyIntensity?: number;
+  
+  /** Ground color for ambient light */
+  groundColor?: Color;
+  
+  /** Ground intensity */
+  groundIntensity?: number;
+  
+  /** Use light probes */
+  probes?: boolean;
+  
+  /** Indirect diffuse intensity */
+  indirectDiffuse?: number;
+  
+  /** Indirect specular intensity */
+  indirectSpecular?: number;
+  
+  /** Ambient occlusion intensity */
+  aoIntensity?: number;
+  
+  /** Use screen-space AO */
+  screenSpaceAO?: boolean;
+}
+
+/**
+ * LightingTrait - Manages dynamic lighting and illumination
+ */
+export class LightingTrait {
+  private lights: Map<string, LightSource> = new Map();
+  private globalIllumination: GlobalIlluminationConfig;
+  private lightIdCounter: number = 0;
+
+  constructor(config?: GlobalIlluminationConfig) {
+    this.globalIllumination = {
+      enabled: true,
+      intensity: 1.0,
+      skyColor: { r: 0.5, g: 0.7, b: 1.0 },
+      skyIntensity: 1.0,
+      groundColor: { r: 0.4, g: 0.4, b: 0.4 },
+      groundIntensity: 0.5,
+      probes: true,
+      indirectDiffuse: 1.0,
+      indirectSpecular: 1.0,
+      aoIntensity: 1.0,
+      screenSpaceAO: true,
+      ...config,
+    };
+  }
+
+  /**
+   * Add a light to the scene
+   */
+  public addLight(light: LightSource): string {
+    const id = light.name || `light_${this.lightIdCounter++}`;
+    this.lights.set(id, light);
+    return id;
+  }
+
+  /**
+   * Get light by ID
+   */
+  public getLight(id: string): LightSource | undefined {
+    return this.lights.get(id);
+  }
+
+  /**
+   * Get all lights
+   */
+  public getLights(): LightSource[] {
+    return Array.from(this.lights.values());
+  }
+
+  /**
+   * Get lights by type
+   */
+  public getLightsByType(type: LightType): LightSource[] {
+    return Array.from(this.lights.values()).filter(l => l.type === type);
+  }
+
+  /**
+   * Update light properties
+   */
+  public updateLight(id: string, updates: Partial<LightSource>): boolean {
+    const light = this.lights.get(id);
+    if (!light) return false;
+    this.lights.set(id, { ...light, ...updates });
+    return true;
+  }
+
+  /**
+   * Remove light
+   */
+  public removeLight(id: string): boolean {
+    return this.lights.delete(id);
+  }
+
+  /**
+   * Clear all lights
+   */
+  public clearLights(): void {
+    this.lights.clear();
+  }
+
+  /**
+   * Get global illumination config
+   */
+  public getGlobalIllumination(): GlobalIlluminationConfig {
+    return { ...this.globalIllumination };
+  }
+
+  /**
+   * Update global illumination
+   */
+  public updateGlobalIllumination(
+    updates: Partial<GlobalIlluminationConfig>
+  ): void {
+    this.globalIllumination = {
+      ...this.globalIllumination,
+      ...updates,
+    };
+  }
+
+  /**
+   * Enable/disable GI
+   */
+  public setGIEnabled(enabled: boolean): void {
+    this.globalIllumination.enabled = enabled;
+  }
+
+  /**
+   * Set ambient light colors (skybox mode)
+   */
+  public setAmbientLight(
+    skyColor: Color,
+    groundColor: Color,
+    intensity: number = 1.0
+  ): void {
+    this.globalIllumination.skyColor = skyColor;
+    this.globalIllumination.groundColor = groundColor;
+    this.globalIllumination.skyIntensity = intensity;
+    this.globalIllumination.groundIntensity = intensity * 0.5;
+  }
+
+  /**
+   * Enable/disable screen-space ambient occlusion
+   */
+  public setScreenSpaceAO(enabled: boolean, intensity: number = 1.0): void {
+    this.globalIllumination.screenSpaceAO = enabled;
+    this.globalIllumination.aoIntensity = intensity;
+  }
+
+  /**
+   * Create directional light (sun)
+   */
+  public createDirectionalLight(
+    direction: Vector3,
+    color: Color,
+    intensity: number = 1.0,
+    castShadows: boolean = true
+  ): string {
+    const light: LightSource = {
+      type: 'directional',
+      name: `sun_${this.lightIdCounter}`,
+      direction,
+      color,
+      intensity,
+      shadow: castShadows
+        ? {
+            type: 'soft',
+            resolution: 2048,
+            cascades: 4,
+            softness: 1.0,
+          }
+        : undefined,
+      volumetric: true,
+      priority: 100,
+    };
+    return this.addLight(light);
+  }
+
+  /**
+   * Create point light
+   */
+  public createPointLight(
+    position: Vector3,
+    color: Color,
+    intensity: number,
+    range: number,
+    castShadows: boolean = false
+  ): string {
+    const light: LightSource = {
+      type: 'point',
+      name: `point_${this.lightIdCounter}`,
+      position,
+      color,
+      intensity,
+      range,
+      shadow: castShadows
+        ? {
+            type: 'soft',
+            resolution: 512,
+            softness: 0.5,
+          }
+        : undefined,
+      priority: 50,
+    };
+    return this.addLight(light);
+  }
+
+  /**
+   * Create spot light
+   */
+  public createSpotLight(
+    position: Vector3,
+    direction: Vector3,
+    color: Color,
+    intensity: number,
+    range: number,
+    spotAngle: number = 45,
+    castShadows: boolean = true
+  ): string {
+    const light: LightSource = {
+      type: 'spot',
+      name: `spot_${this.lightIdCounter}`,
+      position,
+      direction,
+      color,
+      intensity,
+      range,
+      spotAngle,
+      innerSpotAngle: spotAngle * 0.5,
+      shadow: castShadows
+        ? {
+            type: 'soft',
+            resolution: 1024,
+            softness: 0.8,
+          }
+        : undefined,
+      priority: 75,
+    };
+    return this.addLight(light);
+  }
+
+  /**
+   * Create area light for soft lighting
+   */
+  public createAreaLight(
+    position: Vector3,
+    color: Color,
+    intensity: number,
+    width: number,
+    height: number
+  ): string {
+    const light: LightSource = {
+      type: 'area',
+      name: `area_${this.lightIdCounter}`,
+      position,
+      color,
+      intensity,
+      range: Math.max(width, height) * 2,
+      priority: 25,
+    };
+    return this.addLight(light);
+  }
+
+  /**
+   * Get shadow-casting lights
+   */
+  public getShadowCastingLights(): LightSource[] {
+    return Array.from(this.lights.values()).filter(l => l.shadow && l.shadow.type !== 'none');
+  }
+
+  /**
+   * Get light count by type
+   */
+  public getLightCount(): { [key in LightType]: number } {
+    const counts = {
+      directional: 0,
+      point: 0,
+      spot: 0,
+      area: 0,
+      probe: 0,
+    };
+    for (const light of this.lights.values()) {
+      counts[light.type]++;
+    }
+    return counts;
+  }
+
+  /**
+   * Estimate light impact for performance optimization
+   */
+  public getPerformanceImpact(): {
+    totalLights: number;
+    shadowCasters: number;
+    estimatedGPUCost: 'low' | 'medium' | 'high';
+  } {
+    const totalLights = this.lights.size;
+    const shadowCasters = this.getShadowCastingLights().length;
+
+    let estimatedGPUCost: 'low' | 'medium' | 'high' = 'low';
+    if (totalLights > 16 || shadowCasters > 4) {
+      estimatedGPUCost = 'high';
+    } else if (totalLights > 8 || shadowCasters > 2) {
+      estimatedGPUCost = 'medium';
+    }
+
+    return {
+      totalLights,
+      shadowCasters,
+      estimatedGPUCost,
+    };
+  }
+
+  /**
+   * Get scene complexity info
+   */
+  public getSceneInfo(): string {
+    const counts = this.getLightCount();
+    const impact = this.getPerformanceImpact();
+    return `Lighting: ${counts.directional} dir, ${counts.point} point, ${counts.spot} spot | ` +
+           `Shadows: ${impact.shadowCasters} | GPU: ${impact.estimatedGPUCost}`;
+  }
+
+  /**
+   * Dispose and cleanup
+   */
+  public dispose(): void {
+    this.lights.clear();
+  }
+}
+
+/**
+ * HoloScript+ @lighting trait factory
+ */
+export function createLightingTrait(config?: GlobalIlluminationConfig): LightingTrait {
+  return new LightingTrait(config);
+}
+
+/**
+ * Preset lighting configurations
+ */
+export const LIGHTING_PRESETS = {
+  /** Neutral studio lighting */
+  studio: (): GlobalIlluminationConfig => ({
+    enabled: true,
+    intensity: 1.0,
+    skyColor: { r: 0.5, g: 0.5, b: 0.5 },
+    skyIntensity: 0.5,
+    groundColor: { r: 0.3, g: 0.3, b: 0.3 },
+    groundIntensity: 0.3,
+  }),
+
+  /** Bright outdoor lighting */
+  outdoor: (): GlobalIlluminationConfig => ({
+    enabled: true,
+    intensity: 1.2,
+    skyColor: { r: 0.7, g: 0.85, b: 1.0 },
+    skyIntensity: 1.0,
+    groundColor: { r: 0.4, g: 0.4, b: 0.35 },
+    groundIntensity: 0.6,
+    indirectDiffuse: 1.2,
+  }),
+
+  /** Dim interior lighting */
+  interior: (): GlobalIlluminationConfig => ({
+    enabled: true,
+    intensity: 0.6,
+    skyColor: { r: 0.3, g: 0.3, b: 0.35 },
+    skyIntensity: 0.4,
+    groundColor: { r: 0.2, g: 0.2, b: 0.2 },
+    groundIntensity: 0.2,
+  }),
+
+  /** Night scene */
+  night: (): GlobalIlluminationConfig => ({
+    enabled: true,
+    intensity: 0.3,
+    skyColor: { r: 0.01, g: 0.01, b: 0.02 },
+    skyIntensity: 0.1,
+    groundColor: { r: 0.02, g: 0.02, b: 0.02 },
+    groundIntensity: 0.05,
+    screenSpaceAO: false,
+  }),
+
+  /** Sunset/golden hour */
+  sunset: (): GlobalIlluminationConfig => ({
+    enabled: true,
+    intensity: 1.1,
+    skyColor: { r: 1.0, g: 0.7, b: 0.3 },
+    skyIntensity: 1.0,
+    groundColor: { r: 0.6, g: 0.4, b: 0.2 },
+    groundIntensity: 0.8,
+  }),
+};

package/src/traits/MaterialTrait.js

@@ -0,0 +1,194 @@
+/**
+ * @holoscript/core Material Trait
+ *
+ * Enables advanced material and shader properties for photorealistic rendering
+ * Supports PBR (Physically Based Rendering) workflows
+ */
+/**
+ * MaterialTrait - Enables photorealistic material rendering
+ */
+export class MaterialTrait {
+    constructor(config) {
+        this.textureCache = new Map();
+        this.material = {
+            type: 'pbr',
+            ...config,
+        };
+    }
+    /**
+     * Get material properties
+     */
+    getMaterial() {
+        return { ...this.material };
+    }
+    /**
+     * Update material property
+     */
+    setProperty(key, value) {
+        this.material[key] = value;
+    }
+    /**
+     * Get PBR properties
+     */
+    getPBRProperties() {
+        return this.material.pbr;
+    }
+    /**
+     * Update PBR material
+     */
+    updatePBR(pbr) {
+        if (!this.material.pbr) {
+            this.material.pbr = {
+                baseColor: { r: 1, g: 1, b: 1 },
+                metallic: 0,
+                roughness: 0.5,
+            };
+        }
+        this.material.pbr = { ...this.material.pbr, ...pbr };
+    }
+    /**
+     * Add texture map
+     */
+    addTexture(texture) {
+        if (!this.material.textures) {
+            this.material.textures = [];
+        }
+        this.material.textures.push(texture);
+    }
+    /**
+     * Get all textures
+     */
+    getTextures() {
+        return [...(this.material.textures || [])];
+    }
+    /**
+     * Clear texture cache (for memory optimization)
+     */
+    clearTextureCache() {
+        this.textureCache.clear();
+    }
+    /**
+     * Get shader code if custom
+     */
+    getCustomShader() {
+        return this.material.customShader;
+    }
+    /**
+     * Set custom shader
+     */
+    setCustomShader(shader) {
+        this.material.customShader = shader;
+    }
+    /**
+     * Get optimization hints
+     */
+    getOptimization() {
+        return this.material.optimization;
+    }
+    /**
+     * Enable/disable texture streaming
+     */
+    setTextureStreaming(enabled) {
+        if (!this.material.optimization) {
+            this.material.optimization = {};
+        }
+        this.material.optimization.streamTextures = enabled;
+    }
+    /**
+     * Set texture compression
+     */
+    setCompression(compression) {
+        if (!this.material.optimization) {
+            this.material.optimization = {};
+        }
+        this.material.optimization.compression = compression;
+    }
+    /**
+     * Enable material instancing for performance
+     */
+    setInstanced(instanced) {
+        if (!this.material.optimization) {
+            this.material.optimization = {};
+        }
+        this.material.optimization.instanced = instanced;
+    }
+    /**
+     * Dispose and cleanup
+     */
+    dispose() {
+        this.textureCache.clear();
+    }
+}
+/**
+ * HoloScript+ @material trait factory
+ */
+export function createMaterialTrait(config) {
+    return new MaterialTrait(config);
+}
+/**
+ * Preset materials for common use cases
+ */
+export const MATERIAL_PRESETS = {
+    /** Shiny metal */
+    chrome: () => ({
+        type: 'pbr',
+        pbr: {
+            baseColor: { r: 0.77, g: 0.77, b: 0.77 },
+            metallic: 1.0,
+            roughness: 0.1,
+        },
+    }),
+    /** Rough plastic */
+    plastic: () => ({
+        type: 'pbr',
+        pbr: {
+            baseColor: { r: 1, g: 1, b: 1 },
+            metallic: 0,
+            roughness: 0.8,
+        },
+    }),
+    /** Wood texture */
+    wood: () => ({
+        type: 'pbr',
+        pbr: {
+            baseColor: { r: 0.6, g: 0.4, b: 0.2 },
+            metallic: 0,
+            roughness: 0.4,
+        },
+    }),
+    /** Glass */
+    glass: () => ({
+        type: 'transparent',
+        blendMode: 'blend',
+        pbr: {
+            baseColor: { r: 1, g: 1, b: 1, a: 0.3 },
+            metallic: 0,
+            roughness: 0.0,
+            ior: 1.5,
+            transmission: 0.9,
+        },
+    }),
+    /** Emissive (glowing) */
+    emissive: () => ({
+        type: 'pbr',
+        pbr: {
+            baseColor: { r: 0, g: 1, b: 0 },
+            metallic: 0,
+            roughness: 1.0,
+            emission: {
+                color: { r: 0, g: 1, b: 0 },
+                intensity: 2.0,
+            },
+        },
+    }),
+    /** Skin material */
+    skin: () => ({
+        type: 'pbr',
+        pbr: {
+            baseColor: { r: 1, g: 0.8, b: 0.7 },
+            metallic: 0,
+            roughness: 0.5,
+            ambientOcclusion: 0.8,
+        },
+    }),
+};