Справочник по функциям и классам (ч. 1)

Такая тема уже давно существует на АМК форуме, и курирует ее malandrinus, но по выводам из ответов/вопросов, я понял, что у многих не доходят руки покопать в интернете и найти всем известный АМК форум... потому решил создать такую же тему, здесь...
1. собственно ссылка на АМК форум...
2. ссылка на источник.

Но так как там вся информация идет не организована и в разброс, здесь я сделаю всю информацию в шапке темы и под спойлерами:
» Слова автора темы на АМК

В данной теме собраны сведения по скриптовой модели сталкера: функции и классы, методы и свойства, взаимосвязь классов и последовательность работы с ними, связь работы классов и файлов конфигураций. К наполнению темы приглашаются все желающие.
В наполнении темы непосредственно участвовали и существенно мне помогли: Monnoroch, Kolmogor, Unnamed Black Wolf, меченый(стрелок), IQDDD, Kirag, Taroz, dan, lekzd, 7.9, Garry_Galler, AKKK1, Bakи много других людей.

Оглавление
Основы:
Класс alife_simulator. Базовые операции с серверными объектами
» alife_simulator

Класс нужен для выполнения самых базовых задач на серверной стороне: создание и удаление объектов, поиск объектов по идентификаторам, перевод в онлайн/оффлайн, проверка инфопорций. Из этого ряда странным образом выбивается получение номера текущего уровня.
Объект такого класса всего один и может быть получен глобальной функцией alife(). Используем примерно так:

local sim = alife() -- получаем сам объект класса alife_simulator
local sactor = sim:actor() -- получаем серверный объект для актора

Формальное описание:

class alife_simulator {
float switch_distance(); // получить дистанцию переключения онлайн/оффлайн
void switch_distance(float dist); // установить дистанцию. Не работает!
int level_id(); // номер текущего уровня
string level_name(int level_id) // возвращает имя уровня по его id
cse_abstract* create(string <имя секции объекта>, vector* position, int level_vertex_id, int game_vertex_id) // создание объектов на уровне
cse_abstract* create(string <имя секции объекта>, vector* position, int level_vertex_id, int game_vertex_id, int parent_id) // создание объектов в инвентаре
cse_abstract* create_ammo(string <имя секции патронов>, vector* position, int level_vertex_id, int game_vertex_id, int parent_id, int amount) // создание пачек с патронами
cse_alife_dynamic_object* create(int <индекс объекта в all.spawn> ) // создание объекта на основе секции в all.spawn
int spawn_id(int id) // индекс секции в all.spawn для объекта с заданным id
void release(cse_abstract* obj, bool); // удаление объекта.
cse_alife_dynamic_object* object(int id, bool no_assert); // получение объекта по id.
cse_alife_dynamic_object* object(int id); // эквивалентно предыдущей функции с no_assert == true.
cse_alife_dynamic_object* object(string name); // получение объекта по имени. В ЗП нет!
cse_alife_dynamic_object* story_object(int story_id); // получения объекта по сюжетному идентификатору
cse_alife_creature_actor* actor(); // получение серверного объекта актора. Можно и просто получить его по id, равному 0
bool valid_object_id(int id); // проверяет, что аргумент не равен 65535 (-1). На редкость бесполезная функция.
void set_switch_online(int id, bool v); // устанавливает флажок flSwitchOnline, который определяет возможность перехода в онлайн
void set_switch_offline(int id, bool v); // устанавливает флажок flSwitchOffline, который определяет возможность перехода в оффлайн
void set_interactive(int id, bool v); // устанавливает флажок flInteractive
bool has_info(int id, string info_portion); // проверяет наличие инфопоршена
bool dont_has_info(int id, string info_portion); // проверяет отсутствие инфопоршена
void add_out_restriction(cse_alife_monster_abstract* obj, int restrictor_id); // установка ограничения на выход
void add_in_restriction(cse_alife_monster_abstract* obj, int restrictor_id); // установка ограничения на вход
void remove_out_restriction(cse_alife_monster_abstract* obj, int restrictor_id); // снятие ограничения на выход
void remove_in_restriction(cse_alife_monster_abstract* obj, int restrictor_id); // снятие ограничения на вход
void remove_all_restrictions(int object_id, const enum RestrictionSpace::ERestrictorTypes type); // снятие всех ограничений либо на вход, либо на выход
// Возможно, отвечают за убийство в оффлайне
void kill_entity(cse_alife_monster_abstract* monster, int game_vertex_id, cse_alife_schedulable* obj);
void kill_entity(cse_alife_monster_abstract* monster, int game_vertex_id); // эквивалентно первой функции с obj == 0
void kill_entity(cse_alife_monster_abstract* monster); // эквивалентно второй с game_vertex_id, равным gvid монстра, переданного в первом аргументе
};

Комментарии к некоторым функциям:

void switch_distance(float dist);

функция для установки онлайн-радиуса. У меня всегда вызывает вылет. Впрочем, этот радиус можно изменить в файле конфигурации alife.ltx секции [alife]. Там параметр switch_distance. Там-же есть параметр гистерезиса перехода switch_factor.

string level_name(int level_id)
функция возвращает системное имя уровня, например "L01_Escape" для Кордона. В списке строк для многих уровней есть внятные имена. Их можно получить так:
local level_name = game.translate_string(string.lower(alife():level_name(level_id)))

Функция create с аргументом parent_id, позволяет создавать только инвентарные предметы. Аргументamount функции create_ammo задаёт количество патронов в пачке. Пачка всегда создаётся одна. Номер секции в файле all.spawn для функции create с одним аргументом и spawn_id - это просто порядковый номер расположения объекта в all.spawn. Имеет тенденцию меняться после перепаковки с помощью acdc.
Функции create возвращают созданный объект. Однако он приведён к типу cse_abstract, и с ним возможны не все операции. Лучше после создания объекта получить объект заново, используя одну из функций поиска объектов.

С функцией release требуется осторожность. Некоторые объекты перед удалением надо переводить в оффлайн. Второй булевский аргумент этой функции игнорируется.

Функции set_switch_online, set_switch_offline и set_interactive позволяют менять соответствующие флажки из поля object_flags. Флажки flSwitchOnline и flSwitchOffline периодически проверяются для каждого объекта и определяют возможность перехода в онлайн или оффлайн соответственно. Если они обаtrue, то объект будет переходить в онлайн/оффлайн автоматически при пересечении онлайн-радиуса. Комбинации true/false и false/true соответственно форсируют одно из состояний вне зависимости от расстояния до актора. Естественно, это всё имеет смысл при нахождении объекта на одном уровне с актором.
Для некоторых объектов проверка осуществляется не этими флажками, а функциями can_switch_online иcan_switch_offline, которые надо перегрузить в скриптовом серверном классе и, таким образом, управлять переключением. Собственно для остальных объектов управление также осуществляется этими функциями, просто они по дефолту возвращают значения этих флажков.

С флажком flInteractive я не экспериментировал, только выяснил, что функция interactive возвращаетtrue, если установлены в 1 три флажка: flInteractive, flVisibleForAI и flUsefulForAI. Это имеет смысл для НПС, но какой именно - пока не выяснял.

В функциях для управления ограничениями надо передавать id рестрикторов. У рестрикторов имеется собственное поле типа, но, как мне показалось, в данных функциях собственный тип рестриктора игнорируется.
В функции remove_all_restrictions второй аргумент type определяет, какие именно ограничения надо удалить. Допустимые значения для этой функции: 4 - in, 5 - out.

Подробнее о типах рестрикторов
Их всего шесть, что определяется вот таким перечислением:

enum RestrictionSpace::ERestrictorTypes {
eDefaultRestrictorTypeNone, // 0
eDefaultRestrictorTypeOut, // 1
eDefaultRestrictorTypeIn, // 2
eRestrictorTypeNone, // 3
eRestrictorTypeIn, // 4
eRestrictorTypeOut, // 5
};

Можно обратить внимание, что в all.spawn никогда нет рестрикторов с типами 4 и 5. Не бывает также и типа 1.
В целом можно сделать ряд предположений:
- тип рестриктора 0 или 3 - это как бы "не рестриктор" вообще, и используются в основном для скриптовых зон, где движок ни за что не отвечает, а все проверки выполняются скриптами.
- только типы рестриктора 1 и 2 имеют смысл для движка и, по всей видимости, приводят к созданию зон "куда все не ходят"
- зоны "откуда всем ходу нет" очевидно лишены смысла, поэтому и не встречается в природе тип 1
- что касается типов 4 и 5, то это выходит не типы рестрикторов, а специальные константы для функции. Зачем их поместили в это-же перечисление, не знаю. Ещё раз, выглядит так, использовать можно рестрикторы с любым типом (поскольку, как я говорил, тип их не проверяется).
Обратите также внимание, что у класса game_object имеются функции, также отвечающие за управление ограничениями.

Назначение всех вариантов функции kill_entity неясно. Вроде бы отвечают за убийство в оффлайне, но у меня стабильно вызывали вылет.

Пространства имён. Глобальные функции для большого числа задач.
» Вступление

Глобальные фунции или иначе функции из пространств имён. Такая функция в любом месте вызывается следующим образом:
<пространство имён>.<имя функции>(<список аргументов>)
Пространства имён - это всего лишь способ сгруппировать функции по некоторому признаку. Хотя надо заметить, что логика группировки функций в сталкере иной раз не поддаётся объяснению.
Всего есть несколько пространств имён: безымянное (т.е. функции из него вызываются просто по именам как обычные глобальные функции), game, level, relation_registry, actor_stats. В ЧН (и ЗП) появилось пространство имён main_menu, кроме того есть незначительные изменения в остальных: некоторые функции исчезли, некоторые добавлены. Изменения однако незначительны.
Сейчас рассматриваем только три основных пространства имён (безымянное, game, level) и только дляТЧ.

» Безымянное пространство имён

Функции, которые не работают, вызывают вылеты или непонятно их назначение
function log(string) -- видимо для дебаговой версииfunction error_log(string) -- видимо для дебаговой версии
function flush() -- видимо для дебаговой версии
bool app_ready() -- готовность чего-то к чему-то

пока игра не загружена, у возвращает false, после загрузки - true
bool editor() -- под редактором??? Это то, чего нам как ушей не видать???
int script_server_object_version() -- число, знать бы что означает
function verify_if_thread_is_running()
function xrRender_test_r2_hw()

Получение некоторых глобальных объектов
alife_simulator* alife() -- см. описание alife_simulator
render_device* device() -- см. описание render_device
CGameGraph* game_graph() -- получение глобального графа игры
CConsole* get_console() -- получение объекта для управления консолью. Это и так все знают
CUIGameCustom* get_hud() -- получение объекта для управления худом. Можно добавлять к худу свои окошки и элементы управления. Так делают всякие индикаторы.
FS* getFS() -- файловые операции. см. описание FS
string command_line() -- командная строка, включая полный путь к исполняемому файлу
string user_name() -- сетевое имя игрока (вроде бы имя активного пользователя в системе)
cef_storage* ef_storage() -- хз что такое

Работа с файлами конфигурации
ini_file* create_ini_file(string) -- создаёт из строки объект типа ini_file в памяти
ini_file* game_ini() -- открытый файл "config\game.ltx" и все его вложения
ini_file* system_ini() -- открытый файл "config\system.ltx" и все его вложения

Побитовые операции
function bit_and(number, number)
function bit_not(number)
function bit_or(number, number)
function bit_xor(number, number)
function dik_to_bind(number) -- я подозреваю, что преобразует константу из набора DIK_keys в константу из набора key_bindings
DWORD GetARGB(number, number, number, number) -- формирует 32-х разрядное целое из 4-х отдельных байт. для задания цвета. Где используется - точно не известно.

Всякий мелкий утиль
void prefetch(string <имя модуля>) -- вызывает загрузку и прекомпиляцию модуля. Имя модуля указывается без расширения ".script"
int time_global() -- реальное время (в миллисекундах) с начала запуска программы
void buy_condition(ini_file*, string <имя секции>) -- прочитать настройки торговца, на покупку из файла конфигурации и определённой
секции. Только непонятно, для кого читаются эти настройки
void buy_condition(float, float) -- непонятная функция.
void sell_condition(ini_file*, string <имя секции>) -- аналогично на продажу
void sell_condition(float, float) -- непонятная функция
void show_condition(ini_file*, string <имя секции>) -- совсем непонятно

Далее описанные функции позволяют преобразовать ссылку на базовый класс в ссылку на производный для получения доступа к методам производного класса за деталями надо обращаться в описание соответствущих иерархий. надеюсь, руки до этого дойдут
action_planner* cast_action_to_planner(action_base*)
action_base* cast_planner_to_action(action_planner*)
cse_alife_creature_abstract* cast_alife_object_to_creature(cse_alife_object*)
cse_alife_trader_abstract* cast_alife_object_to_trader_abstract(cse_alife_object*)

Получение встроенных шрифтов
CGameFont* GetFontDI()
CGameFont* GetFontGraffiti19Russian()
CGameFont* GetFontGraffiti22Russian()
CGameFont* GetFontGraffiti32Russian()
CGameFont* GetFontGraffiti50Russian()
CGameFont* GetFontLetterica16Russian()
CGameFont* GetFontLetterica18Russian()
CGameFont* GetFontLetterica25()
CGameFont* GetFontMedium()
CGameFont* GetFontSmall()

Некая информация о текстурах. В ЗП эти функции убраны
CGameFont* GetTextureInfo(string, string)
CGameFont* GetTextureName(string)
CGameFont* GetTextureRect(string)

» Пространство имён game

CTime* get_game_time() -- возвращает игровое время в виде объекта класса CTime
void start_tutorial(string) -- запускает туториал, зарегистрированный в файле ui\game_tutorials.xml. В частности, на туториалах сделаны сны
bool has_active_tutorial() -- запущен ли туториал
int time() -- игровое время (в игровых миллисекундах) с начала игры (т.е. с начала прохождения игры)
string translate_string(string) -- получает вменяемую строку по её строковому идентификатору из одного из xml файлов, прописанных в файле \config\localization.ltx в секции [string_table] в параметре files если там такой строки нет, то возвращает свой аргумент - исходную строку

» Продолжение темы. Часть 2