simple-circuit-engine 0.0.11 → 0.0.13

package/dist/scene/shared/utils/GeometryUtils.d.ts

@@ -0,0 +1,337 @@
+import { Position, Rotation } from '../../../core/index.ts';
+import { ExtrudeGeometry } from 'three';
+/**
+ * Geometry Utilities
+ * @module scene/shared/utils/GeometryUtils
+ *
+ * Helper functions for creating Three.js geometries for grid and circuit elements
+ */
+import * as THREE from 'three';
+/**
+ * convenience to control standard rotations of meshes on X-Z plan
+ */
+export type Direction2D = 'right' | 'bottom' | 'left' | 'top';
+/**
+ * Create a grid helper for the scene
+ *
+ * @param size - Size of the grid
+ * @param divisions - Number of grid divisions
+ * @param colorCenterLine - Color for center lines
+ * @param colorGrid - Color for grid lines
+ * @returns GridHelper object
+ */
+export declare function createGridHelper(size: number, divisions: number, colorCenterLine: number, colorGrid: number): THREE.GridHelper;
+/**
+ * optimal number of grid divisions for a given size
+ * @param size
+ */
+export declare function computeDivisionsForSize(size: number): number;
+/**
+ * Components, branching points and wires intermediate points snap to the nearest integer grid point.
+ * @param position
+ * @constructor
+ */
+export declare function nearestWorldSnapPosition(position: THREE.Vector3): THREE.Vector3;
+/**
+ * Converts a world 3D position to the snapped 2D model grid position.
+ * @param position
+ * @constructor
+ */
+export declare function worldToGridPosition(position: THREE.Vector3): Position;
+/**
+ * Converts a model grid 2D position to the world 3D position.
+ * @param position
+ * @constructor
+ */
+export declare function gridToWorldPosition(position: Position): THREE.Vector3;
+/**
+ * Converts a world 3D rotation to the model grid 2D rotation.
+ * @param rotation
+ * @constructor
+ */
+export declare function worldToGridRotation(rotation: THREE.Euler): Rotation;
+/**
+ * Converts model grid 2D rotation to the world 3D rotation.
+ * @param rotation
+ * @constructor
+ */
+export declare function gridToWorldRotation(rotation: Rotation): THREE.Euler;
+/**
+ * Get the bounding box of a Three.js object in world space
+ *
+ * @param object - The Three.js object to get bounds for
+ * @returns Box3 representing the world-space bounding box
+ */
+export declare function getObjectBoundingBox(object: THREE.Object3D): THREE.Box3;
+/**
+ * Project a 3D world position to 2D screen coordinates
+ *
+ * @param worldPosition - Position in world space
+ * @param camera - Camera to use for projection
+ * @param width - Viewport width in pixels
+ * @param height - Viewport height in pixels
+ * @returns Screen coordinates {x, y} where (0,0) is top-left
+ */
+export declare function worldToScreenPosition(worldPosition: THREE.Vector3, camera: THREE.Camera, width: number, height: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Check if a 3D point (projected to screen space) is inside a 2D screen rectangle
+ *
+ * @param worldPosition - Position in world space
+ * @param camera - Camera to use for projection
+ * @param width - Viewport width in pixels
+ * @param height - Viewport height in pixels
+ * @param rect - Screen rectangle with min/max coordinates
+ * @returns true if the projected point is inside the rectangle
+ */
+export declare function isPointInScreenRect(worldPosition: THREE.Vector3, camera: THREE.Camera, width: number, height: number, rect: {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}): boolean;
+/**
+ * Check if an object's center point is inside a screen rectangle
+ * Used for rectangle selection of components and branching points
+ *
+ * @param object - The Three.js object to check
+ * @param camera - Camera to use for projection
+ * @param width - Viewport width in pixels
+ * @param height - Viewport height in pixels
+ * @param rect - Screen rectangle with min/max coordinates
+ * @returns true if object's center is inside the rectangle
+ */
+export declare function isObjectInScreenRect(object: THREE.Object3D, camera: THREE.Camera, width: number, height: number, rect: {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}): boolean;
+/**
+ * Create a ring geometry with given inner/outer radius and depth (y axis)
+ * @param innerRadius
+ * @param outerRadius
+ * @param depth
+ * @param steps
+ * @constructor
+ */
+export declare function RingGeometry(innerRadius: number, outerRadius: number, depth: number, steps: number): ExtrudeGeometry;
+/**
+ * Create an ExtrudeGeometry for the body of an AND gate.
+ * Shape is centered at origin: flat side on the left, semicircle on the right,
+ * matching the standard logic gate schematic representation.
+ * Handles both standard (width > height / 2) and tall (width ≤ height / 2) proportions.
+ *
+ * Input pins attach on the left flat side (x = -width/2).
+ * Output pin attaches at the rightmost point of the arc (x = +width/2).
+ *
+ * The thickness parameter controls a visual state trick:
+ * - LOW state:         thin thickness → gate appears as an empty shell
+ * - HIGH state:        thick thickness → gate appears filled
+ * - TRANSITIONING:     medium thickness → gate appears half-filled
+ *
+ * @param width     - Total width, from left flat edge to rightmost arc point
+ * @param height    - Total height; also determines the arc radius (= height / 2)
+ * @param thickness - Wall thickness of the gate shell
+ * @param depth     - Extrusion depth
+ * @param steps     - Number of extrusion steps
+ * @constructor
+ */
+export declare function AndGateGeometry(width: number, height: number, thickness: number, depth: number, steps?: number): ExtrudeGeometry;
+/**
+ * Create an ExtrudeGeometry for the inner hole of an AND gate body.
+ * Returns null when thickness is large enough that the gate has no hole.
+ * Handles both standard (width > height / 2) and tall (width ≤ height / 2) proportions.
+ *
+ * @param width     - Total width, from left flat edge to rightmost arc point
+ * @param height    - Total height
+ * @param thickness - Wall thickness of the gate shell
+ * @param depth     - Extrusion depth
+ * @param steps     - Number of extrusion steps
+ */
+export declare function AndGateHoleGeometry(width: number, height: number, thickness: number, depth: number, steps?: number): ExtrudeGeometry | null;
+/**
+ * Create an ExtrudeGeometry for the body of an OR gate.
+ * Same structure as AndGateGeometry but the left side is a concave arc (curves inward)
+ * instead of a flat edge, matching the standard logic gate schematic representation.
+ * Handles both standard (width > height / 2) and tall (width ≤ height / 2) proportions.
+ *
+ * Input pins attach on the left curved side (nominally at x = -width/2).
+ * Output pin attaches at the rightmost point of the right arc (x = +width/2).
+ *
+ * The thickness parameter controls the same visual state trick as AndGateGeometry:
+ * - LOW state:         thin thickness → gate appears as an empty shell
+ * - HIGH state:        thick thickness → gate appears filled
+ * - TRANSITIONING:     medium thickness → gate appears half-filled
+ *
+ * Back arc geometry: the concave left side bows inward (rightward) by backInset = halfH * 0.4.
+ * The arc center sits far to the left; u_b is its x-distance to the back-left corners.
+ * The inner hole back arc is concentric with the outer (same center, radius += 0.1), giving a
+ * truly constant perpendicular wall thickness of 0.1 along the entire back curve, independent
+ * of the thickness parameter.
+ *
+ * @param width     - Total width, from leftmost back curve point to rightmost arc point
+ * @param height    - Total height; also determines the right arc radius (= height / 2)
+ * @param thickness - Wall thickness of the gate shell
+ * @param depth     - Extrusion depth
+ * @param steps     - Number of extrusion steps
+ * @constructor
+ */
+export declare function OrGateGeometry(width: number, height: number, thickness: number, depth: number, steps?: number): ExtrudeGeometry;
+/**
+ * Create an ExtrudeGeometry for the inner hole of an OR gate body.
+ * Returns null when thickness is large enough that the gate has no hole.
+ * Handles both standard (width > height / 2) and tall (width ≤ height / 2) proportions.
+ *
+ * @param width     - Total width
+ * @param height    - Total height
+ * @param thickness - Wall thickness of the gate shell
+ * @param depth     - Extrusion depth
+ * @param steps     - Number of extrusion steps
+ */
+export declare function OrGateHoleGeometry(width: number, height: number, thickness: number, depth: number, steps?: number): ExtrudeGeometry | null;
+/**
+ * Create an ExtrudeGeometry for the XOR gate tail — the distinctive extra curved bar
+ * placed to the left of an OrGateGeometry body to form the full XOR gate symbol.
+ *
+ * Back-arc parameters (backInset, u_b, cx_b, r_b, angle_b) are identical to those in
+ * OrGateGeometry so this geometry aligns correctly when placed at the same centre.
+ *
+ * Note: the tail arc's centre is shifted left by tailWidth (radius stays constant = r_b), so
+ * the tail always spans the full gate height regardless of tailWidth.
+ * For bars to be visible, barsSeparation must be less than orHeight − 2 × thickness.
+ *
+ * @param orWidth        - Width of the paired OR gate body
+ * @param orHeight       - Height of the paired OR gate body
+ * @param tailWidth      - How far left the tail arc's corners are from the OR gate's left corners
+ * @param thickness      - Wall thickness of the arc shell AND height of each bar
+ * @param barsSeparation - Vertical gap between the two bars (centred on y = 0)
+ * @param depth          - Extrusion depth
+ * @param steps          - Number of extrusion steps
+ */
+export declare function XorGateTailGeometry(orWidth: number, orHeight: number, tailWidth: number, thickness: number, barsSeparation: number, depth: number, steps?: number): ExtrudeGeometry;
+/**
+ * Create an ExtrudeGeometry shaped like an L (or mirrored L) with a configurable
+ * angle between the two arms.
+ *
+ * Default orientation (`invert = false`) produces a `|_`-like shape:
+ *   base arm extends to the right, stem arm extends upward at the given angle.
+ * When `invert = true` the shape is mirrored horizontally (`_|`-like):
+ *   base arm extends to the left, stem arm mirrors accordingly.
+ *
+ * The `angle` parameter (in degrees) controls the inner angle between the two arms:
+ *   - 90°  → standard right-angle L
+ *   - 120° → obtuse junction (`\_`-like)
+ *   - 60°  → acute junction
+ *
+ * Both the inner (concave) and outer (convex) junction corners are rounded
+ * equally with `junctionRadius` (similar to CSS border-radius).
+ * When 0 both corners are sharp. The arc sweep adapts to the angle: (180° − angle).
+ *
+ * The geometry is centered on its bounding box.
+ *
+ * At 90°, `width` and `height` correspond exactly to the bounding box dimensions.
+ * At other angles the bounding box changes but the arm lengths remain consistent:
+ * base inner arm = width − thickness, stem inner arm = height − thickness.
+ *
+ * @param width           - Base arm length (bounding-box width at 90°)
+ * @param height          - Stem arm length (bounding-box height at 90°)
+ * @param thickness       - Arm thickness of the L
+ * @param angle           - Inner angle between the two arms, in degrees (typically 30–150)
+ * @param invert          - If true, mirror horizontally
+ * @param junctionRadius  - Radius of the rounded junction corners, inner and outer (0 = sharp)
+ * @param depth           - Extrusion depth
+ * @param steps           - Number of extrusion steps
+ */
+export declare function LGeometry(width: number, height: number, thickness: number, angle: number, invert: boolean, junctionRadius: number, depth: number, steps?: number): ExtrudeGeometry;
+export declare function CyclicTrapezoidGeometry(width: number, tailHeight: number, headHeight: number, thickness: number, depth: number, steps?: number): ExtrudeGeometry;
+/**
+ * Create an ExtrudeGeometry shaped like an empty rectangle (frame/border).
+ * Shape is centered at origin. The inner hole is a smaller rectangle inset
+ * by `thickness` on all four sides.
+ *
+ * @param width     - Total width of the outer rectangle
+ * @param height    - Total height of the outer rectangle
+ * @param thickness - Wall thickness of the frame (inset on each side)
+ * @param depth     - Extrusion depth
+ * @param steps     - Number of extrusion steps
+ * @constructor
+ */
+export declare function EmptyRectangleGeometry(width: number, height: number, thickness: number, depth: number, steps?: number): ExtrudeGeometry;
+/**
+ * Create an ExtrudeGeometry shaped like a rectangle with a rectangular "nail"
+ * (intrusion or protrusion)
+ * The main rectangle is centered at origin; the nail hangs inside or outside it.
+ *
+ * @param width      - Total width of the rectangle
+ * @param height     - Height of the main rectangle body
+ * @param nailWidth  - Width of the nail intrusion
+ * @param nailHeight - Height of the nail
+ * @param nailX      - Horizontal center of the nail, measured from the rectangle's left edge
+ * @param protusion  - if false nail will enter inside the rectangle (intrusion), else outside (protusion)
+ * @param depth      - Extrusion depth
+ * @param steps      - Number of extrusion steps
+ * @throws Error if nail dimensions or position are geometrically invalid
+ * @constructor
+ */
+export declare function RectangleWithNailGeometry(width: number, height: number, nailWidth: number, nailHeight: number, nailX: number, protusion: boolean, depth: number, steps?: number): ExtrudeGeometry;
+/**
+ * Create an ExtrudeGeometry for the inner hole of a cyclic trapezoid.
+ * Returns null when the geometry should be solid (no hole).
+ *
+ * @param width      - Total width
+ * @param tailHeight - Height of the left (tail) side
+ * @param headHeight - Height of the right (head) side (0 for triangle)
+ * @param thickness  - Wall thickness
+ * @param depth      - Extrusion depth
+ * @param steps      - Number of extrusion steps
+ */
+export declare function CyclicTrapezoidHoleGeometry(width: number, tailHeight: number, headHeight: number, thickness: number, depth: number, steps?: number): ExtrudeGeometry | null;
+/**
+ * Create an ExtrudeGeometry for a drip (teardrop) shape.
+ * The shape has a sharp pointed tip at the top and a rounded bottom.
+ * Shape is centered at origin.
+ *
+ * Construction: the rounded bottom is a circle of radius width/2 centered at
+ * y = -height/2 + width/2. Two straight tangent lines connect the circle to the
+ * tip at (0, +height/2). This requires height > width so the tip sits above the
+ * circle and the tangent lines exist.
+ *
+ * @param width     - Total width
+ * @param height    - Total height (must be > width)
+ * @param thickness - Wall thickness of the shell
+ * @param depth     - Extrusion depth
+ * @param steps     - Number of extrusion steps
+ * @throws Error if height <= width (tip too low for tangent construction)
+ * @constructor
+ */
+export declare function DripGeometry(width: number, height: number, thickness: number, depth: number, steps?: number): ExtrudeGeometry;
+/**
+ * Create an ExtrudeGeometry for the inner hole of a drip shape.
+ * Returns null when thickness is large enough that the drip has no hole.
+ *
+ * @param width     - Total width
+ * @param height    - Total height (must be > width)
+ * @param thickness - Wall thickness
+ * @param depth     - Extrusion depth
+ * @param steps     - Number of extrusion steps
+ * @throws Error if height <= width
+ */
+export declare function DripHoleGeometry(width: number, height: number, thickness: number, depth: number, steps?: number): ExtrudeGeometry | null;
+/**
+ * Create an ExtrudeGeometry shaped like japanese hiragana Ku and katakana Ko (くコ)
+ * Shape is centered horizontally at the junction between the two and vertically at the middle height
+ * by `kuThickness` on all four sides.
+ *
+ * @param kuWidth     - width of the left ku part (outer)
+ * @param koWidth     - width of the right ko part (outer)
+ * @param height    - Total height of the outer geometry
+ * @param kuThickness - Wall kuThickness of the frame (inset on ku side)
+ * @param koThickness - Wall koThickness of the frame (inset on ko side)
+ * @param depth     - Extrusion depth
+ * @param steps     - Number of extrusion steps
+ * @constructor
+ */
+export declare function KuKoGeometry(kuWidth: number, koWidth: number, height: number, kuThickness: number, koThickness: number, depth: number, steps?: number): ExtrudeGeometry;

package/dist/scene/shared/utils/LayerConstants.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Three.js Layer Constants for Hitbox Organization
+ * @module scene/shared/utils/LayerConstants
+ *
+ * Defines layer assignments for priority-based raycasting and rendering.
+ */
+/**
+ * Three.js layer assignments for hitbox meshes and rendering
+ *
+ * Layers enable priority-based raycasting by querying layers sequentially.
+ * Lower layer numbers = higher priority for hover detection.
+ *
+ * @remarks
+ * - Layer 0 is reserved for default visual rendering
+ * - Hitbox layers (1-3) are invisible but raycastable
+ * - Camera.layers should include only layer 0 for rendering
+ * - Raycaster.layers is set per-query based on priority
+ *
+ * @example
+ * ```typescript
+ * import { HitboxLayers } from './LayerConstants';
+ *
+ * // Assign hitbox to component layer
+ * hitboxMesh.layers.set(HitboxLayers.COMPONENT);
+ *
+ * // Raycast only enode hitboxes
+ * raycaster.layers.set(HitboxLayers.ENODE);
+ * ```
+ */
+export declare const HitboxLayers: {
+    /** Default layer for visual rendering (do not use for hitboxes) */
+    readonly DEFAULT: 0;
+    /** Enode hitboxes - highest hover priority */
+    readonly ENODE: 1;
+    /** Component hitboxes - medium hover priority */
+    readonly COMPONENT: 2;
+    /** Wire hitboxes - lowest hover priority */
+    readonly WIRE: 3;
+};
+export type HitboxLayerValue = (typeof HitboxLayers)[keyof typeof HitboxLayers];

package/dist/scene/shared/utils/LightingUtils.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Lighting Utilities
+ * @module scene/shared/utils/LightingUtils
+ *
+ * Helper functions for setting up scene lighting
+ */
+import * as THREE from 'three';
+/**
+ * Create an ambient light with default intensity
+ *
+ * @param color - Light color (hex)
+ * @param intensity - Light intensity (0-1)
+ * @returns AmbientLight
+ */
+export declare function createAmbientLight(color?: number, intensity?: number): THREE.AmbientLight;
+/**
+ * Create a directional light with default positioning
+ *
+ * @param color - Light color (hex)
+ * @param intensity - Light intensity
+ * @param position - Light position
+ * @returns DirectionalLight
+ */
+export declare function createDirectionalLight(color?: number, intensity?: number, position?: THREE.Vector3): THREE.DirectionalLight;
+/**
+ * Setup standard scene lighting (ambient + directional)
+ *
+ * @param scene - Scene to add lights to
+ * @returns Array of created lights
+ */
+export declare function setupSceneLights(scene: THREE.Scene): THREE.Light[];

package/dist/scene/shared/utils/MaterialUtils.d.ts

@@ -0,0 +1,73 @@
+import { LineMaterial } from 'three/examples/jsm/lines/LineMaterial.js';
+/**
+ * Material Utilities
+ * @module scene/shared/utils/MaterialUtils
+ *
+ * Helper functions for creating and managing Three.js materials
+ */
+import * as THREE from 'three';
+/**
+ * Create a standard material with common defaults
+ *
+ * @param color - Base color (hex)
+ * @param options - Additional material options
+ * @returns MeshStandardMaterial
+ */
+export declare function createStandardMaterial(color: number, options?: {
+    emissive?: number;
+    emissiveIntensity?: number;
+    metalness?: number;
+    roughness?: number;
+    transparent?: boolean;
+    opacity?: number;
+}): THREE.MeshStandardMaterial;
+/**
+ * Create a material for wire lines
+ *
+ * @param color - Line color (hex)
+ * @param linewidth - Line width (note: may not work on all platforms)
+ * @returns LineBasicMaterial
+ */
+export declare function createLineMaterial(color?: number, linewidth?: number): THREE.LineBasicMaterial;
+/**
+ * Create a LineMaterial for Line2 rendering with consistent line width
+ *
+ * Note: Resolution must be set after creation using material.resolution.set(width, height)
+ *
+ * @param color - Line color (hex, default: 0xffffff/white)
+ * @param linewidth - Line width in pixels (default: 2)
+ * @returns LineMaterial for Line2 objects
+ *
+ * @example
+ * ```typescript
+ * const material = createLine2Material(0xffffff, 2);
+ * material.resolution.set(window.innerWidth, window.innerHeight);
+ * ```
+ */
+export declare function createLine2Material(color?: number, linewidth?: number): LineMaterial;
+/**
+ * Update material state for component state changes
+ *
+ * @param material - Material to update
+ * @param state - Component state data
+ */
+export declare function updateMaterialState(material: THREE.MeshStandardMaterial, state: {
+    isActive?: boolean;
+    isHighlighted?: boolean;
+    customColor?: number;
+    emissiveIntensity?: number;
+}): void;
+/**
+ * Create a semi-transparent preview material
+ *
+ * @param baseColor - Base color
+ * @param opacity - Transparency level (0-1)
+ * @returns MeshStandardMaterial configured for preview
+ */
+export declare function createPreviewMaterial(baseColor: number, opacity?: number): THREE.MeshStandardMaterial;
+/**
+ * Create an error state material (for validation feedback)
+ *
+ * @returns MeshStandardMaterial in error state (red tint)
+ */
+export declare function createErrorMaterial(): THREE.MeshStandardMaterial;

package/dist/scene/shared/utils/Options.d.ts

@@ -0,0 +1,16 @@
+import { ControllerOptions, EngineOptions, MapControlsOptions } from '../types';
+/**
+ * returns default complete mapControlsOptions or an autocompleted partial mapControlOptions
+ * @param options
+ */
+export declare function mapControlsOptions(options?: MapControlsOptions | undefined): MapControlsOptions;
+/**
+ * returns default complete controllerOptions or an autocompleted partial controllerOptions
+ * @param options
+ */
+export declare function controllerOptions(options?: ControllerOptions | undefined): ControllerOptions;
+/**
+ * returns default complete engineOptions or and autoCompleted partial engineOptions
+ * @param options
+ */
+export declare function engineOptions(options?: EngineOptions | undefined): EngineOptions;