npm package: @nandstudios/launch-screen
Description: A customizable launch screen with Three.js GLB viewer, clean mouse-follow shader effects, and configurable launch lifecycle
Author: NAND Studios
Latest version: 4.3.7

# @nandstudios/launch-screen


```bash
v 4.3.0
```

A customizable launch screen component for Vue 3 with Three.js 3D GLB viewer, mouse-reactive shader effects, Unicorn Studio support, and fully configurable animations.

## Quick Start

```bash
npm install @nandstudios/launch-screen three
```

```vue
<template>
  <Transition name="fade">
    <LaunchScreen
      v-if="showLaunchScreen"
      project-number="001"
      display-mode="3d-center"
      model-path="/models/logo.glb"
      :animation="{ rotationY: 0.5, floating: true, mouseReactive: true, speedPreset: 'spring' }"
    />
  </Transition>
</template>

<script setup>
import { ref, onMounted } from 'vue'
import { LaunchScreen } from '@nandstudios/launch-screen'
import '@nandstudios/launch-screen/style.css'

const showLaunchScreen = ref(true)
onMounted(() => setTimeout(() => showLaunchScreen.value = false, 5000))
</script>

<style>
.fade-leave-active { transition: opacity 1.5s ease-out; }
.fade-leave-to { opacity: 0; }
</style>
```

## Display Modes

| Mode | Description |
|------|-------------|
| `3d-center` | Three.js GLB model centered with transparent background |
| `3d-background` | Three.js GLB model as fullscreen background |
| `unicorn-center` | Unicorn Studio JSON animation centered |
| `unicorn-background` | Unicorn Studio as fullscreen background |
| `small-image` | Simple logo/image display |

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `projectNumber` | `string` | `'000'` | Text shown in scrolling banners |
| `displayMode` | `string` | `'unicorn-center'` | Display mode (see table above) |
| `modelPath` | `string` | `'/model.glb'` | Path to GLB file (3d modes) |
| `threeConfig` | `ThreeViewerConfig` | `{}` | Three.js viewer config JSON |
| `animation` | `AnimationConfig` | `{}` | Animation settings |
| `shaderEffect` | `ShaderEffectConfig` | — | Mouse-trail shader effect |
| `backgroundColor` | `string` | `'#ffeef0'` | Background color |
| `backgroundGradient` | `string` | — | CSS gradient for background |
| `backgroundClass` | `string` | — | Custom CSS class for background |
| `backgroundTransparent` | `boolean` | `false` | Fully transparent background |
| `showAmbientSpots` | `boolean` | `false` | Enable floating ambient white spot layer |
| `unicornProjectPath` | `string` | `'/UNI/mm.json'` | Unicorn Studio JSON path |
| `smallImageUrl` | `string` | `'/logo.png'` | Image for small-image mode |
| `fallbackImage` | `string` | `'/logo.png'` | Fallback image while loading |
| `showScrollingText` | `boolean` | `true` | Show scrolling text banners |

## Three.js Viewer Config

Pass a JSON config object to `threeConfig`:

```vue
<LaunchScreen
  display-mode="3d-center"
  model-path="/models/hero.glb"
  :three-config="{
    cameraDistance: 6,
    cameraFov: 40,
    cameraPosition: { x: 0, y: 1, z: 6 },
    modelScale: 1.5,
    modelPosition: { x: 0, y: -0.5, z: 0 },
    modelRotation: { x: 0, y: 0.5, z: 0 },
    ambientLightIntensity: 0.7,
    ambientLightColor: '#ffffff',
    directionalLightIntensity: 0.9,
    directionalLightColor: '#ffffff',
    directionalLightPosition: { x: 5, y: 10, z: 7 }
  }"
/>
```

| Config Key | Type | Default | Description |
|------------|------|---------|-------------|
| `cameraDistance` | `number` | `5` | Camera distance from origin |
| `cameraFov` | `number` | `45` | Camera field of view |
| `cameraPosition` | `{x,y,z}` | `{0,0,5}` | Camera position |
| `modelScale` | `number` | `1` | Model scale multiplier |
| `modelPosition` | `{x,y,z}` | `{0,0,0}` | Model position |
| `modelRotation` | `{x,y,z}` | `{0,0,0}` | Initial model rotation (radians) |
| `ambientLightIntensity` | `number` | `0.6` | Ambient light strength |
| `ambientLightColor` | `string` | `'#ffffff'` | Ambient light color |
| `directionalLightIntensity` | `number` | `0.8` | Directional light strength |
| `directionalLightColor` | `string` | `'#ffffff'` | Directional light color |
| `directionalLightPosition` | `{x,y,z}` | `{5,10,7.5}` | Directional light position |

The viewer background is always **transparent**, so the LaunchScreen background shows through.

## Animation Settings

```vue
<LaunchScreen
  display-mode="3d-center"
  model-path="/models/logo.glb"
  :animation="{
    rotationY: 0.5,
    floating: { amplitude: 0.15, speed: 1.2 },
    mouseReactive: { sensitivity: 0.4, smoothing: 0.05 },
    speedPreset: 'spring',
    rotationAngle: 20
  }"
/>
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `rotationY` | `boolean \| number` | `0.3` | Y-axis rotation speed. `false` disables |
| `floating` | `boolean \| {amplitude, speed}` | `true` | Floating bob animation |
| `mouseReactive` | `boolean \| {sensitivity, smoothing}` | `true` | Mouse-based tilting |
| `speedPreset` | `string` | `'spring'` | Animation easing (see below) |
| `rotationAngle` | `number` | `15` | Max mouse-tilt angle in degrees |

### Speed Presets

| Preset | Description |
|--------|-------------|
| `linear` | Constant speed, no easing |
| `exponential` | Cubic acceleration curve |
| `spring` | Smooth spring-like deceleration |
| `elastic` | Bouncy overshoot effect |
| `bounce` | Ball-bounce easing |

## Shader Effect Presets

Add mouse-reactive shader effects as an overlay. These are Three.js-powered GLSL shaders.

```vue
<LaunchScreen
  display-mode="3d-center"
  model-path="/models/logo.glb"
  :shader-effect="{ type: 'pixelate', scale: 10, radius: 150 }"
/>
```

### Available Presets

#### `pixelate` - Pixel Blob
A circular mouse-following area with a mosaic/pixel block pattern. `scale` controls pixel size (higher = bigger pixels).

```vue
:shader-effect="{ type: 'pixelate', scale: 12, radius: 130, strength: 0.9 }"
```

#### `blur` - Blur Blob
A soft glowing circle that follows the mouse with a smooth trail. Uses real `backdrop-filter` blur on content + Three.js glow trail. `scale` controls blur intensity.

```vue
:shader-effect="{ type: 'blur', scale: 15, radius: 100, strength: 0.6 }"
```

#### `motion-blur` - Motion Blur
Directional blur streaks based on mouse movement speed and direction. Stronger when moving fast, fades when stopped.

```vue
:shader-effect="{ type: 'motion-blur', scale: 20, radius: 80, strength: 0.7 }"
```

#### `invert` - Invert Colors
Inverts the colors of everything behind the mouse cursor circle. Uses `mix-blend-mode: difference` for real content inversion. Default color is white (standard invert).

```vue
:shader-effect="{ type: 'invert', radius: 120, strength: 1.0 }"
```

Custom invert colors via `invertColorMap`:

```vue
:shader-effect="{
  type: 'invert',
  radius: 120,
  invertColorMap: {
    center: '#ff00ff',
    edge: '#00ffff'
  }
}"
```

### Shader Effect Parameters

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `type` | `string` | — | `'pixelate'`, `'blur'`, `'motion-blur'`, `'invert'` |
| `scale` | `number` | varies | Effect strength (pixel size / blur amount) |
| `radius` | `number` | varies | Circle radius in pixels |
| `strength` | `number` | varies | Effect opacity (0-1) |
| `hardness` | `number` | varies | Edge hardness (0=soft, 1=hard) |
| `tail` | `number` | varies | Trail length (number of trail points) |
| `fluidity` | `number` | varies | Movement smoothness (lower=smoother) |
| `dissipation` | `number` | varies | Trail fade speed (higher=faster fade) |
| `momentum` | `number` | varies | Mouse momentum carry (0-1) |
| `invertColorMap` | `object` | — | Custom colors for invert effect |

## Background Customization

### Solid Color
```vue
<LaunchScreen background-color="#1a0a2e" />
```

### CSS Gradient
```vue
<LaunchScreen background-gradient="linear-gradient(135deg, #0f0c29, #302b63, #24243e)" />
```

### Custom CSS Class
```vue
<LaunchScreen background-class="my-custom-bg" />
```

```css
.my-custom-bg .nand_gradient-bg {
  background: conic-gradient(from 45deg, #ff006e, #8338ec, #3a86ff, #ff006e) !important;
}
```

### Transparent
```vue
<LaunchScreen :background-transparent="true" />
```

### CSS Variables
```css
:root {
  --launch-screen-primary: #ffeef0;
  --launch-screen-secondary: #000080;
  --launch-screen-text-color: #000000;
  --launch-screen-duration: 5s;
}
```

## Standalone Components

All components can be used independently:

### ThreeViewer
```vue
<script setup>
import { ThreeViewer } from '@nandstudios/launch-screen'
</script>

<template>
  <ThreeViewer
    model-path="/models/product.glb"
    width="600px"
    height="400px"
    :config="{ cameraDistance: 4, ambientLightIntensity: 0.8 }"
    :animation="{ rotationY: 0.2, floating: true, mouseReactive: true }"
  />
</template>
```

### ShaderEffect
```vue
<script setup>
import { ShaderEffect } from '@nandstudios/launch-screen'
</script>

<template>
  <ShaderEffect type="invert" :radius="150" :strength="1" />
</template>
```

## Vue Plugin

```javascript
import { createApp } from 'vue'
import App from './App.vue'
import LaunchScreen from '@nandstudios/launch-screen'
import '@nandstudios/launch-screen/style.css'

const app = createApp(App)
app.use(LaunchScreen) // Registers LaunchScreen, ThreeViewer, ShaderEffect, UnicornViewer globally
app.mount('#app')
```

## Examples

### 3D Center with Spring Animation
```vue
<LaunchScreen
  display-mode="3d-center"
  model-path="/models/logo.glb"
  project-number="001"
  :animation="{ rotationY: 0.4, floating: { amplitude: 0.2, speed: 0.8 }, speedPreset: 'spring' }"
  background-color="#0a0a0a"
/>
```

### 3D Background with Pixel Effect
```vue
<LaunchScreen
  display-mode="3d-background"
  model-path="/models/scene.glb"
  :three-config="{ cameraDistance: 8, cameraFov: 60 }"
  :animation="{ rotationY: 0.1, mouseReactive: { sensitivity: 0.5, smoothing: 0.03 } }"
  :shader-effect="{ type: 'pixelate', scale: 6, radius: 180 }"
/>
```

### Invert Effect with Custom Colors
```vue
<LaunchScreen
  display-mode="small-image"
  small-image-url="/logo.svg"
  :shader-effect="{
    type: 'invert',
    radius: 140,
    strength: 1,
    invertColorMap: { center: '#ff6b6b', edge: '#4ecdc4' }
  }"
  background-gradient="linear-gradient(135deg, #667eea, #764ba2)"
/>
```

### Minimal with Blur Trail
```vue
<LaunchScreen
  project-number="042"
  :shader-effect="{ type: 'blur', scale: 20, radius: 120 }"
/>
```

## Dependencies

- **Vue 3** (required peer dependency)
- **Three.js** (optional peer dependency - required for `3d-center`, `3d-background`, and shader effects)

If you only use `unicorn-center`, `unicorn-background`, or `small-image` modes without shader effects, Three.js is not needed.

```bash
# Full install
npm install @nandstudios/launch-screen three

# Without Three.js (unicorn/image modes only)
npm install @nandstudios/launch-screen
```

## Browser Support

- Chrome 80+
- Firefox 75+
- Safari 14+
- Edge 80+

## License

MIT

---

*Made by [NAND Studios](https://nand-studios.com)*