The launcher fetches project messages from announcements.json on main at startup and when the user enables the setting. See Architecture § Launcher communication for how the launcher fetches, filters, and queues them.
Use announcements for short, time-sensitive messages. They do not replace the changelog or troubleshooting guides. Keep the body useful without the action link.
The launcher selects the first eligible entry. just announcement set inserts or replaces an entry at the top, so the message that must win goes first. An entry counts as seen when the user dismisses its popup. A text change does not show it again. Use a new id for a follow-up. The preference store keeps the latest 100 seen IDs.
Previewing a popup#
- Run the isolated debug simulator with
just preview. - Open Settings → Developer.
- Under HUD and popups, set Popup to Custom Markdown and type the message.
- Press Show Popup to see it in the real popup modal.
Publishing#
Prepare a feed entry with:
just announcement set \
feedback-2026-08 \
"Help improve Arknights Client" \
/tmp/feedback.md \
"Open GitHub Issues" \
https://github.com/LuMiSxh/Arknights-MacOS-Client/issues
The recipe takes snake-case arguments and writes camel-case JSON. action_title and action_url can be "". Four more optional arguments set a version range and display window: min_version, max_version, starts_at, and ends_at. The command validates the entry and writes all fields, with null for unused optional values.
Review announcements.json, run just check, commit it to main, and push. Publishing needs repository write access. GitHub can briefly cache the response, so changes may not reach every client immediately. To hide an entry from installations that have not fetched it yet, run just announcement remove ID.
Feed schema and eligibility#
The feed root needs schemaVersion: 1 and an announcements array of at most 20 entries. The launcher rejects a feed larger than 128 KiB. manage_announcements.py enforces the field rules below, and the launcher repeats the safety checks before it displays an entry.
| Field | Purpose |
|---|---|
id |
Stable lowercase identifier ([a-z0-9][a-z0-9._-]{0,79}) used for once-only display |
enabled |
Allows an entry to remain in the file without being presented |
title |
Popup title, at most 120 characters |
body |
Markdown body, at most 4,000 characters |
actionTitle / actionURL |
Optional button and HTTPS destination; set both or neither |
minimumVersion / maximumVersion |
Optional inclusive X.Y.Z launcher-version range |
startsAt / endsAt |
Optional ISO-8601 UTC window ending in Z; the end is exclusive |
An entry is eligible only when it is enabled, unseen, inside its date window, and compatible with the running version. The launcher shows at most one new entry per check and logs a failed fetch without blocking installation or launch.
Popup Markdown#
The popup uses the launcher's native Markdown parser, not the website renderer. It supports headings, paragraphs, bullet items, tables, fenced code, dividers, inline emphasis, and the five GitHub alert markers, and ignores frontmatter. Advanced Markdown can appear as plain text. Verify content in the real popup.