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:

						boolDidNotFail, intError						= game.cf_operation(arg1, arg2, ...) for can_fail operations
						intResult, intError									= game.lhs_operation(lhs_arg, arg1, arg2, ...) for lhs operations
						boolDidNotFail, intResult, intError	= game.cf_lhs_operation(lhs_arg, arg1, arg2, ...) for operations which are both can_fail and lhs
						intError														= game.operation(arg1, arg2, ...) for all other operations
						
						(lhs = left hand side? Operations that assign a value, e.g. val_add)
						(cf  = can fail, e.g. agent_is_active)
					

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.

With Lhs operations, there is a slight problem. Their syntax is:
(lhs_op, <destination_param>, <param1>, <param2>, ...)

While in lua you want to write:
result = game.lhs_op(param1, param2, ...)

Why is this a problem?
Because of different parameter count. Now, WSE could detect that you are calling an Lhs operation and fill in the missing parameter, but: the operation might actually use the initial value of it to affect the result.
An obvious example for this is val_add. It makes no sense to write result = val_add(5). What is it adding 5 to?

Whether or not an operation uses the initial value can't simply be detected by WSE. So in the past it used to be that you had to write result = game.lhs_op(some_number, var1, var2, ...) for all lhs operations (some_number was just 0 mostly). Annoying.

However, after further inspection, it is reasonable to assume that only val_ operations do this. Therefore WSE update adds game.op:

						local val = game.agent_get_slot(0, agent_id, slot_no)
						local val = game.op.agent_get_slot(agent_id, slot_no)
					

It will add the 0 automatically for any lhs_operation, except for ones that start with val_. If you find operations where this is wrong, please contact AgentSmith on TaleWorlds forum.

If you don't want to write the .op all the time, call game.op.make_default(). It is optional because of legacy code.
gop = game.op also works.

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

Example:

						game.reg[0] = 123
						local i = game.reg[0]
						game.sreg[0] = "test string"
						local s = game.sreg[0]
						game.preg[0] = game.pos.new()
						local pos = game.preg[0]
					

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

						game.preg[0]:rotX(30)
					

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:

						local p = game.preg[0]
						p:rotX(30)
						game.preg[0] = p
					

To access global variables, use game.gvar.gvar_name

						game.gvar.g_encountered_party = 123
						print(game.gvar.g_encountered_party)
					

WSE will read variables.txt at startup to translate gvar_name. If this file is incorrect for any reason, accessing a gvar may produce an error or access a random gvar. You can't create new gvars.

For every header_[name].py or ID_[name].py file you copied to your "msfiles" folder, a new table will be generated: game.const.[name]
This table will be filled with all the constants from that file.
If there are two files with the same [name], e.g. header_scenes and ID_scenes, the tables will get merged.

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

						^(\w+)=(((-)?0x[\da-fA-F]+)|((-)?\d+(\.\d+)?))$
						^(\w+)=(\w+)$
					

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. To display a warning in this case, set [lua] disable_game_const_warnings = 0 in wse_settings.ini.

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:

						game.addTrigger("mst_multiplayer_dm", -28, 0, 0, condCB)
					

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

						game.addTrigger("mst_multiplayer_dm", game.const.ti_on_agent_hit, 0, 0, condCB)
						--or if you like to be specific:
						game.addTrigger("mst_multiplayer_dm", game.const.triggers.ti_on_agent_hit, 0, 0, condCB)
					

To add mission template triggers, use index = game.addTrigger(strTemplateId|intTemplateNo, 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. If conditionsCallback returns false, consequencesCallback will not be executed. If it returns true or nothing, consequencesCallback will be executed.

Example:

						function condCB()
							doStuff()
							return true
						end
						game.addTrigger("mst_multiplayer_dm", 1, 0, 0, condCB)
					

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

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

Useful functions:

• game.getCurTemplateNo() returns the index of the current mission template. Note that no template will be loaded at the time main.lua is executed.
• 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.
• game.getNumTemplates() returns number of mission templates.
• game.getTemplateId(index) returns the id/name of mission template at index.
• game.getNumTriggers(strTemplateId|intTemplateNo) returns the number of triggers for this mission template.

Item triggers:

• index = game.addItemTrigger(strItemID|intItemNo, numTriggerInterval, funcCallback)
• success = game.removeItemTrigger(strItemID|intItemNo, index)
• num = game.getNumItemTriggers(strItemID|intItemNo)

Example:

						game.addItemTrigger("itm_fighting_pick", game.const.ti_on_weapon_attack, function()
							print("agent no " .. game.store_trigger_param_1(0) .. " swung a fighting pick")
						end)
					

Scene prop triggers:

• index = game.addScenePropTrigger(strPropID|intPropNo, numTriggerInterval, funcCallback)
• success = game.removeScenePropTrigger(strPropID|intPropNo, index)
• num = game.getNumScenePropTriggers(strPropID|intPropNo)

Example:

						game.addScenePropTrigger(game.const.spr_apple_a, game.const.ti_on_scene_prop_init, function()
							print("Apple " .. game.store_trigger_param_1(0) .. " initialized.")
						end)
					

World triggers:

Due to technical reasons, these work differently. You need to assign a callback to game.OnWorldTrigger:

game.OnWorldTrigger = function(date) ... end

It will be called after the game checks the modsys triggers, and receive time in hours. It will be called even if the game is paused, but date won't change.
The game will save the state of its triggers to the savefile, so that for example ti_once does not reactivate when you load a save. You have to save this data manually if you need it. (Use game.OnSave(), game.OnLoadSave())
Time conversions according to WSE source:

• hours = date
• days = date / 24
• weeks = date / 168
• months = date / 720
• years = date / 8640

For technical reasons, if there are modsys errors in a trigger added in lua (for example invalid agent_id), it will report as line 0, opcode 5113.

To use iterators (try_for_agents, try_for_players, ...), use the provided iterator functions game.partiesIt, game.agentsIt, game.propInstIt, game.playersIt

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

						game.partiesIt()
						game.agentsIt([pos, radius, [use_grid]]) --pos: integer for pos register or table of type game.pos
						game.propInstIt([subKindNo], [metaType]) --a.k.a. [object_id], [object_type]
						game.playersIt([skip_server])
					

Example:

						for curPlayer in game.playersIt(true) do --skip server. You can also use 1 or 0
							foo(curPlayer)
						end
					

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.

						set_fixed_point_multiplier(1),
						position_get_x(":x", 0), #get pos0_x in meters
						set_fixed_point_multiplier(100),
						position_get_x(":x", 0), #get pos0_x in centimeters
					

In Lua it's simpler, you work with floating point numbers. "1.0" always means 1 meter, "0.01" always means 1 centimeter.

						--this is equivalent to above modsys example
						print(game.preg[0].o.x) --pos0_x float
					

• 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)
    										function moveX(self, val) --Move by val into local X direction
    										function moveY(self, val) --Move by val into local Y direction
    										function moveZ(self, val) --Move by val into local Z direction
    										function move(self, val) --Move by val into local directions, val must be table with any of x,y,z entries
    										function dist(self, pos2) --returns distance between self.o and pos2.o
    										function isBehind(self, pos2) --returns true if self is behind pos2 (shorthand for game.position_is_behind_position)
    									

Example:

						local pos0 = game.preg[0]
						local newRot = game.rotation.new(pos0.rot)
						local newPos = game.pos.new({rot = newRot})
						newPos:rotX(45)
						newPos:rotate({x = 90, z = 180})
						newPos:move({x = 10, z = 5})
					

You can add presentations using index = game.addPrsnt(tablePrsnt)

tablePrsnt must have the following format

						tablePrsnt = {
							id = str,
							[flags] = {int, int, ...},
							[mesh] = int,
							triggers = {[numTriggerConst] = func, ...}
						}
					

[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.

Return value: the index of the new presentation.

Example:

						--copy header_presentations.py, header_triggers.py and ID_meshes.py to your msfiles folder for this example.
						local index = game.addPrsnt({
							id = "myPrsnt",
							flags = {game.const.prsntf_read_only, game.const.prsntf_manual_end_only},
							--you can initialize an array like this, without keys - they don't matter here anyway.
							mesh = game.const.mesh_cb_ui_main,
							triggers = {
									[game.const.ti_on_presentation_load] = function ()
										--The const inside the [] declares a number key, similar to keyName = 123 for string keys.
										game.presentation_set_duration(9999999)
										local overlay = game.create_mesh_overlay(0, game.const.mesh_mp_ingame_menu)
							
										local position = game.pos.new()
										position.o.x = 0.3
										position.o.y = 0.3
										game.overlay_set_position(overlay, position)
							
										position.o.x = 0.5
										position.o.y = 0.8
										game.overlay_set_size(overlay, position)
									end
							}
						})
						game.start_presentation(index)
					

Remove using game.removePrsnt(index). Remember, removing will shift above indices.

On dedicated, add/remove will do and return nothing.

For technical reasons, if there are modsys errors in a presentation added in lua (for example invalid agent_id), it will report as line 0, opcode 5113.

You can add particle systems using index = game.addPsys(tablePsys)

tablePsys must have the following format

						tablePsys = {
							id = str, [flags] = {int, int, ...}, mesh = str|int,
							num_particles = int, life = num, damping = num, gravity_strength = num, turbulance_size = num, turbulance_strength = num,
							alpha_keys			= {{num, num}, {num, num}},
							  red_keys			= {{num, num}, {num, num}},
							green_keys			= {{num, num}, {num, num}},
							 blue_keys			= {{num, num}, {num, num}},
							scale_keys			= {{num, num}, {num, num}},
							emit_box_size		= {num, num, num},
							emit_velocity		= {num, num, num},
							emit_dir_randomness = num,
							rotation_speed = num,
							rotation_damping = num
						}
					

[flags] can be omited and defaults to no flags at all.

Return value: the index of the new particle system.

Example:

							local psys = game.addPsys({id = "blabla", flags = {game.const.psf_billboard_3d, game.const.psf_global_emit_dir}, mesh = "prt_mesh_snow_fall_1",
								num_particles = 150,
								life = 2,
								damping = 0.2,
								gravity_strength = 0.1,
								turbulance_size = 30,
								turbulance_strength = 20,
								alpha_keys = {{0.2, 1}, {1, 1}},
								red_keys = {{1.0, 1.0}, {1, 1.0}},
								green_keys = {{1.0, 1.0}, {1, 1.0}},
								blue_keys = {{1.0, 1.0}, {1, 1.0}},
								scale_keys = {{1.0, 1.0},   {1.0, 1.0}},
								emit_box_size = {10, 10, 0.5},
								emit_velocity = {0, 0, -5.0},
								emit_dir_randomness = 1,
								rotation_speed = 200,
								rotation_damping = 0.5
							})
							game.particle_system_burst(psys, game.preg[0], 20)
					

Remove using game.removePsys(index). Remember, removing will shift above indices.

On dedicated, add/remove will do and return nothing.

You can hook module operations using game.hookOperation(operation, funcCallback).

This means whenever the module system uses the operation, your callback will be executed first.

operation must be either the operation name as a string or an opcode integer.

Operation hooks are experimental - it can be very useful, but you risk crashes.

The return values of funcCallback control further behaviour.

If it returns nothing or true, the module operation will be executed as usual.

If the first return value is false, the module operation will not be executed.

If the second return value is a bool, the module system will think it is executing a cf operation (so if the bool is false, it will break execution, like e.g. (eq, 1, 0),).

If the second return value is a number, the module system will think it is executing a lhs operation and try to set the return value

If the callback returns three values, the module system will think it is executing a cf/lhs operation. The 2nd return value must be the cf value and the 3rd the lhs value

In short, the variants are:

						boolExecute
						boolExecute, boolFail
						boolExecute, numLhs
						boolExecute, boolFail, numLhs
					

To unhook an operation, use game.hookOperation(operation, nil).

The hook will not be triggered when calling operations from lua. However, this task can be achieved by overwritting the game metatable, which is defined as:

						game.mt = {
								__index = function(table, key)
										return function(...)
												return game.execOperation(key,...)
										end
								end
						}
					

One could, for example, do (NOT FINISHED YET):

						game.mt = {
								__index = function(table, key)
										If key == "player_get_gold" then
												return myCustomGoldCalculation
												--return function that takes all args (...) and returns gold
												--this function should, if neccessary, use game.execOperation("player_get_gold", args)
												--instead of game.player_get_gold(args), for avoiding an infinite loop.
										end
										return function(...)
												return game.execOperation(key,...)
										end
								end
						}
						setmetatable(game, game.mt)
					

You could even go one step further and create a wrapper for game.hookOperation that automates this process for you.

You can hook scripts using game.hookScript(script_no, funcCallback).

funcCallback will receive all script parameters. Its return values control further behaviour:

If it returns false, the script will not be executed.

If it returns numbers, the script parameters will be replaced with them, then the script is executed.

Example:

						local a = 0
						game.hookScript(game.script.game_get_console_command, function(...)
						  print("Hook")
						  a = a + 1

						  if a <= 5 then
						    local s = ""
						    for i = 1, select("#", ...) do
						      s = s .. tostring(select(i, ...)) .. "     "
						    end

						    print("CONSOLE CMD", a, "blocked, params were: ", s)
						    return false

						  elseif a <= 10 then
						    return 2, 1, 4 --set team 1 bot count to 4. At least for NW

						  elseif a == 15 then
						    game.hookScript(game.script.game_get_console_command, nil)
						  end
						end)
					

To unhook a script, use game.hookScript(script_no, nil).

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

  Example:

  									local no = game.getScriptNo("game_start")
  									game.call_script(no)
  								

  WSE Update now provides a wrapper: game.script.[name]

  										game.call_script(game.script.game_start)
  									

• game.getCurTemplateNo() returns the index of the current mission template. Note that no template will be loaded at the time main.lua is executed.
• 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.
• game.getNumTemplates() returns number of mission templates.
• game.getTemplateId(index) returns the id/name of mission template at index.
• game.getNumTriggers(strTemplateId|intTemplateNo) returns the number of triggers for this mission template.
• game.getMeshId(index) returns name of mesh at index (mesh no). Note: This does not access the mesh list in module_meshes. Index is for the internal list of all meshes loaded from the .brf files.
• game.getNumMeshes() returns number of meshes. Note: This does not access the mesh list in module_meshes. It is for the internal list of all meshes loaded from the .brf files.
• game.OnRglLogWrite(str) this function, if it exists, gets called when something gets written to rgl_log.txt. It receives the log message as its parameter. A bad idea is to use game.display_message in this function, as it will easily cause an infinite loop. You can however use print(). Any error (which would normally trigger the event again, which would trigger the error, ...) caused by this function will be catched and logged safely.

• game.OnChatMessageReceived(intPlayerNo, boolIsTeamChat, strMsg) this function, if it exists, gets called when a chat message is received (both client and server). It will be called after the corresponding module system script. If it returns a string the message will be overwritten, if it returns true the message will be supressed. Returning something will overwrite any action the module script may have taken.

• game.OnGameLoad() this function, if it exists, gets called when the game loads.

  game.OnSave() this function, if it exists, gets called after a game is saved successfully.

  game.OnLoadSave() this function, if it exists, gets called after a savegame is loaded successfully.

• game.fail() when used during a lua_call operation it will make the MS code fail, like any other cf operation can do.

  Example:

  								(try_begin),
  										(lua_push_int, 456),
  										(lua_call, "@is123", 1),
  										(display_message, "@Yes it is."),
  								(else_try),
  										(display_message, "@Nah"),
  								(try_end),
  							

  								function is123(val)
  										if val ~= 123 then
  												game.fail()
  										end
  								end
  							

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.getOperationFlags(strOperationName) - Flags: None = 0x0, Lhs = 0x1, Cf = 0x2 (this is what WSE figured from reading header_operations.py, the engine may not agree).
• game.getReg(intTypeId, intIndex) typeIds are: 0 = int, 1 = str, 2 = pos
• game.setReg(intTypeId, intIndex, val)
• game.getGvar(key)
• game.setGvar(key, value)