Skip to content

Lua Scripting System

Configuration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
    //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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
-- 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