MVPulse 0.1

MVPulse is an unofficial, crowdsourced Discord MVP spawn-window tracker and guild hunt board for Ragnarok: The New World. Members report an MVP as alive or down; MVPulse keeps the latest observation for each configured boss and line/instance, calculates the server's configured respawn window, and lets hunters join or scout it.

MVPulse does not scrape the game, automate the client, use OCR, call an external API, read Discord message content, or link game accounts. The package contains no real boss catalog or unverified SEA timers.

Five-step setup

1. Install MVPulse from YourBot.gg and approve storage:kv, discord:send_message, and interaction:respond. The manifest declares interaction:respond explicitly; YourBot would otherwise auto-add it from the slash commands.
2. As a server manager, open Dashboard → Boss Catalog. Add each boss using a lowercase slug, display name, optional aliases/map, and your community's verified minimum/maximum respawn minutes. Leave both timer values blank when unknown.
3. Open Dashboard → Setup. Choose the board size and retention. To use alerts, enter the numeric Discord channel ID, set the pre-alert lead time, then enable alerts.
4. Have a member create the first observation with /mvp-report boss:<name> status:<alive|down>. Boss input accepts the display name, slug, or an alias.
5. Run /mvpulse, select a hunt for details, and use Join, Scout, or Leave. Use /mvp-next for the next several hours and /mvp-my for personal hunts.

Commands

• /mvpulse [boss] [instance] shows the current public hunt board, capped by the configured board size. Its menu opens a hunt detail view.
• /mvp-report boss status [instance] [minutes-ago] [map] creates a public community observation. status is alive or down; instance defaults to world; minutes-ago accepts 0–240 and is valid only for down. Non-Latin instance labels are now tracked as distinct hunts, so labels such as Канал 1 and Комната 1 no longer collapse into one slot.
• /mvp-next [hours] shows open and upcoming windows in the next 1–24 hours (default 6), sorted by start time.
• /mvp-my privately shows hunts the caller joined or is scouting.

YourBot does not forward autocomplete interactions. Boss input is free text, and MVPulse suggests close configured matches when it cannot resolve one.

Timing and accuracy

For a down observation, MVPulse calculates:

killed_at   = reported_at - minutes_ago
window_start = killed_at + configured minimum respawn time
window_end   = killed_at + configured maximum respawn time

Discord renders the stored UTC epoch timestamps in each viewer's local timezone. MVPulse performs no timezone conversion.

Community reports and configured timers can be incomplete, delayed, or wrong. A shown window is an estimate, not a guarantee. Confirm in game. A down report is still accepted when no timer is configured and is labeled Timer not configured.

Respawn timers accept 1 to 2880 minutes (up to 48 hours). A window is allowed to run longer than the configured retention because an active down hunt's storage now survives until after its window closes, even when the window opens later than plain retention would otherwise keep it — so a long respawn window never expires before it opens.

Dashboard

Overview (viewer)

• Active-hunts, open-windows, and reports-today stat cards.
• A paginated current-hunts table.
• Usage help and the accuracy disclaimer.

Setup (manager)

• Enable alerts: master switch; off by default.
• Alert channel ID: 15–22 digit Discord channel ID. A missing channel safely suppresses the sweep.
• Pre-alert minutes: 0–180 before the window begins. Values below about 6 are unreliable against the five-minute sweep and may be missed; 0 disables the pre-alert entirely. Neither affects the window-open alert.
• Optional role ID: blank or a 15–22 digit Discord role ID.
• Ping role when window opens: off by default and applies only to the configured role and open alert.
• Board size: 1–25 observations.
• Hunt retention: 24–168 hours.

Boss Catalog (manager)

• A paginated boss table.
• An upsert form for slug, display name, aliases, default map, timer range, enabled state, and notes.
• Up to 100 bosses and 10 aliases per boss.
• Editing is a merge: saving an existing slug overwrites only the fields you fill in, and blank text or number fields keep their stored values. Type or delete a value only when you mean to change it.
• The Enabled toggle is the exception — it is always applied on save. Because the form always loads blank (the table cannot prefill it, so you must know the slug you intend to edit), editing a currently-disabled boss re-enables it unless you also set Enabled off.
• There is no destructive delete. Disable an obsolete boss to retire or clear it.

Every save is validated in Python. Invalid input returns a dashboard error and is not written.

Alerts

The production sweep runs every five minutes through both the code decorator and the manifest cron declaration. It sends at most 10 alerts per run, with window-open alerts ahead of pre-window alerts. Durable KV keys make each alert type once-only; the sent marker is written before the send and rolled back on failure, so a failed Discord send is logged and becomes retryable rather than lost or duplicated.

The window-open alert now fires even for fixed-timer bosses (minimum equals maximum) and for windows shorter than the five-minute sweep, using a short grace past the window close so brief windows are not skipped. It remains once-only. A window that is overdue well beyond that grace still does not alert.

Only a validated, manager-configured role ID can form a role mention, and only on window-open alerts when explicitly enabled. Untrusted text — boss names, maps, instances, aliases, and notes — is neutralized before it appears in a bot message. In Discord message bodies (the board, hunt details, and alerts) markdown and link metacharacters are backslash-escaped so injected text cannot render bold/italic or a clickable masked link, and bare :// URLs are broken so they do not autolink. In plain-text surfaces that do not interpret markdown (dashboard tables and the hunt select menu) @ is suppressed to defuse mentions. Interaction replies also disable automatic mentions with allowed_mentions={"parse": []}.

Privacy and storage

MVPulse stores only:

• Server settings and manager-created boss records.
• Immutable community reports plus the latest active observation.
• The reporting member's Discord ID for attribution.
• Discord IDs needed for join/scout membership and reverse lookup.
• Once-only alert markers.

Active observations and memberships use the configured 24–168 hour retention, extended when needed so the key survives until after the respawn window closes; memberships are aligned to the hunt's own expiry so /mvp-my never surfaces a hunt whose record is already gone. Immutable reports use that TTL plus 24 hours. MVPulse never stores credentials, IP addresses, Discord message content, or game account IDs. Storage is isolated per Discord server by YourBot's KV service.

Capabilities

• storage:kv stores server settings, boss records, observations, memberships, and alert markers.
• discord:send_message posts configured pre-window and window-open alerts.
• interaction:respond powers command and component replies. It is declared explicitly in the manifest, though YourBot also auto-adds it from the declared slash commands. Components update their source message with respond(update_message=True), so discord:edit_message is neither declared nor used.

No read-message, message-content, SQL, HTTP proxy, secrets, or filesystem-write capability is requested.

Troubleshooting

• Unknown boss: check the suggested name or ask a manager to add/enable it in Boss Catalog.
• Timer not configured: set both minimum and maximum respawn minutes, or intentionally leave both blank.
• No alert: confirm alerts are enabled, the channel ID is 15–22 digits, the window is not overdue, and the bot can post in that channel.
• No role ping: confirm both the role ID and Ping role when window opens are set. Pre-alerts never ping.
• Stale button/menu: run /mvpulse again. Old or superseded controls are rejected safely.
• Empty board: create a configured boss, then submit /mvp-report.

Development

Python 3.10+ is required. Runtime dependencies are limited to the YourBot SDK and the Python standard library.

python -m pip install -r requirements.txt -r requirements-dev.txt
python -m pytest
python -m compileall .
yourbot doctor
yourbot validate
python scripts/build_zip.py

If the host exposes only python3, substitute python3 for python.

The builder writes dist/mvpulse-0.1.0.zip, puts manifest.json and __main__.py at the zip root, excludes tests/caches/local environment files, and enforces the marketplace's 25 MB compressed, 100 MB uncompressed, fewer-than-500-file, and 10 MB-per-file limits.

SDK compatibility

MVPulse targets the documented YourBot SDK v0.8.4 behavior. As of July 20, 2026, the official developer documentation advertises v0.8.4 and specifies production pool-mode delivery for functions present in the manifest cron array. The public Python package index currently offers v0.8.3 as its newest release, so the suite is executed against v0.8.3's compatible runtime surface.

The manifest therefore declares interaction:respond explicitly. The shipped v0.8.3 yourbot validate hard-errors without it, and the v0.8.4 documentation calls an explicit declaration harmless but redundant because slash commands auto-add it. Declaring it satisfies the real validator with no downside under either contract.

One local CLI diagnostic remains stale: v0.8.3 yourbot doctor scans only root-level Python files for capability use and therefore warns that discord:send_message appears unused; the call lives in mvpulse/cron_tasks.py and is covered by strict-capability tests. Re-run it when the v0.8.4 package is published.