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

1. Install the library

yarn add @badskuns/vara-network-motion

2. Import library

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

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

3. 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.

Basic tips and hints:

• Hold down the left mouse button to move camera
• Hold down the right mouse button to pan camera
• Use z axis button for fast navigation to initial camera direction

• Click on existing point with pressed cmnd button to add point nearby
• Click on existing point with pressed shift button to remove point

See tutorial video

• Base Placement

https://github.com/gear-tech/vara-network-with-motion-design/assets/19685464/a334b089-9b1d-4de5-8268-287d29798113

• Material Updates

https://github.com/gear-tech/vara-network-with-motion-design/assets/19685464/c71dc035-dfce-4cd2-bd90-9f72170a5b5e

• Wave config controls

https://github.com/gear-tech/vara-network-with-motion-design/assets/19685464/645a8023-359c-4d2b-b08a-3f135d8c9e73

• Lights controls

https://github.com/gear-tech/vara-network-with-motion-design/assets/19685464/f17356da-7c51-490a-a7ce-b7595d993d09

License

Vara Network Motion is released under the Approval License. See the LICENSE file for more information.