RunRena SDK

SDK для подключения к игре RunRena через WebSocket.

🎮 О игре RunRena

RunRena — это мультиплеерная сессионная игра в жанре "арена побега", где игроки управляют гладиаторами-новобранцами в смертельной гонке за выживание.

🌟 Концепция

Вдохновленная идеями из Screeps, RunRena представляет собой уникальный опыт, где каждый игрок может написать собственного бота или управлять персонажем вручную через API. Это не просто игра — это платформа для экспериментов с алгоритмами и стратегиями.

🏛️ Мир игры

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

⚠️ Осторожно! Слишком долгое пребывание рядом с форпостом привлечет внимание стражей. А через 5 минут после старта арена будет зачищена элитными войсками — и все выжившие погибнут.

⚔️ Игровая механика

🕐 Сессия

• Длительность: пока есть хотя бы один живой игрок или до 5 минут
• Минимум игроков: 1
• Лобби: 1 минута ожидания после первого подключения

🗺️ Мир

• Размер карты: от 50 клеток в длину
• Стартовая зона: 5×10 клеток (зона возле старта)
• Зона спасения: 1×10 клеток (правая граница)

👁️ Обзор

• Видимость: только 5×5 клеток вокруг персонажа
• Навигация: без координат — ориентируйтесь по окружению
• Вызов: планируйте маршрут, не видя всей карты

🎯 Действия

• 1 действие за тик (1 секунда)
• Движение: вверх, вниз, влево, вправо
• Будущее: атака, подбор предметов, использование объектов

⏱️ Цикл игры

Каждая секунда делится на фазы:

• 0-300мс: Прием команд от игроков
• 300-600мс: Обработка и валидация действий
• 600-700мс: Буфер
• 700-1000мс: Отправка обновлений игрокам

🏆 Система очков

Цель: Добраться до выхода живым!

Награда: Очки равны количеству секунд, оставшихся до конца сессии

• Чем быстрее вы дойдете — тем больше очков получите
• Счет сохраняется в таблице результатов

🎯 Условия победы

Сессия заканчивается когда:

• ✅ Все игроки достигли финиша
• 💀 Все игроки погибли
• ⏰ Истекло 5 минут

Готовы испытать свои навыки программирования и стратегического мышления? Добро пожаловать на арену!

🚀 Установка

npm install @runrena/sdk

⚡ Быстрый старт

import { RunRenaClient, moveDirection } from '@runrena/sdk';

const client = new RunRenaClient({
  url: 'ws://localhost:8080'
});

// Подключение
await client.connect();

// Вход в лобби
client.enterToLobby('MyNickname');

// Обработка событий
client.onLobbyWelcome((message) => {
  console.log('Добро пожаловать!', message.playerId);
});

client.onGamePlayerState((message) => {
  if (message.playerState === 'alive') {
    client.move(moveDirection.UP);
  }
});

API

RunRenaClient

Основной класс для подключения к игре.

Конструктор

new RunRenaClient(options?: RunRenaClientOptions)

Параметры:

• options.url - URL WebSocket сервера (по умолчанию: 'ws://localhost:8080')
• options.reconnectAttempts - Количество попыток переподключения (по умолчанию: 5)
• options.reconnectInterval - Интервал между попытками переподключения в мс (по умолчанию: 3000)

Методы

connect(): Promise<void>

Подключается к серверу.

disconnect(): void

Отключается от сервера.

enterToLobby(nickname: string): void

Входит в лобби с указанным никнеймом.

move(direction: MoveDirectionValue): void

Отправляет команду движения игрока.

Направления:

• moveDirection.UP - вверх
• moveDirection.DOWN - вниз
• moveDirection.LEFT - влево
• moveDirection.RIGHT - вправо

reconnect(): void

Переподключает игрока с сохраненными данными.

get connected: boolean

Возвращает состояние подключения.

get lobbyInfo: { playerId: string | null; token: string | null }

Возвращает информацию о текущем игроке.

События

Клиент предоставляет типизированные методы для подписки на события:

onConnect(callback: () => void)

Подписка на событие подключения к серверу.

client.onConnect(() => {
  console.log('Подключен к серверу');
});

onDisconnect(callback: () => void)

Подписка на событие отключения от сервера.

client.onDisconnect(() => {
  console.log('Отключен от сервера');
});

onError(callback: (error: Error) => void)

Подписка на ошибки подключения или обработки сообщений.

client.onError((error) => {
  console.error('Ошибка:', error.message);
});

onLobbyWelcome(callback: (message: LobbyWelcomeMessage) => void)

Подписка на приветственное сообщение от лобби.

client.onLobbyWelcome((message) => {
  console.log('Player ID:', message.playerId);
  console.log('Token:', message.token);
  console.log('Игра начнется в:', new Date(message.startGameAt));
});

onLobbyPing(callback: (message: LobbyPingMessage) => void)

Подписка на ping сообщения от лобби.

client.onLobbyPing((message) => {
  console.log('Игроков в лобби:', message.playersNumber);
  console.log('Игра начнется в:', new Date(message.startGameAt));
});

onGamePlayerState(callback: (message: PlayerStateMessage) => void)

Подписка на состояние игрока во время игры.

client.onGamePlayerState((message) => {
  console.log('Tick:', message.tickIndex);
  console.log('Состояние:', message.playerState);
  console.log('Видимая область:', message.visibleArea);
});

onGameOver(callback: (message: GameOverMessage) => void)

Подписка на окончание игры.

client.onGameOver((message) => {
  console.log('Ранг:', message.rank);
  console.log('Счет:', message.score);
  console.log('Сбежал:', message.escaped);
});

onGameError(callback: (message: GameErrorMessage) => void)

Подписка на ошибки в игре.

client.onGameError((message) => {
  console.error('Ошибка игры:', message.message);
});

Преимущества типизированных событий

Новый API предоставляет следующие преимущества:

• Типобезопасность: TypeScript проверяет типы параметров колбеков
• Автодополнение: IDE предоставляет автодополнение для свойств сообщений
• Рефакторинг: Безопасное переименование свойств с проверкой всех использований
• Документация: Четкие сигнатуры методов показывают, какие данные ожидаются
• Отсутствие опечаток: Невозможно ошибиться в названии события

// ❌ Старый способ (не рекомендуется)
client.on('lobby.welcome', (message) => {
  // message имеет тип any, нет автодополнения
  console.log(message.playerId); // Может быть опечатка
});

// ✅ Новый способ (рекомендуется)
client.onLobbyWelcome((message) => {
  // message имеет тип LobbyWelcomeMessage
  console.log(message.playerId); // Автодополнение и проверка типов
});

Типы данных

Состояния игрока

• playerState.ALIVE - игрок жив
• playerState.DEAD - игрок мертв

Типы точек на карте

• pointType.WALL - стена
• pointType.EMPTY - пустое место
• pointType.SELF_PLAYER - текущий игрок
• pointType.SOME_PLAYER - другой игрок

Направления движения

• moveDirection.UP - вверх
• moveDirection.DOWN - вниз
• moveDirection.LEFT - влево
• moveDirection.RIGHT - вправо

Пример полного использования

import { RunRenaClient, moveDirection } from '@runrena/sdk';

async function runGame() {
  const client = new RunRenaClient({
    url: 'ws://localhost:8080',
    reconnectAttempts: 3,
    reconnectInterval: 2000,
  });

  // Обработчики событий
  client.onConnect(() => {
    console.log('Подключен к серверу');
    client.enterToLobby('MyBot');
  });

  client.onLobbyWelcome((message) => {
    console.log('В лобби! Игра начнется в:', new Date(message.startGameAt));
  });

  client.onGamePlayerState((message) => {
    if (message.playerState === 'alive') {
      // Простая логика движения
      const directions = Object.values(moveDirection);
      const randomDirection = directions[Math.floor(Math.random() * directions.length)];
      client.move(randomDirection);
    }
  });

  client.onGameOver((message) => {
    console.log(`Игра окончена! Ранг: ${message.rank}, Счет: ${message.score}`);
  });

  client.onError((error) => {
    console.error('Ошибка:', error.message);
  });

  try {
    await client.connect();
  } catch (error) {
    console.error('Не удалось подключиться:', error);
  }
}

runGame();

Примеры

В папке examples/ находятся примеры использования SDK:

• basic.ts - Базовый пример с простой логикой движения
• typed-events.ts - Демонстрация преимуществ типизированных событий

Для запуска примера:

# Сборка SDK
npm run build

# Запуск примера (требует tsx)
npx tsx examples/basic.ts

Разработка

Для разработки SDK:

# Установка зависимостей
npm install

# Сборка
npm run build

# Разработка с автопересборкой
npm run dev

Лицензия

ISC