Sujeciones y puntos fijos

Fija bordes completos, esquinas, partes de un borde o coordenadas exactas de la cuadrícula.

attachment determina qué partículas tienen masa inversa cero. Las partículas fijas permanecen en su posición original mientras las fuerzas y restricciones mueven el resto de la cuadrícula.

Estructura de TypeScript

El tipo público es una unión discriminada y se exporta desde flag-cloth y flag-cloth/react.

type EdgeAttachment = 'left' | 'right' | 'top' | 'bottom';
type CornerAttachment =
  | 'top-left'
  | 'top-right'
  | 'bottom-left'
  | 'bottom-right';

type GridPoint = readonly [x: number, y: number];

interface PartialEdgeAttachment {
  edge: EdgeAttachment;
  every?: number; // valor predeterminado: 1
  offset?: number; // valor predeterminado: 0
}

interface PointAttachment {
  points: ReadonlyArray<GridPoint>;
}

type Attachment =
  | EdgeAttachment
  | CornerAttachment
  | 'none'
  | PartialEdgeAttachment
  | PointAttachment;

Bordes completos, esquinas y tela libre

attachment: 'left'         // predeterminado: borde izquierdo completo
attachment: 'right'
attachment: 'top'
attachment: 'bottom'
attachment: 'top-left'     // una partícula de la esquina
attachment: 'bottom-right'
attachment: 'none'         // todas las partículas quedan libres

Los nombres de las esquinas describen la tela en su orientación inicial, antes de deformarse.

Bordes parciales

Utiliza every para fijar una de cada N partículas y offset para elegir dónde comienza la secuencia.

attachment: {
  edge: 'left',
  every: 2,
}

attachment: {
  edge: 'top',
  every: 3,
  offset: 1,
}

En left y right, el desplazamiento cuenta hacia abajo desde la partícula superior. En top y bottom, cuenta hacia la derecha desde la partícula izquierda. every se redondea hacia abajo y nunca puede ser menor que 1; offset se redondea hacia abajo y nunca puede ser menor que 0.

Con segments: { x: 8, y: 4 }, el borde superior contiene las coordenadas [0, 0] hasta [8, 0]. { edge: 'top', every: 3, offset: 1 } fija [1, 0], [4, 0] y [7, 0].

Coordenadas personalizadas

Los puntos personalizados utilizan coordenadas de la cuadrícula de simulación, no píxeles, UV, dimensiones CSS ni posiciones del mundo.

[0, 0]                         [segments.x, 0]
 superior izquierda ───────────── superior derecha
          │                            │
          │          [x, y]            │
          │                            │
 inferior izquierda ───────────── inferior derecha
[0, segments.y]              [segments.x, segments.y]

import type { Attachment } from 'flag-cloth';

const attachment = {
  points: [
    [0, 0],   // esquina superior izquierda
    [0, 10],  // mitad de una cuadrícula con 20 filas
    [4, 4],   // un punto interior
  ],
} satisfies Attachment;

const flag = createFlagCloth({
  container,
  texture: '/flag.webp',
  segments: { x: 32, y: 20 },
  attachment,
});

Las coordenadas se redondean al entero más cercano. Se ignoran los puntos fuera de 0...segments.x o 0...segments.y. Repetir un punto no causa problemas.

React

El componente de React acepta la misma unión Attachment; no existe un tipo reducido exclusivo para React.

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

const mastPins = {
  points: [[0, 0], [0, 5], [0, 10], [0, 15], [0, 20]],
} satisfies Attachment;

export function Flag() {
  return (
    <FlagCloth
      texture="/flag.webp"
      segments={{ x: 32, y: 20 }}
      attachment={mastPins}
      canvasWidth="100%"
      canvasHeight={520}
    />
  );
}

Cambiar puntos fijos en tiempo de ejecución

await flag.setOptions({
  attachment: { edge: 'top', every: 2 },
});

Cambiar attachment elimina la máscara anterior, aplica la nueva y actualiza la masa inversa de las partículas sin reconstruir la topología ni el renderizador. Los puntos recién fijados vuelven a su posición original. Cuando React recibe una nueva prop attachment, el wrapper utiliza la misma ruta de setOptions().

Las partículas fijas normalmente no pueden arrastrarse. Define interaction.allowPinned: true si el puntero debe moverlas temporalmente; al soltarlas regresarán a su posición fija.