minecards-renderer/README.md

A library for displaying interactive 3D collectible cards for Telegram bot Minecrads and their web interface.

# Minecards Renderer

[![npm version](https://img.shields.io/npm/v/minecards-renderer.svg?style=flat-square)](https://www.npmjs.com/package/minecards-renderer)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)

Библиотека для отрисовки красивых и интерактивных коллекционных 3D-карточек для проекта **Mincards**.

[**Посмотреть живое демо**](https://ivansobolev.github.io/CardViewer/)

## О проекте

Этот рендерер был создан как фронтенд-компонент для проекта **Mincards** — Телеграм-бота с веб-интерфейсом, где пользователи могут коллекционировать карточки с Minecraft-ютуберами.

Задача библиотеки — взять набор данных (редкость, изображения, скин) и превратить их в красивую, анимированную и интерактивную карточку прямо в браузере.

### Ключевые возможности

*   🎨 **Динамическая рамка редкости:** Анимированная рамка меняет свой цвет в зависимости от редкости карты (`Wood`, `Iron`, `Gold`, `Diamond`, `Netherite`, `Signed`).
*   🖼️ **Настраиваемый фон и логотип:** Легко задать уникальный фон для карты и логотип пака.
*   🕺 **Анимированный 3D-скин:** Отображает и анимирует стандартный скин Minecraft, используя библиотеку `skin3d`.
*   ✨ **Интерактивные эффекты:** Карта реагирует на движение мыши, создавая 3D-эффект наклона. Редкие карты имеют дополнительный эффект мерцания.
*   🎟️ **Система наклеек:** Позволяет динамически загружать и отображать HTML-контент поверх карты, создавая систему "наклеек" или других кастомных элементов.
*   📦 **Простота встраивания:** Разработана как инструмент, который легко интегрировать в любой веб-проект.

## Установка

Для установки библиотеки используйте npm или yarn:

```bash
npm install minecards-renderer
```

## Быстрый старт

Использовать библиотеку очень просто. Вам понадобится контейнер в HTML и несколько строк JavaScript.

**1. HTML**

Добавьте на свою страницу `div` элемент, в котором будет отрисована карточка.

```html
<!-- Задайте размеры контейнера через CSS -->
<div id="card-container"></div>
```

**2. JavaScript**

Импортируйте класс `Card` и стили, создайте объект с данными и инициализируйте карточку.

```javascript
import { Card } from 'minecards-renderer';
// Не забудьте импортировать стили!
import 'minecards-renderer/dist/style.css';

// 1. Найдите контейнер на странице
const cardContainer = document.getElementById('card-container');

// 2. Подготовьте данные для карточки
// (В реальном проекте эти данные будут приходить с вашего бэкенда)
const cardData = {
    rarity: 'Signed',
    backgroundImage: 'https://i.imgur.com/your-background.png',
    skinImage: 'https://i.imgur.com/your-skin.png',
    packLogoImage: 'https://i.imgur.com/your-pack-logo.jpg',
    stickerUrl: '/api/stickers/cool-sticker.html' // Необязательный параметр
};

// 3. Создайте новый экземпляр карточки
const myCard = new Card(cardContainer, cardData);
```

## API

### `new Card(container, options)`

Создает и отрисовывает новую карточку.

*   `container` (HTMLElement): DOM-элемент, внутри которого будет создана карточка.
*   `options` (Object): Объект с параметрами для настройки внешнего вида карты.

### Объект `options`

| Параметр          | Тип      | Обязательный | Описание                                                                                                                              |
| ----------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `rarity`          | `String` | **Да**       | Редкость карты. Влияет на цвет рамки и эффекты. Возможные значения: `'Wood'`, `'Iron'`, `'Gold'`, `'Diamond'`, `'Netherite'`, `'Signed'`. |
| `backgroundImage` | `String` | **Да**       | URL-адрес фонового изображения для карты.                                                                                             |
| `skinImage`       | `String` | **Да**       | URL-адрес файла скина Minecraft (например, `64x64.png`).                                                                                |
| `packLogoImage`   | `String` | **Да**       | URL-адрес изображения для логотипа пака в правом нижнем углу.                                                                         |
| `stickerUrl`      | `String` | Нет          | URL, по которому будет загружен HTML-контент для "наклеек". Если не указан, слой наклеек будет пустым.                                  |

### Методы экземпляра

#### `card.destroy()`

Полностью удаляет карточку, ее DOM-элементы и все обработчики событий. Это важно использовать в одностраничных приложениях (SPA) при смене страницы, чтобы избежать утечек памяти.

```javascript
// Когда карточка больше не нужна
myCard.destroy();
```

## Стилизация

Библиотека поставляется с готовым файлом стилей, который необходимо импортировать.

```javascript
import 'minecards-renderer/dist/style.css';
```

**Важно:** Контейнер, в который вы помещаете карточку, должен иметь заданные размеры (ширину и высоту). Библиотека адаптирует карточку под размеры контейнера. Рекомендуемое соотношение сторон — близкое к **360x560px**.

```css
#card-container {
    width: 360px;
    height: 560px;
}
```

## Лицензия

Распространяется под лицензией MIT. Смотрите файл `LICENSE` для более подробной информации.