There are three other built-in functions that may prove useful to you: dofile, require, and type.
Loads and executes a script file. The contents of the file will be executed as though it was typed directly into the script. The syntax is:
dofile(file_path);
For example, say we typed the following script into a file called MyScript.lua (just a text file containing this script, created with notepad or some other text editor):
Dialog.Message("Hello", "World");
Now we drag and drop the file onto AutoPlay Media Studio’s main window. (This will copy the file into the project's Scripts folder.) A dialog will appear that asks if we want to add a require line to our global script. Click “No” for now. We will explain the require statement later.
Now, wherever we add the following line of script to an event:
dofile(_SourceFolder.."\\AutoPlay\\Scripts\\MyScript.lua");
...that script file will be read in and executed immediately. In this case, you would see a message box with the friendly “hello world” message.
Tip: Use the dofile function to save yourself from having to re-type or re-paste a script into your projects over and over again.
Loads and runs a script file into the scripting engine. It is similar to dofile except that it will only load a given file once per session, whereas dofile will re-load and re-run the file each time it is used. The syntax is:
require(file_path);
If the file is located in AutoPlay's Scripts folder, you should not include the file extension.
So, for example, even if you do two requires in a row:
require("foo");
require("foo"); -- this line won't do anything
...only the first one will ever get executed. After that, the scripting engine knows that the file has been loaded and run, and future calls to require that file will have no effect.
Note that as long as you put the .lua file into your project’s Scripts folder, you don't even have to provide a full path to the file. For example:
require("MyScript");
...is the same as:
require(_SourceFolder.."\\AutoPlay\\Scripts\\MyScript.lua");
Since require will only load a given script file once per session, it is best suited for loading scripts that contain only variables and functions. Since variables and functions are global by default, you only need to “load” them once; repeatedly loading the same function definition would just be a waste of time.
This makes the require function a great way to load external script libraries. Every script that needs a function from an external file can safely require() it, and the file will only actually be loaded the first time it’s needed.
This function will tell you the type of value contained in a variable. It returns the string name of the variable type. Valid return values are “nil,” “number,” “string,” “boolean,” “table,” “function,” "thread," and "userdata." For example:
a = 989;
strType = type(a); -- sets strType to "number"
a = "Hi there";
strType = type(a); -- sets strType to "string"
The type function is especially useful when writing your own functions that need certain data types in order to operate. For example, the following function uses type() to make sure that both of its arguments are numbers:
-- find the maximum of two numbers
function Max(Number1, Number2)
-- make sure both arguments are numeric
if (type(Number1) ~= "number") or (type(Number2)
~= "number") then
Dialog.Message("Error",
"Please enter numbers");
return nil -- we're using nil
to indicate an error condition
else
if Number1 >= Number2 then
return
Number1;
else
return
Number2;
end
end
end
AutoPlay Media Studio comes with a large number of built-in functions. In the program interface, these built-in functions are commonly referred to as actions. For scripting purposes, actions and functions are essentially the same; however, the term “actions” is generally reserved for those functions that are built into the program and are included in the alphabetical list of actions in the online help. When referring to functions that have been created by other users or yourself, the term “functions” is preferred.