Аркадный зал Школы Империи

Погодные клиенты: контракт 1.7

Нормативное дополнение к обзору API. База всех относительных URL в погодных JSON: https://games.oopssre.ru/assets/arcade/views/. Даже путь внутри вложенного прогноза разрешается от этой базы. Версия документа 1.7, версии схем JSON и непрозрачные версии содержимого — разные величины.

Документы и обязательные различия

ДокументНазначение
manifest-v3.jsonКаталог коллекций, форматов и загрузок; schema: 3
weather/C/current.jsonСнимок последнего обновления коллекции C; schema: 1, type: weather
weather/C/forecast-D.jsonГотовое расписание устройства D; schema: 1, document_type: weather-forecast
weather/C/assets.jsonКаталог подготовленных изображений; schema: 1
ZIP из downloadsРисунки коллекции и устройства; не актуальный прогноз

current.json не является часами: после границы его интервала следующий кадр выбирается по прогнозу. Верхний ready означает наличие хотя бы одного готового формата, поэтому выбранный формат проверяется отдельно.

Текущее состояние

ПоляЗначение
collection_id, titleИдентичность и название оформления
source_id, world_id, sourceИсточник real или game-world, мир либо null, описание источника либо null
location, location_revision, timezoneНазвание, широта, долгота и часовой пояс; непрозрачная ревизия; IANA timezone
formats, package_versionsОбъявленные форматы и версии их пакетов
status, reasonОбщая готовность и причина либо null
filesГотовые файлы по идентификаторам устройств
format_statusНеобязательные статус и причина каждого формата
season, time_of_day, weather, weather_codeСостояние, если определено; погодная группа и код могут быть null
state_id, state_title, moon_phase, world_dateНеобязательные идентификатор, подпись, лунная фаза и дата мира
valid_from, valid_until, forecast_valid_untilНеобязательные границы готовности
weather_fetched_at, refresh_afterМомент получения погоды либо null; рекомендация обновления
refresh_errorПоследняя ошибка {at, message} либо null
preview, preview_formatНеобязательное превью и его формат
last_successful_imageПоследний успешный кадр либо null
delivery.direct_image.enabledДоступность постоянных адресов изображения

generated_at, document_type и contract_version не являются обязательными полями current.json. Температура, ветер и весь набор числовых измерений не входят в обещание этого API: для динамической композиции используются отдельные входы.

Файл содержит url, format: jpeg, rendition, width, height, aspect, bytes, sha256, cache_key. cache_key — ключ задачи подготовки, а sha256 — контрольная сумма байтов. Запись current.files[D] может дополнительно содержать state_id, state_title, постоянный image_url и превью. Необязательное превью содержит URL, формат, размеры, размер файла и SHA-256. Обычный thumbnail имеет длинную сторону до 640 px; плеерное превью готовится отдельно.

Прогноз и интервалы

Готовый прогноз содержит collection_id, format, source_id, world_id, contract_version, необязательную package_version, location, location_revision, timezone, generated_at, valid_until, refresh_after, weather_fetched_at, source, season_months, astronomy, intervals. Версии сравниваются на равенство; из них нельзя извлекать календарь или номер релиза клиента. Верхний status у готового документа может отсутствовать. Недоступный прогноз допускает сокращённую форму: status: unavailable, generated_at: null, valid_until: null, intervals: [].

Горизонт — 24 часа от generated_at, а не до местной полуночи. Выбор: valid_from <= now < valid_until, с точными абсолютными датами и смещениями. Соседние равные состояния могут объединяться; число интервалов не обязано быть 24. refresh_after — срок повторного запроса, не срок пригодности кадра.

Интервал содержит границы, world_date, season, time_of_day, weather, weather_code, state_id, moon_phase, status, image_url и file для готового изображения. image_url готового интервала совпадает с file.url, а не с постоянным адресом current. Возможны preview и player_preview. Неготовый интервал содержит причину, image_url: null и не имеет готового file.

astronomy содержит движок, days, солнечное погружение и лунную политику. День задаёт dawn, sunrise, sunset, dusk, moon_phase; в полярных условиях события могут быть null. Клиент использует готовые интервалы и не обязан пересчитывать Astral. Значение local в старом календаре обычных коллекций не заменяет часовой пояс погодного источника.

Коды состояния

Сезоны: spring, summer, autumn, winter. Части суток: dawn, day, dusk, night. Луна: none, new_moon, waxing_crescent, first_quarter, waxing_gibbous, full_moon, waning_gibbous, last_quarter, waning_crescent. none означает отсутствие лунного варианта, а не новолуние.

Погодная группаИсходные коды
clear0
partly-cloudy1, 2
overcast3
fog45, 48
drizzle51, 53, 55
rain61, 63, 80, 81
heavy-rain65, 82
freezing-precipitation56, 57, 66, 67
snow71, 73, 77, 85
heavy-snow75, 86
thunderstorm95
severe-thunderstorm97
thunderstorm-hail96, 99

97 — поддержанное проектом отображение, а не обещание его выдачи Open-Meteo. Эта таблица из 13 групп относится к готовым погодным коллекциям; динамический контракт использует собственные 6 групп. state_id имеет вид <season>-<time_of_day>-<weather>; группа сама может содержать дефисы, поэтому разбиение ровно на три части неверно.

Готовность и ошибки

Статусы: ready, not_ready, unresolved_weather, unavailable, stale. Неизвестный статус не считается готовностью. Причины: weather_unavailable, forecast_expired, unknown_weather_code, state_not_in_collection, prototype_only, artwork_planned, prepared_variant_missing, prepared_file_missing, prepared_file_damaged. Новая неизвестная причина должна отображаться без аварии.

HTTP 200 не гарантирует готовое изображение. Ошибка HTTP, сети или разбора JSON — отдельная ошибка доставки. При недоступности допустимо сохранить предыдущую установленную картинку с честной подписью. Нельзя выдавать её за актуальную, незаметно менять источник или мир. В last_successful_image подпись выбранного устройства берётся из его файла; applied_at — серверная отметка, а не время установки клиентом.

ZIP, совместимость и кеш

Архив выбирается из каталога: нужные collection, format: zip, rendition: D. Запись содержит идентификатор, название, URL, байты, SHA-256 и версию. Читайте URL, а не конструируйте его из названия. ZIP общий для двух источников погоды, но принадлежит одному устройству.

В архиве: manifest.json со schema: 3, document_type: weather-wallpaper-package, type: weather, id, title, version, format, ready_states, total_states, variants; weather-package.json со schema: 1, типом и форматом; README и JPG. Вариант задаёт state_id, название, moon_phase и свойства файла; URL внутри ZIP разрешается относительно ZIP. Совпадают и состояние, и лунный вариант. Версия архива сравнивается с forecast.package_version своего устройства; версия контракта коллекции может измениться из-за другого формата.

assets.json содержит идентичность, версию, форматы, готовность и states. Состояние имеет id, title, status, moon_mode, variants[phase][device], возможные превью. Наличие состояния означает готовность хотя бы одного устройства, а не всех. ZIP содержит рисунки, а не бессрочный прогноз.

Клиент читает совместимую пару current/forecast, проверяет источник, мир, ревизию места, устройство и объявленные версии. При обновлении между запросами перечитывает пару. JSON публикуются атомарно по отдельности, но два HTTP-запроса не образуют транзакцию. Готовый файл скачивается временно, проверяются размер, SHA-256 и размеры JPEG; затем он заменяет локальную копию. Неизвестные необязательные поля можно игнорировать; несовместимую схему нельзя угадывать.

Совместимые расширения

Дополнительный astronomy.events содержит астрономический снимок. В current.json он может появляться независимо от готовности погоды. Неизвестные необязательные поля игнорируются; срок астрономии не продлевает прогноз погоды. Старые солнечные события и художественные фазы сохраняются. Подробнее: астрономия и совместимость.

Порядок чтения: Оглавление · Назад: Спецификация погодного API · Далее: Спецификация динамической темы

Необязательные PNG-мастер, независимая активность, календарь темы и облака/атмосфера: расширения 1.0.90.