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

[Malandrinus 615]

Garry_Galler,

Выкладываю небольшой разбор содержимого полей таблицы db.storage

спасибо за вклад в тему! Очень полезная информация. Описание только движковых классов/функций, хоть и не закончено, но постепенно себя исчерпывает. Между тем остаётся немерянный пласт скриптовых наслоений, которые в сущности являются частью движка, поскольку используются уже поколениями модостроителей практически без изменений. Вот как минимум механизмы логики относятся к этому разряду. Их тоже можно было бы описать здесь.

 

 

Artos,

по мне так лучше, если бы писали здесь статьи хоть как-то, пусть и криво. Почистить и упорядочить в конечном счёте можно, если есть что чистить и упорядочивать. А последнее время вижу только смесь стола заказов и отделения ковырялки.

 

Разумеется, крайне желательно придерживаться примерно такого шаблона изложения (применительно к классам):

1. Общее назначение класса. В объёме одного абзаца или даже предложения объяснить, зачем вообще нужен данный класс. Какой объект он описывает или что можно сделать с его помощью. В случае с CScriptXmlInit это могло бы выглядеть таким образом.

 

Класс CScriptXmlInit предназначен для создания объектов окон (или объектов пользовательского интерфейса) на основе описания, заданного XML. Выгод от использования данного класса может быть несколько:

- вынос громоздкой инициализации во внешние XML файлы позволяет сделать правильное разделение данных и кода, что делает код более компактным, читаемым и в конечном счёте более управляемым.

- возможность задать свойства окон, недоступные для изменения скриптом. К примеру, так можно задать перенос текста в текстовых полях.

В сущности, это самый правильный способ создания окон. При желании можно всегда скриптов изменить нужные динамические характеристики окна. Полностью же скриптовое создание окон используется модостроителями почти всегда только лишь по причине незнания возможностей XML.

 

2. Формальное описание. Примеров таких описаний я наплодил достаточно много. Я предпочитаю некий псевдо C++. В данном случае может выглядеть так.

 

class CScriptXmlInit {
    CScriptXmlInit (); // конструктор, как и для большинства других классов соответствует глобальной функции CScriptXmlInit 

    void ParseFile(string <имя XML файла>); // прочитать файл с описанием окна
    // инициализировать (не создать) окно базового типа, родительское не задано
    bool InitWindow(string <имя тега с описанием>, int index, CUIWindow* <окно для инициализации>);
    // создать окно типа CUIStatic, статический элемент
    CUIStatic* InitStatic(string <имя тега с описанием>, CUIWindow* <родительское окно>); 
     // создать поле для редактирования текста
    CUIEditBox* InitEditBox(string <имя тега с описанием>, CUIWindow* <родительское окно>)
    // и т.д.
}

 

3. Общие комментарии к описанию.

- В целом класс CScriptXmlInit предназначен для компактного с точки зрения кода создания элементов управления, т.е. разных специальных окон, расположенных на родительском окне диалога. Поэтому все методы создания имеют второй аргумент - ссылку на родительское окно. Это то окно, на котором будет расположен создаваемый элемент.

- Только один метод работает не так. Это метод InitWindow, который предназначен для инициализации самого родительского окна. Обращаю внимание, что этот метод не создаёт окно, а только задаёт его параметры (к примеру размеры). Ссылка на уже существующее окно, требующее инициализации, передаётся третьим параметром.

- Все методы принимают аргумент - имя тега, содержащего описание окна. Формат тега, дополнительные теги внутри него и атрибуты тега зависят от создаваемого окна. Их полное описание выходит за рамки данной статьи =(

 

4. Примеры использования. Например так.

    local xml             = CScriptXmlInit()
    xml:ParseFile        ("ui_game_over.xml")
    xml:InitWindow        ("main",0,self) -- здесь self - это ссылка на экземпляр диалога - окна верхнего уровня (не имеющего родителя)
     
    local st             = xml:InitStatic("background", self) -- создать на диалоге статический элемент на основе описания из тега "background"
    self.scroll_view     = xml:InitScrollView("scroll", st) -- создать на диалоге выпадающий список, описанный тегом "scroll"

 

К сожалению для класса CScriptXmlInit этого будет недостаточно, поскольку за каждым методом стоит ещё и описание всех сопутствующих тегов и атрибутов тегов, коих могут быть десятки. В целом же класс самоочевиден. Именно поэтому я его не описывал.

[Malandrinus 615]

Artos

твоя фраза: "... по мне так лучше, если бы писали здесь статьи хоть как-то, пусть и криво" аукается потом не раз ... т.к. многие принимают "хоть как-то, пусть и криво" как руководство к действию, а не осмыслению.

Правда?! Нет, в самом деле? Так это обнадёживает. Я то был искренне уверен, что всем глубоко по барабану.

 

Наиболее удобной (ИМХО) формой подобного топика было бы его разделение на два: собственно справочник с готовыми и статьями/разделами и топик с черновиками, вопросами, пояснениями-трактовками, полемикой, ...

Особенно злостную полемику я отсюда вычищаю, а немногие статьи, написанные не мной, берегу как редкую драгоценность =) Можешь пролистать и убедиться сам, насколько беспочвенны твои опасения по поводу "бездумно набежавших".

 

По поводу XML. Я написал:

Полностью же скриптовое создание окон используется модостроителями почти всегда только лишь по причине незнания возможностей XML.

не вижу, что здесь неправильного. Я написал "почти", что вполне покрывает те единичные случаи, когда элементы настолько динамичны, что даже создавать их через XML смысла нет. Но эти случаи действительно единичны. И в общем основной тезис - "модостроители не знают возможностей XML" (почти все). Если человек знает все возможности, то ему мои рассуждения побоку, сам решит.

 

Не проще ли порой, не штамповать кучку XML'ек, а в самом скрипте динамически подстроить именно так, как нарисовал дизайнер?

Нет, не проще. В подавляющем числе случаев трудозатраты на создание нескольких вариантов конфигов будут гораздо меньше, чем на вариативный код. Собственно, поэтому и придумали идею разделения кода и данных. Кроме того, см. ниже.

 

Иль ты считаешь, что на 1024x768 (это те же 4:3) задуманное будет тем же, что и на 1600x1200, хотя бы с выбором шрифтов?

Таки да, будет тем же, поскольку в сталкере для интерфейса используются виртуальные координаты, и экран всегда имеет размеры 1024х768 вне зависимости от физического разрешения. Поэтому достаточно только создать варианты конфигов для отдельных пропорций. А учитывая доминирование всего двух пропорций задача становится не такой уж и неподъёмной. По большому счёту, для нестандартных пропорций можно мириться с небольшими искажениями.

[Malandrinus 615]

Полтергейст,

этот колбек (callback.zone_enter) работает только для одного класса ce_script_zone. Движковый сет для этого класса имеет имя SCRPTZN, имеется готовая секция с именем "script_zone". Из всех трёх игр этот объект используется только для ТЧ для Арены. Собственно там и можно посмотреть пример использования этого колбека. Это файл xr_zones.script

[Malandrinus 615]

Обычный скриптовый хит и пинает. Степень физического воздействия определяется параметром impulse.

[Malandrinus 615]

KOKC, надо создать окно на основе XML и там в XML задать параметр heading="1". Тогда будет реагировать на задание угла.

[Malandrinus 615]

singapur22,

спасибо!

 

Пара дополнений:

 

r_clsid("section", "param"); --возвращает sid класса секции объекта (применим только к параметру "class")

не sid, а именно clsid. Этот метод возвращает числовое значение зарегистрированного сета, т.е. пары серверный/клиентский классы. Если помните статью про регистрацию классов, то мы в class_registrator.script пишем так:

cs_register (object_factory, "CBurer", "se_monster.se_monster", "SM_BURER", "burer_s")

здесь

CBurer - клиентский класс,

se_monster.se_monster - серверный класс,

burer_s - скриптовое имя сета. Такая константа появится в классе clsid и можно будет к ней обращаться как clsid.burer_s. При этом этой константе будет назначена уникальное числовое значение.

SM_BURER - конфиговое имя сета. Это то, что указывается в параметре class в секции объекта. Вот как раз это значение и читается методом r_clsid. При этом метод возвращает то же значение, что и соответствующая константа из класса clsid.

В игре движок читает таким образом только параметр с именем class, но в скриптах функция будет работать для параметра с любым именем (просто в этом нет практического смысла).

 

function r_string("section", "param"); --считывает строчное значение без каких либо изменений.

как раз с изменениями! Эта функция удаляет из читаемой строки все пробелы и табуляции. Таким образом, если в конфиге было:

[section]
param = ab     cd 1; 2 4; ef   5

то вызов

ini:r_string("section", "param") вернёт "abcd1;24;ef5", т.е. без пробелов. Это даже бывает иногда удобно, но часто таки надо получить нормальную строку. Для этого можно использовать таблицы строк и глобальную функцию game.translate_string(string). Но можно воспользоваться второй функцией

 

function r_string_wq("section", "param");

Эта функция читает также параметр как строку. Если двойных кавычек вокруг строки нет, то она работает в точности как r_string, а вот если кавычки есть, то функция эти кавычки удаляет, а строку оставляет без изменений. Т.е. все пробелы остаются на месте.

 

 

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

ini_file(<имя файла>) -- можно воспринимать эту функцию, как конструктор класса ini_file (в стиле Luabind), а можно как просто глобальную функцию для открытия файла с произвольным именем.

system_ini() -- возвращает открытый файл с именем "config\system.ltx". Комментарии излишни. Это главный конфигурационный файл всея игры со всеми своими включениями, распакованными и в архивах.

game_ini() -- аналогично возвращает открытый файл с именем "config\game.ltx". Тоже между прочим важный файл, содержаший информацию о всех локациях и ещё некоторые полезные вещи.

create_ini_file(<строка с текстом файла>) -- интересная функция, которая позволяет сделать объект ini_file в памяти без собственно физического файла на диске. Аргументом является текст файла конфигурации целиком со всеми переносами строк.

 

Также стоит упомянуть методы классов:

cse_abstract:spawn_ini() -- возвращает custom data серверного класса

game_object:spawn_ini() -- аналогично для клиентского класса

 

 

[Malandrinus 615]

Artos,

Но ведь очевидно, что и суть вопроса и данный метод предназначен для конфиг-файлов (*.ltx, *.xml, и иже), а не для чтения иконок,текстур и пр. 'бинарников'.

Это не так совершенно. И класс FS и все его методы принципиально предназначены для работы с бинарными файлами. Метод типа readZ никак не может быть для текстовых файлов, поскольку в текстовых файлах строки не разделяются физическими нулями, а разделяются специальными символами. Почему может не работать, это другой вопрос.

 

Насчёт наличия в ЧН/ЗП пространства имён io, это вполне может быть недосмотр разработчиков. Сами они его не использовали, а о сообществе они не думали никогда даже в малейшей степени.

[Malandrinus 615]

Artos,

Ваше замечание о предназначении класса FS принципиально для бинарников - достаточно голословно. Можно получить/почитать аргументы/обоснования?

Давайте по порядку. Метод r_stringZ своим названием говорит, что читается с-строка или иначе строка с нулевым терминатором. Это однозначно и безо всяких исключений означает, что в конце этой строки стоит нулевой байт. Текстовые же файлы - это файлы, имеющие достаточно определённую структуру:

1. Принимается соглашение, называемое кодировкой символов, относительно того, какой код символа какой букве соответствует. Часть кодов резервируется для специальных нужд и не соответствует никаким символам. В широко распространённой кодировке ASCII, которая по сути является основной для почти всех современных кодировок, отображаемые символы - это символы начиная с кода 32 (пробел). Ниже расположены управляющие символы. Их 32 и сейчас большая часть не имеет смысла (типа коды управления перфоратором). В том числе не имеет смысла код 0. Имеют смысл только некоторые типа табуляции или символов конца строки.

2. Принимается дополнительное соглашение о делении на строки. Сейчас используется один из двух символов "перевод строки", "возврат каретки" или их комбинация.

Всё.

Относительно символа с кодом "ноль". С самых доисторических времён этот символ имел значение "в строке не встречается". Именно поэтому в языке СИ этот символ был выбран как терминальный символ для хранения строк в памяти, потому что его ну никак не может быть в строке. В таком контексте под "строкой" разумеется не строка текстового файла, а "текст" в самом общем смысле, содержащий любые допустимые форматирующие элементы. Это может быть и текстовый файл целиком. Вот к примеру именно как z-строка хранится кастомдата в нетпакете - целиком файл конфигурации, содержащий несколько строк.

 

Так что вполне очевидно, что метод чтения с-строки ну никак не может быть предназначен для работы с текстовыми файлами.

 

Я сейчас взглянул на пример из поста Kirag-а. Ошибка очевидна. Естественно эта функция вызывает сбой при чтении из текстового файла. Там же нет ни одного физического нуля. Как этот сбой будет проявляться, зависит от того, где находится этот файл. Если на диске, то возможно внутренние механизмы чтения обрабатывают ситуацию иначе, нежели при ситуации нахождения его в архиве. В одном случае тихо завершает чтение, в другом - генерирует вылет. Но и в том и в другом случае - это ошибка.

 

Ещё раз, FS предназначен для работы с бинарными файлами. Если есть желание читать с его помощью из текстовых, то это будет означать, что придётся делать всю работу, которую делает любой текстовый редактор: читать по байту, искать переносы строк и т.д.

 

и относительно вот этого:

1. Метод r_stringZ читает байты до нуль-терминатора или до конца последовательности байтов (при отсутствии терминатора).

Это откуда? Я такого не писал - это точно. Подчёркнутое - неправильно. При отсутствии терминатора будет классический выход за границу массива со всеми вытекающими. Собственно, все ранее приведённые примеры это и показывают. Кстати, поэтому z-строки считаются небезопасными в использовании.

Народ, я сейчас лишён полноценного выхода в интернет и вообще времени маловато. Сложно держать руку на пульсе. Если кому не отвечаю сразу или не отвечаю вообще, то заранее прошу меня извинить. Если не отвечаю в личку, то не стесняйтесь написать ещё раз до тех пор, пока не отвечу. Я вполне серъёзно.

[Malandrinus 615]

Artos,

 

1. 'Об обязательности наличия нуль-терминатора'

 

Предлагаю иную трактовку:

Метод 'r_stringZ' предначен для чтения байт-последовательности до первого обнаруженного нуль-терминатора (zero). Результатом является последовательность символов кодировка которых соответствует прочитанным байтам.

Здесь трактовкам не место. Я изложил факт. Так работают строки в языке СИ. Z-строки - это другое название СИ-строк, или C-строк. Это структура данных вполне однозначная и означает последовательность символов с нулём в конце.

 

3. И последнее, о чем уже не раз повторяю, суть вопроса НЕ в применимости метода, а в том, что ТОЛЬКО с нерасспакованными файлами происходит сбой.

Т.к. природа сбоя непонятна, то (ИМХО) ни что не гарантирует наличия аналогичных сбоев и для других методов (того же r_u8()).

Прочитайте внимательно. Природа сбоя в том, что при попытке чтения нуль-терминированной строки из обычного текстового файла происходит гарантированный выход позиции чтения за пределы файла. Это происходит в любом случае, находится файл в архиве или нет. Разница только в том, как реагирует система на это внештатную ситуацию. В одном случае (файл в архиве) происходит вылет, в другом (на диске), по какой-то причине вылета не происходит. Но это ошибка в обоих случаях! Скорее всего, при чтении другими методами проблем не будет ни в каком варианте, поскольку все остальные функции читают известное количество байт (1, 2, 4 и т.д.). Естественно, будет такая же ошибка, если я и другими функциями дойду до конца файла и попытаюсь оттуда прочитать.

 

К сожалению все же не получил ответа на поставленные вопросы (например: о применимости именно к запакованным файлам любых методов 'r_'). :-(

Признаться, вести дебаты о применимости того или иного метода в ситуации выхода за границы файла - это просто бред, уж извините. Этой ситуации просто не надо допускать. При грамотном создании программы её и не будет.

 

Для гарантированной работы - стОит заморачиваться с распакованными копиями, если это не накладно для игры ...

 

Может да, может нет. В своей старой статье я ранее написал только то, что иногда файл не открывается, если он в архиве. Я уже давно к теме FS не прикасался, но если проблема открытия на самом деле есть (а не была мною придумана по неопытности на тот момент) и может быть решена копированием, то вы правы.

 

Но это ещё до чтения. Если открыли хоть в архиве, хоть на диске, то дальше проблем при чтении быть не должно с любыми методами, просто не пытайтесь выйти за границы файла.

 

[Malandrinus 615]

Artos,

К чему исходники?

 

Есть такая штука Утиный тест. Т.е. если нечто выглядит как утка, плавает как утка и крякает как утка, то это вероятно утка и есть.

 

Так вот есть функция, написанная программистами на C, на языке С, с именем r_sringZ и вылетающая на файлах, не содержащих нулей. ок, язык конечно С++, но это мало что меняет.

 

Не достаточно?

[Malandrinus 615]

Kirag,

Кстати, не знаю, с чего я вбил себе в голову, что символ NULL = конец файла. В парсере XML мусор регулярно читается, может, я и в этом не прав...

Нет никакого нулевого окончания файлов. ОС Windows к файлам ничего не дописывает. Поэтому так делать нельзя. Если читаете текстовый файл с помощью FS, то надо читать его побайтно, потом собрать строку из байтов. Для этого есть функция string.char(<список символов>), а для получения списка из таблицы (куда читали) есть функция unpack(<таблица>).

По байту конечно медленнее, чем разом файл. Но файлы здесь небольшие, это терпимо, а главное - так правильно.

[Malandrinus 615]

Ранее я рекомендовал не использовать операцию конкатенации цепочкой в стиле s1..s2..s3..s4, поскольку счёл из общих соображений, что должен происходить степенной рост времени выполнения и резкое замедление работы при росте числа соединяемых строк. Я это утверждение не проверил, и выяснилось, что я ошибался. RvP провёл тесты и сравнил три разных метода конкатенации. Привожу его тест для чистого Lua в сокращённом виде с результатами измерений в комментариях.

a = "s1"
b = "s2"
c = "s3"
d = "s4"
e = "s5"

t = os.clock()
for i=1, 1000000 do
    local q = table.concat({a, b, c, d, e})
end
print("table", os.clock() - t)        --2.684

t = os.clock()
for i=1, 1000000 do
    local q = a .. b .. c .. d .. e
end
print("concat", os.clock() - t)        --0.96s

t = os.clock()
for i=1, 1000000 do
    local q = string.format("%s%s%s%s%s", a, b, c, d, e)
end
print("format", os.clock() - t)        --4.3s

 

Видно, что format работает медленней всего. Я также провёл дополнительные тесты, которые показали, что все три приведённых методики обеспечивают линейный рост времени выполнения.

 

Выводы из всего этого.

Несколько неожиданная эффективность оператора цепочечной конкатенации очевидна связана с внутренней оптимизацией Lua. Поэтому вот такая строка

local q = a .. b .. c .. d .. e

не эквивалентна вот такому фрагменту

local q = a

q=q..b

q=q..c

q=q..d

q=q..e

во втором случае мы как раз получим степенной рост времени выполнения.

 

Почему медленней работает format. Очевидно это связано с расходами на парсинг строки формата. Хотя эта функция также обеспечивает линейный рост времени выполнения, но каждый параметр в строке формата очевидно съедает своё время.

 

Резюме. Продолжайте писать конкатенацию цепочкой, как делали раньше (впрочем, кто это вообще прочитает?) Рекомендую всё же не переносить эту практику на произвольный язык программирования, поскольку ещё раз, это работает нормально не само по себе, а в силу внутренней оптимизации именно здесь.

 

Также RvP обратил внимание на встроенный в Lua метод конкатенации произвольного числа строк с помощью table.concat (пример смотри выше в тестовом фрагменте). Этот способ даёт возможность соединять произвольное количество строк и обеспечивает линейный рост затрат с минимальными расходами почти сопоставимыми с базовым оператором конкатенации.

Я хочу ещё раз подчеркнуть, что слить произвольное количество строк с помощью конкатенации нормально не получится. Вот этот фрагмент:

local s = ""
for i=1,1000 do
   s = s .. <очередная строка для конкатенации>
end

Это не конкатенация цепочкой! Никакой оптимизации здесь нет, и деградацию производительности вы получите совершенно невероятную.

Это надо делать только так:

local t = {}
for i=1,1000 do
   table.insert(<очередная строка для конкатенации>)
end
s = table.concat(t)

 

Да ещё... Приятно, что хоть кто-то не только читает эту тему, но и относится критически к тому, что здесь пишется. Я как-то надеялся, что так будет с самого начала, но увы.

Изменено 4 Сентября 2011 пользователем malandrinus

[Malandrinus 615]

Real Wolf,

Скорее наоборот.

Очепятался. Спасибо, что заметил.

 

Сохранив в пакет через метод u8 число -10, а прочитав с помощью s8, я получил 0, читая с помощью u8 - 246.

Это странно, поскольку я проверил весь допустимый диапазон [-128, 127] и работает именно так, как я написал. Т.е. пишем с помощью w_u8 отрицательное число и без проблем читаем его с помощью r_s8. Какой движок используешь для теста? Приведи пожалуйста код.

 

P.S.: информацию в посте поправил.

[Malandrinus 615]

Для нажатий клавиш есть колбеки для ТЧ и ЧН в модифицированных dll.

[Malandrinus 615]

AndreySol,

local cs = hud:GetCustomStatic("hud_show_time") 
...
cs:wnd():Show(false) -- а вот это не работает !!!

есть какое-то объяснение такой не любви движка к этому методу класса ?

кастомстатики, создаваемые через ui_custom_msgs.xml, - достаточно специфические. Если нужны с ними изыски, то лучше всего непосредственно в ui_custom_msgs.xml ничего не создавать, только пустое окно без текстуры и вообще всего. А само наполнение сделать отдельно и поместить на статик с помощью AttachChild. С этим окном уже все операции будут работать без проблем.

 

И еще, вышеуказанным способом

...

получить доступ к любому базовому статику на худе не получается, cs всегда == nil.

Я ничего не понял. Что такое базовый статик?

 

SetAutoDelete(bool);

bool IsAutoDelete();

для чего они ?

ставят/снимают флажок автоудаления окна при его отсоединении от родительского или удалении родительского.

[Malandrinus 615]

AndreySol,

в xml-файлах описания окна ивентаря есть такой статик

<dragdrop_belt x="645" y="136" width="410" height="60" cell_width = "60" cell_height="60" rows_num="1" cols_num="5"/>

какой из оконных классов используется для этого статика ?

Первое, это не статик. Статик - это вполне конкретный класс CUIStatic, один из многих оконных классов.

Второе, класс для этого элемента не экспортирован и никак в скриптах не доступен.

[Malandrinus 615]

AndreySol,

класс Frect - 6 переменных, ф-ция set инициализирует только 4. Какие из них ? Зачем две остальных. Как это использовать ?

инициализируются соответственно x1,x2,y1,y2

lt - это left top, координаты левой верхней вершины

rb - right bottom, координаты правой нижней вершины

это объекты класса vector2, который экспортирован только начиная с ЧН. Поэтому в ТЧ попытка получить эти свойства приведёт к вылету. В их использовании особой необходимости по-любому нет.

[Malandrinus 615]

Да там давно надо весь пост про game_object переписывать. У меня накопилось много исправлений и дополнений, но всё руки не доходят это дело оформить. В первую очередь надо оформить пост с истинной иерархией классов, как серверных так и клиентских. Затем полную таблицу сетов (зарегистрированных в движке пар), затем только новый пост про game_object, где все функции рассортированы по этим классам. Найти бы время для всего этого.

[Malandrinus 615]

KD87,

по game_object я подобное начал делать. Пока рассортировал методы по классам, около трети методов описал и проверил в игре. Могу выслать в качестве затравки, чтобы с нуля не пришлось начинать.

Буду весьма признателен за любую помощь.

[Malandrinus 615]

AndreySol,

такой код не дает эффекта:

local color = GetARGB(255,255,255,255)
st_item:SetColor(color)

прозрачность 100% задал, конечно не работает