События игры

То, что происходит в игре, — игрок получает урон, возрождается, умирает, покупает оружие, бросает гранату, раунд заканчивается, — это события на game. Обработчик слышит событие до того, как игра что-то сделает, и может пропустить его, изменить, остановить или ответить вместо игры:

// без урона по своим
game
.
addEventListener
("takeDamage", (
event
) => {
    if (
event
.
attacker
.
team
 == 
event
.
player
.
team
) 
event
.
preventDefault
();
});

// двойной урон с ножа
game
.
addEventListener
("takeDamage", onTakeDamage);

function onTakeDamage(
event
: TakeDamageEvent) {
    const 
weapon
 = 
event
.
attacker
.
activeItem
;
    if (
weapon
 && 
weapon
.
kind
 == "knife") 
event
.
damage
 = 
event
.
damage
 * 2;
}

// игра спрашивает, плагин отвечает: игроки слышат только свою команду
game
.
addEventListener
("canPlayerHearPlayer", (
event
) => 
event
.
listener
.
team
 == 
event
.
sender
.
team
);

События игры приходят из модулей ReAPI и Ham Sandwich. game.addEventListener работает так же, как server.addEventListener (Плагин): имя задаёт тип event, редактор дополняет имена и подчёркивает опечатку, а game.removeEventListener с той же функцией снимает обработчик. Когда снят последний обработчик, событие перестаёт приходить в плагин, пока обработчик не добавят снова.

Что может обработчик

Изменённое поле получат игра и обработчики после этого; если прочитать поле после записи, оно даст новое значение.

Возвращённое значение — ответ на вопрос игры: «слышит ли этот игрок того?», «сколько урона от падения?», «можно ли ему это купить?», — и свой код игра уже не выполняет. У ответа тип события (boolean, number, Player, Entity): вернуть другой — ошибка и в редакторе, и в сборке. Событие, чья функция в игре ничего не отвечает, ответа не принимает.

preventDefault() останавливает действие игры без ответа: урон не наносится, стартовое оружие не выдаётся. Там, где игра ждёт ответ, она получает 0 или false.

После того, как игра сработала

game
.
addEventListener
("fallDamage", (
event
) => 
event
.
result
 / 2, true);   // вдвое меньше урона от падения

game
.
addEventListener
("playerSpawn", (
event
) => {
    
event
.
player
.
give
("weapon_deagle");
}, true);

С true третьим аргументом — или { post: true }, это то же самое — обработчик выполняется после функции игры. event.result — то, что игра ответила, а возвращённое значение его заменяет. Менять поля здесь бесполезно: игра их уже использовала. Чтобы снять такой обработчик, передайте true и в removeEventListener.

Касания

game
.
addEventListener
("touch", onTouch, { 
toucher
: "player", 
touched
: "player" });

function onTouch(
event
: TouchEvent) {
    const 
player
 = new 
Player
(
event
.
toucher
.
id
);
    const 
below
 = new 
Player
(
event
.
touched
.
id
);
    if (
player
.
groundEntity
 == 
below
.
id
) 
console
.
log
(`${
player
.
name
} стоит на ${
below
.
name
}`);
}

"touch" — касание двух сущностей: event.toucher вошла в event.touched, обе — Entity. Касание случается каждый кадр у каждого игрока, который на чём-то стоит, поэтому третий аргумент называет классы, о которых обработчик, — toucher, touched или оба, — и до плагина доходят только эти касания: сервер отсеивает их раньше. Класс, который не задан, — любой класс. event.preventDefault() блокирует касание. Два игрока, коснувшиеся друг друга, — это два касания, по одному в каждую сторону.

Один класс сущностей

game
.
addEventListener
("primaryAttack", onSlash, { 
classname
: "weapon_knife" });

function onSlash(
event
: PrimaryAttackEvent) {
    const 
knife
 = 
event
.
weapon
;
    
knife
.
secondaryAttack
();         // вместо этого правый клик; на нём срабатывают обработчики всех плагинов
    
event
.
preventDefault
();          // а левый — нет
}

game
.
addEventListener
("takeDamage", (
event
) => {
    
console
.
log
(`${
event
.
entity
.
classname
} took ${
event
.
damage
}`);
}, { 
classname
: "func_breakable" });

Атака оружия, использование двери, «мысль» сущности — события одного класса сущностей: его называет classname в третьем аргументе, и до плагина доходят только его сущности — сервер отсеивает остальные раньше. { classname, post: true } слушает после того, как игра сработала.

Событие об игроке — takeDamage, killed, spawn — без classname относится к игроку, а с ним — к другому классу: event.player — игрок, event.entity — сущность названного класса. Событие об оружии — canDeploy, itemPostFrame — без classname относится ко всему оружию, с ним — к одному классу. Событию только об одном классе сущностей — primaryAttack, deploy, think, use — нужен classname. Поле такого события можно присвоить там, где игра его принимает обратно, — сущность и вектор тоже.

Те же функции — методы сущности: игра выполняет их так же, как сама, и обработчики всех плагинов об этом слышат:

knife.deploy();                          // снова в руках: модель и анимация
knife.deploy({ 
hooks
: false });          // только функция игры, без обработчиков
player
.
jump
();
door.use(
player
, 
player
, "toggle", 0);

Что есть у события

• Поля — данные события с типами: event.damage — number, event.damageType — Damage[] (флаги), текст — string. Поле называется словами: event.trace, event.info, event.direction, event.start; подсказка называет параметр так, как его называет ReAPI.
• Сущности — объекты: игрок — Player, оружие — Weapon, всё остальное — Entity. event.attacker.team, event.player.health.
• event.player — игрок, о котором событие: тот, кто получает урон, возрождается, прыгает, ослеплён.
• event.result в обработчике, который выполняется после игры, — ответ игры.

Наведите на имя события — подсказка скажет, что это за событие, на поле — что в нём лежит. Последняя строка подсказки называет его так, как его зовут ReAPI и Ham Sandwich (Pawn: `RG_CBasePlayer_TakeDamage`, `Ham_TakeDamage` ).

С чего начать

¹ На сервере без ReAPI слышно не всё, ² там не слышно: сервер без ReAPI.

Все события, их около 250, показывает редактор.

Событие называется по тому, что делает игра, в camelCase, какой бы модуль его ни слышал: RG_CBasePlayer_TakeDamage и Ham_TakeDamage — оба "takeDamage", RG_CSGameRules_PlayerSpawn — "playerSpawn" (появление игрока в раунде), а RG_CBasePlayer_Spawn — "spawn", Ham_Weapon_PrimaryAttack — "primaryAttack". Тип события — имя в PascalCase с Event: TakeDamageEvent, PrimaryAttackEvent.

canPlayerHearPlayer игра спрашивает, только пока sv_alltalk равен 0: с включённым alltalk она не спрашивает никого. Чтобы заглушить игрока при любом alltalk, есть player.muted (Игроки).

Перечисления и флаги — имена

Поле, в котором лежит одно значение из фиксированного набора, — это имя, а поле с битовыми флагами — массив имён:

game
.
addEventListener
("roundEnd", (
event
) => {
    if (
event
.
reason
 == "targetSaved") 
console
.
log
("точку отстояли");
    if (
event
.
winner
 == "CT") 
console
.
log
("победил спецназ");
});

game
.
addEventListener
("showVguiMenu", (
event
) => {
    if (
event
.
menu
 == "team") 
event
.
preventDefault
();
});

game
.
addEventListener
("sendDeathMessage", (
event
) => {
    if (
event
.
rarity
.
includes
("headshot")) 
console
.
log
("в голову");
});

Присвоенное имя меняет значение, которое получит игра: event.reason = "terroristsWin". Значение, для которого нет имени, — его передал другой плагин или мод, — читается как "unknown" ("none" у RoundWinner и WeaponKind, "UNASSIGNED" у Team), а присваивание "unknown" оставляет поле таким, каким его передала игра. Флаги без имени при присваивании массива флагов сохраняются.

Сервер без ReAPI с v0.2

У ReGameDLL и ReHLDS есть собственные события — появление игрока в раунде, начало и конец раунда, деньги, покупки, — их доставляет ReAPI. На сервере без них — HLDS от Valve с AMX Mod X — большую часть из них слышно так, как их слышит там плагин на Pawn: новый раунд — по сообщению HLTV, конец заморозки и конец раунда — по логу игры, появление и смерть — через Ham Sandwich, деньги — по сообщению Money, покупку — через cstrike. Плагин пишется так же; способ amxts выбирает один раз, когда сервер стартует.

Чего такое событие там дать не может, сказано в таблице ниже и в подсказке редактора к событию. Обработчик, который всё равно этого просит, — preventDefault(), ответ, запись поля, — это одна строка в консоли сервера, один раз на событие; поле, которое событию нечем заполнить, читается как 0, "", null или мир.

Порядок раунда — как у игры: newRound до того, как игроки возродятся, их playerSpawn, newRound после игры, когда они живы, roundStart, roundEnd.

Конец раунда

game
.
endRound
({ 
winner
: "TERRORIST" });                      // победа террористов; следующий раунд через 5 с
game
.
endRound
({ 
winner
: "CT", 
delay
: 3 });
game
.
endRound
({ 
winner
: "draw", 
message
: "Никто не победил" });
game
.
endRound
({ 
winner
: "none", 
delay
: 0.1, 
message
: "" });  // тихий рестарт

Правила игры

if (
game
.
isFreezeTime
) 
console
.
log
("раунд ещё не начался");
game
.
isFreezeTime
 = false;               // закончилась — для собственных проверок игры
game
.
ctWins
 = 0;                         // счёт, на таблице сразу
if (
game
.
roundWinner
 == "CT") 
console
.
log
("последний раунд взял спецназ");

Собственное состояние игры — заморозка, счёт, время раунда, что есть на карте — это поля game, типизированные так же, как поля игрока: число, булево значение, текст, победитель раунда именем. Имена — слова игрока для члена: m_bFreezePeriod — это isFreezeTime, m_iNumCTWins — ctWins, m_iRoundWinStatus — roundWinner, остальные редактор показывает вместе со значением и именем члена. Записанный счёт команды — ctWins, terroristWins — сразу виден на таблице, как когда игра засчитывает раунд.

Async-обработчики

Обработчик может быть async и ждать внутри через await (async). То, что он вернёт до первого await, — его ответ игре. После await игра уже пошла дальше: обработчик ещё может действовать — написать в чат, выдать предмет, — но то, что он вернёт, до игры уже не дойдёт.

Ограничения

• Поле-вектор записывается целиком. event.direction = new Vector(0, 0, 1) поворачивает выстрел traceAttack; event.direction.z = 1 меняет копию, и игра её не увидит.
• Сообщения клиентам слышны через server.addMessageListener (Сообщения); временные эффекты — это эффекты.