vcmi/docs/developers/Lua_Scripting_System.md

Lua Scripting System

Configuration

{
 	//general purpose script, Lua or ERM, runs on server
 	"myScript":
	{
		"source":"path/to/script/with/ext",
		"implements":"ANYTHING"
	},


 	//custom battle spell effect, Lua only, runs on both client and server
 	//script ID will be used as effect 'type' (with mod prefix)
 	"mySpellEffect":
	{
		"source":"path/to/script/with/ext",
		"implements":"BATTLE_EFFECT"
	},

	//TODO: object|building type
 	//custom map object or building, Lua only, runs on both client and server
 	//script ID will be used as 'handler' (with mod prefix)
 	"myObjectType":
	{
		"source":"path/to/script/with/ext",
		"implements":"MAP_OBJECT"
	},
	//TODO: server query
	//TODO: client query

}

Lua

API Reference

TODO In near future Lua API may change drastically several times. Information here may be outdated

Globals

• DATA - persistent table
• • DATA.ERM contains ERM state, anything else is free to use.
• GAME - IGameInfoCallback API
• BATTLE - IBattleInfoCallback API
• EVENT_BUS - opaque handle, for use with events API
• SERVICES - root "raw" access to all static game objects
• • SERVICES:artifacts()
• • SERVICES:creatures()
• • SERVICES:factions()
• • SERVICES:heroClasses()
• • SERVICES:heroTypes()
• • SERVICES:spells()
• • SERVICES:skills()
• require(URI)
• -works similar to usual Lua require
• -require("ClassName") - loads additional API and returns it as table (for C++ classes)
• -require("core:relative.path.to.module") - loads module from "SCRIPTS/LIB"
• -TODO require("modName:relative.path.to.module") - loads module from dependent mod
• -TODO require(":relative.path.to.module") - loads module from same mod
• logError(text) - backup error log function

Low level events API

-- Each event type must be loaded first
local PlayerGotTurn = require("events.PlayerGotTurn")

-- in this example subscription handles made global, do so if there is no better place
-- !!! do not store them in local variables
sub1 = 	PlayerGotTurn.subscribeAfter(EVENT_BUS, function(event)
		--do smth
	end)

sub2 = 	PlayerGotTurn.subscribeBefore(EVENT_BUS, function(event)
		--do smth
	end)

Lua standard library

VCMI uses LuaJIT, which is Lua 5.1 API, see upstream documentation

Following libraries are supported

• base
• table
• string
• math
• bit

ERM

Features

• no strict limit on function/variable numbers (technical limit 32 bit integer except 0))
• TODO semi compare
• DONE macros

Bugs

• TODO Broken XOR support (clashes with `X` option)

Triggers

• TODO !?AE Equip/Unequip artifact
• WIP !?BA when any battle occurs
• WIP !?BF when a battlefield is prepared for a battle
• TODO !?BG at every action taken by any stack or by the hero
• TODO !?BR at every turn of a battle
• !?CM (client only) click the mouse button.
• TODO !?CO Commander triggers
• TODO !?DL Custom dialogs
• DONE !?FU function
• TODO !?GE "global" event
• TODO !?GM Saving/Loading
• TODO !?HE when the hero # is attacked by an enemy hero or visited by an allied hero
• TODO !?HL hero gains a level
• TODO !?HM every step a hero # takes
• !?IP Multiplayer support.
• TODO !?LE (!$LE) An Event on the map
• WIP !?MF stack taking physical damage(before an action)
• TODO !?MG casting on the adventure map
• !?MM scroll text during a battle
• TODO !?MR Magic resistance
• TODO !?MW Wandering Monsters
• WIP !?OB (!$OB) visiting objects
• DONE !?PI Post Instruction.
• TODO !?SN Sound and ERA extensions
• !?TH town hall
• TODO !?TL Real-Time Timer
• TODO !?TM timed events

Receivers

VCMI

• !!MC:S@varName@ - declare new "normal" variable (technically v-var with string key)
• TODO Identifier resolver
• WIP Bonus system

ERA

• DONE !!if !!el !!en
• TODO !!br !!co
• TODO !!SN:X

WoG

• TODO !!AR Артефакт (ресурс) в определенной позиции
• TODO !!BA Битва
• !!BA:A$ return 1 for battle evaluation
• TODO !!BF Препятствия на поле боя
• TODO !!BG Действий монстров в бою
• TODO !!BH Действия героя в бою
• TODO !!BM Монстр в битве
• WIP !!BU Универсальные параметры битвы
• TODO !!CA Замок
• TODO !!CD Разрушения замков
• TODO !!CE События в замке
• TODO !!CM Клика мышью
• TODO !!DL Нестандартный диалог (только ТЕ или выше)
• TODO !!CO Командиры
• WIP !!DO Многократный вызов функции
• TODO !!EA Бонусы опыта существ
• TODO !!EX Опыт стека
• DONE !!FU Однократный вызов функции
• TODO !!GE Глобальное событие
• WIP !!HE Герой
• TODO !!HL Новый уровень героя
• TODO !!HO Взаимодействия героев
• TODO !!HT Подсказки по правому клику
• WIP !!IF Диалоги и флагов
• TODO !!IP Сетевой сервис битвы
• TODO !!LE Локальное события
• WIP !!MA Общие параметры монстров
• DONE !!MC Макросы
• WIP !!MF Получение физ. урона в бою
• TODO !!MM Текст в битве
• WIP !!MO Монстр в определенной позиции
• TODO !!MP Контроль MP3
• TODO !!MR Сопротивления магии
• TODO !!MW Бродячих монстров
• WIP !!OB Объект в определенной позиции
• TODO !!OW Параметры игрока
• TODO !!PM Пирамиды или новые объекты
• TODO !!PO Информация квадрата карты
• TODO (???) !!QW Журнала
• TODO !!SN Проигрываемые звуков
• TODO !!SS Настройка заклинаний (только ТЕ или выше)
• TODO !!TL Контроль времени хода (только ТЕ или выше)
• TODO !!TM Временный таймер
• TODO !!TR Квадрата карты (почва, проходимость, т.п.)
• TODO !!UN Универсальная команда
• !#VC Контроль переменных
• WIP !!VR Установка переменных

Persistence