CommandLua

Contents

• Selector
• Wrapper/Descriptor
• Data types
• Notes
• Functions
• Tables

Reference

• ScenEdit

Topics

• 01-getting-started
• 02-creation
• 98-event_handling
• 99-code-examples

Examples

• mission1.lua
• scenedit_addunit.lua
• scenedit_mission.lua

Module ScenEdit

Lua is a case sensitive language.

When accessing object properties directly as in ‘unit.name’, the property should be in lower which will match the Lua generated code. There may be a few special cases (e.g. mission.SISH=true which is a shortcut for scrub_if_side_human) which will be documented below.

However, when accessing the properties through the module functions below, both the keyword/property and the value are case insensitive; the code will worry about matching them up.

Selector
These define the information required as part of the ‘select’ process for the functions. In the case of functions that ‘add’ things, these are also key elements to the adding process. Other properties may be included in the ‘selector’ such as when updating an existing table.

When selecting units, it is preferable to use the GUID as the identifier for a precise match. If not, then the side and name for a more limited search. And as a last option, just the name which search all units in the scenario. When using just the name, usually the first matching name is returned. This is okay if the names are unique. Thus including the side, it will only check the units on that side for a match.

Wrapper
These define the information that is returned from some functions. This information can be usually modified either directly (object.field) or by a wrapper Set(..) function. The particular wrapper Set(..) function is preferred as some validation is performed on the input to ensure that it is within the bounds of the field being updated.

Data type
These cover any special considerations for the data, such as longitude/latitude; degrees, DMS, N/S, E/W, etc.

Error handling
Usually when a Lua script fails, an error is thrown that ends the script at that point. While this may be okay in most cases, it is not often desired. Whenever a Command Lua function gets an error, it will normally return a ‘nil’, and the error message will be available as a Lua global variables; ‘errmsg’ will have the last error message, ‘errfnc’ the Command Lua function that gave the error, and ‘errnum’ the error code (0 is no error, and any value >0 will be an error). Thus if you get back a ‘nil’, you can check to see if that is due to an error or no data.

Example:
without the new error handling, the script below would probably terminate after the SE_AddMission() and the rest of script would not run.

local mission = ScenEdit_AddMission('USA','Marker strike','strike',{type='land'})
if mission == nil then
 if _errnum_ ~= 0 then print('Failed to add:' .. _errmsg_) else print('Something else') end
else
 print(mission)
 do some more command lua stuff...
end

Note: Due to how errors are now handle from SR7, if a command fails in the console window, it will show an error. If the command runs outside the console (as in an event script), it will not fail with a visible error but return a nil or or some other value. One issue with commands running in an event is that sometimes they fail with an in-game message that actually stops the rest of the script from running. Now, these event scripts will run without any in-game message showing, and the designer should check the result of the command and handle any error condition, and let the remaining script run as needed.

My intent is have all command errors behave in the same fashion in the console window; and the command errors outside a console behave without stopping the script. Which requires the designer to cater for the specific error conditions.

To emulate the expected outcome from an event, put Tool_EmulateNoConsole(true) at the start of the script to be tested; it is not required in the event code as the script is already not running in a console.

Note also, that the Lua history log should also record the event script errors.

Selector

Wrapper/Descriptor

Data types

Notes

Functions

Tables

Selectors

ActionUpdate

• ID: string The GUID of the action [READONLY]
• Description: string Description or GUID of action
• NewName: string If specified, the new name of the action
• Mode: string Operation to do - ‘list’, ‘add’, ‘remove’, ‘update’ (default) SE_Set…()
• Type: string Type of action [required only for ‘add’ option]
• Other: various values apply to Type of action.

ConditionUpdate

• ID string The GUID of the condition [READONLY]
• Description string Description or GUID of condition
• NewName string If specified, the new name of the condition
• Mode string Operation to do - ‘list’, ‘add’, ‘remove’, ‘update’ (default) SE_Set…()
• Type string Type of condition [required only for ‘add’ option]
• Other various values apply to Type of condition.