wave-flag-studio

v1.0.1

Published

a month ago

Customizable 3D cloth flag simulation library powered by Three.js

0High
0Medium
0Low

sumant_raj

flag flagwaver threejs cloth-simulation 3d webgl wave-flag flag-studio

Wave Flag Studio 🚩

A lightweight, customizable 3D flag simulation NPM library powered by Three.js and real-time cloth physics aerodynamics.

Installation & Usage

Option A: Via NPM (React, Vue, Next.js, Vite, Webpack)

npm install wave-flag-studio three

import { FlagStudio } from 'wave-flag-studio';

// Simple default initialization (loads embedded SVG flag, 5 m/s wind, 3.5m staff)
const studio = new FlagStudio('#viewer');

Option B: Via CDN Script Tag (Plain HTML / No Build Tool Needed)

Include Three.js and wave-flag-studio directly in any HTML file:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Flag Studio Demo</title>
  <style>
    body { margin: 0; overflow: hidden; background: #000; }
    #flag-container { width: 100vw; height: 100vh; }
  </style>
</head>
<body>
  <div id="flag-container"></div>

  <!-- Include Three.js & WaveFlagStudio -->
  <script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js"></script>
  <script src="https://unpkg.com/wave-flag-studio/dist/wave-flag-studio.umd.js"></script>
  <script>
    // Initialize FlagStudio directly in browser
    const studio = new WaveFlagStudio.FlagStudio('#flag-container', {
      flagImage: 'https://flagcdn.com/w640/in.png', // Any image URL or SVG
      windSpeed: 6
    });
  </script>
</body>
</html>

Custom Options

const studio = new FlagStudio('#viewer', {
  flagImage: '/my-custom-flag.png',              // URL, relative path, or Data URI (default: embedded SVG)
  windSpeed: 8,                                   // Wind speed in m/s (default: 5)
  windDirection: { x: 1, y: 0.05, z: 0.1 },      // Wind direction vector (default: { x: 1, y: 0.04, z: 0.08 })
  flagWidth: 1.35,                                // Flag width in meters (default: 1.35)
  flagHeight: 0.9,                                // Flag height in meters (default: 0.9)
  staffLength: 3.5,                               // Staff length in meters (default: 3.5)
  staffWidth: 0.045,                              // Staff diameter (default: 0.045)
  showStaff: true,                                // Show/hide vertical staff & ornament (default: true)
});

Dynamic API Methods

studio.setWindSpeed(10);                             // Update wind speed live
studio.setWindDirection({ x: 0.5, y: 0.1, z: 1.0 }); // Update wind direction live
studio.setFlagImage('/path/to/another-flag.jpg');     // Change flag image live
studio.destroy();                                    // Clean up resources on unmount

How to Publish to NPM & Host Online

1. Publish Package to NPM Registry

Run these commands in your project terminal:

# 1. Build production bundle
npm run build

# 2. Login to your free NPM account (create one at https://npmjs.com if needed)
npm login

# 3. Publish package publicly to NPM
npm publish --access public

Once published, your library will be available instantly on NPM (npm install wave-flag-studio) and CDN (https://unpkg.com/wave-flag-studio).

2. Host Live Website Demo Online (Free)

Option A: Vercel / Netlify (Recommended)

Push your project to a GitHub repository (git push origin main).
Go to vercel.com or netlify.com and click Import Project from GitHub.
Set build command to npm run build and output directory to dist.
Click Deploy — your live website link will be generated instantly (e.g. https://wave-flag-studio.vercel.app).

Option B: GitHub Pages

Install gh-pages package: npm install -D gh-pages
Add script to package.json: "deploy": "npm run build && gh-pages -d dist"
Run npm run deploy. Your site is hosted live at https://<your-username>.github.io/wave-flag-studio/.