ScenePreview

RU: ScenePreview (клиентский мод) 🖼️🎬

ScenePreview — клиентский Fabric-мод для Minecraft 1.20.1, предназначенный для создания «чистых» превью и красивых скриншотов: быстрые настройки кадра, скрытие лишнего, управление разрешением скриншотов и локализация.

🎯 Цели и сценарии

• 📸 Делать скриншоты/превью без HUD и лишних объектов в кадре
• 🌐 Снимать NPC/сцены на серверах без установки мода на сервер
• 🧼 Быстро переключать «режимы съёмки»: скрыть игроков/мобов/дроп/небо, поставить однотонный/хрома фон
• 🧩 Получать PNG с прозрачностью (для монтажа/превью)
• 🖥️ Делать скриншоты в пользовательском разрешении (выше/ниже текущего экрана)

✨ Основной функционал

🎛️ Меню превью (ScenePreview Menu)

• ⌨️ Открывается по клавише J (настраиваемо)
• 🧭 Отдельный экран настроек с категориями/переключателями и понятным состоянием
• 🧷 Быстрые кнопки на экране (вверху справа):
  • Menu — открыть меню
  • Screenshot — сделать скриншот
  • ⚡ Настройки применяются сразу; сохранение — по выбору пользователя (через конфиг)

📸 Скриншот одной кнопкой

• ⌨️ Клавиша по умолчанию: H (настраиваемо)
• ✅ Делает скриншот с учётом текущих настроек «очистки кадра» и «разрешения/масштаба»
• 💬 Опционально: уведомление в чате о сохранении + путь к файлу

🧼 Очистка кадра (Frame Cleanup)

Переключатели:

• 🧿 Hide HUD (скрыть интерфейс/прицел/хотбар) — опционально
• 🧱 Hide Blocks (скрыть блоки мира)
• ☁️ Hide Sky (скрыть небо)
• 🎨 Background Color (HEX) — однотонный/хрома фон
  • ввод: #RRGGBB или RRGGBB
  • валидация и сохранение последнего значения
  • 🪙 Hide Dropped Items (скрыть предметы на земле)
  • 👥 Hide Entities (скрыть все сущности)
    • под-фильтры (можно как вложенные или отдельные правила):
      • 🧍 Hide Players
      • 🐾 Hide Mobs
      • 🗿 Hide Armor Stands
      • 🏹 Hide Vehicles/Projectiles (опционально)

👤 Выборочное скрытие (Selective Hiding)

• Можно скрывать конкретную сущность, оставив остальные видимыми:
  • 🧍 игрок / «игрокоподобный NPC» (в т.ч. NewNPC и похожие)
  • 🗿 стойка для брони (ArmorStand)
  • Варианты UX (достаточно одного, можно оба):
    1. 🎯 По наведению (цель под прицелом): Hide target / Unhide target
    2. 📋 Список ближайших сущностей в меню (радиус N блоков) + поиск
  • 🧠 Хранение исключений (UUID):
    • Always Hidden — скрывать всегда (в рамках ScenePreview)
    • Always Visible — показывать даже при глобальном скрытии (если включено)
  • 🔀 Приоритеты:
    • глобально скрываем сущности, но Always Visible — показываем
    • Always Hidden — скрываем независимо от общих переключателей

🖼️ Прозрачный PNG (Transparent Output)

• Режим Transparent PNG: автоматический или отдельным переключателем
• Требование: при включённых Hide Blocks + Hide Sky фон становится прозрачным (alpha)
• Формат: PNG с альфа-каналом
• Если включён Background Color (HEX):
  • либо он перекрывает прозрачность
  • либо показывается предупреждение в UI (на выбор реализации)

🧾 Разрешение скриншота (Screenshot Resolution)

Секция Resolution:

• Mode:
  • 🖥️ Screen (как на экране)
  • 📐 Custom (ширина/высота)
  • 🔍 Scale (0.5x / 1x / 2x / 3x / 4x)
  • 🧷 Presets (720p, 1080p, 1440p, 4K, 5K и т.д.)
  • Custom fields:
    • Width (px), Height (px)
    • 🔒 Lock Aspect Ratio (опционально)
  • 🛡️ Ограничения:
    • минимум (пример): 320×180
    • максимум: разумный предел (например 16384 по стороне) или предупреждение о памяти
  • 🧩 Реализация:
    • рендер в offscreen framebuffer нужного размера + сохранение в PNG
    • при необходимости — отключение некоторых эффектов во избежание артефактов

🗂️ Вывод и нейминг (рекомендуется)

• Папка: screenshots/ + подпапка scenepreview/ (настраиваемо)
• Нейминг:
  • scene_YYYY-MM-DD_HH-mm-ss.png
  • опционально: добавлять мир/сервер/разрешение
  • 🧭 Опционально: кнопка/ссылка Open folder в уведомлении

🌍 Локализация (Languages)

• Мод автоматически использует язык Minecraft
• 📚 Поддержка 15 языков (минимум RU/EN + остальные)
• Все строки UI/подсказки/уведомления — через lang-файлы
• Fallback: EN

⌨️ Управление (Controls)

• J — открыть/закрыть меню ScenePreview
• H — сделать скриншот
• Опционально:
  • K — быстрый toggle «Clean mode» (набор скрытий)
  • HUD-кнопки: Menu / Screenshot

🧩 Совместимость

• ✅ Мод клиентский: ставится только на клиент
• ✅ Работает на ванильных и модифицированных серверах без установки на сервер
• 🤝 Дружит с NPC-модами: «player-like NPC» должны корректно скрываться/показываться (Selective Hiding)
• 🏷️ Про голограммы (ArmorStand-текст на сервере):
  • Если сервер использует голограммы на ArmorStand (например “Chat Holograms”), они могут скрываться при Hide Armor Stands / Hide Entities
  • Рекомендуемая опция:
    • Hide holograms — скрывать только сущности с тегом chat_holograms (или заданным), не влияя на обычные ArmorStand

⚙️ Конфиг и сохранение

• Файл: config/scenepreview.json (или стандартная система конфигов Fabric)
• Сохранять:
  • состояния переключателей
  • HEX фон
  • режим разрешения + значения custom/preset/scale
  • списки UUID для Selective Hiding (по выбору)
  • 🧹 Кнопка «Reset to defaults» в меню

✅ Нефункциональные требования

• 🚀 Производительность: без заметной просадки FPS при закрытом меню
• 🔒 Приватность: без телеметрии/сетевых запросов
• 🧱 Стабильность: корректно при смене мира/сервера/измерений
• 💡 UX: подсказки (tooltips), подтверждения, валидация HEX/разрешения

EN: ScenePreview (client-side mod) 🖼️🎬

ScenePreview is a client-side Fabric mod for Minecraft 1.20.1 made for clean previews and cinematic screenshots: fast frame cleanup toggles, entity/player hiding, screenshot resolution control, and built-in localization.

🎯 Goals & use cases

• 📸 Take screenshots without HUD clutter and unwanted objects
• 🌐 Work on servers without requiring server installation
• 🧼 Quickly switch “shooting modes”: hide players/mobs/items/sky, set solid/chroma background
• 🧩 Export transparent PNGs for compositing/editing
• 🖥️ Capture screenshots at custom resolutions (higher/lower than the current screen)

✨ Core features

🎛️ Preview Menu

• ⌨️ Default hotkey: J (rebindable)
• 🧭 Dedicated settings screen with categories/toggles and clear state
• 🧷 On-screen quick buttons (top-right):
  • Menu — open menu
  • Screenshot — take screenshot
  • ⚡ Settings apply instantly; persistence is optional via config

📸 One-key screenshot

• ⌨️ Default hotkey: H (rebindable)
• ✅ Captures using current cleanup + resolution settings
• 💬 Optional chat notification with saved file path

🧼 Frame Cleanup

Toggles:

• 🧿 Hide HUD (optional)
• 🧱 Hide Blocks
• ☁️ Hide Sky
• 🎨 Background Color (HEX) (solid/chroma)
  • accept #RRGGBB / RRGGBB with validation
  • 🪙 Hide Dropped Items
  • 👥 Hide Entities
    • sub-filters (either nested or standalone rules):
      • 🧍 Hide Players
      • 🐾 Hide Mobs
      • 🗿 Hide Armor Stands
      • 🏹 Hide Vehicles/Projectiles (optional)

👤 Selective Hiding

• Hide a specific entity while keeping others visible:
  • 🧍 player / player-like NPC (e.g., NewNPC-style)
  • 🗿 armor stand
  • UX options (either is fine, both optional):
    1. 🎯 Crosshair target: Hide target / Unhide target
    2. 📋 Nearby entity list (radius N) + search
  • UUID lists:
    • Always Hidden
    • Always Visible (optional)
  • 🔀 Priority:
    • global hide on, but Always Visible → render it
    • Always Hidden → hide regardless (within ScenePreview)

🖼️ Transparent PNG

• Transparent PNG mode: automatic or toggleable
• Requirement: with Hide Blocks + Hide Sky, background becomes transparent (alpha)
• Output: PNG with alpha channel
• If Background Color (HEX) is enabled:
  • it overrides transparency, or UI shows a warning (implementation choice)

🧾 Screenshot Resolution Control

Resolution section:

• Mode:
  • 🖥️ Screen
  • 📐 Custom (width/height)
  • 🔍 Scale (0.5x / 1x / 2x / 3x / 4x)
  • 🧷 Presets (720p, 1080p, 1440p, 4K, 5K, etc.)
  • Custom fields:
    • Width (px), Height (px)
    • 🔒 Lock Aspect Ratio (optional)
  • 🛡️ Limits:
    • minimum (example): 320×180
    • reasonable max (e.g. 16384 per side) or memory warning
  • 🧩 Implementation:
    • offscreen framebuffer render at target size + PNG export
    • optionally disable certain effects to avoid artifacts

🗂️ Output & naming (recommended)

• Output folder: screenshots/ + scenepreview/ subfolder (configurable)
• Naming:
  • scene_YYYY-MM-DD_HH-mm-ss.png
  • optional: include world/server name and resolution
  • 🧭 Optional Open folder action in notification

🌍 Localization

• Automatically follows Minecraft language
• 📚 15 languages (at minimum RU/EN plus others)
• Full UI/tooltips/notifications localized via lang files
• Fallback: EN

⌨️ Controls

• J — open/close ScenePreview menu
• H — take screenshot
• Optional:
  • K — quick “Clean mode” preset toggle
  • HUD buttons: Menu / Screenshot

🧩 Compatibility

• ✅ Client-side only
• ✅ Works on vanilla and modded servers without server installation
• 🤝 NPC mod friendly: player-like NPCs supported by Selective Hiding
• 🏷️ Server holograms (ArmorStand text):
  • ArmorStand-based holograms (e.g., “Chat Holograms”) may be affected by Hide Armor Stands / Hide Entities
  • Recommended extra toggle:
    • Hide holograms — hide only entities with tag chat_holograms (or configured tag), without hiding normal armor stands

⚙️ Config

• File: config/scenepreview.json (or standard Fabric config system)
• Persist:
  • toggles
  • HEX color
  • resolution mode + custom/preset/scale values
  • Selective Hiding UUID lists (optional)
  • 🧹 Reset-to-default button

✅ Non-functional requirements

• 🚀 Performance: no noticeable FPS hit while menu is closed
• 🔒 Privacy: no telemetry/network calls
• 🧱 Stability: safe across world/server/dimension changes
• 💡 UX: tooltips, confirmations, HEX/resolution validation