# Opciones y controles compartidos

Opciones de creación y controles modificables disponibles en todos los efectos.

Todos los efectos aceptan estas opciones de creación y devuelven el mismo `EffectHandle`. Las opciones específicas de cada efecto se explican en sus [referencias individuales](/docs/es/api/effects/).

## Opciones de creación

[Sección titulada «Opciones de creación»](#opciones-de-creación)

Usa el tipo exportado `AttachmentOptions`. Solo host es obligatorio. Los efectos salvo Burned paper amplían este tipo con `ColorAttachmentOptions`.

| Propiedad                                                                                                                                                                                                                    | Tipo                    | Predeterminado               |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------- |
| `host` Contenedor del efecto: un elemento HTML ya presente en la página, con una posición CSS distinta de static. Debe contener el elemento objetivo en el mismo documento; no puede ser el propio objetivo.                 | `HTMLElement`           | Obligatorio                  |
| `clock` Usa manual para controlar el tiempo con tu código o GSAP; auto lo avanza automáticamente.                                                                                                                            | `'manual' \| 'auto'`    | `'manual'`                   |
| `motion` respect suprime la salida con movimiento reducido. static siempre dibuja un efecto inmóvil en el tiempo cero, con cualquier preferencia.                                                                            | `'respect' \| 'static'` | `'respect'`                  |
| `seed` Semilla aleatoria fija. Permite repetir el patrón con el mismo tiempo, ajustes y objetivo capturado. No determina la cantidad de aleatoriedad ni garantiza píxeles idénticos entre dispositivos.                      | `number`                | `0`                          |
| `time` Tiempo inicial del efecto en segundos. Acepta valores negativos.                                                                                                                                                      | `number`                | `0`                          |
| `intensity` Intensidad inicial del efecto. Los valores aceptados se limitan al intervalo de 0 a 1; la respuesta visual depende del efecto.                                                                                   | `number`                | `1`                          |
| `color` Color decorativo principal opcional para todos los efectos excepto Burned paper. Acepta #RGB, #RRGGBB, rgb(...) y rgba(..., 1). Omitirlo conserva los colores originales del efecto; asignar undefined los restaura. | `string \| undefined`   | Omitido (colores originales) |

Todos los valores numéricos deben ser finitos. time, seed, intensity y los controles solo de creación deben ser representables como float32. Los controles artísticos modificables, incluso al crearlos, aceptan cualquier número finito y se limitan a 0–1; los demás valores no válidos generan un error antes de aplicar el límite. Para cambiar una opción de creación distinta de `time` o `intensity`, libera la instancia y crea otra.

Solo un efecto puede usar un objetivo a la vez. Las relaciones de contenedor no válidas y los objetivos superpuestos generan un error síncrono. Libera el efecto existente antes de aplicar otro al mismo objetivo, a uno de sus ancestros o a uno de sus descendientes. Esta restricción se refiere al árbol del DOM, no a cualquier superposición visual.

## Controles modificables

[Sección titulada «Controles modificables»](#controles-modificables)

Lee y modifica estas propiedades de la instancia de efecto. Los cambios pueden leerse de inmediato. Cuando la salida está disponible, se dibujan en el siguiente fotograma sin volver a capturar el elemento.

| Propiedad                                                                                                                                               | Tipo                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `time` Tiempo del efecto en segundos. Permite avanzar y retroceder, incluso a tiempos negativos.                                                        | `number`              |
| `intensity` Intensidad del efecto, limitada al intervalo de 0 a 1 después de validar el valor. No es un ajuste universal de altura ni de opacidad.      | `number`              |
| `color` Color decorativo principal opcional. Todos los efectos excepto Burned paper lo admiten; asigna undefined para recuperar los colores originales. | `string \| undefined` |

Todos los valores numéricos deben ser finitos. time e intensity deben ser representables como float32. intensity y los controles específicos se limitan a 0–1; estos últimos aceptan cualquier número finito. Una asignación no válida genera un error y conserva el valor anterior. Usa un solo controlador por propiedad: asignaciones directas, una línea de tiempo u otro controlador de animación.

## Controla la animación

[Sección titulada «Controla la animación»](#controla-la-animación)

Usa `clock: ‘auto’` para la animación automática. domfx avanza el tiempo mientras puede dibujar el efecto, sin contar el tiempo en pausa, oculto o fuera de pantalla.

Usa `clock: ‘manual’` para el control externo mediante tu código o GSAP. domfx nunca avanza el tiempo en este modo, ni siquiera después de `resume()`. Sigue observando el objetivo y programa el renderizado para el siguiente fotograma.

`time` elige un punto de la animación en segundos. No es un progreso de 0 a 1 ni el tiempo real transcurrido. Puedes retroceder o usar valores negativos. Deja cada propiedad a cargo de un solo controlador de animación.

## Movimiento reducido

[Sección titulada «Movimiento reducido»](#movimiento-reducido)

El valor predeterminado `motion: ‘respect’` suprime la salida cuando la persona solicita movimiento reducido. Cuando la preferencia vuelva a cambiar, llama explícitamente a `retry()`. No sustituye automáticamente la animación por un fotograma inmóvil.

`motion: ‘static’` siempre dibuja un efecto inmóvil en el tiempo cero, con cualquier preferencia. Puedes seguir leyendo el valor asignado a `time`, pero no cambia el fotograma dibujado. La intensidad y las actualizaciones de captura siguen funcionando. `resume()` no lo anima.

Consulta [estado y métodos del efecto](/docs/es/api/effect-handle/) para preparación, pausa, reanudación, actualización de captura, reintento y limpieza.
