Skip to content

README.md

Latest commit

 

History

History
136 lines (93 loc) · 3.82 KB

README.md

File metadata and controls

136 lines (93 loc) · 3.82 KB

Fuzzy Cloud Text

Interactive 3D text rendered as a fuzzy particle cloud using React, Vite, and Three.js.

Preview

What This Project Does

This app renders editable text into a 3D particle-based cloud effect:

  • You type into a hidden contenteditable element.
  • The text is rasterized to an offscreen canvas.
  • Pixel coordinates are sampled and converted into particle instances.
  • A Three.js scene displays and animates those instances in real time.

The app is a frontend-only SPA (no backend API).

Tech Stack

  • React 18 + react-router-dom
  • Vite 3 (dev/build tooling)
  • Three.js + postprocessing
  • styled-components
  • zustand (shared viewer state)
  • ESLint + Prettier

Quick Start

Prerequisites

  • Node.js 18+ recommended
  • Yarn (project uses a yarn.lock)

Install

yarn install

Run Dev Server

yarn start

Vite is configured to run on:

  • http://localhost:4000
  • host exposed via --host (accessible on local network)

Build for Production

yarn build

Output is generated in dist/.

Available Scripts

  • yarn start - start Vite development server
  • yarn build - create production build
  • yarn lint - run ESLint with auto-fix
  • yarn format - format JS/JSX/JSON/Markdown with Prettier

Project Structure

src/
  components/
    ThreeViewer/
      ThreeViewer.jsx        # React wrapper around ThreeEngine
      libs/
        ThreeEngine.js       # Scene/camera/renderer/loaders/composer
        CloudText.js         # Text sampling -> instanced particles
  pages/
    Main/
      Main.jsx               # Main page hosting the viewer
  state/
    store.js                 # Zustand viewer/light/environment state
  dataset/
    routes.js                # SPA routes
    environments.js          # HDR environment presets
public/
  draco/                     # Draco decoder files (required for GLTF Draco)

How Rendering Works

  1. ThreeViewer creates a ThreeEngine instance and hidden text input (#input_3d_text).
  2. CloudText reads input HTML, normalizes line breaks, and computes caret position.
  3. Text is drawn onto an internal canvas using the configured font settings.
  4. Non-empty pixels are mapped into world-space coordinates.
  5. A THREE.InstancedMesh is rebuilt/updated with particle transforms.
  6. Each frame updates particle growth, cursor blink, and renderer/composer output.

Configuration and Customization

Change default text/font behavior

Edit constants near the top of src/components/ThreeViewer/libs/CloudText.js:

  • FONT_NAME
  • FONT_SIZE
  • FONT_SCALE_FACTOR
  • initial this.string

Change environments and lighting defaults

  • Environment presets: src/dataset/environments.js
  • Store defaults for sun/ambient/exposure: src/state/store.js

Scene engine behavior

Main rendering/loader/camera logic lives in:

  • src/components/ThreeViewer/libs/ThreeEngine.js

Environment Variables

No runtime environment variables are currently required by app code (import.meta.env / process.env not used in src/).

Deployment Notes

  • Deploy dist/ as a static site.
  • Keep public/draco available at /draco/ in production (used by DRACOLoader).
  • Cloud particle alpha texture is loaded from an external URL in CloudText; if offline/self-hosted deployment is needed, vendor that texture locally.

Known Caveats

  • In CloudText.updateCursorOpacity(), clock.getElapsedTime() is referenced instead of this.clock.getElapsedTime(). This can cause a runtime error when cursor opacity updates.
  • public/manifest.json appears to contain unrelated branding text and may need updating if this project is published as-is.

Notes on Testing

There is currently no test runner configured (test script is not defined). Linting and formatting are the primary code quality checks in this repository.