How to use WSE/LUA

To call operations, use game.operation_name(arg1, arg2, ...)

Example: game.display_message("test string")

String and pos arguments are passed to the game via the games registers (overwritting them), starting from reg[128] and counting downwards.

Notice that the argument type matters. For example, if an operation expects an integer, you cannot pass a string that contains a number.

Return values are:

While most Lhs operations don't require an actual value for lhs_arg (in those cases it's strictly a return variable, for example player_get_gold), some (for example val_add) do, so you have to specify it anyway.

Real-world lhs_operation example:

Note that in Lua, you don't have to assign all return values. For example, if you don't care about the error code, just omit the corresponding lhs var.

I'm not sure what the error code signalizes, however it should be 0 if there was no error.

To access registers, use game.reg[n] , game.sreg[n] and game.preg[n]

Example:

As of the current version, registers are copied by value instead of by reference. So doing things like:

Does not change the actual game register. This is likely going to be improved in a future version. What you have to do instead for now is:

For every header_[name].py or ID_[name].py file you copied to your "msfiles" folder (except header_operations.py), a new table will be generated: game.const.[name]

This table will be filled with all the constants from that file.

As of the current version, only lines that match one of the two following regexes (regular expressions) will be accepted:

This probably looks intimidating to you, but really all it says is that your constant must either be a number, a hex number, or another constant (from the same file, currently).

In other words: constant = num|hexNum|otherConstant

If the match fails, the line will be ignored and a warning message will be triggered which you can safely ignore.

You can omit the [name] part in game.const.[name].[constant], in which case all tables in game.const will be searched for your constant and the first result will be used.

So let's say you want to add a deathmatch trigger for ti_on_agent_hit. Instead of this:

You could copy header_triggers.py to your msfiles folder and do:

To add triggers, use game.addTrigger(strTemplateId, numCheckTime, numDelayTime, numRearmTime, funcConditionsCallback, [funcConsequencesCallback])

These work exactly like module system triggers. Times can be float values or values from header_triggers.py (the numbers, string names are not supported yet), just like you would do it in the MS. The callbacks must return a boolean. If conditionsCallback returns false, consequencesCallback will not be executed.

This function is fairly expensive, as it involves copying the entire array of triggers and then adding the new one.

Example:

addTrigger returns an integer that is the index of the added trigger.

You can also remove triggers by using game.removeTrigger(strTemplateId, intTriggerIndex). If intTriggerIndex is negative, the trigger with (numTriggers + intTriggerIndex) gets removed (e.g. to remove the last trigger, use -1).

To use iterators (try_for_agents, try_for_players, ...), use the provided iterator functions game.partiesI, game.agentsI, game.propInstI, game.playersI

These work exactly like module system iterators and take the same arguments.

Example:

To work with positions, the following "classes" are provided: game.rotation, game.pos and vector3 (see under miscellaneous)

Keep in mind that these don't need the fixed point multiplier that the module system requires you to use.

The MS multiplier is essentially a way of specifying the current unit of length.

MS Example:

Consider the lua counterpart to "always have a fixed point multiplier of 1".

• game.rotation

  • game.rotation.new([obj]) - constructor. obj can be used to specify initial values.

  • game.rotation.prototype

    s = vector3.new({x = 1}) --x axis

    f = vector3.new({y = 1}) --forwards/y axis

    u = vector3.new({z = 1}) --up/z axis

    function getRot(self) --returns vector3.new({z = yaw, x = pitch, y = roll})

    function rotX(self, angle) --rotate around x axis, angle in degrees

    function rotY(self, angle) --rotate around y axis, angle in degrees

    function rotZ(self, angle) --rotate around z axis, angle in degrees

    function rotate(self, rotVec3) --rotate around all axis, zxy order, angle in degrees

• game.pos

  • game.pos.new([obj]) - constructor. obj can be used to specify initial values.

  • game.pos.prototype

    o = vector3.new() --position in the world

    rot = game.rotation.new() --rotation, or heading of the pos if you like

     

    --see game.rotation.prototype for these

    function getRot(self)

    function rotX(self, angle)

    function rotY(self, angle)

    function rotZ(self, angle)

    function rotate(self, rotVec3)

Example:

You can add presentations using game.addPrsnt(tablePrsnt)

tablePrsnt must have the following format

[flags] can be omited and defaults to no flags at all. If you copied header_presentation.py to your msfiles folder, you can use the flags defined there.

[mesh] can be omited and defaults to 0. If you copied ID_meshes.py to your msfiles folder, you can use the mesh nos defined there.

triggers must have at least one element, the key being a number and the value being a function. If you copied header_triggers.py to your msfiles folder, you can use the trigger values defined there.

Basic example:

• game.getScriptNo(script_name), use in conjunction with game.call_script(scriptNo, ...)

  Example:

  local no = game.getScriptNo("game_start")

  game.call_script(no)

• game.getCurTemplateId(), returns the id/name of the current mission template. Note that no template will be loaded at the time main.lua is executed.

Other WSE LUA API functions - these could be useful for advanced users, but you should get along fine without ever using them.

• game.execOperation(strOperationName, arg1, arg2, ....) - see operations

• game.getReg(intTypeId, intIndex) typeIds are: 0 = int, 1 = str, 2 = pos

• game.setReg(intTypeId, intIndex, val)

• tableShallowCopy(t, copyMetatable) - returns a copy of table t, however any object items will still reference the same object. If copyMetatable ~= nil, the returned table will have the same metatable as t, as given by getmetatable(t).
• tableRecursiveCopy(t, copyMetatable) - returns a copy of table t. All table items in t and further down the "tree" will be actual copies by value instead of by reference. If copyMetatable ~= nil, all metatables will be copied (by value), as given by getmetatable(t).
• vector3 - class for storing and manipulating 3D vectors

  • vector3.prototype

    x = 0

    y = 0

    z = 0

    function len(self) --returns the length of the vector

  • vector3.new([obj]) - constructor. obj; can be used to specify initial values.

  • vector3 operators + - * ==

  • Example:

    local vecA = vector3.new({x = 60, y = 30})

    local vecB = vector3.new()

     

    game.display_message(tostring(vecA:len())) --67.08...

     

    if vecA == vecB then

    --will not happen

    end

     

    vecA = vecA * vecB --{60*0, 30*0, 0*0}

    if vecA == vecB then

    --will happen

    end

Changes include:

• Disabled package.loadlib, package.cpath, io.popen. os.execute, os.getenv, os.tmpname, ffi library, loading bytecode (can be exploited)

• Restrict dofile, loadfile and all IO operations to the lua directory