SceneCamera - Animate your 3D Camera simply using Tweens

A little while ago I was glazing through the 3D Lab example project and I thought I wonder if I could use Tweens to move the camera. So I threw together a prototype at the time and forgot about it (…as you do :D) then whilst I was randomly looking through my projects I came accross the code again and thought I’d give it some attention :D.

So I’ve spent on and off since yesterday evening hammering out bugs and refactoring away some of the more hastily written code and come up with SceneCamera, a fully tween-able 3D Camera which allows you to tween any combination of the parameters available in the 3D Lab example using tween, tween.path or tween.sequence.

How To Use

SceneCamera uses the built in perspective and camera functions in combination with the built in tween library allowing simple but powerful custom camera movements which appear smooth (hopefully, big changes over short times may not be :D) because it is animated to new positions.

Please note: easing is mostly compatible, however it appears tween.easing.bounce and tween.easing.elastic
and thier derrivatives do not work currently. There maybe other easing types that don’t either! :slight_smile:

Create and start, stop and reset single movements

local completedCallback = function(...) print(...) end

local move =,{angle=360,eye={y=600}},{easing=tween.easing.backIn}) -- creates a single movement

local mid,m = move(completedCallback,"Single Movement finished") -- calls tween and calls callback when finished

m:stop() -- calls tween.stop()

m:reset() -- calls tween.reset()

Create and start,stop and reset path movements

local path =,{{angle=180}, {eye = {x=360}} }) -- creates a path movement

local pid,p=path(completedCallback,"Path Movement Completed") -- calls tween.path and calls callback when finished

p:stop() -- calls tween.stop()

p:reset() -- calls tween.reset()

Creates a start,stop,reset sequence movements

     --creates a sequence movement
     local seq ={before=1,time=2,after=1,eye={x=180,y=300},centre={x=20,y=20}},
    {time=2,eye={x=0,y=0}, centre={x=0,y=0}})
      -- calls tween.sequence and calls callback when finished
      local sid,s=seq(completedCallback,"Sequence Movement Completed")
      m:stop() -- calls tween.stop()

     m:reset() -- calls tween.reset()

Supported values and types for movement functions

    --    supported movement parameters for all movement functions
    --    eye - vec3 - camera eye
    --    centre - vec3 - camera centre
    --    up - vec3 - camera up
    --    fov - int / float - perspective fov
    --    aspect - int / float - aspect ratio
    --    size - int / float - size / zoom
    --    angle - int / float - rotation around origin 
    -- sequence function specific additional  parameters
    --     time - int /float - duration of the movement
    --     before- int / float - tween.delay before
    --     after - int/ float- tween.delay after
    --     callback - function - callback function
    --     args - table - args to pass to callback
    --     options - table of options (easing and loop) 
    --     e.g options={easing=tween.easing.cubicIn, loop=tween.loop.pingpong}

Source code and AutoInstall

SceneCamera AutoInstall

SceneCamera Source

Hope you all enjoy! :smiley:

Version Log

V1.03 - Simplified init function and default value setting. Init now syncs vec3 parameters with defaults allowing single values to be set e.g `local cam = SceneCamera({eye={x=10}})`

V1.02 - Added example use with touch.

V1.0.1 - Fixed mistake which prevented single and sequence movements from being cumulative.