mirror of
https://github.com/vcmi/vcmi.git
synced 2024-12-26 22:57:00 +02:00
204 lines
6.3 KiB
Markdown
204 lines
6.3 KiB
Markdown
< [Documentation](../Readme.md) / Lua Scripting System
|
|
|
|
# Configuration
|
|
|
|
``` javascript
|
|
{
|
|
//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 |