1. Введение
Данная система предлагает возможность создания нового оружия (для игрока) без непосредственного вмешательства в игровой код. Однако
не исключается возможность создания полу-скриптовых оружий, у которых часть функций объявлена в коде, а остальное находится в текстовом описании.
Система включает в себя следующие базовые возможности:

1.Поддержка системы ACTов для view_модели, подобных тем, что используются в монстрах и в HL2
2.Поддержка новых эвентов (реализовано частично)
3.Поддержка большинства основных настроек из текстовых файлов (информация об оружии, худ, параметры аттак и.т.д.)
4.Поддержка совмещенных моделей (w_model + p_model)
5.Поддержка смены скина и боди для view_ модели.
6.Новые функции для кодера, максимально упрощающие создание новой пушки (в случае если оружие требует вмешательства в код).

2. Моделлинг
Модели для оружия включают в себя две модели - модель с префиксом v_ и модель с префиксом w_.
Сами префиксы не приниципиальны и могут отсутствовать вовсе. Они нужны лишь для того, чтобы
не запутаться. Модель с префиксом v_ - это модель, которую игрок видит в своих руках.
Для неё существует система актов. Модели с префиксом w_ мы рассмотрим более подробно далее.
Компиляция моделей с новыми ACT_ами осуществляется компилятором, входящим в состав xash.

2.1 Акты оружия
Ниже перечислены основные акты оружия, а также пометка, если они уже используются в коде.
Xash weapon system допускает отсутствие дополнительных анимаций, проигрывая при их отсутствии
базовые. Кастомные анимации могут использоваться по усмотрению модмейкера.

ACT_VM_NONE - пустая анимация-разделитель. Не используется в коде.
ACT_VM_DEPLOY - поднятие снаряженного оружия
ACT_VM_DEPLOY_EMPTY - поднятие пустого оружия (проигрывается, если все патроны закончились)
ACT_VM_HOLSTER - опускание снаряженного оружия
ACT_VM_HOLSTER_EMPTY - опускание пустого оружия (проигрывается, если все патроны закончились)
ACT_VM_IDLE - анимация бездействия (игрок не нажимает на кнопки аттаки)
ACT_VM_IDLE_IS - анимация бездействия, если включен железный прицел
ACT_VM_RANGE_ATTACK - анимация первичной аттаки
ACT_VM_RANGE_ATTACK_IS - анимация первичной аттаки, если включен железный прицел
ACT_VM_MELEE_ATTACK - анимация вторичной аттаки
ACT_VM_MELEE_ATTACK_IS - анимация вторичной аттаки, если включен железный прицел
ACT_VM_SHOOT_LAST - анимация первичной аттаки, выстрел последним патроном в обойме
ACT_VM_SHOOT_LAST_IS - анимация первичной аттаки, выстрел последним патроном в обойме, если включен железный прицел
ACT_VM_LAST_MELEE_ATTACK - анимация вторичной аттаки, последний выстрел
ACT_VM_LAST_MELEE_ATTACK_IS - анимация вторичной аттаки, последний выстрел, если включен железный прицел
ACT_VM_START_RELOAD - анимация начала перезарядки, влияет на её характер. При наличии этой анимации включается режим
перезарядки, как у дробовика (начало, циклическая анимация добавки патрона, конец)
ACT_VM_START_RELOAD_IS - тоже самое, если включен железный прицел
ACT_VM_RELOAD - типичная анимация перезарядки (например смена обоймы у глока), циклическое добавление по одному
патрону, если присутствует ACT_VM_START_RELOAD
ACT_VM_RELOAD_IS - тоже самое, если включен железный прицел
ACT_VM_RELOAD_EMPTY - перезарядка с пустого магазина
ACT_VM_RELOAD_EMPTY_IS - тоже самое, если включен железный прицел
ACT_VM_TURNON - анимация для аттаки "switchmode"
ACT_VM_TURNOFF - анимация для аттаки "switchmode@
ACT_VM_PUMP - окончание процесса перезарядки для трёх анимаций (как у дробовика)
ACT_VM_PUMP_IS - тоже самое, если включен железный прицел
ACT_VM_PUMP_EMPTY - окончание процесса перезарядки, которая была начата с пустого магазина (обычно не используется)
ACT_VM_PUMP_EMPTY_IS - тоже самое, если включен железный прицел
ACT_VM_START_CHARGE - используется в оружии weapon_handgrenade (полу-виртуальное оружие)
ACT_VM_CHARGE - на данный момент не используется в коде
ACT_VM_OVERLOAD - на данный момент не используется в коде
ACT_VM_IDLE_EMPTY - анимация бездействия в случае когда патроны израсходованы
ACT_VM_IDLE_EMPTY_IS - тоже самое, если включен железный прицел
ACT_VM_IRONSIGHT_ON - анимация включения железного прицела
ACT_VM_IRONSIGHT_OFF - анимация выключения железного прицела
ACT_VM_SHOOT_EMPTY - анимация стрельбы без патронов (например нажатие на спусковой крючок, но без отдачи от выстрела)
ACT_VM_SHOOT_EMPTY_IS - тоже самое, если включен железный прицел
ACT_VM_IRONSIGHT_ON_EMPTY - анимация включения железного прицела в случае когда патроны израсходованы
ACT_VM_IRONSIGHT_OFF_EMPTY - анимация выключения железного прицела в случае когда патроны израсходованы

Акты необходимо прописывать в qc скрипте, после указания всех настроек. Пример:
$sequence "idle1" "idle1" fps 16 ACT_VM_IDLE1 1
Или:
$sequence "shoot" "shoot" fps 25 ACT_VM_RANGE_ATTACK1 1
Компиляция осуществляется базовым компилятором, входящим в состав Paranoia SDK. Другие компиляторы не подходят.
Цифра после имени акта означает удельный вес анимации. Если у вас несколько анимаций "idle" вы можете указывать им разный удельный
вес и тогда эти анимации будут проигрываться чаще остальных. Если удельный вес всех анимаций с одинаковыми актами будет равен,
то они будут выбираться случайным образом. Это работает для любого акта.

2.2 События
События (эвенты) предназначены для проигрывания визуальных эффектов на view_модели. На данный момент доступны следующие типы событий:
5001 (вспышка, динамический свет, дым от первого аттачмента) Тип вспышки традиционно закодирован в номере.
5002 (искры из первого аттачмента)
5004 (проигрывание звука из первого аттачмента)
5005 (всплески воды для левой ноги NPC, при условии, что он идёт по воде) Всплеск появится на месте четвертого ататчмента.
5006 (полёт гильзы по направлению между третьим и четвертым аттачментом). Не рекомендуется к использованию.
5007 (дым из первого аттачмента)
5008 (дым из второго аттачмента)
5011 (вспышка, динамический свет, дым от второго аттачмента) Тип вспышки традиционно закодирован в номере.
5015 (всплески воды для правой ноги NPC, при условии, что он идёт по воде) Всплеск появится на месте третьего ататчмента.
5021 (вспышка, динамический свет, дым от третьего аттачмента) Тип вспышки традиционно закодирован в номере.
5031 (вспышка, динамический свет, дым от четвертого аттачмента) Тип вспышки традиционно закодирован в номере.
5040 (создание системы партиклей для оригина модели, в настройках путь к файлу .aur)
5041 (создание системы партиклей для первого аттачмента, в настройках путь к файлу .aur)
5042 (создание системы партиклей для второго аттачмента, в настройках путь к файлу .aur)
5043 (создание системы партиклей для третьего аттачмента, в настройках путь к файлу .aur)
5044 (создание системы партиклей для четвертого аттачмента, в настройках путь к файлу .aur)

На данный момент Xash Weapon System ® имеет два новых эвента. Первый, предназначен для проигрывания
звука на клиенте с рандомным параметром pitch - это удобно использовать для перезарядки. Пример:
{ event 5005 5 "weapons/shotgun/shotgun_reload1.wav" }
Второй используется для выброса гильз. Модельку гильзы нужно обязательно закэшировать в файле precache.txt
Пример эвента:
{ event 5060 5 "models/shellBuck.mdl" }

2.3 w_ модели
В отличие от оригинального Half-Life, где на каждое оружие требовалось три модели, в xash используется
более разумная система. Каждому оружия нужно только две модели - первая это т.н. viewmodel т.е. та, которую
игрок видит от первого лица. И вторая - worldmodel, которую игрок видит у других игроков в руках( а также
и у себя в режиме thirdperson) и лежащей на земле в виде предмета, который можно подобрать.
При создании моделей для нового оружия очень важно учитывать, что первой всегда идет анимация "оружие в руках игрока".
Данная анимация должна иметь соответствующее кол-во костей, аналогичное правой руке базовой модельки игрока.
Вторая и последующие анимации костей могут не иметь вовсе. Достаточно просто поместить модельку на "пол" в вашем
ЗД редакторе.

3. Скриптовая система
Новая система позволяет очень гибко настраивать первичную и вторичную аттаку оружия, меняя количество
патронов, скорострельность и многое другое. Если вы хотите добавить новое оружие, не изменяя уже существующие,
вам понадобиться создать новый файл в папке scripts/weapons. Название файла обязательно должно начинаться с префикс weapon_, это
подсказка для системы, что в этом файле хранятся настройки оружия. Если вы хотите получить это оружие при помощи чита impulse 101,
вам так же потребуется добавить его название в файл impulse101.txt

3.1 Синтаксис
Файл оружия имеет несколько секций с различными параметрами пушки. Каждая секция имеет определенное
название из которого становиться понятным, для чего она предназначена:
WeaponData - эта секция содержит глобальную информацию об оружии - слот, в котором оно будет находиться,
модели, используемые оружием, размер обоймы, тип используемых патронов, и.т.д.
PrimaryAttack - эта секция содержит в себе настройки для первичной аттаки. Тип действия, скорострельность,
и силу отдачи.
SecondaryAttack - то же самое, но для вторичной аттаки.
SoundData - эта облаcть содержит информацию о звуках первичной и вторичной аттаки, а также о звуке пустого
оружия.
"hudsprite" - здесь находиться информация о спрайтах, используемых оружием. В частности иконка патронов,
иконка выбранного оружия, иконка прицела и.т.д. Таких секций может быть несколько, в каждой может быть описан только
один спрайт.
Вы можете комментировать ненужные вам строки двумя слэшами // подобно тому, как это делается в С++.
Вы можете располагать секции в произвольном порядке, можете не брать ключевые слова и параметры в кавычки,
если вам это не нравится. Некоторые параметры позволяют вводить случайное значение формата "min..max".
Как правило это отражено в комментарии к данному параметру. Если вам не нужен какой-либо параметр, вы можете
вообще его не прописывать. Помните также, что вы ОБЯЗАТЕЛЬНО должны закрывать секции фигурными скобками,
чтобы система могла определить к какой секции относится какой параметр.


3.1.1 WeaponData
WeaponData
{

"viewmodel" "models/weapons/v_glock.mdl" // Путь к модели, которую мы видим от первого лица
"playermodel" "models/weapons/w_glock.mdl" // Путь к модели, которая лежит на земле и видна от третьего лица
"anim_prefix" "onehanded" // Префикс анимации для игрока.
// Подходящий можно подобрать, заглянув в модельку игрока:
// crowbar - подходит для монтировки и аналогичных палок
// trip - этот префикс - для мины-ловушки, которую держат 2 руками
// onehanded - обыкновенный пистолетик, типа глока
// python - почти тоже, что и onehanded но с более сильной отдачей
// shotgun - дробовик в руках, на уровне пояса
// gauss - лучевая пушка, на уровне пояса
// mp5 - автомат на уровне пояса
// rpg - ракетница на плече
// egon - "пылесос", с перекинутым через плечо, ранцем
// squeak - снарки, подходит и для ручных гранат
// hive - оружие чужих, однако подойдет и для пультов управления
// bow - арбалет, на уровне груди
// в собстенной модельке игрока вы можете добавлять новые анимации с новыми
// префиксами на ваше усмотрение.

"bucket" "0" // номер слота (от 0 до 10)
"bucket_position" "2" // позиция в слоте ( от 0 до 10)
"clip_size" "noclip" // размер обоймы, напишите "noclip" если оружие обоймы не имеет
"defaultammo" "1" // стартовое количество патронов для первичной аттаки (доступен диапазон через две точки)
"defaultammo2" "0" // стартовое количество патронов для вторичной аттаки (доступен диапазон через две точки)
"primary_ammo" "nuke" // тип патронов для первичной аттаки. Используйте имена из ammodesc.txt
// "none" - патронов нет, только проигрывание анимации
"secondary_ammo" "none" // тип патронов для вторичной аттаки. Используйте имена из ammodesc.txt
// "none" - патронов нет, только проигрывание анимации
"weight" "10" // "вес" оружия для автопереключения в случае когда закончились патроны
"ThrowOffset" "8 3 -5" // смещение от центра взгляда. Используется для выстрела гранатой и ракетой, чтобы они
// появлялись "из дула оружия", а не из центра экрана. Для огнестрельного оружия не используется.
"volume" "normal" // громкость выстрела. Используется для AI монстров (они слышат этот звук). Может принимать
// следюущие значения: "none", "quiet", "normal", "loud"
"flash" "normal" // яркость вспышки при выстреле. Используется для AI монстров (они видят эту вспышку). Может
// принимать следующие значения: "none", "dim", "normal", "bright"
"SpreadTime" "0.1" // аналог параметра "returntime" из старой системы spread_settings.txt. Значения совпадают.
"MaxSpeed" "100" // максимальная скорость игрока в процентном соотношении.
"MaxSpeedIS" "50" // тоже самое, для включенного оптического\железного прицела
"JumpHeight" "100" // максимальная высота прыжка игрока в процентном соотношении.
"JumpHeightIS" "50" // тоже самое, для включенного оптического\железного прицела
"item_flags" "IronSight|AutoAim" // флаги оружия. Включают различные дополнительные способности. Флаги обозначаются ключевым
// словом и разделителем между ними. Разделитель выглядит так же как и в С++, это символ |
// описание флагов можно посмотреть в приложении1 к данному разделу.
}

Следующие две секции - это PrimaryAttack и SecondaryAttack соответственно. Набор параметров для них абсолютно
одинаковый, поэтому мы рассмотрим какую-либо одну секцию.

3.1.2 PrimaryAttack
PrimaryAttack
{
"action" "ammo1" // тип выполняемого действия. Параметр определяет, что произойдет, если
// вы нажмете кнопку аттаки. Допускаются следующие варианты:
// "ammo1" - использовать первичный тип патронов
// "ammo2" - использовать вторичный тип патронов
// "laserdot" - включает и выключает лазерный прицел соответственно
// "zoom" - включает и выключает плавный зум с прицелом (не работает в текущей версии)
// "flashlight" - включает и выключает фонарик.
// "switchmode" - включает и выключает альтернативную аттаку.
// "swing" - удар монтировки (используются как ACT_RANGE так и ACT_MELEE)
// "IronSight" - включает и выключает железный прицел
// "Scope" - включает и выключает оптический прицел
// "none" - действие отсутствует
// любое другое значение - клиентская команда. Например "fire t1" активирует на карте все энтити с targetname t1.
"SpreadRange" "2..3" // замена параметрам minspread и maxspread из файла spread_settings.txt
"SpreadRangeIS" "1..1.5" // тоже самое, для включенного железного\оптического прицела
"SpreadType" "E_CUBE" // замена параметру equalize из файла spread_settings.txt. Допустимые значения:
// E_LINEAR - изменение разброса линейно во времени
// E_QUAD - по параболе (вначале узкий, потом резко расширяется)
// E_CUBE - кубическая парабола
// E_SQRT - наоборот (быстро расширяется и плавно переходит в максимальный)
// по умолчанию применяется E_LINEAR
"SpreadTypeIS" "E_SQRT" // тоже самое для включенного железного\оптического прицела
"SpreadExpand" "0.5" // замена параметру expand из файла spread_settings.txt. Вводимые значения совпадают.
"SpreadExpandIS" "0.2" // тоже самое для включенного железного\оптического прицела

"PunchAngle" "-1..2" "-0.5..0.5" "0"
// три числа, замена параметрам minpunch и maxpunch из файла spread_settings.txt. Каждое число может быть
// диапазоном, либо еденичным числом. Задаёт угол отклонения по XYZ соответственно. Пропускать значения нельзя.
// Все три должны присутствовать.
"PunchAngleIS" "-0.1..0.2" "-0.2..0.2" "0"
// тоже самое для включенного железного\оптического прицела
"recoil" "0..-2" // сила отдачи. Может иметь диапазон значений. (UNDONE)
"nextattack" "0.5" // время между выстрелами в секундах. Чем меньше значение - тем больше скорость. -1 - время проигрывания анимации.
"SmashDecal" "knife1" // имя группы декалей, которая будет оставлена при аттаке. Работает только в сочетании с типом аттаки "swing"
}

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

3.1.2 SoundData
В этой секции указаываются звуки, используемые огнестрельным либо лучевым оружием при выстреле.
Гранаты и ракеты имеют свой собственный звук выстрела, изменить который нельзя, без модификации кода.
SoundData
{
"shootsound1" "weapons/glock/pl_gun3.wav" // звук выстрела. Вы можете прописать этот параметр
// несколько раз, с разными путями к звуку и все они
// будут использоваться при выстреле случайным образом.
// кол-во звуков не может быть более 8.
"shootsound2" "weapons/glock/pl_gun1.wav" // тоже, но для вторичной аттаки
"emptysound" "weapons/cock1.wav" // звук пустого оружия. Допустимо использование не более 8 звуков.
}

3.1.2 "hudsprite"
Эта секция состоит из множества одинаковых подсекций с настройками спрайтов для оружия.
Подсекция выглядит следующим образом:
"hudsprite"
{
"name" "weapon_s"
"file" "sprites/items02.spr" // путь к спрайту
"x" "0" // начало верхнего левого угла иконки по горизонтали
"y" "180" // начало верхнего левого угла иконки по вертикали
"width" "170" // размер иконки по горизонтали
"height" "45" // размер иконки по вертикали
}
Иконка в данном случае - это часть большого спрайта, на котором вы хотите указать конкретную область
и использовать только её, в качестве нужного вам изображения. Это прежде всего удобно тем, что один спрайт
может содержать почти все нужные вам иконки. Если вы используете принцип "один спрайт - одна иконка" не указывайте
параметры "х", "y", "width", "height" вообще.
Список допустимых имен приведен ниже:
"weapon" - картинка невыбранного оружия
"weapon_s" - картинка выбранного оружия (как правило копия "weapon" но с каким либо эффектом, например засветкой
"ammo" - иконка патронов для первичной аттаки
"ammo2" - иконка патронов для вторичной аттаки
"crosshair" - иконка прицела
"autoaim" - иконка автоприцела
"zoom" - иконка прицела в режиме увеличения
"zoom_autoaim" - иконка автоприцела в режиме увеличения.
Ни один из вышеприведенных параметров в данной секции никак не влияет на какие-либо характеристики оружия
и не является обязательным к написанию.

3.1.3 Приложение1
Флаги позволяют задать оружию какие-либо особенности, не влияющие в целом на его боевые характеристики,
но скорее на его дополнительные качества. Принцип описания флагов упомянут в разделе 3.1.1
Названия флагов и их описание:

SelectOnEmpty // это оружие можно выбрать, даже если у него кончились патроны
NoAutoReload // это оружие игрок должен всегда перезаряжать вручную
NoAutoSwitch // игрок не переключиться с этого оружия на другое, если у него кончились патроны
LimitInWorld // ограниченное кол-во в мире (например гранаты)
Exhaustible // оружие, состоящее из одних патронов (например гранаты)
NoDuplicate // этот флаг запрещает брать копию оружия - например второй нож
AutoAim // включает автоприцел для любого вида оружия, точность берется из параметра SpreadRange
AllowFireMode // позволяет переключать режим ведения огня (одиночный, автоматический). Режим огня переключается
// при помощи команды impulse 45.
UnderWater // разрешает оружию стрелять под водой
IronSight // включает клиентские эффекты железного прицела (меняет FOV, включает DOF)
Scope // включает клиентские эффекты оптического прицела (меняет FOV, включает DOF, рисует спрайт прицела)
AutoFire // оружие по умолчанию работает в автоматическом режиме (в паре с флагом AllowFireMode задает начальный режим стрельбы)

3.2 Ограничения
Данная система не позволяет создавать не огнестрельные оружия, не прибегая к кодингу.
Оружий не может быть больше 30, включая текущие. Обойма ВСЕГДА используется первичными патронами,
вне зависимости от того какие именно это патроны.

4. Особенности
Xash weapon system использует анимационно-зависимую модель поведения.
Это означает, что система пытается найти ту или иную анимацию и строит свое дальнейшее поведение именно основываясь на налиичии
или отсутствии ключевой анимации. Возьмем например ACT_VM_DEPLOY_EMPTY и ACT_VM_HOLSTER_EMPTY - Этих анимаций нету в базовых моделях,
но они будут проигрываться при наличии. Это позволяет сделать ваше оружие более реалистичным. Ключевая анимация ACT_VM_START_RELOAD
влияет на перезарядку еще более глобально - если такая анимация имеется в модели перезарядка будет осуществляться в цикле, подобно тому,
как это сделано у дробовика. При её отсутствии произойдет обычная перезарядка "Обойма-Обойма". Анимация ACT_VM_RELOAD_EMPTY
также будет проигрываться при её наличии, однако не повлияет на сам процесс перезарядки.
Все анимации RANGE_ATTACK и MELEE_ATTACK пытаются проигрываться в случайном порядке, однако проигрываются
только те, которые имеются в модели, что вполне естественно. Это же справедливо и для IDLE анимаций.
Таким образом вы можете просто добавить новых анимаций чтобы разнообразить ваше оружие.
Учитвайте что альтернативная аттака использует MELEE_ATTACK, первичная аттака использует RANGE_ATTACK,
а выпуск различных ракет ВСЕГДА использует только MELEE аттак. это например делает невозможным создание
оружия, котрое стреляет альтернативной аттакой, скажем "9мм" пулями, а вторичной - "м203" гранатами,
поскольку обе аттаки будут использовать один и тот же набор анимаций и это будет выглядеть не слишком
красиво. Также нужно учитывать, что, выбрав "action" "swing", оружие использующее пули будет себя вести,
мягко говоря, не совсем адекватно. Такие аттаки, как "flashlight", "zoom" и "laserdot" одинаково хорошо
работает на всех пушках, но монтировка с лазерным прицелом будет выглядеть, согласитесь, достаточно странно.
Фонарик, используемый в данной системе - обычный фонарик от игрока, что не исключает двойное управление.