API игры и типы

Вспомогательные методы SDK покрывают повторяющиеся задачи, а API игры — это объекты, свойства и методы, которые предоставляет KILLSCRIPT. В нём находятся игроки, предметы, камеры, физика, состояние Defusal, UI, визуальные объекты, чат, звук и остальная модель модуля.

В одном проекте нормально и ожидаемо использовать оба слоя.

Прямой вызов API игры

Проект от CLI автоматически подключает правильные объявления типов. Для глобальных API Agents, Physics, Cameras и NotificationController не нужен импорт реализации:

import { quaternion } from "@killscript/sdk/client";

const camera = Cameras.Main;
const direction = quaternion.rotate(camera.Rotation, Vector3.forward);
const hit = Physics.Raycast(camera.Position, direction, 100);

if (hit.HasHit) {
  NotificationController.ShowHint(
    `Surface distance: ${hit.Distance}`,
    2,
  );
}

TypeScript не умеет типизировать нативный оператор Quaternion, поэтому пример использует один вспомогательный метод SDK для поворота, а затем продолжает работать с объектами игры. Так же поступайте в остальных местах, где небольшой метод делает прямой вызов API понятнее.

Разный API клиента и Reflex

У созданного проекта две конфигурации типов:

• tsconfig.client.json подключает @killscript/types/client для камер, ввода, UI, звука и остальных клиентских API отображения;
• tsconfig.server.json подключает @killscript/types/server для Reflex и не содержит клиентских глобальных API.

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

Типы показывают право записи и значения, которые отсутствуют независимо от состояния игры. Поле нельзя изменить лишь потому, что оно похоже на JavaScript-свойство, а необязательный объект требует проверки undefined.

Скрытие данных по видимости условно и пока не полностью выражается типами. Для невидимого Entity проверяйте IsVisible перед чтением всех полей, кроме ID и Name. Для невидимого Hitbox проверяйте IsVisible перед чтением остальных полей, даже если TypeScript показывает их обязательными.

Где искать поведение, а не только сигнатуру

Открывайте отдельный проверенный справочник KILLSCRIPT API, когда нужно узнать:

• где появляется notification или hint;
• доступно ли поле на клиенте или сервере и можно ли в него писать;
• в каких координатах или единицах задано значение;
• что означает событие и какие поля есть в его payload;
• минимальный пример нативного вызова.

Эта документация объясняет TypeScript-инструменты и вспомогательные методы. Справочник API объясняет поведение игры. Разделы ссылаются друг на друга, вместо того чтобы держать здесь вторую устаревающую копию API.

Откуда берутся типы

Объявления типов генерируются из публичных метаданных LuaType/LuaGen игровой сборки, затем уточняются проверенными контекстом, правом записи и статически необязательными значениями. Они существуют только при компиляции и ничего не добавляют в Lua.

Game и Random помечены самой игрой как LuaDocSkip, поэтому не считаются поддерживаемым публичным API модулей. Tutorial internals также не относятся к поддерживаемому процессу создания модулей. Это осознанное исключение, а не забытая обёртка.

Если проверенный публичный элемент API игры отсутствует в объявлениях, его имя и контекст клиента или Reflex следует оформить как баг покрытия типов.