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 Установка переменных

6.3 KiB Raw Blame History