diff --git a/doc/en/scripting/builtins/libapp.md b/doc/en/scripting/builtins/libapp.md new file mode 100644 index 00000000..00b6ae9a --- /dev/null +++ b/doc/en/scripting/builtins/libapp.md @@ -0,0 +1,130 @@ +# *app* library + +A library for high-level engine control, available only in script/test mode. + +The script/test name without path and extension is available as `app.script`. The file path can be obtained as: +```lua +local filename = "script:"..app.script..".lua" +``` + +## Functions + +```lua +app.tick() +``` + +Executes one tick of the engine main loop. + +```lua +app.sleep(time: number) +``` + +Waits for the specified time in seconds, executing the engine main loop. + +```lua +app.sleep_until( + -- function that checks the wait finishing condition + predicate: function() -> bool, + -- maximum number of engine cycle ticks, after which + -- an exception "max ticks exceed" will be thrown + [optional] max_ticks = 1e9 +) +``` + +Waits for the condition checked by the function to be true, executing the engine main loop. + +```lua +app.quit() +``` + +Quits the engine, printing the call stack to track where the function was called. + +```lua +app.reconfig_packs( + -- packs to add + add_packs: table, + -- packs to remove + remove_packs: table +) +``` + +Updates the packs configuration, checking its correctness (dependencies and packs existence). + +To remove all packs from the configuration, you can use `pack.get_installed()`: + +```lua +app.reconfig_packs({}, pack.get_installed()) +``` + +In this case, `base` will also be removed from the configuration. + +```lua +app.new_world( + -- world name + name: str, + -- seed of generation + seed: str, + -- name of generator + generator: str +) +``` + +Creates a new world and opens it. + +```lua +app.open_world(name: str) +``` + +Opens a world by name. + +```lua +app.reopen_world() +``` + +Reopens the world. + +```lua +app.close_world( + -- save the world before closing + [optional] save_world: bool=false +) +``` + +Closes the world. + +```lua +app.delete_world(name: str) +``` + +Deletes a world by name. + +```lua +app.get_version() -> int, int +``` + +Returns the major and minor engine versions. + +```lua +app.get_setting(name: str) -> value +``` + +Returns the value of a setting. Throws an exception if the setting does not exist. + +```lua +app.set_setting(name: str, value: value) +``` + +Sets the value of a setting. Throws an exception if the setting does not exist. + +```lua +app.get_setting_info(name: str) -> { + -- default value + def: value + -- minimum value + [numeric settings only] min: number, + -- maximum value + [numeric settings only] max: number +} +``` + +Returns a table with information about the setting. Throws an exception if the setting does not exist. diff --git a/doc/ru/scripting/builtins/libapp.md b/doc/ru/scripting/builtins/libapp.md new file mode 100644 index 00000000..1cf067a2 --- /dev/null +++ b/doc/ru/scripting/builtins/libapp.md @@ -0,0 +1,131 @@ +# Библиотека *app* + +Библиотека для высокоуровневого управления работой движка, доступная только в режиме сценария или теста. + +Имя сценария/теста без пути и расширения доступен как `app.script`. Путь к файлу можно получить как: +```lua +local filename = "script:"..app.script..".lua" +``` + +## Функции + +```lua +app.tick() +``` + +Выполняет один такт основного цикла движка. + +```lua +app.sleep(time: number) +``` + +Ожидает указанное время в секундах, выполняя основной цикл движка. + +```lua +app.sleep_until( + -- функция, проверяющее условия завершения ожидания + predicate: function() -> bool, + -- максимальное количество тактов цикла движка, после истечения которых + -- будет брошено исключение "max ticks exceed" + [опционально] max_ticks = 1e9 +) +``` + +Ожидает истинности утверждения (условия), проверяемого функцией, выполнячя основной цикл движка. + +```lua +app.quit() +``` + +Завершает выполнение движка, выводя стек вызовов для ослеживания места вызова функции. + +```lua +app.reconfig_packs( + -- добавляемые паки + add_packs: table, + -- удаляемые паки + remove_packs: table +) +``` + +Обновляет конфигурацию паков, проверяя её корректность (зависимости и доступность паков). + +Для удаления всех паков из конфигурации можно использовать `pack.get_installed()`: + +```lua +app.reconfig_packs({}, pack.get_installed()) +``` + +В этом случае из конфигурации будет удалён и `base`. + +```lua +app.new_world( + -- название мира + name: str, + -- зерно генерации + seed: str, + -- название генератора + generator: str +) +``` + +Создаёт новый мир и открывает его. + +```lua +app.open_world(name: str) +``` + +Открывает мир по названию. + +```lua +app.reopen_world() +``` + +Переоткрывает мир. + +```lua +app.close_world( + -- сохранить мир перед закрытием + [опционально] save_world: bool=false +) +``` + +Закрывает мир. + +```lua +app.delete_world(name: str) +``` + +Удаляет мир по названию. + +```lua +app.get_version() -> int, int +``` + +Возвращает мажорную и минорную версии движка. + +```lua +app.get_setting(name: str) -> value +``` + +Возвращает значение настройки. Бросает исключение, если настройки не существует. + +```lua +app.set_setting(name: str, value: value) +``` + +Устанавливает значение настройки. Бросает исключение, если настройки не существует. + + +```lua +app.get_setting_info(name: str) -> { + -- значение по-умолчанию + def: value + -- минимальное значение + [только числовые настройки] min: number, + -- максимальное значение + [только числовые настройки] max: number +} +``` + +Возвращает таблицу с информацией о настройке. Бросает исключение, если настройки не существует.