From 88fe079f95e16cd8e0e1f3184d968690ce4c6b91 Mon Sep 17 00:00:00 2001 From: AnyOldName3 Date: Fri, 17 Jan 2025 00:53:19 +0000 Subject: [PATCH 01/76] Don't mangle settings with the comment character in their value '#' is a valid character in setting values - it's only a comment if it's the first non-" \t\r\n" character on a line. Making the comment ignoring match the parser we use elsewhere should avoid mangling data. --- apps/mwiniimporter/importer.cpp | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/apps/mwiniimporter/importer.cpp b/apps/mwiniimporter/importer.cpp index 8c7c238b4a..cc38eed211 100644 --- a/apps/mwiniimporter/importer.cpp +++ b/apps/mwiniimporter/importer.cpp @@ -352,12 +352,10 @@ MwIniImporter::multistrmap MwIniImporter::loadCfgFile(const std::filesystem::pat std::string line; while (std::getline(file, line)) { - - // we cant say comment by only looking at first char anymore - int comment_pos = static_cast(line.find('#')); - if (comment_pos > 0) + // ignore comments - keep in sync with configfileparser.cpp + if (line.find('#') == line.find_first_not_of(" \t\r\n")) { - line = line.substr(0, comment_pos); + continue; } if (line.empty()) From e345fca99a4fe987bb9a13aa9ee7a79e6191a2a2 Mon Sep 17 00:00:00 2001 From: AnyOldName3 Date: Fri, 17 Jan 2025 01:21:24 +0000 Subject: [PATCH 02/76] trim_ws, too --- apps/mwiniimporter/importer.cpp | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/apps/mwiniimporter/importer.cpp b/apps/mwiniimporter/importer.cpp index cc38eed211..c3b23eff5c 100644 --- a/apps/mwiniimporter/importer.cpp +++ b/apps/mwiniimporter/importer.cpp @@ -11,6 +11,23 @@ namespace sfs = std::filesystem; +namespace +{ + // from configfileparser.cpp + std::string trim_ws(const std::string& s) + { + std::string::size_type n, n2; + n = s.find_first_not_of(" \t\r\n"); + if (n == std::string::npos) + return std::string(); + else + { + n2 = s.find_last_not_of(" \t\r\n"); + return s.substr(n, n2 - n + 1); + } + } +} + MwIniImporter::MwIniImporter() : mVerbose(false) , mEncoding(ToUTF8::WINDOWS_1250) @@ -371,6 +388,8 @@ MwIniImporter::multistrmap MwIniImporter::loadCfgFile(const std::filesystem::pat std::string key(line.substr(0, pos)); std::string value(line.substr(pos + 1)); + key = trim_ws(key); + value = trim_ws(key); if (map.find(key) == map.end()) { From 33553c0cf7aeebd334a1a5c7b6e857251409451f Mon Sep 17 00:00:00 2001 From: AnyOldName3 Date: Fri, 17 Jan 2025 01:34:08 +0000 Subject: [PATCH 03/76] Handle encoding a bit more cleverly * use the value from the existing openmw.cfg if it exists and we weren't told to use something else on the command line * write the value to openmw.cfg if it wasn't there or we've overridden it --- apps/mwiniimporter/main.cpp | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/apps/mwiniimporter/main.cpp b/apps/mwiniimporter/main.cpp index 0beb2b38cc..b934d0967e 100644 --- a/apps/mwiniimporter/main.cpp +++ b/apps/mwiniimporter/main.cpp @@ -126,12 +126,20 @@ int wmain(int argc, wchar_t* wargv[]) MwIniImporter importer; importer.setVerbose(vm.count("verbose") != 0); + MwIniImporter::multistrmap cfg = importer.loadCfgFile(cfgFile); + // Font encoding settings - std::string encoding(vm["encoding"].as()); + std::string encoding; + if (vm["encoding"].defaulted() && cfg.contains("encoding") && !cfg["encoding"].empty()) + encoding = cfg["encoding"].back(); + else + { + encoding = vm["encoding"].as(); + cfg["encoding"] = {encoding}; + } importer.setInputEncoding(ToUTF8::calculateEncoding(encoding)); MwIniImporter::multistrmap ini = importer.loadIniFile(iniFile); - MwIniImporter::multistrmap cfg = importer.loadCfgFile(cfgFile); if (!vm.count("fonts")) { From 84c497b1fb4ca4d254e3b2c5daa6e5e9b5eb214d Mon Sep 17 00:00:00 2001 From: AnyOldName3 Date: Fri, 17 Jan 2025 01:45:09 +0000 Subject: [PATCH 04/76] capitulate --- apps/mwiniimporter/main.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/mwiniimporter/main.cpp b/apps/mwiniimporter/main.cpp index b934d0967e..6e4242cb4e 100644 --- a/apps/mwiniimporter/main.cpp +++ b/apps/mwiniimporter/main.cpp @@ -135,7 +135,7 @@ int wmain(int argc, wchar_t* wargv[]) else { encoding = vm["encoding"].as(); - cfg["encoding"] = {encoding}; + cfg["encoding"] = { encoding }; } importer.setInputEncoding(ToUTF8::calculateEncoding(encoding)); From 5b18edf938626c7e342500f52ffea61edfce2542 Mon Sep 17 00:00:00 2001 From: Alexei Kotov Date: Wed, 5 Mar 2025 19:55:21 +0300 Subject: [PATCH 05/76] Interrupt bound item effect if equipment failed (#8383) --- apps/openmw/mwmechanics/spelleffects.cpp | 42 ++++++++++++++---------- 1 file changed, 25 insertions(+), 17 deletions(-) diff --git a/apps/openmw/mwmechanics/spelleffects.cpp b/apps/openmw/mwmechanics/spelleffects.cpp index 7035c7f61c..c5af5f2bae 100644 --- a/apps/openmw/mwmechanics/spelleffects.cpp +++ b/apps/openmw/mwmechanics/spelleffects.cpp @@ -174,7 +174,7 @@ namespace return -1; } - void addBoundItem(const ESM::RefId& itemId, const MWWorld::Ptr& actor) + bool addBoundItem(const ESM::RefId& itemId, const MWWorld::Ptr& actor) { MWWorld::InventoryStore& store = actor.getClass().getInventoryStore(actor); MWWorld::Ptr boundPtr = *store.MWWorld::ContainerStore::add(itemId, 1); @@ -185,9 +185,6 @@ namespace MWWorld::ActionEquip action(boundPtr); action.execute(actor); - if (actor != MWMechanics::getPlayer()) - return; - MWWorld::Ptr newItem; auto it = slot >= 0 ? store.getSlot(slot) : store.end(); // Equip can fail because beast races cannot equip boots/helmets @@ -195,16 +192,24 @@ namespace newItem = *it; if (newItem.isEmpty() || boundPtr != newItem) - return; + { + store.remove(boundPtr, 1); + return false; + } - MWWorld::Player& player = MWBase::Environment::get().getWorld()->getPlayer(); + if (actor == MWMechanics::getPlayer()) + { + MWWorld::Player& player = MWBase::Environment::get().getWorld()->getPlayer(); - // change draw state only if the item is in player's right hand - if (slot == MWWorld::InventoryStore::Slot_CarriedRight) - player.setDrawState(MWMechanics::DrawState::Weapon); + // change draw state only if the item is in player's right hand + if (slot == MWWorld::InventoryStore::Slot_CarriedRight) + player.setDrawState(MWMechanics::DrawState::Weapon); - if (prevItem != store.end()) - player.setPreviousItem(itemId, prevItem->getCellRef().getRefId()); + if (prevItem != store.end()) + player.setPreviousItem(itemId, prevItem->getCellRef().getRefId()); + } + + return true; } void removeBoundItem(const ESM::RefId& itemId, const MWWorld::Ptr& actor) @@ -626,16 +631,19 @@ namespace MWMechanics case ESM::MagicEffect::BoundHelm: case ESM::MagicEffect::BoundBoots: case ESM::MagicEffect::BoundShield: + { if (!target.getClass().hasInventoryStore(target)) - invalid = true; - else { - const std::string& item = sBoundItemsMap.at(effect.mEffectId); - addBoundItem(ESM::RefId::stringRefId( - world->getStore().get().find(item)->mValue.getString()), - target); + invalid = true; + break; } + const std::string& item = sBoundItemsMap.at(effect.mEffectId); + const MWWorld::Store& gmst = world->getStore().get(); + const ESM::RefId itemId = ESM::RefId::stringRefId(gmst.find(item)->mValue.getString()); + if (!addBoundItem(itemId, target)) + invalid = true; break; + } case ESM::MagicEffect::FireDamage: case ESM::MagicEffect::ShockDamage: case ESM::MagicEffect::FrostDamage: From 918a6352e4ce3098a59ea06d69431676aecfbbf4 Mon Sep 17 00:00:00 2001 From: Alexei Kotov Date: Wed, 5 Mar 2025 23:43:35 +0300 Subject: [PATCH 06/76] Let cancelled bound item effect remain active for the frame --- apps/openmw/mwmechanics/spelleffects.cpp | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/apps/openmw/mwmechanics/spelleffects.cpp b/apps/openmw/mwmechanics/spelleffects.cpp index c5af5f2bae..91e24f946f 100644 --- a/apps/openmw/mwmechanics/spelleffects.cpp +++ b/apps/openmw/mwmechanics/spelleffects.cpp @@ -192,10 +192,7 @@ namespace newItem = *it; if (newItem.isEmpty() || boundPtr != newItem) - { - store.remove(boundPtr, 1); return false; - } if (actor == MWMechanics::getPlayer()) { @@ -641,7 +638,7 @@ namespace MWMechanics const MWWorld::Store& gmst = world->getStore().get(); const ESM::RefId itemId = ESM::RefId::stringRefId(gmst.find(item)->mValue.getString()); if (!addBoundItem(itemId, target)) - invalid = true; + effect.mTimeLeft = 0.f; break; } case ESM::MagicEffect::FireDamage: From 3f63700e993367c45548c995f6bf0fb30d02d737 Mon Sep 17 00:00:00 2001 From: Alexei Kotov Date: Sun, 9 Mar 2025 19:20:24 +0300 Subject: [PATCH 07/76] Improve topic and magic effect list padding accuracy This also touches the quest list, but there are bigger problems with the journal than just padding --- apps/openmw/mwgui/dialogue.cpp | 5 ++++- components/widgets/list.cpp | 29 ++++++++++++++++------------- components/widgets/list.hpp | 15 +++++++++++++-- 3 files changed, 33 insertions(+), 16 deletions(-) diff --git a/apps/openmw/mwgui/dialogue.cpp b/apps/openmw/mwgui/dialogue.cpp index e14c400978..6b1e007770 100644 --- a/apps/openmw/mwgui/dialogue.cpp +++ b/apps/openmw/mwgui/dialogue.cpp @@ -588,10 +588,13 @@ namespace MWGui if (mTopicsList->getItemCount() > 0) mTopicsList->addSeparator(); + // Morrowind uses 3 px invisible borders for padding topics + constexpr int verticalPadding = 3; + for (const auto& keyword : mKeywords) { std::string topicId = Misc::StringUtils::lowerCase(keyword); - mTopicsList->addItem(keyword); + mTopicsList->addItem(keyword, verticalPadding); auto t = std::make_unique(keyword); mKeywordSearch.seed(topicId, intptr_t(t.get())); diff --git a/components/widgets/list.cpp b/components/widgets/list.cpp index 896057443c..416590ed48 100644 --- a/components/widgets/list.cpp +++ b/components/widgets/list.cpp @@ -29,14 +29,14 @@ namespace Gui MyGUI::Align::Top | MyGUI::Align::Left | MyGUI::Align::Stretch, getName() + "_ScrollView"); } - void MWList::addItem(std::string_view name) + void MWList::addItem(std::string_view name, int verticalPadding) { - mItems.emplace_back(name); + mItems.emplace_back(name, verticalPadding); } void MWList::addSeparator() { - mItems.emplace_back(std::string{}); + addItem({}); } void MWList::adjustSize() @@ -48,7 +48,6 @@ namespace Gui { constexpr int _scrollBarWidth = 20; // fetch this from skin? const int scrollBarWidth = scrollbarShown ? _scrollBarWidth : 0; - constexpr int spacing = 3; int viewPosition = -mScrollView->getViewOffset().top; while (mScrollView->getChildCount()) @@ -60,25 +59,27 @@ namespace Gui int i = 0; for (const auto& item : mItems) { - if (!item.empty()) + mItemHeight += item.mVPadding; + if (!item.mName.empty()) { if (mListItemSkin.empty()) return; MyGUI::Button* button = mScrollView->createWidget(mListItemSkin, MyGUI::IntCoord(0, mItemHeight, mScrollView->getSize().width - scrollBarWidth - 2, 24), - MyGUI::Align::Left | MyGUI::Align::Top, getName() + "_item_" + item); - button->setCaption(item); + MyGUI::Align::Left | MyGUI::Align::Top, getName() + "_item_" + item.mName); + button->setCaption(item.mName); button->getSubWidgetText()->setWordWrap(true); button->getSubWidgetText()->setTextAlign(MyGUI::Align::Left); button->eventMouseWheel += MyGUI::newDelegate(this, &MWList::onMouseWheelMoved); button->eventMouseButtonClick += MyGUI::newDelegate(this, &MWList::onItemSelected); button->setNeedKeyFocus(true); - int height = button->getTextSize().height; + // Morrowind list item text widgets are typically 18 pixels tall + int height = button->getTextSize().height + 2; button->setSize(MyGUI::IntSize(button->getSize().width, height)); button->setUserData(i); - mItemHeight += height + spacing; + mItemHeight += height; } else { @@ -87,8 +88,9 @@ namespace Gui MyGUI::Align::Left | MyGUI::Align::Top | MyGUI::Align::HStretch); separator->setNeedMouseFocus(false); - mItemHeight += 18 + spacing; + mItemHeight += 18; } + mItemHeight += item.mVPadding; ++i; } @@ -123,18 +125,19 @@ namespace Gui const std::string& MWList::getItemNameAt(size_t at) { assert(at < mItems.size() && "List item out of bounds"); - return mItems[at]; + return mItems[at].mName; } void MWList::sort() { // A special case for separators is not needed for now - std::sort(mItems.begin(), mItems.end(), Misc::StringUtils::ciLess); + std::sort(mItems.begin(), mItems.end(), + [](const auto& left, const auto& right) { return Misc::StringUtils::ciLess(left.mName, right.mName); }); } void MWList::removeItem(const std::string& name) { - auto it = std::find(mItems.begin(), mItems.end(), name); + auto it = std::find_if(mItems.begin(), mItems.end(), [&name](const auto& item) { return item.mName == name; }); assert(it != mItems.end()); mItems.erase(it); } diff --git a/components/widgets/list.hpp b/components/widgets/list.hpp index 3d5e320cf7..f67a7da97b 100644 --- a/components/widgets/list.hpp +++ b/components/widgets/list.hpp @@ -36,7 +36,7 @@ namespace Gui void adjustSize(); void sort(); - void addItem(std::string_view name); + void addItem(std::string_view name, int verticalPadding = 0); void addSeparator(); ///< add a seperator between the current and the next item. void removeItem(const std::string& name); size_t getItemCount(); @@ -64,7 +64,18 @@ namespace Gui MyGUI::Widget* mClient; std::string mListItemSkin; - std::vector mItems; + struct ListItemData + { + std::string mName; + int mVPadding; + + ListItemData(std::string_view name, int verticalPadding) + : mName(name) + , mVPadding(verticalPadding) + { + } + }; + std::vector mItems; int mItemHeight; // height of all items }; From 0a49c5f71ef91a646ab730df1784e6c0659eeaf0 Mon Sep 17 00:00:00 2001 From: Kindi Date: Fri, 4 Apr 2025 15:36:01 +0800 Subject: [PATCH 08/76] show global script variables in showVars --- apps/openmw/mwscript/globalscripts.hpp | 2 ++ apps/openmw/mwscript/miscextensions.cpp | 45 +++++++++++++++++++++++++ 2 files changed, 47 insertions(+) diff --git a/apps/openmw/mwscript/globalscripts.hpp b/apps/openmw/mwscript/globalscripts.hpp index 083695b51b..47c3f1ef6c 100644 --- a/apps/openmw/mwscript/globalscripts.hpp +++ b/apps/openmw/mwscript/globalscripts.hpp @@ -64,6 +64,8 @@ namespace MWScript void removeScript(const ESM::RefId& name); + const std::unordered_map>& getScripts() const { return mScripts; } + bool isRunning(const ESM::RefId& name) const; void run(); diff --git a/apps/openmw/mwscript/miscextensions.cpp b/apps/openmw/mwscript/miscextensions.cpp index ed2ef756e6..42e556c982 100644 --- a/apps/openmw/mwscript/miscextensions.cpp +++ b/apps/openmw/mwscript/miscextensions.cpp @@ -1223,6 +1223,50 @@ namespace MWScript runtime.getContext().report(str.str()); } + void printGlobalScriptsVars(Interpreter::Runtime& runtime) + { + std::stringstream str; + str << std::endl << "Global Scripts:"; + + const auto& scripts = MWBase::Environment::get().getScriptManager()->getGlobalScripts().getScripts(); + + // sort for user convenience + std::map> globalScripts(scripts.begin(), scripts.end()); + + auto printVariables = [&str](std::string_view scptName, const auto& names, const auto& values, + std::string_view type) { + size_t size = std::min(names.size(), values.size()); + for (size_t i = 0; i < size; ++i) + { + str << std::endl << scptName << "->" << names[i] << " = " << values[i] << " (" << type << ")"; + } + }; + + for (const auto& [refId, script] : globalScripts) + { + // Skip dormant global scripts + if (!script->mRunning) + continue; + + const std::string scptName = refId.serializeText(); + const Compiler::Locals& complocals + = MWBase::Environment::get().getScriptManager()->getLocals(refId); + const Locals& locals + = MWBase::Environment::get().getScriptManager()->getGlobalScripts().getLocals(refId); + + if (locals.isEmpty()) + str << std::endl << "No variables in script " << scptName; + else + { + printVariables(scptName, complocals.get('s'), locals.mShorts, "short"); + printVariables(scptName, complocals.get('l'), locals.mLongs, "long"); + printVariables(scptName, complocals.get('f'), locals.mFloats, "float"); + } + } + + runtime.getContext().report(str.str()); + } + public: void execute(Interpreter::Runtime& runtime) override { @@ -1233,6 +1277,7 @@ namespace MWScript { // No reference, no problem. printGlobalVars(runtime); + printGlobalScriptsVars(runtime) } } }; From 71a6b26b4fbc69a4568049c62b65e4e5e946619d Mon Sep 17 00:00:00 2001 From: Kindi Date: Fri, 4 Apr 2025 19:36:06 +0800 Subject: [PATCH 09/76] add missing semicolon, add leading whitespace, --- apps/openmw/mwscript/miscextensions.cpp | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/apps/openmw/mwscript/miscextensions.cpp b/apps/openmw/mwscript/miscextensions.cpp index 42e556c982..04d7fb8f2a 100644 --- a/apps/openmw/mwscript/miscextensions.cpp +++ b/apps/openmw/mwscript/miscextensions.cpp @@ -1192,6 +1192,10 @@ namespace MWScript MWBase::World* world = MWBase::Environment::get().getWorld(); std::vector names = runtime.getContext().getGlobals(); + + // sort for user convenience + std::sort(names.begin(), names.end()); + for (size_t i = 0; i < names.size(); ++i) { char type = world->getGlobalVariableType(names[i]); @@ -1238,7 +1242,7 @@ namespace MWScript size_t size = std::min(names.size(), values.size()); for (size_t i = 0; i < size; ++i) { - str << std::endl << scptName << "->" << names[i] << " = " << values[i] << " (" << type << ")"; + str << std::endl << " " << scptName << "->" << names[i] << " = " << values[i] << " (" << type << ")"; } }; @@ -1255,7 +1259,7 @@ namespace MWScript = MWBase::Environment::get().getScriptManager()->getGlobalScripts().getLocals(refId); if (locals.isEmpty()) - str << std::endl << "No variables in script " << scptName; + str << std::endl << " No variables in script " << scptName; else { printVariables(scptName, complocals.get('s'), locals.mShorts, "short"); @@ -1277,7 +1281,7 @@ namespace MWScript { // No reference, no problem. printGlobalVars(runtime); - printGlobalScriptsVars(runtime) + printGlobalScriptsVars(runtime); } } }; From a5580718f7078cc9e082188052274c27dfc87b27 Mon Sep 17 00:00:00 2001 From: Kindi Date: Sat, 5 Apr 2025 11:26:34 +0800 Subject: [PATCH 10/76] clangformat --- apps/openmw/mwscript/miscextensions.cpp | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/apps/openmw/mwscript/miscextensions.cpp b/apps/openmw/mwscript/miscextensions.cpp index 04d7fb8f2a..bdab10b084 100644 --- a/apps/openmw/mwscript/miscextensions.cpp +++ b/apps/openmw/mwscript/miscextensions.cpp @@ -1237,14 +1237,15 @@ namespace MWScript // sort for user convenience std::map> globalScripts(scripts.begin(), scripts.end()); - auto printVariables = [&str](std::string_view scptName, const auto& names, const auto& values, - std::string_view type) { - size_t size = std::min(names.size(), values.size()); - for (size_t i = 0; i < size; ++i) - { - str << std::endl << " " << scptName << "->" << names[i] << " = " << values[i] << " (" << type << ")"; - } - }; + auto printVariables + = [&str](std::string_view scptName, const auto& names, const auto& values, std::string_view type) { + size_t size = std::min(names.size(), values.size()); + for (size_t i = 0; i < size; ++i) + { + str << std::endl + << " " << scptName << "->" << names[i] << " = " << values[i] << " (" << type << ")"; + } + }; for (const auto& [refId, script] : globalScripts) { From 302d92561d946a32f0a90783f824041452245464 Mon Sep 17 00:00:00 2001 From: Cody Glassman Date: Mon, 16 Jun 2025 15:36:43 -0700 Subject: [PATCH 11/76] docs - begin restructing docs --- apps/openmw/mwlua/README.md | 2 +- docs/requirements.txt | 3 + docs/source/_static/luadoc.css | 60 ++++- docs/source/_static/theme.css | 11 + docs/source/conf.py | 29 ++- .../reference/lua-scripting/ai/combat.rst | 36 +++ .../reference/lua-scripting/ai/escort.rst | 49 ++++ .../reference/lua-scripting/ai/follow.rst | 37 +++ .../reference/lua-scripting/ai/pursue.rst | 25 ++ .../reference/lua-scripting/ai/travel.rst | 28 +++ .../reference/lua-scripting/ai/wander.rst | 53 +++++ .../reference/lua-scripting/aipackages.rst | 225 ------------------ docs/source/reference/lua-scripting/api.rst | 55 +---- .../lua-scripting/engine_handlers.rst | 14 ++ .../source/reference/lua-scripting/events.rst | 4 +- docs/source/reference/lua-scripting/index.rst | 6 +- .../lua-scripting/index_aipackages.rst | 24 ++ .../lua-scripting/index_auxpackages.rst | 21 ++ .../lua-scripting/index_interfaces.rst | 25 ++ .../lua-scripting/index_packages.rst | 37 +++ .../reference/lua-scripting/overview.rst | 8 +- .../lua-scripting/setting_renderers.rst | 4 +- .../lua-scripting/tables/aux_packages.rst | 31 ++- .../lua-scripting/tables/interfaces.rst | 79 +++--- .../lua-scripting/tables/packages.rst | 113 +++++---- .../lua-scripting/user_interface.rst | 96 ++++---- .../reference/lua-scripting/version.rst | 3 +- .../lua-scripting/widgets/container.rst | 45 +++- .../reference/lua-scripting/widgets/image.rst | 2 + .../reference/lua-scripting/widgets/text.rst | 2 + .../lua-scripting/widgets/textedit.rst | 2 + .../lua-scripting/widgets/widget.rst | 2 + docs/source/reference/modding/extended.rst | 2 +- docs/source/reference/modding/index.rst | 4 +- .../modding/texture-modding/index.rst | 6 +- .../source/reference/postprocessing/index.rst | 6 +- files/data/scripts/omw/ai.lua | 2 +- files/data/scripts/omw/settings/player.lua | 2 +- files/lua_api/openmw/ambient.lua | 4 +- files/lua_api/openmw/animation.lua | 3 +- files/lua_api/openmw/async.lua | 3 +- files/lua_api/openmw/camera.lua | 4 +- files/lua_api/openmw/core.lua | 4 +- files/lua_api/openmw/debug.lua | 4 +- files/lua_api/openmw/input.lua | 2 +- files/lua_api/openmw/interfaces.lua | 1 + files/lua_api/openmw/markup.lua | 3 +- files/lua_api/openmw/menu.lua | 3 +- files/lua_api/openmw/nearby.lua | 4 +- files/lua_api/openmw/postprocessing.lua | 4 +- files/lua_api/openmw/self.lua | 5 +- files/lua_api/openmw/storage.lua | 3 +- files/lua_api/openmw/types.lua | 3 +- files/lua_api/openmw/ui.lua | 4 +- files/lua_api/openmw/util.lua | 3 +- files/lua_api/openmw/vfs.lua | 3 +- files/lua_api/openmw/world.lua | 4 +- 57 files changed, 732 insertions(+), 485 deletions(-) create mode 100644 docs/source/_static/theme.css create mode 100644 docs/source/reference/lua-scripting/ai/combat.rst create mode 100644 docs/source/reference/lua-scripting/ai/escort.rst create mode 100644 docs/source/reference/lua-scripting/ai/follow.rst create mode 100644 docs/source/reference/lua-scripting/ai/pursue.rst create mode 100644 docs/source/reference/lua-scripting/ai/travel.rst create mode 100644 docs/source/reference/lua-scripting/ai/wander.rst delete mode 100644 docs/source/reference/lua-scripting/aipackages.rst create mode 100644 docs/source/reference/lua-scripting/index_aipackages.rst create mode 100644 docs/source/reference/lua-scripting/index_auxpackages.rst create mode 100644 docs/source/reference/lua-scripting/index_interfaces.rst create mode 100644 docs/source/reference/lua-scripting/index_packages.rst diff --git a/apps/openmw/mwlua/README.md b/apps/openmw/mwlua/README.md index ed911eb01d..a1cfeb1f1b 100644 --- a/apps/openmw/mwlua/README.md +++ b/apps/openmw/mwlua/README.md @@ -3,7 +3,7 @@ This folder contains the C++ implementation of the Lua scripting system. For user-facing documentation, see -[OpenMW Lua scripting](https://openmw.readthedocs.io/en/latest/reference/lua-scripting/index.html). +[Lua scripting](https://openmw.readthedocs.io/en/latest/reference/lua-scripting/index.html). The documentation is generated from [/docs/source/reference/lua-scripting](/docs/source/reference/lua-scripting). You can find instructions for generating the documentation at the diff --git a/docs/requirements.txt b/docs/requirements.txt index f46cc5c95d..0e02883062 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -3,3 +3,6 @@ sphinx==7.1.2 docutils==0.18.1 jinja2==3.1.6 sphinx_rtd_theme==3.0.1 +sphinx-design==0.6.1 +furo==2024.8.6 +sphinx-copybutton==0.5.2 \ No newline at end of file diff --git a/docs/source/_static/luadoc.css b/docs/source/_static/luadoc.css index aa83013def..8a2e01c082 100644 --- a/docs/source/_static/luadoc.css +++ b/docs/source/_static/luadoc.css @@ -1,10 +1,9 @@ #luadoc tt { font-family: monospace; } -#luadoc p, +/* #luadoc p, #luadoc td, #luadoc th { font-size: .95em; line-height: 1.2em;} -#luadoc p, #luadoc ul { margin: 10px 0 0 10px;} @@ -109,5 +108,60 @@ #luadoc dl, #luadoc dd {margin: 0px; line-height: 1.2em;} -#luadoc li {list-style: bullet;} +#luadoc li {list-style: bullet;} */ +#luadoc pre.example { + background-color: #eeffcc; + border: 1px solid #e1e4e5; + padding: 10px; + margin: 10px 0 10px 0; + overflow-x: auto; +} + + +#luadoc pre.example code { + color: var(--color-content-foreground); + background-color: #eeffcc; + border: none; + white-space: pre; + padding: 0px; +} + +#luadoc code { + /* background-color: inherit; + color: inherit; + border: none; */ + font-family: monospace; +} + +body[data-theme="dark"] #luadoc pre.example { + background-color: #eeffcc; +} + +@media (prefers-color-scheme: dark) { + body:not([data-theme="light"]) #luadoc pre.example { + background-color: #eeffcc; + } +} + +#luadoc a:not(:link) { + font-weight: bold; + color: var(--color-content-foreground); + text-decoration: none; + cursor: inherit; +} + +#luadoc p em { font-family: 'monospace';} + +#luadoc a:link { font-weight: bold; color: var(--color-link);; text-decoration: none; } +#luadoc a:visited { font-weight: bold; color: var(--color-link--hover); text-decoration: none; } +#luadoc a:link:hover { text-decoration: underline; } + +.context-wrapper { + display: flex; + gap: 4px; +} + +table.docutils { + width: 100%; +} \ No newline at end of file diff --git a/docs/source/_static/theme.css b/docs/source/_static/theme.css new file mode 100644 index 0000000000..2f0ef03b28 --- /dev/null +++ b/docs/source/_static/theme.css @@ -0,0 +1,11 @@ +.content { + width: 60em; +} + +a.next-page, a.prev-page { + color: var(--color-link); +} + +a.next-page:hover, a.prev-page:hover { + text-decoration: underline; +} \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index fbce7975da..38c1b01033 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -37,6 +37,8 @@ extensions = [ 'sphinx.ext.coverage', 'sphinx.ext.viewcode', 'sphinx.ext.autosectionlabel', + 'sphinx_design', + 'sphinx_copybutton', ] #autosectionlabel_prefix_document = True @@ -91,7 +93,14 @@ except Exception as ex: rst_prolog = f""" .. |luaApiRevision| replace:: {luaApiRevision} +.. |luaApiRevisionBadge| replace:: :bdg-link-info-line:`API v{luaApiRevision} ` + .. |ppApiRevision| replace:: {ppApiRevision} +.. |bdg-ctx-menu| replace:: :bdg-warning:`menu` +.. |bdg-ctx-global| replace:: :bdg-danger:`global` +.. |bdg-ctx-player| replace:: :bdg-secondary:`local:player` +.. |bdg-ctx-local| replace:: :bdg-info:`local` +.. |bdg-ctx-all| replace:: :bdg-danger:`global` :bdg-warning:`menu` :bdg-info:`local` """ # The language for content autogenerated by Sphinx. Refer to documentation @@ -138,7 +147,7 @@ primary_domain = 'c' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'sphinx_rtd_theme' +html_theme = 'furo' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -146,14 +155,20 @@ html_theme = 'sphinx_rtd_theme' html_theme_options = { 'navigation_with_keys': True, 'flyout_display': 'attached', + 'sidebar_hide_name': False, + 'top_of_page_buttons': [], } +html_css_files = [ + "theme.css", + "luadoc.css", + "figures.css" +] + # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] def setup(app): - app.add_css_file('figures.css') - app.add_css_file('luadoc.css') try: subprocess.call(['bash', project_root + '/docs/source/generate_luadoc.sh']) except Exception as e: @@ -161,19 +176,19 @@ def setup(app): # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -#html_title = None +html_title = 'OpenMW' # A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = 'OpenMW Documentation' +# html_short_title = 'OpenMW Documentation' # The name of an image file (relative to this directory) to place at the top # of the sidebar. -#html_logo = 'https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/_static/images/openmw.png' +html_logo = 'https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/_static/images/openmw.png' # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -#html_favicon = 'https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/_static/images/favicon.png' +html_favicon = 'https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/_static/images/favicon.png' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/docs/source/reference/lua-scripting/ai/combat.rst b/docs/source/reference/lua-scripting/ai/combat.rst new file mode 100644 index 0000000000..06dd9c1452 --- /dev/null +++ b/docs/source/reference/lua-scripting/ai/combat.rst @@ -0,0 +1,36 @@ +Combat +====== + +.. include:: ../version.rst + +Attack another actor. + +**Arguments** + +.. list-table:: + :header-rows: 1 + :widths: 20 20 60 + + * - name + - type + - description + * - type + - string [required] + - the name of the package (see packages listed below) + * - cancelOther + - boolean [default=true] + - whether to cancel all other AI packages + * - target + - `GameObject <../openmw_core.html##(GameObject)>`_ [required] + - the actor to attack + +**Examples** + +.. code-block:: Lua + + -- from local script add package to self + local AI = require('openmw.interfaces').AI + AI.startPackage({type='Combat', target=anotherActor}) + + -- via event to any actor + actor:sendEvent('StartAIPackage', {type='Combat', target=anotherActor}) diff --git a/docs/source/reference/lua-scripting/ai/escort.rst b/docs/source/reference/lua-scripting/ai/escort.rst new file mode 100644 index 0000000000..fd9f2d05e5 --- /dev/null +++ b/docs/source/reference/lua-scripting/ai/escort.rst @@ -0,0 +1,49 @@ +Escort +====== + +.. include:: ../version.rst + +Escort another actor to the given location. + +**Arguments** + +.. list-table:: + :header-rows: 1 + :widths: 20 20 60 + + * - name + - type + - description + * - type + - string [required] + - the name of the package (see packages listed below) + * - cancelOther + - boolean [default=true] + - whether to cancel all other AI packages + * - target + - `GameObject <../openmw_core.html##(GameObject)>`_ [required] + - the actor to follow + * - destPosition + - `3d vector <../openmw_util.html##(Vector3)>`_ [required] + - the destination point + * - destCell + - Cell [optional] + - the destination cell + * - duration + - number [optional] + - duration in game time (will be rounded up to the next hour) + * - isRepeat + - boolean [optional] + - Will the package repeat (true or false) + +**Example** + +.. code-block:: Lua + + actor:sendEvent('StartAIPackage', { + type = 'Escort', + target = object.self, + destPosition = util.vector3(x, y, z), + duration = 3 * time.hour, + isRepeat = true + }) diff --git a/docs/source/reference/lua-scripting/ai/follow.rst b/docs/source/reference/lua-scripting/ai/follow.rst new file mode 100644 index 0000000000..ac6b70bcf7 --- /dev/null +++ b/docs/source/reference/lua-scripting/ai/follow.rst @@ -0,0 +1,37 @@ +Follow +====== + +.. include:: ../version.rst + +Follow another actor. + +**Arguments** + +.. list-table:: + :header-rows: 1 + :widths: 20 20 60 + + * - name + - type + - description + * - type + - string [required] + - the name of the package (see packages listed below) + * - cancelOther + - boolean [default=true] + - whether to cancel all other AI packages + * - target + - `GameObject <../openmw_core.html##(GameObject)>`_ [required] + - the actor to follow + * - destCell + - Cell [optional] + - the destination cell + * - duration + - number [optional] + - duration in game time (will be rounded up to the next hour) + * - destPosition + - `3d vector <../openmw_util.html##(Vector3)>`_ [optional] + - the destination point + * - isRepeat + - boolean [optional] + - Will the package repeat (true or false) diff --git a/docs/source/reference/lua-scripting/ai/pursue.rst b/docs/source/reference/lua-scripting/ai/pursue.rst new file mode 100644 index 0000000000..08385c57ae --- /dev/null +++ b/docs/source/reference/lua-scripting/ai/pursue.rst @@ -0,0 +1,25 @@ +Pursue +====== + +.. include:: ../version.rst + +Pursue another actor. + +**Arguments** + +.. list-table:: + :header-rows: 1 + :widths: 20 20 60 + + * - name + - type + - description + * - type + - string [required] + - the name of the package (see packages listed below) + * - cancelOther + - boolean [default=true] + - whether to cancel all other AI packages + * - target + - `GameObject <../openmw_core.html##(GameObject)>`_ [required] + - the actor to pursue diff --git a/docs/source/reference/lua-scripting/ai/travel.rst b/docs/source/reference/lua-scripting/ai/travel.rst new file mode 100644 index 0000000000..06a47c868d --- /dev/null +++ b/docs/source/reference/lua-scripting/ai/travel.rst @@ -0,0 +1,28 @@ +Travel +====== + +.. include:: ../version.rst + +Go to given location. + +**Arguments** + +.. list-table:: + :header-rows: 1 + :widths: 20 20 60 + + * - name + - type + - description + * - type + - string [required] + - the name of the package (see packages listed below) + * - cancelOther + - boolean [default=true] + - whether to cancel all other AI packages + * - destPosition + - `3d vector <../openmw_util.html##(Vector3)>`_ [required] + - the point to travel to + * - isRepeat + - boolean [optional] + - Will the package repeat (true or false) diff --git a/docs/source/reference/lua-scripting/ai/wander.rst b/docs/source/reference/lua-scripting/ai/wander.rst new file mode 100644 index 0000000000..fc702f12e2 --- /dev/null +++ b/docs/source/reference/lua-scripting/ai/wander.rst @@ -0,0 +1,53 @@ +Wander +====== + +.. include:: ../version.rst + +Wander nearby current position. + +**Arguments** + +.. list-table:: + :header-rows: 1 + :widths: 20 20 60 + + * - name + - type + - description + * - type + - string [required] + - the name of the package (see packages listed below) + * - distance + - float [default=0] + - the actor to follow + * - duration + - number [optional] + - duration in game time (will be rounded up to the next hour) + * - idle + - table [optional] + - Idle chance values, up to 8 + * - isRepeat + - boolean [optional] + - Will the package repeat (true or false) + +**Example** + +.. code-block:: Lua + + local idleTable = { + idle2 = 60, + idle3 = 50, + idle4 = 40, + idle5 = 30, + idle6 = 20, + idle7 = 10, + idle8 = 0, + idle9 = 25 + } + actor:sendEvent('StartAIPackage', { + type = 'Wander', + distance = 5000, + duration = 5 * time.hour, + idle = idleTable, + isRepeat = true + }) diff --git a/docs/source/reference/lua-scripting/aipackages.rst b/docs/source/reference/lua-scripting/aipackages.rst deleted file mode 100644 index 7a23d156f5..0000000000 --- a/docs/source/reference/lua-scripting/aipackages.rst +++ /dev/null @@ -1,225 +0,0 @@ -Built-in AI packages -==================== - -.. include:: version.rst - -Starting an AI package ----------------------- - -There are two ways to start AI package: - -.. code-block:: Lua - - -- from local script add package to self - local AI = require('openmw.interfaces').AI - AI.startPackage(options) - - -- via event to any actor - actor:sendEvent('StartAIPackage', options) - -``options`` is Lua table with arguments of the AI package. - -**Common arguments that can be used with any AI package** - -.. list-table:: - :header-rows: 1 - :widths: 20 20 60 - - * - name - - type - - description - * - type - - string [required] - - the name of the package (see packages listed below) - * - cancelOther - - boolean [default=true] - - whether to cancel all other AI packages - -Combat ------- - -Attack another actor. - -**Arguments** - -.. list-table:: - :header-rows: 1 - :widths: 20 20 60 - - * - name - - type - - description - * - target - - `GameObject `_ [required] - - the actor to attack - -**Examples** - -.. code-block:: Lua - - -- from local script add package to self - local AI = require('openmw.interfaces').AI - AI.startPackage({type='Combat', target=anotherActor}) - - -- via event to any actor - actor:sendEvent('StartAIPackage', {type='Combat', target=anotherActor}) - -Pursue ------- - -Pursue another actor. - -**Arguments** - -.. list-table:: - :header-rows: 1 - :widths: 20 20 60 - - * - name - - type - - description - * - target - - `GameObject `_ [required] - - the actor to pursue - -Follow ------- - -Follow another actor. - -**Arguments** - -.. list-table:: - :header-rows: 1 - :widths: 20 20 60 - - * - name - - type - - description - * - target - - `GameObject `_ [required] - - the actor to follow - * - destCell - - Cell [optional] - - the destination cell - * - duration - - number [optional] - - duration in game time (will be rounded up to the next hour) - * - destPosition - - `3d vector `_ [optional] - - the destination point - * - isRepeat - - boolean [optional] - - Will the package repeat (true or false) - -Escort ------- - -Escort another actor to the given location. - -**Arguments** - -.. list-table:: - :header-rows: 1 - :widths: 20 20 60 - - * - name - - type - - description - * - target - - `GameObject `_ [required] - - the actor to follow - * - destPosition - - `3d vector `_ [required] - - the destination point - * - destCell - - Cell [optional] - - the destination cell - * - duration - - number [optional] - - duration in game time (will be rounded up to the next hour) - * - isRepeat - - boolean [optional] - - Will the package repeat (true or false) - -**Example** - -.. code-block:: Lua - - actor:sendEvent('StartAIPackage', { - type = 'Escort', - target = object.self, - destPosition = util.vector3(x, y, z), - duration = 3 * time.hour, - isRepeat = true - }) - -Wander ------- - -Wander nearby current position. - -**Arguments** - -.. list-table:: - :header-rows: 1 - :widths: 20 20 60 - - * - name - - type - - description - * - distance - - float [default=0] - - the actor to follow - * - duration - - number [optional] - - duration in game time (will be rounded up to the next hour) - * - idle - - table [optional] - - Idle chance values, up to 8 - * - isRepeat - - boolean [optional] - - Will the package repeat (true or false) - -**Example** - -.. code-block:: Lua - - local idleTable = { - idle2 = 60, - idle3 = 50, - idle4 = 40, - idle5 = 30, - idle6 = 20, - idle7 = 10, - idle8 = 0, - idle9 = 25 - } - actor:sendEvent('StartAIPackage', { - type = 'Wander', - distance = 5000, - duration = 5 * time.hour, - idle = idleTable, - isRepeat = true - }) - -Travel ------- - -Go to given location. - -**Arguments** - -.. list-table:: - :header-rows: 1 - :widths: 20 20 60 - - * - name - - type - - description - * - destPosition - - `3d vector `_ [required] - - the point to travel to - * - isRepeat - - boolean [optional] - - Will the package repeat (true or false) diff --git a/docs/source/reference/lua-scripting/api.rst b/docs/source/reference/lua-scripting/api.rst index 82a860b355..adede0b0d6 100644 --- a/docs/source/reference/lua-scripting/api.rst +++ b/docs/source/reference/lua-scripting/api.rst @@ -7,54 +7,15 @@ Lua API reference .. toctree:: :hidden: - engine_handlers - user_interface - aipackages + index_packages + index_auxpackages + index_aipackages + index_interfaces + UI setting_renderers + Engine Handlers events - openmw_ambient - openmw_animation - openmw_async - openmw_camera - openmw_core - openmw_debug - openmw_input - openmw_markup - openmw_menu - openmw_nearby - openmw_postprocessing - openmw_self - openmw_storage - openmw_types - openmw_ui - openmw_util - openmw_vfs - openmw_world - openmw_aux_calendar - openmw_aux_time - openmw_aux_ui - openmw_aux_util - interface_activation - interface_ai - interface_animation - interface_camera - interface_controls - interface_gamepadcontrols - interface_item_usage - interface_mwui - interface_settings - interface_skill_progression - interface_ui - interface_crimes - iterables - - -- :ref:`Engine handlers reference` -- :ref:`User interface reference ` -- `Game object reference `_ -- `Cell reference `_ -- :ref:`Built-in AI packages` -- :ref:`Built-in events` + Iterables **API packages** @@ -66,7 +27,7 @@ Player scripts are local scripts that are attached to a player. .. include:: tables/packages.rst -**openmw_aux** +**Auxiliary packages** ``openmw_aux.*`` are built-in libraries that are itself implemented in Lua. They can not do anything that is not possible with the basic API, they only make it more convenient. Sources can be found in ``resources/vfs/openmw_aux``. In theory mods can override them, but it is not recommended. diff --git a/docs/source/reference/lua-scripting/engine_handlers.rst b/docs/source/reference/lua-scripting/engine_handlers.rst index ac6979a236..29b14aee55 100644 --- a/docs/source/reference/lua-scripting/engine_handlers.rst +++ b/docs/source/reference/lua-scripting/engine_handlers.rst @@ -7,6 +7,8 @@ Engine handler is a function defined by a script, that can be called by the engi **Can be defined by any script** +|bdg-ctx-all| + .. list-table:: :widths: 20 80 @@ -16,6 +18,8 @@ Engine handler is a function defined by a script, that can be called by the engi **Can be defined by any non-menu script** +|bdg-ctx-global| |bdg-ctx-local| + .. list-table:: :widths: 20 80 @@ -39,6 +43,8 @@ Engine handler is a function defined by a script, that can be called by the engi **Only for global scripts** +|bdg-ctx-global| + .. list-table:: :widths: 20 80 @@ -61,6 +67,8 @@ Engine handler is a function defined by a script, that can be called by the engi **Only for local scripts** +|bdg-ctx-local| + .. list-table:: :widths: 20 80 @@ -86,6 +94,8 @@ Engine handler is a function defined by a script, that can be called by the engi **Only menu scripts and local scripts attached to a player** +|bdg-ctx-menu| |bdg-ctx-player| + .. list-table:: :widths: 20 80 @@ -140,6 +150,8 @@ Engine handler is a function defined by a script, that can be called by the engi **Only for local scripts attached to a player** +|bdg-ctx-player| + .. list-table:: :widths: 20 80 @@ -152,6 +164,8 @@ Engine handler is a function defined by a script, that can be called by the engi **Only for menu scripts** +|bdg-ctx-menu| + .. list-table:: :widths: 20 80 diff --git a/docs/source/reference/lua-scripting/events.rst b/docs/source/reference/lua-scripting/events.rst index 282e3d1173..007e0e43d1 100644 --- a/docs/source/reference/lua-scripting/events.rst +++ b/docs/source/reference/lua-scripting/events.rst @@ -1,5 +1,5 @@ -Built-in events -=============== +Events +====== .. include:: version.rst diff --git a/docs/source/reference/lua-scripting/index.rst b/docs/source/reference/lua-scripting/index.rst index f3764c4401..8db10bdae1 100644 --- a/docs/source/reference/lua-scripting/index.rst +++ b/docs/source/reference/lua-scripting/index.rst @@ -1,6 +1,6 @@ -#################### -OpenMW Lua scripting -#################### +############# +Lua scripting +############# .. note:: OpenMW Lua is not compatible with MWSE. diff --git a/docs/source/reference/lua-scripting/index_aipackages.rst b/docs/source/reference/lua-scripting/index_aipackages.rst new file mode 100644 index 0000000000..2b8b41bb08 --- /dev/null +++ b/docs/source/reference/lua-scripting/index_aipackages.rst @@ -0,0 +1,24 @@ +AI packages +============ + +.. include:: version.rst + +.. toctree:: + :hidden: + :glob: + + ai/* + +Starting an AI package +---------------------- + +There are two ways to start AI package: + +.. code-block:: Lua + + -- from local script add package to self + local AI = require('openmw.interfaces').AI + AI.startPackage(options) + + -- via event to any actor + actor:sendEvent('StartAIPackage', options) diff --git a/docs/source/reference/lua-scripting/index_auxpackages.rst b/docs/source/reference/lua-scripting/index_auxpackages.rst new file mode 100644 index 0000000000..e50fe45026 --- /dev/null +++ b/docs/source/reference/lua-scripting/index_auxpackages.rst @@ -0,0 +1,21 @@ +################## +Auxiliary Packages +################## + +.. include:: version.rst + +.. toctree:: + :hidden: + + aux_calendar + aux_time + aux_ui + aux_util + + +**Auxiliary packages** + +``openmw_aux.*`` are built-in libraries that are itself implemented in Lua. They can not do anything that is not possible with the basic API, they only make it more convenient. +Sources can be found in ``resources/vfs/openmw_aux``. In theory mods can override them, but it is not recommended. + +.. include:: tables/aux_packages.rst diff --git a/docs/source/reference/lua-scripting/index_interfaces.rst b/docs/source/reference/lua-scripting/index_interfaces.rst new file mode 100644 index 0000000000..06f21ee7d5 --- /dev/null +++ b/docs/source/reference/lua-scripting/index_interfaces.rst @@ -0,0 +1,25 @@ +########## +Interfaces +########## + +.. include:: version.rst + +.. toctree:: + :hidden: + + activation + ai + animation + camera + controls + gamepadcontrols + item_usage + mwui + settings + skill_progression + ui + crimes + +**Interfaces of built-in scripts** + +.. include:: tables/interfaces.rst diff --git a/docs/source/reference/lua-scripting/index_packages.rst b/docs/source/reference/lua-scripting/index_packages.rst new file mode 100644 index 0000000000..53a836519f --- /dev/null +++ b/docs/source/reference/lua-scripting/index_packages.rst @@ -0,0 +1,37 @@ +######## +Packages +######## + +.. include:: version.rst + +.. toctree:: + :hidden: + + ambient + animation + async + camera + core + debug + input + markup + menu + nearby + postprocessing + self + storage + types + ui + util + vfs + world + +**API packages** + +API packages provide functions that can be called by scripts. I.e. it is a script-to-engine interaction. +A package can be loaded with ``require('')``. +It can not be overloaded even if there is a lua file with the same name. +The list of available packages is different for global and for local scripts. +Player scripts are local scripts that are attached to a player. + +.. include:: tables/packages.rst diff --git a/docs/source/reference/lua-scripting/overview.rst b/docs/source/reference/lua-scripting/overview.rst index b889b09a9f..2061e4efe9 100644 --- a/docs/source/reference/lua-scripting/overview.rst +++ b/docs/source/reference/lua-scripting/overview.rst @@ -384,8 +384,8 @@ Player scripts are local scripts that are attached to a player. .. include:: tables/packages.rst -openmw_aux ----------- +Auxiliary packages +------------------ ``openmw_aux.*`` are built-in libraries that are themselves implemented in Lua. They can not do anything that is not possible with the basic API, they only make it more convenient. Sources can be found in ``resources/vfs/openmw_aux``. In theory mods can override them, but it is not recommended. @@ -544,7 +544,7 @@ The protection mod attaches an additional local script to every actor. The scrip In order to be able to intercept the event, the protection script should be placed in the load order below the original script. -See :ref:`the list of events ` that are used by built-in scripts. +See :ref:`the list of events ` that are used by built-in scripts. Timers @@ -618,7 +618,7 @@ An example: } } -Also in `openmw_aux`_ is the helper function ``runRepeatedly``, it is implemented on top of unsavable timers: +Also in `Auxiliary packages`_ is the helper function ``runRepeatedly``, it is implemented on top of unsavable timers: .. code-block:: Lua diff --git a/docs/source/reference/lua-scripting/setting_renderers.rst b/docs/source/reference/lua-scripting/setting_renderers.rst index b85c7fbaab..f315615cb4 100644 --- a/docs/source/reference/lua-scripting/setting_renderers.rst +++ b/docs/source/reference/lua-scripting/setting_renderers.rst @@ -1,5 +1,5 @@ -Built-in Setting Renderers -========================== +Setting Renderers +================= .. include:: version.rst diff --git a/docs/source/reference/lua-scripting/tables/aux_packages.rst b/docs/source/reference/lua-scripting/tables/aux_packages.rst index d0217ce202..d51949e1b2 100644 --- a/docs/source/reference/lua-scripting/tables/aux_packages.rst +++ b/docs/source/reference/lua-scripting/tables/aux_packages.rst @@ -1,12 +1,19 @@ -+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ -| Built-in library | Can be used | Description | -+=========================================================+====================+===============================================================+ -|:ref:`openmw_aux.calendar ` | everywhere | | Game time calendar | -+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw_aux.util ` | everywhere | | Miscellaneous utils | -+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw_aux.time ` | everywhere | | Timers and game time utils | -+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw_aux.ui ` | by player and menu | | User interface utils | -| | scripts | | -+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ +.. list-table:: + :widths: 30 40 60 + :header-rows: 1 + + * - Module + - Context + - Description + * - :doc:`calendar ` + - |bdg-ctx-all| + - Game time calendar + * - :doc:`util ` + - |bdg-ctx-all| + - Miscellaneous utils + * - :doc:`time ` + - |bdg-ctx-all| + - Timers and game time utils + * - :doc:`ui ` + - |bdg-ctx-menu| |bdg-ctx-player| + - User interface utils diff --git a/docs/source/reference/lua-scripting/tables/interfaces.rst b/docs/source/reference/lua-scripting/tables/interfaces.rst index d8dfffe47d..bdf8104678 100644 --- a/docs/source/reference/lua-scripting/tables/interfaces.rst +++ b/docs/source/reference/lua-scripting/tables/interfaces.rst @@ -1,48 +1,43 @@ .. list-table:: - :widths: 20 20 60 + :widths: 30 40 60 + :header-rows: 1 * - Interface - - Can be used + - Context - Description - * - :ref:`Activation ` - - by global scripts + * - :doc:`Activation ` + - |bdg-ctx-global| - Allows to extend or override built-in activation mechanics. - * - :ref:`AI ` - - by local scripts - - Control basic AI of NPCs and creatures. - * - :ref:`AnimationController ` - - by local scripts - - Control animations of NPCs and creatures. - * - :ref:`Camera ` - - by player scripts - - | Allows to alter behavior of the built-in camera script - | without overriding the script completely. - * - :ref:`Controls ` - - by player scripts - - | Allows to alter behavior of the built-in script - | that handles player controls. - * - :ref:`GamepadControls ` - - by player scripts - - | Allows to alter behavior of the built-in script - | that handles player gamepad controls. - * - :ref:`ItemUsage ` - - by global scripts - - | Allows to extend or override built-in item usage - | mechanics. - * - :ref:`SkillProgression ` - - by local scripts - - | Control, extend, and override skill progression of the - | player. - * - :ref:`Settings ` - - by player, menu, and global scripts - - Save, display and track changes of setting values. - * - :ref:`MWUI ` - - by player and menu scripts - - Morrowind-style UI templates. - * - :ref:`UI ` - - by player scripts - - | High-level UI modes interface. Allows to override parts - | of the interface. - * - :ref:`Crimes ` - - by global scripts + * - :doc:`ItemUsage ` + - |bdg-ctx-global| + - Allows to extend or override built-in item usage mechanics. + * - :doc:`Crimes ` + - |bdg-ctx-global| - Commit crimes. + * - :doc:`AI ` + - |bdg-ctx-local| + - Control basic AI of NPCs and creatures. + * - :doc:`AnimationController ` + - |bdg-ctx-local| + - Control animations of NPCs and creatures. + * - :doc:`SkillProgression ` + - |bdg-ctx-local| + - Control, extend, and override skill progression of the player. + * - :doc:`Camera ` + - |bdg-ctx-player| + - Allows to alter behavior of the built-in camera script without overriding the script completely. + * - :doc:`Controls ` + - |bdg-ctx-player| + - Allows to alter behavior of the built-in script that handles player controls. + * - :doc:`GamepadControls ` + - |bdg-ctx-player| + - Allows to alter behavior of the built-in script that handles player gamepad controls. + * - :doc:`UI ` + - |bdg-ctx-player| + - High-level UI modes interface. Allows to override parts of the interface. + * - :doc:`Settings ` + - |bdg-ctx-global| |bdg-ctx-menu| |bdg-ctx-player| + - Save, display and track changes of setting values. + * - :doc:`MWUI ` + - |bdg-ctx-menu| |bdg-ctx-player| + - Morrowind-style UI templates. diff --git a/docs/source/reference/lua-scripting/tables/packages.rst b/docs/source/reference/lua-scripting/tables/packages.rst index e66926e5e4..290b7d3507 100644 --- a/docs/source/reference/lua-scripting/tables/packages.rst +++ b/docs/source/reference/lua-scripting/tables/packages.rst @@ -1,49 +1,64 @@ -+------------------------------------------------------------+--------------------+---------------------------------------------------------------+ -| Package | Can be used | Description | -+============================================================+====================+===============================================================+ -|:ref:`openmw.ambient ` | by player and menu | | Controls background sounds for given player. | -| | scripts | | -+------------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw.animation ` | by local and | | Animation controls | -| | player scripts | | -+------------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw.async ` | everywhere | | Timers and callbacks. | -+------------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw.camera ` | by player scripts | | Controls camera. | -+------------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw.core ` | everywhere | | Functions that are common for both global and local scripts | -+------------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw.debug ` | by player scripts | | Collection of debug utils. | -+------------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw.input ` | by player and menu | | User input. | -| | scripts | | -+------------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw.interfaces