Update()

##Overview

The Update() event is triggered dozens of times per second and allows your script to constantly update itself.

##Syntax

function Update( timeElapsed )
  -- your code here
end

Where:

• timeElapsed is the amount of time since the event was last triggered

##Example

local count = 0

function Update()
  count = count + 1
  this.Tooltip = 'I have been updated '..count..' times.'
end

##Performance

Whatever your frame rate is (frames per second), that's how many times this event is being called. For every instance of your object on the map. So if you've got 100 objects, and 25 fps, that's a total of 2,500 calls to their Update() functions per second. Because of this you should always 'despam' the function using Game.Time() - like this:

-- despam Update
local Now   = Game.Time
local Delay = 2 -- game seconds = prison minutes
local Ready = Now() + Delay

function Update( timeSinceLastUpdate ) -- called repeatedly, every frame
  if Now() > Ready then

    -- your code here

    Ready = Now() + Delay
  end
end

The Delay (update interval) is defined in terms of game seconds (where each second is equivalent to a prison minute). Try and make Delay as big as possible, as that will minimise CPU load and performance issues.

More advanced tricks include spreading update code over several frames (particularly important if your update code is quite bulky).

Here's a basic example:

-- despam variables here (removed for sake of brevity)

local FirstTask = true

function Update()
  if Now() > Ready then

    if FirstTask then

      -- first task code here

    else

      -- second task code here

    end

    FirstTask = not FirstTask -- toggle between tasks
    Ready = Now() + Delay
  end
end

And a more advanced example:

-- despam variables here (removed for sake of brevity)

local Tasks = {} -- forward reference
local NextTask = 1

function Update()
  if Now() > Ready then

    Tasks[ NextTask ]()

    if NextTask == #Tasks then
      NextTask = 1 -- back to start
    else
      NextTask = NextTask + 1
    end

    Ready = Now() + Delay
  end
end

Tasks[1] = function()
  -- code for task 1 here
end

Tasks[2] = function()
  -- code for task 2 here
end

-- etc...

Another nice trick is to have a variable despam Delay based on what happened in the last update. For example, your default Delay might be two seconds, but on some occasions you'll know for sure that a longer delay can be used. Building on the example above, we could implement that as follows:

-- despam variables here (removed for sake of brevity)

local Tasks = {} -- forward reference
local NextTask = 1

function Update()
  if Now() > Ready then

    Ready = Now() + ( Tasks[ NextTask ]() or Delay )

    -- faster version of next task determination code:
    NextTask = NextTask == #Tasks and 1 or ( NextTask + 1 )
  end
end

Tasks[1] = function()
  -- code for task 1 here

  return 15 -- wait 15 seconds before next task
end

Tasks[2] = function()
  -- code for task 2 here

  -- no return value means 'use default delay'
end

##See Also

• Create()
• [Save-Load Cycle Guide](Save-Load Cycle Guide)
• [Object Events](Object Events)