Minecards Renderer

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

Посмотреть живое демо

О проекте

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

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

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

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

Установка

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

npm install minecards-renderer

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

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

1. HTML

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

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

2. JavaScript

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

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) при смене страницы, чтобы избежать утечек памяти.

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

Стилизация

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

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

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

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

Лицензия

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