ascii-splash

A terminal ASCII animation app that adds visual flow to your IDE workspace.

Transform your terminal into a mesmerizing visual experience with 23 interactive patterns, 138 presets, 5 color themes, and a powerful command system. Perfect as an ambient background for your coding sessions!

✨ Features

• 🎨 23 Interactive Patterns - Waves, Starfield, Matrix, Rain, Quicksilver, Particles, Spiral, Plasma, Tunnel, Lightning, Fireworks, Life, Maze, DNA, Lava Lamp, Smoke, Snow, Ocean Beach, Campfire, Aquarium, Night Sky, Snowfall Park, Metaball Playground
• 🎯 138 Total Presets - 6 carefully crafted variations for each pattern
• 🌈 5 Color Themes - Ocean, Matrix, Starlight, Fire, Monochrome (all patterns adapt)
• 🔗 Shareable Scenes (v0.5.0+) - Press Shift+S to copy a 12-char share code; splash play <code> reproduces the scene byte-for-byte on any machine
• ⌨️ Advanced Command System - Multi-key commands for quick pattern/preset/theme switching
• 💾 Favorites System - Save and recall your favorite combinations
• 🔀 Shuffle Mode - Auto-cycle presets or entire configurations
• 🖱️ Full Mouse Support - Interactive effects with mouse movement and clicks
• ⚡ High Performance - <5% CPU usage with double-buffered rendering
• 🎛️ Quality Presets - LOW (15 FPS), MEDIUM (30 FPS), HIGH (60 FPS)
• 📝 Configuration File - Persistent settings with JSON config
• 🔧 CLI Arguments - Flexible command-line options

🎬 Visual Preview

Hero Patterns

Additional Patterns

See all 23 patterns in action! Try them yourself with ascii-splash - press 1-9, then n to cycle through all patterns.

🚀 Quick Start

# Run instantly with npx (no install required)
npx ascii-splash

# Or install globally
npm install -g ascii-splash
splash

Local Development:

git clone https://github.com/reowens/ascii-splash.git
cd ascii-splash
npm install
npm run build
npm start

📦 Installation

Global Installation (Recommended)

npm install -g ascii-splash
splash

Using npx (No Install)

npx ascii-splash

Local Development

git clone https://github.com/reowens/ascii-splash.git
cd ascii-splash
npm install
npm run build
npm start

⚙️ Command Line Options

# Run with defaults (medium quality, waves pattern, mouse enabled)
splash

# Start with specific pattern
splash --pattern starfield
splash -p matrix

# Set performance mode
splash --quality high
splash -q low

# Custom FPS (overrides performance mode)
splash --fps 45
splash -f 15

# Set color theme
splash --theme fire
splash -t matrix

# Disable mouse interaction
splash --no-mouse

# Combine options
splash --pattern quicksilver --quality high --theme starlight --no-mouse

# Render an image (v0.4.0+, requires sharp)
splash --photo path/to/photo.jpg
splash --photo ~/Pictures/cat.png --theme matrix
# After it loads, press `.` / `,` to cycle through 18 photo presets
# (halfblock, braille, dither, edge — see "Photo Mode" below).

# Layered scene: photo background + procedural overlay (v0.4.0 Phase 3+)
splash --photo ~/Pictures/beach.jpg --pattern wave
splash --photo ~/Pictures/night-sky.jpg --pattern starfield
splash --photo ~/Pictures/code-screenshot.png --pattern matrix
# Status bar reads "Photo + <Overlay>". Cycle to the standalone photo
# or any procedural pattern with `n` / `b`.

# Show version
splash --version
splash -V

# Show help
splash --help
splash -h

Available Options

| Option | Short | Description | Values | | ------------ | ----- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | --pattern | -p | Starting pattern | waves, starfield, matrix, rain, quicksilver, particles, spiral, plasma, tunnel, lightning, fireworks, life, maze, dna, lavalamp, smoke, snow, oceanbeach, campfire, aquarium, nightsky, snowfallpark, metaball | | --quality | -q | Performance mode | low, medium (default), high | | --fps | -f | Custom FPS (10-60) | Number (overrides performance mode FPS) | | --theme | -t | Color theme | ocean (default), matrix, starlight, fire, monochrome | | --photo | | Render an image (v0.4.0+) | Path to a JPEG / PNG / WebP / etc. that sharp can decode. Adds a 24th photo pattern with 18 presets across halfblock / braille / symbol modes. | | --no-mouse | | Disable mouse | Flag (no value) | | --version | -V | Show version | | | --help | -h | Show help | |

Subcommands (v0.5.0+):

| Subcommand | Description | | -------------------- | ----------------------------------------------------------------------------------------- | | splash share | Print a 12-character share code for the bootstrapped state and exit. No TTY required. | | splash play <code> | Decode a share code and boot directly into the encoded scene (byte-for-byte reproducible) |

📸 Photo Mode (v0.4.0+, on feature/v0.4.0-phase1-photo-pattern)

splash --photo PATH adds a PhotoPattern alongside the 23 procedural patterns. The image is decoded via sharp, resized to fit the terminal preserving aspect ratio, and drawn into the same Cell[][] buffer the procedural patterns use — so themes, the command system, favorites, etc. all keep working.

| Preset | Name | Mode | Pipeline | | ------ | -------------------- | ---------- | ----------------------------------------------------------------------------- | | 1 | Default | half-block | truecolor, no preprocessing | | 2 | High Contrast | half-block | contrast 1.6× around mid-gray | | 3 | Inverted | half-block | channel inversion | | 4 | Grayscale | half-block | BT.601 luminance only | | 5 | Background Tinted | half-block | space + bg color (single-color cells) | | 6 | Edge-Only (Sobel) | half-block | Sobel magnitude → threshold 64 | | 7 | Edge-Only (DoG) | half-block | Difference-of-Gaussians σ=(1,2) → thresh 16 | | 8 | Braille | braille | luminance threshold 128, 8× resolution | | 9 | Braille Inverted | braille | inverted threshold | | 10 | Braille Dithered | braille | Floyd-Steinberg → braille | | 11 | Braille Edges | braille | Sobel → braille line art | | 12 | Halfblock Bayer | half-block | Bayer 8×8 ordered dither, 8 levels | | 13 | Symbol | symbol | chafa-style 8×8 matcher, all 34 candidates (ASCII + block + quadrant + shade) | | 14 | Symbol ASCII | symbol | matcher restricted to ASCII shapes — text-art aesthetic | | 15 | Symbol Block | symbol | matcher restricted to blocks / quadrants / shades — no letters | | 16 | Symbol High-Contrast | symbol | all candidates, contrast 1.6× — punchier output | | 17 | Symbol Mono | symbol | all candidates, grayscale luminance | | 18 | Symbol ASCII Mono | symbol | ASCII only + grayscale — pure text-art monochrome |

Cycle presets at runtime with . / ,, or jump directly with c13 (preset 13). Half-block presets give 2× vertical resolution via ▀ / ▄ with 24-bit fg+bg ANSI per cell; braille presets pack 8 dots per cell using U+2800–U+28FF for 8× resolution at the cost of being monochrome per cell; symbol presets render at 8× resolution by matching each 8×8 source patch against 34 hand-authored bitmap candidates and emitting the codepoint whose lit/unlit partition best separates the patch into two color clusters (chafa-style — the "wow mode").

🎬 Layered scenes (v0.4.0 Phase 3+, on feature/v0.4.0-phase1-photo-pattern)

splash --photo bg.jpg --pattern X adds a 'layered' slot that composes the photo background with the chosen procedural overlay. The status bar reads Photo + <Overlay>. Cycling with n / b still reaches every procedural pattern + the standalone photo — the layered slot is one entry alongside them.

Sparse overlays compose naturally — they paint a few cells, leaving the rest as photo:

| Overlay | What you see | | --------- | ---------------------------------------- | | starfield | Stars drift across the photo | | lightning | Lightning strikes flash across the photo | | rain | Raindrops fall through the photo | | snow | Snowflakes drift down | | matrix | Green code rain over the photo | | fireworks | Bursts on top of the photo | | dna | DNA helix on top | | particles | Particles + trails over the photo | | smoke | Rising smoke plumes |

Dense overlays (Plasma, Wave) opt-in via the transparentBg flag (passed automatically when used in layered mode). Plasma's dimmest cells and Wave's far-from-crest cells are skipped, letting the photo show through.

Demo combinations to try:

• splash --photo ~/Pictures/beach.jpg --pattern wave — beach with overlaid waves cresting across the photo
• splash --photo ~/Pictures/night-sky.jpg --pattern starfield — additional moving starfield over a star photo
• splash --photo ~/Pictures/code-screenshot.png --pattern matrix — green matrix rain falling through the source code

Status: v0.4.0 Phases 1 + 2 + 3 + 4 are done on the feature branch but not yet released to npm. Phase 5 (Kitty / iTerm2 / Sixel native protocol pass-through) is the next milestone.

🔗 Share Codes (v0.5.0+, on feature/v0.5.0-phase7-share-codes)

Every procedural pattern is now deterministic — the random seed that drives a scene can be captured in a 12-character code and replayed on any machine, byte-for-byte.

Three entry points:

| How | What it does | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Shift+S (in-app) | Encodes the running scene, copies the code to your clipboard, shows a toast Share code XXXXXXXXXXXX copied. Falls back to printing the code if no clipboard tool is available. | | splash share | Prints a code for the would-be-initial-scene (config defaults + a fresh random seed) and exits. No TTY required — usable in scripts and CI. | | splash play <code> | Decodes the code and boots directly into the encoded scene. Validates against your local config and refuses on mismatch (so a code from a differently-configured machine fails loudly instead of silently playing a different scene). |

Try it:

# In one terminal, generate a code
$ splash share
2N9KT7VBQX3M

# In another, play it back — byte-for-byte identical animation
$ splash play 2N9KT7VBQX3M

Format: 12 characters from the Crockford base32 alphabet (no I, L, O, U — codes survive being read aloud over the phone). Case-insensitive. You can also paste it hyphenated as 2N9K-T7VB-QX3M — decoding strips the hyphens.

What's encoded:

• Pattern (0–22 procedural patterns; Photo and Layered slots are intentionally excluded — they depend on a local image file)
• Preset (1–6)
• Theme (ocean / matrix / starlight / fire / monochrome)
• PRNG seed (u32 — the actual scene state)
• 13-bit fingerprint of your non-default pattern config (so a code generated on a machine with custom settings won't silently produce a different scene on yours)

Errors:

• Share code is version N, but this build only understands v1 — upgrade ascii-splash to play a code from a newer release.
• Share code must be 12 characters — code was truncated or has extra characters.
• Invalid character "X" in share code — typo, or a char outside Crockford base32.
• This share code was made with different settings for "pattern" — your local config has overrides that would change the scene. Use the default config to play this code, or ask the sender to share their config too.

📝 Configuration File

ascii-splash supports persistent configuration via a JSON file at:

• Linux/macOS: ~/.config/ascii-splash/.splashrc.json
• Windows: %APPDATA%\ascii-splash\.splashrc.json

Settings merge with priority: CLI args > Config file > Defaults

💡 For technical details (ConfigLoader, schema, implementation), see docs/ARCHITECTURE.md#configuration-system

Example Configuration

See examples/.splashrc.example for a complete example with all available options.

{
  "defaultPattern": "waves",
  "quality": "medium",
  "fps": 30,
  "mouseEnabled": true,

  "patterns": {
    "waves": {
      "frequency": 0.1,
      "amplitude": 3,
      "speed": 1.0,
      "layers": 3,
      "rippleDuration": 2000
    },
    "starfield": {
      "starCount": 200,
      "speed": 50,
      "forceFieldRadius": 15,
      "forceFieldStrength": 200
    }
  }
}

Available Settings

Global Settings:

• defaultPattern - Starting pattern (waves, starfield, matrix, rain, quicksilver, particles, spiral, plasma, tunnel, lightning, fireworks, life, maze, dna, lavalamp, smoke, snow, oceanbeach, campfire, aquarium, nightsky, snowfallpark, metaball)
• quality - Quality preset (low, medium, high)
• fps - Target frames per second (10-60)
• theme - Color theme (ocean, matrix, starlight, fire, monochrome)
• mouseEnabled - Enable/disable mouse interaction

Pattern-Specific Settings:

Each pattern has its own configuration options. See examples/.splashrc.example for details:

• waves - frequency, amplitude, speed, layers, rippleDuration
• starfield - starCount, speed, forceFieldRadius, forceFieldStrength
• matrix - columnDensity, speed, fadeTime, distortionRadius
• rain - dropCount, speed, splashDuration
• quicksilver - blobCount, speed, viscosity, mousePull
• particles - particleCount, speed, gravity, mouseForce, spawnRate
• spiral - spiralCount, rotationSpeed, armLength, density, expandSpeed
• plasma - frequency, speed, complexity
• tunnel - shape, ringCount, ringSpacing, speed, rotationSpeed, radius
• lightning - boltDensity, branchProbability, branchAngle, fadeTime, strikeInterval, maxBranches, thickness
• fireworks - burstSize, launchSpeed, gravity, fadeRate, spawnInterval, trailLength
• life - cellSize, updateFrequency, initialDensity, birthChance, survivalChance
• maze - cellSize, generationSpeed, algorithm

Creating Your Config

1. Copy the example config:

   mkdir -p ~/.config/ascii-splash
   cp examples/.splashrc.example ~/.config/ascii-splash/.splashrc.json

2. Edit ~/.config/ascii-splash/.splashrc.json with your preferences

3. Run splash - your settings will be loaded automatically!

🎮 Controls

⌨️ Keyboard

• c: Command mode (advanced multi-key commands - presets, favorites, search, shuffle)
• 1-9: Switch to pattern 1-9
• n/b: Next/Previous pattern (cycles through all 23 patterns)
• ./,: Next/Previous preset (cycles through 6 presets per pattern)
• p: Pattern mode - Type pattern number, name, or pattern.preset combo:
  • p → 12 → Enter: Switch to pattern 12
  • p → 3.5 → Enter: Switch to pattern 3, preset 5
  • p → waves → Enter: Switch to waves pattern
  • p → Enter (empty): Previous pattern
  • 5-second timeout or ESC to cancel
• r: Random (pattern + preset + theme)
• s: Save current config to file
• Shift+S: Copy share code for the current scene to clipboard (v0.5.0+)
• Space: Pause/Resume
• +/-: Adjust FPS (10-60)
• [/]: Cycle performance modes (LOW/MEDIUM/HIGH)
• t: Cycle color themes
• ?: Toggle help overlay
• d: Toggle debug info (performance metrics)
• q/ESC/Ctrl+C: Exit

🖱️ Mouse

• Move: Interactive effects (ripples, repulsion, distortion, spawning)
• Click: Special effects (big splash, explosion, spawn columns/drops)

🌈 Color Themes

Press t to cycle through 5 beautiful color themes:

Ocean (Default)

• Blues, cyans, and teals
• Calm and soothing palette
• Perfect for waves and water patterns

Matrix

• Classic green monochrome
• Hacker aesthetic
• Pairs perfectly with Matrix pattern

Starlight

• Deep blues, purples, and white
• Cosmic space theme
• Ideal for starfield effect

Fire

• Reds, oranges, and yellows
• Warm and energetic
• Great for high-energy patterns

Monochrome

• Grayscale gradient
• Clean and minimal
• Works with everything

Each theme uses color interpolation to provide smooth gradients. All patterns automatically adapt to the selected theme!

💡 For technical details (theme interface, color interpolation algorithm), see docs/ARCHITECTURE.md#theme-system

🎨 Patterns

1. Waves (Press 1)

Smooth flowing sine waves with ripple effects

• Multiple wave layers (1-5 depending on quality)
• Mouse creates ripples
• Click for big splashes
• Ocean color gradient
• Metrics: Active ripples, wave layers

2. Starfield (Press 2)

3D starfield with parallax depth

• Stars move toward viewer (50-200 stars)
• Mouse repels stars (force field)
• Click creates explosion burst
• Size varies with depth
• Metrics: Star count, active explosions

3. Matrix (Press 3)

Classic digital rain effect

• Falling character columns
• Katakana characters
• Mouse distorts characters
• Click spawns new columns
• Metrics: Column count, density

4. Rain (Press 4)

Simple falling droplets

• Drops bounce off mouse cursor
• Mouse spawns extra drops
• Click creates splash effects
• Ground splash animations
• Metrics: Active drops, splashes

5. Quicksilver (Press 5)

Flowing liquid mercury effect

• Organic metallic liquid flow using Perlin noise
• Silver/chrome color gradients
• Mouse creates ripples in metal surface
• Click spawns mercury droplets with physics
• Reflective surface simulation
• Metrics: Active droplets, ripples, flow intensity

6. Particles (Press 6)

Physics-based particle system

• Particles with gravity, velocity, and collision
• Mouse attract/repel toggle (click to switch)
• Click creates burst of 20 particles
• Boundary bouncing with energy loss
• Theme-based coloring by velocity
• Metrics: Particle count, mode (attract/repel)

7. Spiral (Press 7)

Rotating logarithmic spirals

• Multiple spiral arms (3 default)
• Continuous rotation animation
• Mathematical spiral formula
• Distance-based intensity
• Theme-based gradient coloring
• Metrics: Arm count, point count

8. Plasma (Press 8)

Fluid plasma effect

• Multiple sine wave combination
• Smooth color transitions
• Circular and diagonal wave patterns
• Theme-based intensity coloring
• Continuous animation
• Metrics: Wave count, complexity level
• 6 Presets: Gentle Waves, Standard Plasma, Turbulent Energy, Lava Lamp, Electric Storm, Cosmic Nebula

9. Tunnel (Press 9)

3D geometric tunnel with perspective

• Multiple shape modes: circle, square, triangle, hexagon, star
• Perspective projection with depth
• Rotation animation for hypnotic effect
• Mouse parallax (shifts vanishing point)
• Click reverses direction + speed boost
• Metrics: Ring count, shape, speed, depth
• 6 Presets: Circle Tunnel, Hyperspeed, Square Vortex, Triangle Warp, Hexagon Grid, Stargate

10. Lightning

Electric bolts with recursive branching

• Bresenham line algorithm for bolt segments
• Recursive branching (probability-based)
• Flash effect with fade-out
• Auto-strikes at intervals
• Mouse creates charge particles
• Click spawns 3-4 area bolts
• Metrics: Bolt count, branch count, charge particles
• 6 Presets: Cloud Strike, Tesla Coil, Ball Lightning, Fork Lightning, Chain Lightning, Spider Lightning

11. Fireworks

Particle explosions with physics

• 3-phase lifecycle: launch → explode → fall
• Particle trails with history tracking
• Theme-based burst colors with fade
• Gravity and velocity physics
• Auto-spawn timer
• Click for instant 1.5x explosion
• Metrics: Active fireworks, particle count, explosions
• 6 Presets: Sparklers, Grand Finale, Fountain, Roman Candle, Chrysanthemum, Strobe

12. Life (Press n from Pattern 11)

Conway's Game of Life cellular automaton

• Classic infinite cellular automaton simulation
• Life/death rules with configurable birth/survival thresholds
• Generates complex living patterns (gliders, oscillators, still lifes)
• Mouse click to toggle cells on/off (paint mode)
• Patterns evolve with natural emergence behavior
• Metrics: Living cells, generation count, pattern stability
• 6 Presets: Still Life, Beehive, Gliders, Oscillators, Garden, Chaos

13. Maze (Press n from Pattern 12)

Dynamic maze generation and solving

• Multiple generation algorithms (Recursive Backtrack, Aldous-Broder, Prim, Hunt-Kill, Wilson, Braid)
• Animated maze generation with visual pathfinding
• Click to generate new maze with current algorithm
• Supports different cell sizes for various visual styles
• Perfect for hypnotic ambient animations
• Metrics: Maze cells, generation progress, algorithm type
• 6 Presets: Recursive Backtrack, Aldous-Broder, Prim, Hunt-Kill, Wilson, Braid

14. DNA (Press n from Pattern 13)

Double helix DNA strand animation

• Rotating double helix structure with base pairs
• Smooth 3D perspective projection
• Base pair connections with proper geometry
• Mouse interaction affects rotation speed
• Click to randomize strand colors
• Metrics: Rotation angle, base pair count
• 6 Presets: Classic, Fast Spin, Slow Motion, Rainbow, Unraveling, Pulse

15. Lava Lamp (Press n from Pattern 14)

Metaball-based lava lamp simulation

• Organic blob shapes using metaball algorithm
• Physics simulation with buoyancy, drift, and turbulence
• Perlin noise for natural flowing motion
• Vertical wrapping for continuous lava lamp cycle
• Mouse attracts/repels blobs with force field
• Click to spawn new blobs (max 20)
• Metrics: Blob count, average blob radius
• 6 Presets: Classic, Turbulent, Gentle, Many Blobs, Giant Blob, Strobe

16. Smoke (Press n from Pattern 15)

Physics-based smoke particle simulation

• Rising smoke plumes with Perlin noise turbulence
• Realistic particle opacity and dissipation
• Height-based color gradient for natural smoke effect
• Multiple smoke sources with configurable density
• Mouse creates force field to blow smoke away
• Click spawns burst of 15 smoke particles
• Metrics: Active particles, plume count, average opacity
• 6 Presets: Gentle Wisp, Campfire, Industrial, Incense, Fog, Steam

17. Snow (Press n from Pattern 16)

Falling particles with seasonal effects

• Realistic downward falling motion with gravity and wind drift
• Perlin noise turbulence for natural movement
• Particle rotation as they fall
• Ground accumulation feature (optional)
• 5 particle types: snow, cherry blossoms, autumn leaves, confetti, ash
• Mouse creates wind force field pushing particles
• Click spawns burst of 20 particles
• Metrics: Active particles, accumulated, average velocity
• 6 Presets: Light Flurries, Blizzard, Cherry Blossoms, Autumn Leaves, Confetti, Ash

18. Ocean Beach (Press o)

Serene beach scene with animated ocean waves

• Multi-layered scene with sky, clouds, sun, ocean, beach, and seagulls
• Animated wave system with realistic water motion
• Footprints appear when clicking on the beach
• Seagulls fly in the sky and react to mouse movement
• Dynamic sun position changes with presets
• Scene-based architecture with sprite and particle systems
• Metrics: Layers, sprites, particles, emitters, footprints, water line
• 6 Presets: Calm Morning, Midday Sun, Stormy, Sunset, Night Beach, Tropical

19. Campfire

Cozy campfire scene with flickering flames

• Scene-based rendering with layered forest background
• Animated fire particles with realistic flame physics
• Rising smoke plumes with Perlin noise turbulence
• Floating embers that drift upward and fade
• Starry night sky backdrop with twinkling stars
• Mouse interaction affects flame direction
• Metrics: Flame particles, embers, smoke density, star count
• 6 Presets: Gentle Ember, Roaring Fire, Dying Coals, Bonfire, Candlelight, Inferno

20. Aquarium

Underwater scene with swimming fish and bubbles

• Multi-layered aquatic environment with corals and seaweed
• AI-controlled fish with schooling behavior
• Rising bubble particles from bottom
• Animated seaweed swaying in current
• Light rays filtering from surface
• Click to spawn new fish, mouse attracts fish
• Metrics: Fish count, bubble count, plant animations
• 6 Presets: Tropical Reef, Deep Sea, Koi Pond, Jellyfish, Shark Tank, Coral Garden

21. Night Sky

Starry night sky with celestial phenomena

• Procedurally generated star field with variable brightness
• Shooting stars with trails at random intervals
• Optional moon phases and aurora effects
• Constellation patterns with connecting lines
• Parallax movement based on mouse position
• Click to trigger shooting star
• Metrics: Star count, shooting stars, aurora intensity
• 6 Presets: Clear Night, Meteor Shower, Aurora Borealis, Full Moon, Nebula, Galaxy

22. Snowfall Park

Winter park scene with falling snow

• Layered winter landscape with trees and benches
• Falling snow particles with wind physics
• Ground accumulation that builds up over time
• Streetlamp glow with light cone effects
• Footprints appear when clicking on ground
• Mouse creates wind gusts affecting snow
• Metrics: Snowflakes, accumulation level, wind speed
• 6 Presets: Light Flurries, Heavy Snow, Blizzard, Peaceful Evening, Ice Storm, Christmas Eve

23. Metaball Playground

Interactive metaball physics simulation

• Advanced metaball algorithm with smooth blob merging
• Multiple physics modes: gravity, attraction, repulsion
• Color blending where blobs intersect
• Adjustable surface tension and viscosity
• Mouse attracts/repels metaballs
• Click to spawn new metaballs (max configurable)
• Metrics: Blob count, merge events, physics mode
• 6 Presets: Lava Flow, Bubble Bath, Plasma Orbs, Mercury Drops, Cell Division, Cosmic Soup

⚡ Performance Modes

Press [ or ] to cycle through performance modes:

LOW (15 FPS)

Optimized for low-end systems or minimal CPU usage

• 50% particle count
• Reduced visual layers
• Target: <3% CPU usage

MEDIUM (30 FPS) - Default

Balanced performance and visual quality

• Standard particle count
• Full visual effects
• Target: <5% CPU usage

HIGH (60 FPS)

Maximum quality for high-end systems

• 200% particle count
• Enhanced visual layers
• Silky smooth animations

📊 Performance Monitoring

Press d to toggle the debug overlay showing:

• Current pattern and theme
• Real-time FPS (color-coded: green/yellow/red)
• Current performance mode
• Frame timing breakdown
• Pattern render time
• Changed cells ratio (buffer efficiency)
• Dropped frames counter
• Min/Avg/Max FPS statistics
• Pattern-specific metrics

🚄 Performance Characteristics

Optimized for low resource usage:

• CPU: 2-6% (depending on FPS preset)
• Memory: ~40-50MB
• Target: 30 FPS stable (adjustable 15-60)

📊 For detailed metrics and benchmarks, see docs/PROJECT_STATUS.md#performance-metrics

🏗️ Architecture

ascii-splash uses a clean 3-layer architecture:

• Renderer Layer: Terminal control with double-buffering for flicker-free rendering
• Engine Layer: Animation loop running at target FPS, commands, performance monitoring
• Pattern Layer: 23 interactive patterns with themes and presets

src/
├── types/          # Core interfaces and types
├── renderer/       # Terminal rendering with double-buffering
├── engine/         # Animation loop, commands, performance monitoring
├── patterns/       # Pattern implementations (23 total)
├── config/         # Configuration system
└── main.ts         # Entry point and input handling

For detailed technical architecture, see docs/ARCHITECTURE.md.

🎯 Command System

Press c to enter command mode for advanced features:

Quick Commands

• c1, c2, etc. - Apply preset to current pattern
• cp3 - Switch to pattern 3
• ct2 - Switch to theme 2
• cp3+t2 - Switch pattern AND theme

Favorites

• cF1 - Save current state to favorite slot 1
• cf1 - Load favorite slot 1
• cfl - List all saved favorites

Special Commands

• c* - Random preset (current pattern)
• c** - Random pattern + preset + theme
• c? - List presets for current pattern
• c?? - Show ALL presets catalog
• c! - Toggle shuffle mode (10s intervals)
• c!5 - Shuffle with 5s intervals
• c!! - Shuffle ALL (pattern+preset+theme)
• c/term - Search patterns/themes
• cs - Save current config to file

For the complete command reference, see the section above.

🗺️ What's Next

The next major release is v0.4.0 — "From Engine to Canvas", which makes images and video first-class inputs alongside the existing procedural patterns. The full plan is in docs/planning/v0.4.0-ROADMAP.md. Highlights:

• ✅ splash --photo path/to/img.jpg — render any image at 2× vertical resolution using upper/lower half-block characters (Phase 1, done on the feature branch).
• ✅ Braille mode + Floyd-Steinberg / Bayer dithering + Sobel / DoG edge detection — line art and high-contrast portraits (Phase 2, done on the feature branch).
• ✅ Scene composition — layer procedural patterns over photo backgrounds via splash --photo bg.jpg --pattern starfield (Phase 3, done on the feature branch; the v0.4 headline).
• ✅ Chafa-style symbol matcher — wow-mode rendering with implicit edge detection via 8×8 bitmap matching. 34 hand-authored symbols across ASCII / block / quadrant / shade tag groups; per 8×8 patch the matcher picks the bitmap whose lit/unlit partition best separates the patch into two color clusters. 18 photo presets total (Phase 4, done on the feature branch).
• 📋 Native protocol pass-through for Kitty / iTerm2 / Sixel terminals — the photo goes straight to the GPU when supported, halfblock fallback otherwise (Phase 5).
• 📋 Color-mask sprites — multi-color hand-drawn scenes (Phase 6).
• 📋 Seeded PRNG + share codes + asciinema export — splash share produces a code that reproduces an exact scene; splash record writes a .cast you can drop into a PR (Phases 7-8).

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📄 License

MIT License - Copyright (c) 2025 reoiv

🙏 Acknowledgments

Built with:

• terminal-kit - Terminal control and rendering
• chalk - Color output
• commander - CLI argument parsing
• conf - Configuration management
• sharp - Image decode + resize (v0.4.0+, only loaded when --photo is used)

Photo-mode rendering is informed by reading (not copying):

• viuer (MIT) — the half-block algorithm in block.rs is the basis for HalfBlockRenderer.
• chafa (LGPL-3.0) — algorithm reference for Bayer dithering and the Phase 4 symbol matcher. The matcher core was re-implemented from the algorithm description in symbol-renderer.c:98-268; bitmaps were hand-authored from scratch.
• drawille (AGPL-3.0) — Unicode Braille bit-pack reference (re-derived independently from the U+2800 spec).
• ascii-image-converter (Apache-2.0) — brightness ramp and braille reference.

🔗 Links

• GitHub Repository
• npm Package
• Report Issues
• Technical Architecture
• v0.4.0 Roadmap

Made with ❤️ for terminal enthusiasts