В этом разделе описано, как добавлять новые карты в приложение: формат данных, расположение файлов и шаги по внесению изменений.

Где хранятся данные

Тип данных Где хранится

База карт

app/src/main/assets/cards.json

Изображения карт

app/src/main/res/drawable/ (PNG или WebP)

Состояние колоды героя

SQLite через Room (создается автоматически при установке)
База карт и изображения — это исходные ресурсы приложения. Они включаются в APK при компиляции. Чтобы добавить новые карты, нужно пересобрать приложение.

Формат cards.json

Файл cards.json содержит массив объектов. Каждый объект — одна карта.

[
  {
    "id": 1,
    "name": "Blazing Strike",
    "type": "ABILITY",
    "cardSet": "Core",
    "imageRes": "card_blazing_strike"
  },
  {
    "id": 2,
    "name": "Iron Shield",
    "type": "EQUIPMENT",
    "cardSet": "Core",
    "imageRes": "card_iron_shield"
  }
]

Описание полей

Поле Тип Описание

id

Int

Уникальный числовой идентификатор карты. Не должен повторяться в рамках всего файла.

name

String

Название карты. Используется в поиске и отображается в интерфейсе.

type

String

Тип карты. Должен точно совпадать с одним из значений перечисления CardType (все буквы ЗАГЛАВНЫЕ). Определяет лимиты в колоде.

cardSet

String

Название набора, из которого карта. Используется для фильтрации. Пример: "Core", "Act 1".

imageRes

String

Имя ресурса изображения без расширения. Должно совпадать с именем файла в res/drawable/ (без .png/.webp).

Допустимые значения поля type

Значения поля type берутся из перечисления CardType.kt в исходном коде. Актуальный список всегда в CardType.kt на GitHub.

Текущие известные типы: HERO_SHEET, WEAPON, ARMOR, TRINKET, RELIC, ITEM_UPGRADE, BACKPACK, DISCIPLINE.

Изображения карт

Требования к изображениям

  • Формат: PNG или WebP

  • Расположение: app/src/main/res/drawable/

  • Именование: только строчные буквы, цифры и символ подчеркивания _. Без пробелов и дефисов. Без расширения в поле imageRes в JSON.

Пример

Если карта называется "Blazing Strike", то:

  1. Файл изображения: app/src/main/res/drawable/card_blazing_strike.png

  2. В JSON: "imageRes": "card_blazing_strike"

Рекомендуемое разрешение

Рекомендуемое соотношение сторон карт из Middara — вертикальное (портретное). Оптимальное разрешение: 400×560px. При превышении этого размера Coil автоматически масштабирует изображение под размер компонента.

Как добавить новую карту

  1. Подготовьте изображение в нужном разрешении и формате

  2. Добавьте файл изображения в app/src/main/res/drawable/

  3. Откройте app/src/main/assets/cards.json

  4. Добавьте объект карты в конец массива (перед закрывающей ]):

      ,
  {
    "id": 42,
    "name": "Название карты",
    "type": "ABILITY",
    "cardSet": "Core",
    "imageRes": "card_название_карты"
  }

  5. Проверьте уникальность поля id — он не должен совпадать с существующими картами

  6. Соберите и установите приложение через Android Studio или командой:

    ./gradlew installDebug

Валидация JSON

Перед сборкой убедитесь, что JSON-файл валиден. Используйте любой онлайн-валидатор, например jsonlint.com, или встроенную проверку Android Studio (файл подсвечивается красным при синтаксических ошибках).

Опечатка в поле type (например, "Ability" вместо "ABILITY") приведет к тому, что карта не будет распознана корректно — тип упадет в значение по умолчанию или вызовет ошибку при парсинге.