telegram-slot-map 1.0.2

Complete and customizable mapping of Telegram slot machine (🎰) dice values (1-64) to symbol combinations

telegram-slot-map

Полная и настраиваемая расшифровка всех 64 исходов слота 🎰 в Telegram.

Когда бот отправляет dice с эмодзи 🎰, сервер возвращает dice.value — число от 1 до 64. Эта библиотека даёт точное соответствие каждой комбинации символов и позволяет заменить их на свои эмодзи, стикеры или текст.

---

📦 Установка

pip install telegram-slot-map

---

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

Когда вы создаете Telegram бота с игровым функционалом (казино, слоты), вам нужно:

1. Понимать результат — что выпало на слоте по числу от 1 до 64
2. Кастомизировать внешний вид — заменить стандартные символы на свои
3. Реализовать игровую логику — проверять выигрышные комбинации

Эта библиотека решает все три задачи!

---

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

Что вы получаете от Telegram?

Когда бот отправляет dice с эмодзи 🎰:

# Пример с aiogram
from aiogram import Bot, types

bot = Bot(token="YOUR_TOKEN")

# Отправляем слот
message = await bot.send_dice(chat_id=chat_id, emoji="🎰")

# Telegram возвращает число от 1 до 64
dice_value = message.dice.value  # Например: 22

Что делает библиотека?

Преобразует это число в понятную комбинацию символов:

from slotmap import get_slot_combination

result = get_slot_combination(22)
print(result)
# Вывод: "cherry cherry cherry"

---

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

1. Базовый пример — получить комбинацию

from slotmap import get_slot_combination

# Получаем комбинацию по значению dice
result = get_slot_combination(1)
print(result)  # "bar bar bar"

result = get_slot_combination(43)
print(result)  # "lemon lemon lemon"

result = get_slot_combination(64)
print(result)  # "seven seven seven"

Что получаете: строку с названиями символов через пробел.

---

2. Кастомизация — свои эмодзи и символы

Самая мощная функция! Замените стандартные названия на любые эмодзи, текст или даже ID стикеров.

from slotmap import get_slot_combination

# Создаем свой маппинг
MY_SYMBOLS = {
    'bar': '➖',
    'cherry': '🍒',
    'lemon': '🍋',
    'seven': '7️⃣'
}

# Передаем в функцию
print(get_slot_combination(1, symbols=MY_SYMBOLS))
# Вывод: "➖ ➖ ➖"

print(get_slot_combination(22, symbols=MY_SYMBOLS))
# Вывод: "🍒 🍒 🍒"

print(get_slot_combination(64, symbols=MY_SYMBOLS))
# Вывод: "7️⃣ 7️⃣ 7️⃣"

Ключи для замены: 'bar', 'cherry', 'lemon', 'seven'

---

3. Использование в боте — полный пример

from aiogram import Bot, Dispatcher, types
from aiogram.filters import Command
from slotmap import get_slot_combination

bot = Bot(token="YOUR_TOKEN")
dp = Dispatcher()

# Ваши кастомные символы
CASINO_SYMBOLS = {
    'bar': '💎',
    'cherry': '🍒',
    'lemon': '🍋',
    'seven': '🔥'
}

@dp.message(Command("spin"))
async def spin_slot(message: types.Message):
    # Отправляем слот
    slot_message = await message.answer_dice(emoji="🎰")
    
    # Ждем результат (Telegram присылает его через ~3 секунды)
    await asyncio.sleep(3)
    
    # Получаем значение
    dice_value = slot_message.dice.value
    
    # Преобразуем в красивую строку
    result = get_slot_combination(dice_value, symbols=CASINO_SYMBOLS)
    
    # Отправляем пользователю
    await message.answer(f"Результат: {result}")

if __name__ == "__main__":
    dp.run_polling(bot)

Что получает пользователь:

/spin
🎰 [анимация слота]
Результат: 🍒 🍒 🍒

---

4. Игровая логика — проверка выигрышей

Для реализации казино нужно проверять комбинации. Используйте RAW_SLOT_COMBINATIONS:

from slotmap import RAW_SLOT_COMBINATIONS

dice_value = 22  # Значение от Telegram

# Получаем список символов
combo = RAW_SLOT_COMBINATIONS[str(dice_value)]
print(combo)  # ['cherry', 'cherry', 'cherry']

# Проверяем выигрыш
if combo[0] == combo[1] == combo[2]:
    print("ДЖЕКПОТ! Все три символа совпали!")
    win_amount = 1000
elif combo[0] == combo[1]:
    print("Малый выигрыш! Первые два совпали.")
    win_amount = 100
else:
    print("Не повезло. Попробуй еще раз!")
    win_amount = 0

---

5. Продвинутый пример — система выплат

from slotmap import RAW_SLOT_COMBINATIONS

# Таблица выплат
PAYOUTS = {
    'seven': 100,   # Семерка — самая ценная
    'cherry': 50,
    'lemon': 30,
    'bar': 10
}

def calculate_win(dice_value: int, bet: int) -> int:
    """Рассчитывает выигрыш на основе комбинации"""
    combo = RAW_SLOT_COMBINATIONS[str(dice_value)]
    
    # Все три символа совпали
    if combo[0] == combo[1] == combo[2]:
        symbol = combo[0]
        multiplier = PAYOUTS[symbol]
        return bet * multiplier
    
    # Первые два совпали
    elif combo[0] == combo[1]:
        symbol = combo[0]
        multiplier = PAYOUTS[symbol] // 5
        return bet * multiplier
    
    # Проигрыш
    return 0

# Примеры
print(calculate_win(64, bet=10))  # seven-seven-seven: 10 * 100 = 1000
print(calculate_win(22, bet=10))  # cherry-cherry-cherry: 10 * 50 = 500
print(calculate_win(11, bet=10))  # lemon-lemon-bar: 10 * 6 = 60
print(calculate_win(2, bet=10))   # cherry-bar-bar: 0

---

6. Использование с другими библиотеками

python-telegram-bot

from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes
from slotmap import get_slot_combination

SYMBOLS = {'bar': '💎', 'cherry': '🍒', 'lemon': '🍋', 'seven': '🔥'}

async def spin(update: Update, context: ContextTypes.DEFAULT_TYPE):
    # Отправляем слот
    msg = await update.message.reply_dice(emoji="🎰")
    
    # Ждем результат
    await asyncio.sleep(3)
    
    # Получаем и форматируем
    result = get_slot_combination(msg.dice.value, symbols=SYMBOLS)
    await update.message.reply_text(f"Выпало: {result}")

app = Application.builder().token("YOUR_TOKEN").build()
app.add_handler(CommandHandler("spin", spin))
app.run_polling()

Telethon

from telethon import TelegramClient, events
from slotmap import get_slot_combination

client = TelegramClient('session', api_id, api_hash)

@client.on(events.NewMessage(pattern='/spin'))
async def handler(event):
    msg = await client.send_file(event.chat_id, file=types.InputMediaDice(emoticon='🎰'))
    
    await asyncio.sleep(3)
    
    result = get_slot_combination(msg.media.value)
    await event.respond(f"Результат: {result}")

client.start()
client.run_until_disconnected()

---

📚 API Reference

get_slot_combination(value, symbols=None)

Преобразует значение dice в строку с символами.

Параметры:

• value (int): Число от 1 до 64 (значение dice.value от Telegram)
• symbols (dict, optional): Словарь замены символов. Ключи: 'bar', 'cherry', 'lemon', 'seven'

Возвращает:

• str: Строка из трех символов, разделенных пробелами

Исключения:

• ValueError: Если value не в диапазоне 1-64

Примеры:

get_slot_combination(1)  # "bar bar bar"
get_slot_combination(22, {'cherry': '🍒'})  # "🍒 🍒 🍒"

---

RAW_SLOT_COMBINATIONS

Словарь всех 64 комбинаций в виде списков.

Тип: dict[str, list[str]]

Структура:

{
    '1': ['bar', 'bar', 'bar'],
    '2': ['cherry', 'bar', 'bar'],
    ...
    '64': ['seven', 'seven', 'seven']
}

Использование:

from slotmap import RAW_SLOT_COMBINATIONS

combo = RAW_SLOT_COMBINATIONS['22']  # ['cherry', 'cherry', 'cherry']

---

DEFAULT_SYMBOLS

Стандартные символы, используемые по умолчанию.

Тип: dict[str, str]

Значение:

{
    'bar': 'bar',
    'cherry': '🍒',
    'lemon': '🍋',
    'seven': '7️⃣'
}

---

🎲 Справочник всех комбинаций

Всего в Telegram slot machine 4 типа символов:

Ключ	Описание	Стандартный вид
bar	Надпись BAR	bar
cherry	Вишня/Виноград	🍒
lemon	Лимон	🍋
seven	Семерка	7️⃣

Примеры значений:

dice.value	Комбинация
1	bar bar bar
22	cherry cherry cherry
43	lemon lemon lemon
64	seven seven seven
11	lemon lemon bar
32	seven seven cherry

Полный список всех 64 комбинаций доступен в RAW_SLOT_COMBINATIONS.

---

💡 Частые вопросы

Как получить dice.value?

# aiogram
message = await bot.send_dice(chat_id, emoji="🎰")
value = message.dice.value

# python-telegram-bot
message = await update.message.reply_dice(emoji="🎰")
value = message.dice.value

Можно ли использовать ID стикеров вместо эмодзи?

Да! Передайте ID стикеров в словаре:

STICKERS = {
    'bar': 'CAACAgIAAxkBAAEM...',
    'cherry': 'CAACAgIAAxkBAAEN...',
    'lemon': 'CAACAgIAAxkBAAEO...',
    'seven': 'CAACAgIAAxkBAAEP...'
}

result = get_slot_combination(22, symbols=STICKERS)
# Вернет строку с ID стикеров

Как проверить, что выпал джекпот?

combo = RAW_SLOT_COMBINATIONS[str(dice_value)]
is_jackpot = combo[0] == combo[1] == combo[2]

Почему ключи в RAW_SLOT_COMBINATIONS — строки?

Для удобства работы с JSON и совместимости. Используйте str(dice_value) при обращении к словарю.

---

🤝 Вклад в проект

Нашли баг или хотите добавить функцию? Создайте issue или pull request на GitHub!

---

📄 Лицензия

MIT License — используйте свободно в своих проектах.

---

🔗 Полезные ссылки

• Telegram Bot API — sendDice
• aiogram документация
• python-telegram-bot документация