API reference

createFlagCloth(options)

function createFlagCloth(options: FlagClothOptions): FlagClothInstance;

container and texture are required. texture may be null when you want an untextured cloth using material.baseColor.

const flag = createFlagCloth({
  container: document.querySelector<HTMLElement>('#flag')!,
  texture: '/flag.webp',
});

await flag.ready;

Construction throws when the container is missing, the cloth dimensions or segment counts are invalid, WebGL2 is unavailable, or incompatible advanced canvas/context values are supplied. URL texture failures reject ready and setTexture().

Instance properties

There is no getStats() method. Read flag.stats, flag.particleCount, or flag.constraintCount directly.

Instance methods

start(): void

Marks the instance as started and schedules the owned animation loop. With advanced.externalAnimationLoop: true, it enables calls to update() but does not schedule requestAnimationFrame.

pause(): void

Pauses internal and external-loop updates without destroying state.

resume(): void

Marks the instance as started, clears the previous frame timestamp, and resumes work allowed by visibility settings.

update(frameDeltaSeconds, renderFrame = true): void

Advances the fixed-step accumulator by a display-frame delta in seconds. It does not accept a requestAnimationFrame timestamp. Pass false as the second argument to simulate without rendering.

flag.update(1 / 60);
flag.update(deltaSeconds, false);

Long values are capped by simulation.maxFrameDelta. Calls are ignored while the instance is paused, offscreen under the visibility policy, document-hidden under the visibility policy, or not started.

render(): void

Draws the current simulation state without advancing physics.

resize(): void

Measures container.clientWidth and container.clientHeight, then updates the viewport and pixel-ratio-capped backing store when the size changed. ResizeObserver normally calls this automatically.

setTexture(source): Promise<void>

Loads a URL or uploads a ready TexImageSource. Pass null to remove the texture and render material.baseColor. When requests overlap, only the newest texture request is applied.

setWind(partial): void

Merges a Partial<WindOptions> into the current wind field without rebuilding cloth topology.

setOptions(partial): Promise<void>

Merges a FlagClothUpdateOptions object. The promise accounts for an optional texture change.

await flag.setOptions({
  attachment: { edge: 'left', every: 2 },
  wind: { strength: 12 },
  renderer: { preset: 'performance' },
});

width, height, and segments rebuild simulation topology. Other mutable values update the current simulation, renderer, pointer controller, camera, observers, or debug panel. Construction-only advanced, autoStart, and WebGL2 context attributes are deliberately absent from FlagClothUpdateOptions.

reset(): void

Restores initial particle and previous-particle positions, clears accumulated forces and drag state, resets simulation time and the fixed-step accumulator, reapplies pins, and renders once.

destroy(): void

Stops animation, disconnects observers, removes Pointer Event and document listeners, deletes GPU resources, destroys the optional debug panel, and removes a library-owned canvas. Caller-owned canvases are not removed. Repeated calls are safe.

Complete default values

container and texture have no defaults. This is the resolved initial configuration for every optional property:

{
  width: 3,
  height: 2,
  segments: { x: 32, y: 20 },
  attachment: 'left',

  wind: {
    direction: [1, 0.08, 0.3],
    strength: 7,
    turbulence: 0.35,
    gustFrequency: 0.5,
    spatialScale: 0.8,
    aerodynamicCoefficient: 0.35,
  },

  simulation: {
    damping: 0.985,
    gravity: [0, 0, 0],
    fixedTimeStep: 1 / 60,
    maxFrameDelta: 0.1,
    substeps: 2,
    constraintIterations: 6,
    structuralStiffness: 1,
    shearStiffness: 0.9,
    bendStiffness: 0.4,
    maxCorrection: 0.25,
    mass: 1,
  },

  interaction: {
    enabled: true,
    touchAction: "pan-y",
    dragRadius: 1,
    dragStiffness: 0.9,
    maxDragDistance: 4,
    allowPinned: false,
    releaseImpulse: [0, 0, 0],
  },

  renderer: {
    preset: 'quality',
    alpha: true,
    antialias: true,
    desynchronized: false,
    powerPreference: 'high-performance',
    maxPixelRatio: 1.5,
    textureFiltering: 'linear',
    transparent: true,
    backgroundColor: 'transparent',
    shadows: true,
    shadingUpdateInterval: 1,
  },

  material: {
    baseColor: '#f2f4f3',
    ambient: 0.58,
    diffuse: 0.55,
    specular: 0.16,
    shininess: 18,
    foldContrast: 0.42,
    shadowColor: 'rgba(0, 0, 0, 0.3)',
    shadowBlur: 18,
    shadowOffsetX: 10,
    shadowOffsetY: 12,
  },

  lighting: {
    enabled: true,
    intensity: 1,
    direction: [-0.4, 0.7, 1],
  },

  camera: {
    fov: 40,
    near: 0.01,
    far: 100,
    position: null,
    lookAt: [0, 0, 0],
  },

  visibility: {
    pauseWhenOffscreen: true,
    pauseWhenDocumentHidden: true,
  },

  debug: {
    enabled: false,
    updateInterval: 500,
  },

  advanced: {
    canvas: undefined,
    context: undefined,
    externalAnimationLoop: false,
  },

  autoStart: true,
}

The performance renderer preset changes maxPixelRatio to 1, shadows to false, and shadingUpdateInterval to 2. Explicit values supplied with the preset take precedence. Configuration explains the units and runtime behavior of every value.

Core exports

Runtime exports:

createFlagCloth
FlagClothInstance
WebGLClothRenderer
ClothSimulation
FixedTimeStep

Public option and utility types:

AdvancedOptions
Attachment
CameraOptions
ClothMaterialOptions
ClothSimulationConfig
CornerAttachment
DebugOptions
EdgeAttachment
FlagClothOptions
FlagClothStats
FlagClothUpdateOptions
FlagRendererOptions
FlagSegments
GridPoint
InteractionOptions
InteractionTouchAction
LightingOptions
MutableFlagRendererOptions
PartialEdgeAttachment
PointAttachment
RendererPreset
SimulationOptions
TextureSource
Vector3Tuple
VisibilityOptions
WindOptions

React exports

import {
  FlagCloth,
  type FlagClothProps,
  type FlagClothInstance,
} from 'flag-cloth/react';

The React entry also re-exports the option types needed to type prop values, including the complete Attachment union. See React for canvas sizing and update behavior.