@badskuns/vara-network-motion NPM

vara-network-motion

What it's about

Vara Network Motion is a specialized JavaScript library that empowers you to create unique and captivating 3D animations with specific shapes for your Vara web applications. This library unlocks the potential to bring your web designs to life by incorporating dynamic and visually striking motion effects.

Key features of package include:

Shape-based animations: The library provides a wide range of options for animating elements with specific shapes. You can animate objects to follow curves, spirals, or any custom-defined path, allowing you to create stunning visual effects that defy conventional motion design.
Rich customization: Vara Network Motion offers extensive customization options, enabling you to fine-tune the appearance and behavior of your animations. You can adjust parameters such as duration, speed, rotation, scaling, and opacity to achieve the desired effect.
Interactive controls: The library allows you to add interactive controls to your 3D animations, such as mouse-based interactions or touch gestures. This capability enhances user engagement and provides a more immersive experience for your visitors.
Cross-browser compatibility: Vara Network Motion is designed to work seamlessly across various web browsers, ensuring that your animations appear consistently on different platforms and devices.

How to start

yarn install - install all dependencies
npm start - starts app in dev mode

How to build

npm run build - creates production build
npm run build-demo - creates production build for standalone version of 3d module

How to publish

npm run beta - publishes next beta version of package
npm publish - publishes next minor version of package

How to use

Install the library

yarn add @badskuns/vara-network-motion

Import library

import VaraCanvas from "@badskuns/vara-network-motion";

<VaraCanvas debug={false} density={100} displayControls={displayControls} drawControls={drawControls} mouse={mouse} />;

Provide necessary props:

density: number;
debug?: boolean;
displayControls: VaraCanvasDisplayControls;
drawControls: MutableRefObject<VaraCanvasDrawControls>;
mouse?: MouseCoordinates;

density - How many points are used to create surface, if value is small then surface is angular, if amount is too large then it significantly impacts performance. Total amount of dots is density in power of two so 50 will mean 2500 dots and 100 will mean 10000 points. Default value is 100
debug - If set to true then enables OrbitControls for free camera movement and utility performance monitor
displayControls - List of options responsible for displaying elements on scene
drawControls - List of options responsible for controlling lights configuration, wave configuration, wave material configuration, curve that wave follows configuration and camera position configuration
mouse - Object for passing mouse position x and y coordinates from 0 to 1 according to viewport

VaraCanvasDisplayControls

property	type	description
showUtil	`boolean`	Controls display of utility surface grid to control positioning of Plane over curve
showDots	`boolean`	Controls display of utility dots that are created based on density property
showNormals	`boolean`	Controls display of utility normals of surface, important for understanding if normals are computed correctly
showCurve	`boolean`	Controls display of utility curve along which geometry is following
showWaves	`boolean`	Controls display of 3d wave animation
showLights	`boolean`	Controls diplay of lights that are used for surface reflections computations
showGrid	`boolean`	Controls dipsplay of grid representin initial viewport sizes
showPointer	`boolean`	Controls display of mouse pointer utility spehere

VaraCanvasDrawControls:

export type VaraCanvasDrawControls = {
  lightsConfig: VaraCanvasLightsConfig;
  waveConfig: VaraCanvasWaveConfig;
  materialConfig: VaraCanvasMaterialConfig;
  curveConfig: VaraCanvasCurveConfig;
  cameraConfig: VaraCameraConfig;
};

VaraCanvasLightsConfig

Responsible for control of lights that are reflected on wave surface, preferred to be static for scene in production mode

type VaraCanvasColorType = {
  color: string;
  int: number;
};

type VaraCanvasLightsConfig = {
  ambient: VaraCanvasColorType;
  ceiling: VaraCanvasColorType;
  chaoticRounds: VaraCanvasColorType;
  accent1: VaraCanvasColorType;
  accent2: VaraCanvasColorType;
};

property	type	description
ambient	`VaraCanvasColorType`	General ambient color and intensity of scene
ceiling	`VaraCanvasColorType`	Major intensive light of wave
chaoticRounds	`VaraCanvasColorType`	Pseudo chaotic reflections on wave surface
accent1	`VaraCanvasColorType`	Main accent color 1 that gives major color reflection
accent2	`VaraCanvasColorType`	Main accent color 2 that gives major color reflection

VaraCanvasMaterialConfig

Controls surface material and basic physical properties applied to it. Normal map used to create effect of ripples on wave surface and could be controlled during animation with changing of motion value speed

interface SurfaceAxisType {
  x: MotionValue<number>;
  z: MotionValue<number>;
}

type VaraCanvasMaterialConfig = {
  enabled?: boolean;
  color: string;
  roughness: number;
  metalness: number;
  opacity: number;
  density: number;
  speed: SurfaceAxisType;
};

property	type	description
color	`string`	Defines main color of the surface
roughness	`number`	How rough the material appears. 0.0 means a smooth mirror reflection, 1.0 means fully diffuse.
metalness	`number`	How much the material is like a metal. Non-metallic materials such as wood or stone use 0.0, metallic use 1.0, with nothing (usually) in between
opacity	`number`	How transparent material is, 0 means fully tranparent 1 means not transpaarent material
density	`number`	Density of normal map applied to material, higher value of density will lead to more detailed and interference wave surface distortion
speed	`SurfaceAxisType`	Offset speed of normal map by axises relative to surface, higher value of x and y will lead to faster offset of wave surface distortion like wind blows ripples on water

VaraCanvasCurveConfig

This property constructs Centripetal Catmull–Rom spline or better tell combination of paths as single Catmull–Rom curve behaves not good on straight sections that leads to unexpected interpolation artifacts

type VaraCanvasCurveConfig = {
  offset: MotionValue<number>;
  scale: MotionValue<number>;
  closed: boolean;
  dots: [number, number][][];
  magnet: {
    maxDistance: number;
    maxOffset: number;
    amplitude: number;
  };
};

property	type	description
offset	`MotionValue<number>`	Offset on combined curve from begining of current curve to next curve from which total path consists of. If 2 paths were passed into dots config, 0 value will place shape in begining of first curve and 1 will place shape in begining of next curve
scale	`MotionValue<number>`	Scale of the curve impacts not curve by itself, but wave applied to curve, so that means changing of this property will lead to scaling wave along the curve
closed	`boolean`	Property responsible for closing curve to the begining, that means that curve becomes infinite and wave will be cycled
dots	`[x:number, y:number][][]`	3 dimentional array of coordinates that determine curve trajectory. First level of array defines single Catmull curve, path consits of one or multiple curves. Second level of array defines curve path and should consist from at least 2 points, all curves after first one should start with 0,0 coordinates. Third level describes x and y offset in viewport sizes, so -1, 0.5 will mean offset in 1 viewport size left and half viewport top.
magnet.maxDistance	`number`	Distance in viewport width from 0 to 100 when mouse starts impact wave
magnet.maxOffset	`number`	Distance in viewport width from 0 to 100 how far curve could deviate from initial path based on magnet maxDistance property
magnet.amplitude	`number`	Amplitude multiplier that effects basic `waveConfig.amplitude` based on magnet maxDistance property

VaraCameraConfig

This configuration defines position of camera and zoom. x and y coordinates are defined in viewport width and height accordingly relative to beginning of scene axes.

interface SurfaceAxisType {
  x: MotionValue<number>;
  z: MotionValue<number>;
}
interface SceneAxisType extends SurfaceAxisType {
  y: MotionValue<number>;
}

type VaraCameraConfig = {
  zoom: MotionValue<number>;
  position: SceneAxisType;
  lookAt: SceneAxisType;
  releaseCamera: boolean;
};

property	type	description
zoom	`MotionValue<number>`	Controls zoom of camera, default is 20
position	`SceneAxisType`	Controls base position of OrthographicCamera
lookAt	`SceneAxisType`	Controls where OrthographicCamera looks at
releaseCamera	`boolean`	If camera released we could easily rotate it with OrbitControls, otherwise it controlled by camera configuration values like `position` and `lookAt`

VaraCanvasWaveConfig

Main config that controls display of wave and effects it basic visual properties. Surface distortion computed by Perlin Noise algorithm. All properties are motion animated, that means we subscribed to changes of values and could reflect updates on each animation frame

interface SurfaceAxisType {
  x: MotionValue<number>;
  z: MotionValue<number>;
}

type VaraCanvasWaveConfig = {
  amplitude: MotionValue<number>;
  frequency: MotionValue<number>;
  smoothness: MotionValue<number>;
  speed: MotionValue<number>;
  rotation: MotionValue<number>;
  noiseIntensity: SurfaceAxisType;
  offsetSpeed: SurfaceAxisType;
  scaleZ: {
    far: MotionValue<number>;
    near: MotionValue<number>;
    farAmplitude: MotionValue<number>;
    nearAmplitude: MotionValue<number>;
  };
  deformator: {
    shape: MotionValue<number>;
    amplitude: MotionValue<number>;
    frequency: MotionValue<number>;
    smoothness: MotionValue<number>;
    offset: MotionValue<number>;
  };
};

property	type	description
amplitude	`MotionValue<number>`	Amplitude of wave noise
frequency	`MotionValue<number>`	Frequency of wave noise, higher value increseases wave frequency
smoothness	`MotionValue<number>`	Determins smoothing between extremum values
speed	`MotionValue<number>`	How much perlin noise changes with each animation frame, we could change speed of changes or freeze wave
rotation	`MotionValue<number>`	Very specific property that rotates Plane along curve, used to change drawing mode between default `Math.PI/2` and 0 rotation where `deformator` config could be applied.
noiseIntensity	`SurfaceAxisType`	Property to control noise relative to Plane 2d axes. We could make chaotic waves when values are 1, and could make directional waves like tides when one of values is less then 1. Valid values are between 0 and 1
offsetSpeed	`SurfaceAxisType`	Property to control noise offset relative to Plane 2d axes. When waves are moving they have offset of wave crest, so we imitate this behaviour with this property. Basically `offsetSpeed` property makes effect like wave is running somewhere and make movement more natural
scaleZ		Options to add deformations to wave relative to initial camera position
scaleZ.far	`MotionValue<number>`	Applies scale multiplier to far part of surface when `rotation` is set to 0. Value should be larger then 0 and not much larger than 1
scaleZ.near	`MotionValue<number>`	Applies scale multiplier to near part of surface when `rotation` is set to 0. Value should be larger then 0 and not much larger than 1
scaleZ.farAmplitude	`MotionValue<number>`	Applies amplitude multiplier to far part of surface when `rotation` is set to 0. Value should be larger then 0 and not much larger than 1
scaleZ.nearAmplitude	`MotionValue<number>`	Applies amplitude multiplier to near part of surface when `rotation` is set to 0. Value should be larger then 0 and not much larger than 1
deformator		Property to attach additional deformations to surface shape, could be used to totally change shape of surface by very specific reasons like initial animation of waterfall. Applied when `rotation` is set to 0
deformator.shape	`MotionValue<number>`	Property to control deformator shape based on static permutation of perlin noise wave.
deformator.amplitude	`MotionValue<number>`	Property to control deformator amplitude.
deformator.frequency	`MotionValue<number>`	Property to control deformator frequency of wave.
deformator.smoothness	`MotionValue<number>`
deformator.offset	`MotionValue<number>`	Property to control deformator offset in case animation is needed.

Standalone mode

You need to open deployment url to work in standalone mode of application. In this mode you have full control over settings and path of wave and could create custom unique shapes based on vara-network 3d engine.