animotion-saply

A lightweight GSAP-based animation handler that enables declarative motion via HTML data attributes. Ideal for ScrollTrigger, SplitText, and attribute-driven WebGL shader scenes.

For a full non-programmer walkthrough, read: COMPLETE-BEGINNER-GUIDE.md

Installation

npm install animotion-saply

Runtime Requirements

animotion-saply expects these globals to be available at runtime:

• gsap
• ScrollTrigger
• SplitText

The package now ships with:

• ESM build: dist/animotion-saply.esm.mjs
• CJS build: dist/animotion-saply.cjs
• CDN/IIFE build: dist/animotion-saply.min.js

Usage

npm (ESM / client-side)

import "animotion-saply";
// or:
// import { initAnimotionSaply } from "animotion-saply";
// initAnimotionSaply();

npm (CommonJS)

require("animotion-saply");

CDN script

<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/ScrollTrigger.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/SplitText.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/animotion-saply/dist/animotion-saply.min.js"></script>

Using Each Build File Directly

1) dist/animotion-saply.min.js (IIFE / browser script tag)

Use this in plain HTML pages, CMS pages, or when loading from CDN.

<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/ScrollTrigger.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/SplitText.min.js"></script>
<script src="/dist/animotion-saply.min.js"></script>

If installed from npm and copied by your build tool:

<script src="/node_modules/animotion-saply/dist/animotion-saply.min.js"></script>

2) dist/animotion-saply.esm.mjs (ES Module import)

Use this for Vite, modern Webpack, Rollup, or client-side modules.

import "animotion-saply";

Direct file import:

import { initAnimotionSaply } from "animotion-saply/dist/animotion-saply.esm.mjs";
initAnimotionSaply();

3) dist/animotion-saply.cjs (CommonJS require)

Use this in CommonJS environments.

require("animotion-saply");

Direct file require:

const { initAnimotionSaply } = require("animotion-saply/dist/animotion-saply.cjs");
initAnimotionSaply();

Quick Selection Guide

• Use animotion-saply.min.js for <script> tags and CDN usage.
• Use animotion-saply.esm.mjs for modern import workflows.
• Use animotion-saply.cjs for require() workflows.

WebGL Shader Presets (Attribute-based)

Use declarative WebGL presets without writing GLSL:

<section
  data-gsap-webgl
  data-gsap-webgl-id="hero-shader"
  data-gsap-webgl-preset="aurora"
  data-gsap-webgl-props='{
    "autoplay": true,
    "maxDpr": 2,
    "scrollTrigger": { "start": "top bottom", "end": "bottom top", "scrub": true }
  }'
  data-gsap-webgl-preset-props='{ "u_intensity": 0.95, "u_speed": 0.7 }'
></section>

Supported presets:

aurora, liquid, plasma, nebula, vortex, waves, ripples, marble, glitch, pixelate, halftone, tunnel, gridflow, metaball, fire, caustics, clouds, rainbowflow, monoscan, crt, kaleidoscope, chromaticshift, lenswarp, swirl, topography, matrixrain, lava, snow, sandstorm, inkblot, sonar, sunrise, moire, electric, checkerwarp, dreamscape, wireframe, bloomfield, ditherwave

Key attributes:

• data-gsap-webgl: enables shader scene
• data-gsap-webgl-id: unique scene ID for controls
• data-gsap-webgl-preset: preset name
• data-gsap-webgl-props: renderer + behavior config
• data-gsap-webgl-preset-props: override preset uniform defaults
• data-gsap-webgl-uniforms: custom uniforms
• data-gsap-webgl-textures: texture bindings
• data-gsap-webgl-scroll: scroll behavior config
• data-gsap-webgl-tween: GSAP uniform tween list
• data-gsap-webgl-control: global scene control entries (selector|event|sceneID|command)
• data-gsap-webgl-project: load reusable scene project by name
• data-gsap-webgl-scene: scene authoring JSON (layers, passes, keyframes)
• data-gsap-webgl-passes: post-FX stack JSON
• data-gsap-webgl-keyframes: keyframe timeline JSON
• data-gsap-webgl-authoring="true": authoring panel overlay
• data-gsap-webgl-vertex, data-gsap-webgl-fragment: inline custom shaders
• data-gsap-webgl-vertex-id, data-gsap-webgl-fragment-id: shader source from DOM script nodes

Built-in uniforms available to presets/custom shaders:

• u_time
• u_resolution
• u_mouse
• u_scroll
• u_progress
• u_pixelRatio
• u_intensity
• u_speed
• u_scale
• u_seed
• u_colorA
• u_colorB
• u_colorC

Debug:

• window.__GSAP_WEBGL_SCENES__
• window.__GSAP_WEBGL_PRESETS__
• window.__GSAP_WEBGL_PRESET_CATEGORIES__
• window.__GSAP_WEBGL_POSTFX__
• window.__GSAP_WEBGL_PROJECTS__

Preset Categories

• Hero backgrounds: aurora, nebula, dreamscape, sunrise, clouds, rainbowflow
• Liquid/energy: liquid, waves, ripples, caustics, vortex, swirl
• Tech/cyber: crt, matrixrain, monoscan, gridflow, wireframe, electric
• Glitch/experimental: glitch, chromaticshift, pixelate, halftone, moire, ditherwave
• Cinematic/depth: tunnel, lenswarp, kaleidoscope, checkerwarp, plasma, topography
• Organic/material: marble, metaball, lava, fire, sandstorm, inkblot, snow, bloomfield
• Interactive/reactive: sonar, ripples, metaball, vortex, electric, kaleidoscope

Starter Snippets

1) Hero Background (slow ambient)

<section
  data-gsap-webgl
  data-gsap-webgl-id="hero-bg"
  data-gsap-webgl-preset="dreamscape"
  data-gsap-webgl-props='{"autoplay":true,"maxDpr":2}'
  data-gsap-webgl-preset-props='{"u_intensity":0.82,"u_speed":0.35,"u_scale":1.15}'
></section>

2) Scroll-Reactive Section Transition

<section
  data-gsap-webgl
  data-gsap-webgl-id="section-transition"
  data-gsap-webgl-preset="kaleidoscope"
  data-gsap-webgl-props='{
    "autoplay": true,
    "scrollTrigger": {"start":"top bottom","end":"bottom top","scrub":true}
  }'
  data-gsap-webgl-preset-props='{"u_intensity":0.9,"u_speed":0.7}'
></section>

3) Interactive Card Hover Aura

<article
  data-gsap-webgl
  data-gsap-webgl-id="card-aura"
  data-gsap-webgl-preset="sonar"
  data-gsap-webgl-props='{"autoplay":true,"maxDpr":1.5}'
  data-gsap-webgl-preset-props='{"u_intensity":0.95,"u_speed":1.0,"u_scale":0.9}'
></article>

4) Tech Hero (cyber dashboard style)

<section
  data-gsap-webgl
  data-gsap-webgl-id="tech-hero"
  data-gsap-webgl-preset="matrixrain"
  data-gsap-webgl-props='{"autoplay":true}'
  data-gsap-webgl-preset-props='{"u_intensity":0.92,"u_speed":1.25}'
></section>

5) CTA Strip (high-energy)

<section
  data-gsap-webgl
  data-gsap-webgl-id="cta-strip"
  data-gsap-webgl-preset="electric"
  data-gsap-webgl-props='{"autoplay":true}'
  data-gsap-webgl-preset-props='{"u_intensity":1.0,"u_speed":1.2,"u_scale":1.4}'
></section>

6) Scene Control Example

<button class="pause-scene">Pause</button>
<button class="play-scene">Play</button>

<div
  data-gsap-webgl-control=".pause-scene|click|hero-bg|pause,.play-scene|click|hero-bg|play"
></div>

Advanced Engine

Multi-pass Post FX Stack

<section
  data-gsap-webgl
  data-gsap-webgl-id="fx-scene"
  data-gsap-webgl-preset="nebula"
  data-gsap-webgl-passes='[
    {"type":"bloom","uniforms":{"u_amount":0.35,"u_radius":1.6}},
    {"type":"chromatic","uniforms":{"u_amount":0.01}},
    {"type":"vignette","uniforms":{"u_amount":0.22}}
  ]'
></section>

Built-in post FX: bloom, vignette, grain, chromatic, pixelate

Node/Material Graph (Layer-level)

<section
  data-gsap-webgl
  data-gsap-webgl-scene='{
    "layers":[
      {
        "id":"graph-layer",
        "graph":{
          "nodes":[
            {"id":"n1","type":"fbm","input":"p * 2.2 + t * 0.2"},
            {"id":"n2","type":"palette","t":"n1","a":"u_colorA","b":"u_colorB","c":"vec3(1.0)","d":"u_colorC"}
          ],
          "output":"n2"
        }
      }
    ]
  }'
></section>

Scene Authoring (Layers + Keyframes + Reusable Projects)

<section
  data-gsap-webgl
  data-gsap-webgl-id="author-scene"
  data-gsap-webgl-project="cinematic-hero"
  data-gsap-webgl-authoring="true"
  data-gsap-webgl-scene='{
    "layers":[
      {"id":"base","preset":"dreamscape","blend":"normal","uniforms":{"u_intensity":0.8}},
      {"id":"accent","preset":"electric","blend":"screen","uniforms":{"u_intensity":0.3}}
    ],
    "keyframes":[
      {"target":"layer:base.u_speed","from":0.3,"to":0.8,"duration":4,"position":0,"ease":"sine.inOut"},
      {"target":"layer:accent.u_intensity","from":0.2,"to":0.6,"duration":3,"position":0.5,"ease":"sine.inOut"}
    ]
  }'
></section>

Control commands in data-gsap-webgl-control:

• play, pause, toggle, restart, seek:0.5
• timeline:play, timeline:pause, timeline:seek:0.5
• setUniform:u_intensity:0.9
• setLayerUniform:base:u_intensity:0.9
• layerVisible:accent:false
• saveProject:my-project-name

Three.js + GLTF (Attribute-driven)

This project now supports declarative Three.js scenes with GLTF, GSAP ScrollTrigger mappings, and non-scroll interactions.

Runtime requirement

Load these before using data-gsap-three:

• THREE
• GLTFLoader (for GLTF files)
• OrbitControls (optional, only if orbit interaction is enabled)

Basic GLTF scene

<section
  data-gsap-three
  data-gsap-three-id="phone-hero"
  data-gsap-three-model="/models/phone.glb"
  data-gsap-three-props='{
    "fov": 42,
    "cameraZ": 4.8,
    "ambientIntensity": 0.9,
    "directionalIntensity": 1.2,
    "playAllClips": true
  }'
></section>

ScrollTrigger mapping (animate model/camera/material/light paths)

<section
  data-gsap-three
  data-gsap-three-id="watch-scene"
  data-gsap-three-model="/models/watch.glb"
  data-gsap-three-scroll='{
    "start": "top top",
    "end": "bottom bottom",
    "scrub": true,
    "tracks": [
      {"path":"model.rotation.y","from":0,"to":6.28318},
      {"path":"camera.position.z","from":5.2,"to":3.8},
      {"path":"light:key.intensity","from":0.8,"to":1.6},
      {"path":"material:Glass.roughness","from":0.2,"to":0.05}
    ]
  }'
></section>

Non-scroll interactions (without ScrollTrigger)

<section
  data-gsap-three
  data-gsap-three-id="shoe-interactive"
  data-gsap-three-model="/models/shoe.glb"
  data-gsap-three-interactions='{
    "orbitControls": true,
    "enableZoom": true,
    "enablePan": false,
    "hover": {"enabled": true, "scale": 1.06},
    "dragRotate": {"enabled": true, "axis": "y", "sensitivity": 0.006},
    "parallax": {"enabled": true, "strength": 0.28, "duration": 0.3},
    "autoRotate": false,
    "clickMap": [
      {"object":"Laces","command":"set:object:Laces.material.metalness:0.9"},
      {"object":"Sole","command":"set:object:Sole.material.roughness:0.35"}
    ]
  }'
></section>

Global controls

<button class="play-scene">Play</button>
<button class="pause-scene">Pause</button>
<button class="spin-half">Spin 50%</button>
<button class="clip-run">Run Clip</button>

<div
  data-gsap-three-control="
    .play-scene|click|shoe-interactive|play,
    .pause-scene|click|shoe-interactive|pause,
    .spin-half|click|shoe-interactive|seek:0.5,
    .clip-run|click|shoe-interactive|actionPlay:Run
  "
></div>

Supported Three command patterns (data-gsap-three-control)

• play, pause, toggle, restart, seek:0.5
• set:camera.position.z:3.8
• set:model.rotation.y:1.57
• set:object:Wheel_FL.rotation.x:12.56
• actionPlay:ClipName
• actionStop:ClipName
• actionCrossFade:Idle:Run:0.6

Supported reference tokens in paths

• model.*
• camera.*
• scene.*
• group.*
• renderer.*
• object:ObjectName.*
• material:MaterialName.*
• light:LightName.*

Debug registry:

• window.__GSAP_THREE_SCENES__