From VFXPedia

Contents 1 Getting Started : ScriptLib and Event Scripting 1.1 scriptlib(eyeon Script Library) 1.2 Event Suites 1.2.1 Removing Event Suites 1.3 Tips for Script Libraries and Event Scripting (edit) 1.4 Composition Scriptlibs

Getting Started : ScriptLib and Event Scripting

scriptlib(eyeon Script Library)

A scriptlib is a file containing a library of functions that be used in multiple scripts. Included with the default installation of *Fusion 5.is the eyeon.scriptlib, which contains a functions that we've deemed useful in the scripting process. The scriptlib could have additions in it such as variable declarations (added to the globals table, for instance). Script Libraries are installed in the root of the scripts directory ( by default Fusion:\Scripts\ ). In that directory, anything with a .scriptlib extension will be run whenever a composition is created or opened allowing you to access all functions within it. The added benefit of the scriptlib is that you can instruct Fusion to run a set of code every time that a composition is created or opened. The downside to this is that, as said above, Fusion will execute the files in the scripts directory in an arbitrary order. This means that any code you write in the script libraries that is reliant upon other libraries may not work. To get around this, try inserting the functions that are needed at the top of the scriptlib.

Beyond passing functions into the global environment of the composition, the scriptlib also can be set up to perform rote actions on a composition. It could also be used to create custom events set up in event suites.

Event Suites

An event script is a chunk of code that is executed whenever a given event takes place (an event takes place when a user saves a comp, or hits the render button, et-cetera (listed below). This is useful if there is a set of actions that need to be performed before starting a render, or if an action was needed to be taken when a new composition was being saved.

To define a new event, a variable needs to be defined that will be manipulated, and make it into an event suite for the flow with the AddEventSuite(Suite) function. The only Suite that is available at the moment is "Composition". The syntax would be as such:

ev = AddEventSuite("Composition")

ev would now be equal to the event suite table available to a composition. At this point you can now alter the table entry for what the event suite does. The following are the event suites that are available.

    OnOpen() -- Triggers every time a file is opened
 
    OnSave() -- Triggers every time a comp is saved
 
    OnSaveAs() -- Whenever save as is called
 
    OnStartRender() -- Whenever a render starts
 
    OnEndRender() -- Whenever a render ends
 
    OnFrameRendered() -- Whenever a frame is rendered
 
    OnTimeChange() -- Whenever the time changes
 
    OnActivateTool() -- Whenever a tool is made active 

Not all of these events are fully overwrite-able. For instance, OnActivateTool() will still do its default event in addition to the code that's now been integrated.

For a hypothetical situation, let’s the user needs to add a Brightness Contrast tool to a composition with a 1.8 gamma and a saturation of 1.2 every single time a new composition is made for the purposes of interactive viewing. Whenever a render is started, the tool will be disabled. However, we'll still want to call the default action, which can be done by calling "self:default" at some point in the new function.

Let's create a new scriptlib called "LoadEvents.scriptlib". This file will now be run every single time a composition is created or loaded.

-- check to see if the composition variable has been initialized.
while composition == nil do
        -- wait around
end
 
-- Check to see if the composition has a path.
 
compAttrs = composition:GetAttrs()
 
if compAttrs. COMPS_FileName == "" then
 
        -- if it doesn't, set the filename
 
        BC1 = BrightnessContrast({Gamma= 1.8, Saturation = 1.2, Comments = "Created by LoadEvents"})
 
        BC1:SetAttrs({TOOLS_Name = "BC_Interactive"})
 
        -- Set the custom data so that the tool can be found by the event script's later searching.
        BC1:SetData("EVAdjust","EVAdjust")
 
end
 
-- Set up the event suite. Put it into the globals table so that it can be removed later.
 
globals.ev = AddEventSuite("Composition")
 
 
function ev:OnStartRender(event)
        local toollist=comp:GetToolList()
        for i, tool in toollist do
               if tool:GetData("EVAdjust") == “EVAdjust” then
                     tool:SetAttrs({TOOLB_PassThrough= true})        
               end
        end
        self:Default(event)
end
 
function ev:OnEndRender(event)
        self:Default(event)
        local toollist = comp:GetToolList()
        for i, tool in toollist do
               if tool:GetData("EVAdjust") == 1 then
                     tool:SetAttrs({TOOLB_PassThrough= false})
               end
        end
end

Removing Event Suites

Removing an event suite is accomplished by running the RemoveEventSuite(suite) function. In the example scenario, the syntax would be:

RemoveEventSuite(ev)

Tips for Script Libraries and Event Scripting (edit)

Composition Scriptlibs

As mentioned in the beginning, a .scriptlib file in your main Scripts: directory will be executed every time Fusion is started and when a comp is opened. In addition to this, you can also place a .scriptlib file in your Scripts:\Comp folder (where comp scripts are located). In this case, the scriptlib will only be executed every time a comp is opened (or a new one is created). (thanks to Isaac for mentioning this on the mailing list)

If you want a scriptlib to run only once when Fusion is started, you can check for the presence of the composition variable that's available to comp and tool scripts as well:

if composition == nil then
    -- no comp: Fusion is being started
else
    -- a comp is present
end