Referencia de la API

createFlagCloth(options)

function createFlagCloth(options: FlagClothOptions): FlagClothInstance;

container y texture son obligatorios. texture puede ser null para renderizar una tela sin imagen con material.baseColor.

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

await flag.ready;

La construcción lanza un error si falta el contenedor, las dimensiones o segmentos no son válidos, WebGL2 no está disponible o los valores avanzados de canvas/contexto son incompatibles. Los errores de una textura por URL rechazan ready y setTexture().

Propiedades de la instancia

No existe un método getStats(). Lee directamente flag.stats, flag.particleCount o flag.constraintCount.

Métodos de la instancia

start(): void

Marca la instancia como iniciada y programa su bucle de animación. Con advanced.externalAnimationLoop: true, habilita las llamadas a update() sin programar requestAnimationFrame.

pause(): void

Pausa las actualizaciones internas y externas sin destruir el estado.

resume(): void

Marca la instancia como iniciada, limpia el timestamp anterior y reanuda el trabajo permitido por las opciones de visibilidad.

update(frameDeltaSeconds, renderFrame = true): void

Avanza el acumulador de tiempo fijo usando un delta en segundos. No acepta el timestamp de requestAnimationFrame. Pasa false como segundo argumento para simular sin renderizar.

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

Los valores largos se limitan mediante simulation.maxFrameDelta. Las llamadas se ignoran cuando la instancia está pausada, no se ha iniciado, está fuera de pantalla según la política de visibilidad o el documento está oculto.

render(): void

Dibuja el estado actual sin avanzar la física.

resize(): void

Mide container.clientWidth y container.clientHeight, y actualiza el viewport y la resolución interna limitada por pixel ratio cuando cambia el tamaño. Normalmente ResizeObserver lo llama automáticamente.

setTexture(source): Promise<void>

Carga una URL o sube un TexImageSource listo. Pasa null para eliminar la textura y renderizar material.baseColor. Si se solapan varias solicitudes, solo se aplica la más reciente.

setWind(partial): void

Combina un Partial<WindOptions> con el campo de viento actual sin reconstruir la topología.

setOptions(partial): Promise<void>

Combina un objeto FlagClothUpdateOptions. La promesa incluye la carga de una textura nueva cuando corresponda.

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

width, height y segments reconstruyen la topología. Los demás valores mutables actualizan la simulación, el renderizador, el controlador del puntero, la cámara, los observadores o el panel de depuración. advanced, autoStart y los atributos del contexto WebGL2 no aparecen en FlagClothUpdateOptions porque solo se aplican durante la construcción.

reset(): void

Restaura las posiciones iniciales y anteriores, limpia fuerzas y arrastre, reinicia el tiempo y el acumulador, vuelve a aplicar los puntos fijos y renderiza una vez.

destroy(): void

Detiene la animación, desconecta observadores, elimina listeners de Pointer Events y del documento, libera recursos de GPU, destruye el panel opcional y elimina el canvas creado por la biblioteca. No elimina canvases proporcionados por el usuario. Puedes llamarlo varias veces de forma segura.

Valores predeterminados completos

container y texture no tienen valores predeterminados. Esta es la configuración inicial resuelta de todas las propiedades opcionales:

{
  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,
}

El perfil performance cambia maxPixelRatio a 1, shadows a false y shadingUpdateInterval a 2. Los valores explícitos proporcionados junto al perfil tienen prioridad. Configuración explica las unidades y el comportamiento de cada valor.

Exportaciones del núcleo

Exportaciones en tiempo de ejecución:

createFlagCloth
FlagClothInstance
WebGLClothRenderer
ClothSimulation
FixedTimeStep

Tipos públicos:

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

Exportaciones de React

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

El punto de entrada de React también vuelve a exportar los tipos necesarios para las props, incluida la unión completa Attachment. Consulta React para conocer el tamaño del canvas y el comportamiento de las actualizaciones.