Перейти к основному содержимому

Методы

Список доступных функций и объектов для работы с игроками и объектами на сервере.

Объект игрока​

API.movePlayer (pRef, x, y)​

Перемещает игрока в нужное место.

  • pRef (object) - ссылка на объект игрока (API.players[ID])
  • x (float number) - позиция координаты x на локации.
  • y (float number) - позиция координаты y на локации.

Пример создания и перемещения объекта:

let ID = 1; // player ID
let playerReference = API.player[ID];

API.movePlayer(playerReference, 105, 105);

API.kickPlayer (ID)​

Выкидывает игрока из комнаты, сохраняя его прогресс (свойство .objs) и удаляя его из API.players.

  • ID (number) - ID игрока.

Пример:

API.kickPlayer(ID);

Объекты​

API.createObject (prefabName, owner, x, y): int​

Создает объект из префаба в указанной позиции.

  • prefabName (string) - название префаба, копию которого нужно создать.
  • creator (object) - владелец объекта (базовое значение: "server").
  • x (float number) - позиция координаты x на локации.
  • y (float number) - позиция координаты y на локации.

Возвращает ID созданного объекта.

Связь с создателем объекта

Пример владельца игрока: {"p": pID}. Если игрок с указанным ID отключается, то объект будет автоматически удален.

Помимо просто ID, можно указать еще и свойство объекта игрока с определенным значением в виде массива playerConditions. Если значение поменяется, или свойство будет удалено, объект также будет удален.

Пример:

// Если pRef.name1 не существует, или он не равен "value1", созданный ниже объект будет сразу удален.

let _objectID = API.createObject("Object", {"p": pRef.id, "playerConditions": [{"property": "name1", "value": "value1"}]}, _x, _y);

Пример создания объекта из префаба Prefab1 без владельца и находящийся на координатах x:100 y:100:

let objectID = API.createObject("Prefab1", "server", 100, 100);

API.moveObject (objectReference, x, y)​

Перемещает объект в нужное место.

  • objectReference (reference) - ссылка на объект (objects[ID])
  • x (float number) - позиция координаты x на локации.
  • y (float number) - позиция координаты y на локации.

Пример создания и перемещения объекта:

let objectID = API.createObject("Prefab1", "server", 100, 100);
let objectReference = API.objects[objectID];

API.moveObject(objectReference, 105, 105);

API.changeObjectAttr​

API.deleteObject (ID)​

Удаляет объект.

  • ID (number) - ID объекта.

Пример создания и удаления объекта:

let objectID = API.createObject("Prefab1", "server", 100, 100);
API.deleteObject(objectID);

Доступ к игрокам и объектам​

API.players : object​

Объект, содержащий в себе референсы на всех игроков онлайн на сервере.

Доступ по ID игрока: API.players[ID].

API.objects : object​

Объект, содержащий в себе референсы на все объекты на сервере.

Доступ по ID объекта: API.objects[ID].

Расстояние​

API.isWithinDistance(x1, x2, y1, y2, distance) : bool​

Метод сравнивает расстояние между двумя точками: (x1, y1) и (x2, y2) и если оно меньше чем distance, то возвращает значение true. Если расстояние между точками больше чем distance, возвращает значение false.

API.isWithinSquares(x1, x2, y1, y2, distance) : bool​

Метод сравнивает квадрат расстояния между двумя точками: (x1, y1) и (x2, y2) и если оно меньше чем distance, то возвращает значение true. Если расстояние между точками больше чем distance, возвращает значение false.

Таким образом, в случае с isWithinSquares, distance является квадратом того distance, который использовался бы в isWithinDistance.

Зачем это нужно?

Сравнивая квадраты расстояний, не нужно вычислять корни (sqrt). Таким образом, если нужно найти ближайший объект среди объектов, лучше сравнивать расстояния с помощью isWithinSquares, ведь так можно избежать лишней "дорогой" операции извлечения корня (sqrt).

API.distance(x1, x2, y1, y2) : float​

Метод возвращает расстояние между двумя точками: (x1, y1) и (x2, y2).

API.squares(x1, x2, y1, y2) : float​

Метод возвращает квадрат расстояния между двумя точками: (x1, y1) и (x2, y2).

Пример получения ближайшего объекта к определенной координате.
let list = API.getObjectsAround(x, y, "any");

let closestObject = {"id": -1, "distance": Number.POSITIVE_INFINITY};

let nearObjects = list.o;

for (let o = 0; o < nearObjects.length; o++){
    let oID = nearObjects[o];
    let oRef = API.objects[oID];
    if (oRef === undefined){
        continue;
    }

    let _distance = API.squares(x, oRef.x, y, oRef.y);

    if (closestObject.distance > _distance){
        closestObject.id = oID;
        closestObject.distance = _distance;
    }

}

console.log("Closest objectID:", closestObject.id, "Distance:", closestObject.distance);

// В переменной closestObject содержится объект с .id ближайшего к (x, y) объекта.
// Если ни одного объекта нет, .id = -1.

API.getDistance(obj1, obj2) : float​

  • obj1 (object) - референс на объект игрока или объекта (из API.playersObjects или API.objects).
  • obj2 (object) - референс на объект игрока или объекта (из API.playersObjects или API.objects).

Метод возвращает расстояние между двумя объектами: (obj1.x, obj1.y) и (obj2.x, obj2.y).

Подходят любые объекты для сравнения, в которых есть свойства .x и .y.

API.getSquares(obj1, obj2) : float​

  • obj1 (object) - референс на объект игрока или объекта (из API.playersObjects или API.objects).
  • obj2 (object) - референс на объект игрока или объекта (из API.playersObjects или API.objects).

Метод возвращает квадрат расстояния между двумя объектами: (obj1.x, obj1.y) и (obj2.x, obj2.y).

Подходят любые объекты для сравнения, в которых есть свойства .x и .y.

Ближайшие объекты​

API.getEachPlayerAround(x, y, (pID, pRef) => {})​

  • x (float number) - позиция координаты x на локации.
  • y (float number) - позиция координаты y на локации.

Метод вызывает колбек (pID, pRef) => {} с ID и референсом каждого игрока, который находится рядом с позицией (x, y).

Можно остановить получение следующих колбеков, вызвав в текущем return false;.

Пример получения каждого игрока рядом с объектом с ID 1, а если какой-то игрок ближе к этому объекту чем 3 условные единицы расстояния, то объект будет уничтожен:

let objectID = 1;
let objRef = API.objects[objectID];

API.getEachPlayerAround(objRef.x, objRef.y, (pID, pRef) => {

    if (API.getDistance(objRef, pRef) < 3){
        API.deleteObject(objectID);
    }

});
Ранняя остановка колбека

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

Чтобы решить эту проблему, нужно вернуть значение false изнутри колбека:

API.getEachPlayerAround(objRef.x, objRef.y, (pID, pRef) => {

    if (API.getDistance(objRef, pRef) < 3){
        API.deleteObject(objectID);
        return false; // Останавливаем обработку всех следующих игроков, так как это больше не имеет смысла
    }

});

API.getEachObjectAround(x, y, (oID, oRef) => {})​

  • x (float number) - позиция координаты x на локации.
  • y (float number) - позиция координаты y на локации.

Метод вызывает колбек (oID, oRef) => {} с ID и референсом каждого объекта, который находится рядом с позицией (x, y).

Можно остановить получение следующих колбеков, вызвав в текущем return false;.

По сути это тот же метод, что и API.getEachPlayerAround, но для остальных объектов, а не игроков.

API.getObjectsAround(x, y, type) : object​

Не самый эффективный метод

Этот метод составляет два списка из ID игроков и объектов, после чего с этими списками можно работать. Но с помощью предыдущих методов можно сразу приступить к работе с игроками и объектами в более читаемом виде.

Этот метод не рекомендуется использовать на этапе освоения KotikiServer.

Метод возвращает объект вида {"p": [], "o": []}, состоящий из двух массивов: список IDs близких объектов и игроков к координатам x и y.

  • x (float number) - позиция координаты x на локации.
  • y (float number) - позиция координаты y на локации.
  • type (string) - можно выбрать, какие списки получить:
Варианты type
  • "p" для игнорирования объектов.
  • "o" для игнорирования игроков.
  • "any" или любое другое значение - получить списки и игроков и объектов.

Пример получения ближайших к объекту игроков и перебор их массивом:

let objectReference = API.objects[1]; // Получаем объект с ID 1.
let _list = API.getObjectsAround(objectReference.x, objectReference.y, "p");
for (let o = 0; o < _list.p.length; o++){
    let pID = _list.p[o];
    let pRef = API.playersObjects[pID];
    if (pRef === undefined){
        continue;
    }

    // Здесь Ваш код для дальнейшей работы с pRef - референсом текущего близкого игрока к объекту objectReference.


}

Пример получения ближайших к объекту объектов (включая сам объект, так как он очевидно рядом) и перебор их массивом:

let objectID = 1;
let objectReference = API.objects[objectID]; // Получаем объект с ID 1.
let _list = API.getObjectsAround(objectReference.x, objectReference.y, "o");
for (let o = 0; o < _list.o.length; o++){
    let oID = _list.o[o];
    let oRef = API.objects[oID];
    if (oRef === undefined){
        continue;
    }
    if (oID == objectID){
        continue; // Игнорируем сам объект, "вокруг" которого мы получаем ближайшие объекты
    }

    // Здесь Ваш код для дальнейшей работы с oRef - референсом текущего близкого объекта к объекту objectReference.


}

Полезные методы​

API.getEachPlayer((pID, pRef) => {})​

Метод вызывает колбек (pID, pRef) => {} с ID и референсом каждого игрока на сервере.

Можно остановить получение следующих колбеков, вызвав в текущем return false;.

По своей сути работает как API.getEachPlayerAround(), только без ограничений на ближайших к координате игроков.

API.getEachObject((oID, oRef) => {})​

Метод вызывает колбек (oID, oRef) => {} с ID и референсом каждого объекта на сервере.

Можно остановить получение следующих колбеков, вызвав в текущем return false;.

По своей сути работает как API.getEachObjectAround(), только без ограничений на ближайших к координате объектов.

API.randomX() : float​

Метод возвращает случайную координату от minX до maxX (случайная координата на оси X в пределах размера локации).

Пример создания объекта со случайными координатами:

let _objectID = API.createObject("DemoPrefab", "server", API.randomX(), API.randomY());

API.randomY() : float​

Метод возвращает случайную координату от minY до maxY (случайная координата на оси Y в пределах размера локации).

Пример создания объекта со случайными координатами:

let _objectID = API.createObject("DemoPrefab", "server", API.randomX(), API.randomY());

API.cooldown(key1, key2, timeout) : bool​

  • key1 (string) - Один из ключей для индексации, например ID игрока
  • key2 (string) - Один из ключей для индексации, например тип действия
  • timeout (int) - Время для перезарядки в миллисекундах (пример: 1000 - это 1 секунда).

Этот метод используется для временного ограничения какого-либо действия. Если вызвать метод два раза с одинаковыми аргументами, в первом вызове метод вернет true (ограничение зарегистрировано), а во второй раз вернет false (ограничение все еще действует и новое не было зарегистрировано).

Иными словами, этот метод используется, чтобы позволять выполнять какое-то действие только 1 раз за время timeout.

Поместим внутрь события 'tick' такой код:

if (API.cooldown("key1", "key2", 5000) == true){
    console.log("First cooldown.");
}

Получится нечто подобное:

Events.on('tick', (currentTick) => {

    if (API.cooldown("first", "cooldown", 5000) == true){
        console.log("First cooldown.");
    }

});

Сообщение First cooldown. будет выводиться в консоль только раз в 5 секунд (то есть раз в 5,000 мс).

Два аргумента key (key1 и key2) нужны для более удобного понимания логики кулдауна, если он привязан к действию конкретного игрока или объекта.

Например, чтобы разрешить игроку или объекту совершать какое-то действие не чаще одного раза в какой-то промежуток времени:

// Допустим, у нас есть переменная pID с ID игрока:

if (API.cooldown("player" + pID, "actionName", 3000) == true){
    
    // Некоторый код для совершения действия actionName,
    // который не получится выполнить чаще чем раз в 3 секунды.

}

API.playMoneySound(pRef)​

  • pRef (object) - ссылка на объект игрока (API.players[ID])

Метод проигрывает звук "подобранной монетки" на стороне пользователя.

API.showLangErrorText(pRef, key)​

  • pRef (object) - ссылка на объект игрока (API.players[ID])
  • key (string) - индекс элемента языкового файла.

Метод отображает указанному пользователю всплывающее окно об ошибке. Текст ошибки должен находиться в языковом файле.

API.moveTowards(fromRef, toRef, distanceStep)​

  • fromRef (object) - ссылка на первый объект
  • toRef (object) - ссылка на второй объект
  • distanceStep (number) - расстояние

Метод двигает первый объект (fromRef) ко второму объекту (toRef). distanceStep определяет, на какое расстояние приблизить объект. Если distanceStep меньше, чем расстояние между двумя объектами, первый объект сразу переместится на координаты второго объекта.