Skip to content

Performance Guide

Optimizing your Unicorn.studio scenes is crucial for smooth user experiences. While the tool does a lot to help, here are some best practices to ensure your scenes perform well.

Built in Optimizations

At publish

  • Compiles and optimizes shader code for each layer

At runtime

  • Starting from the background and working up the layers, the sdk compresses static layers into a single texture.
  • Device checker reduces scale and DPI of the scene if it detects an old or low end device.
  • Automatically pauses scene rendering if it is out of the viewport.

Scene Management

Layers

  • Each layer requires additional shader passes, which require memory resources
  • Too many layers can impact performance
  • If you have an animated layer on the bottom with static layers above it, the engine will not compress the static layers.

Use the minimum number of layers needed to achieve your desired effect

Effects

  • Each effect adds computational overhead, especially:

    • 3d Shape
    • Bokeh blur
    • Noise blur
    • Bloom
    • FBM
    • Godrays
    • Mouse trail
    • Mouse ripple

  • Before adding a child effect, consider if you can achieve the same result by adding it to the whole scene

  • Consider using pre-rendered images for complex static effects

Optimization Parameters

Resolution Control

Several parameters can be adjusted to balance quality and performance:

Parameter Description Recommended Range
data-us-scale Canvas rendering scale 0.25-1.0
data-us-dpi Scene resolution 1.0-1.5
data-us-fps Frame rate 30-60

Start with lower values and increase until you find the right balance for your use case

Layer Scale Control

You can use the test studio (next to preview button in export window) to see some performance metrics for your scene. You can also downscale individual layers to improve performance. Often, you can make a layer half the size without losing any noticeable quality, but this reduces per pixel operations by 4x!

You need to re-publish your scene after changing the scale of an individual layer

Scene Size

  • Smaller scenes (modules) perform better than fullscreen scenes
  • Consider breaking large scenes into smaller components

Page Implementation

SDK

Make sure to include the library in the head tag of your site if your scene is in the initial viewport.

  • If you're using the Framer component, while it works out of the box, it will load faster if you include the library in the head tag with Custom Code. You can do the same with Webflow and other site builders that offer custom head tag code.
  • You may need to add async or defer to the script tag so as not to block the page load if you're experiencing initial lag.

Some older versions (<1.3.2) of the library are missing some key optimizations

Multiple Scenes

Having multiple scenes on a single page can impact performance:

  • Initial load time increases with each scene
  • Memory usage compounds

Unicorn has built in logic to efficiently manage multiple scenes on a single page, but it is not recommended to have more than 10 scenes on a single page. WebGL has a maximum limit of 16 contexts.

Lazy Loading

Enable lazy loading to improve initial page load: 

<div 
  data-us-project="YOUR_PROJECT_ID"
  data-us-lazyload="true"
></div>

This ensures scenes only initialize when they enter the viewport.

Production Mode

Enable production mode for optimal performance:

  • Serves scene data from CDN
  • Reduces initial load time
  • Improves caching behavior
<div 
  data-us-project="YOUR_PROJECT_ID"
  data-us-production="true"
></div>

You may also get the same benefits if you host your own scene JSON and serve it from a CDN.

Performance Checklist

  • Minimize layer count
  • Enable lazy loading for off-screen scenes data-us-lazyload="true"
  • Use production mode data-us-production="true"
  • Adjust scale/DPI/FPS as needed data-us-scale="0.5" data-us-dpi="1.0" data-us-fps="30"
  • Size scenes appropriately
  • Combine static layers where possible
  • No unnecessary child effects
  • Use pre-rendered images for complex static effects

It's also important to monitor your scene's performance across different devices and browsers

Next: FAQs