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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
# Lua Scripting System
## Configuration
```json
{
//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
```lua
-- 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](https://www.lua.org/manual/5.1/manual.html)
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
|
