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: the manifest cron entry fires it server-side and the SDK routes each firing to the matching @plugin.cron function (SDK 0.8.4+). It sends at most 10 alerts per run, with window-open alerts ahead of pre-window alerts. A durable marker per alert makes each alert type once-only. It is written before the send, and what happens when a send fails depends on why it failed:

• Unknown outcome (the platform did not answer within 30 seconds): the marker is kept and the alert is never re-sent, because Discord may already have posted it and a duplicate ping is worse than a missed one.
• Rejected (unknown channel, the bot cannot post there, an invalid request): logged once with a hint, and not retried for that alert. Fix the setting and later windows alert normally.
• Transient (rate limit, Discord or platform error): retried on a later sweep, at most three attempts per alert, then dropped with an error log.

A marker lives as long as the hunt's active record, so a respawn window longer than the retention period cannot fire its open alert a second time.

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. That role is also the only entry in the send's allowed_mentions, because YourBot suppresses every ping that is not explicitly allowed; every other alert is sent with all pings suppressed. 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. A send the platform rejected is not retried for that alert; once the channel is fixed, the next window alerts normally.
• 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-<version>.zip (the version comes from manifest.json), 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 requires YourBot SDK 0.9.0 or newer (yourbot-sdk>=0.9.0,<0.11) and its suite runs against both 0.9.0 and 0.10.0. As of September 10, 2026, the developer documentation advertises v0.9.0 and the newest release on the package index is v0.10.0. Two behaviours the plugin relies on exist only from 0.9.0:

• ctx.kv.list(..., start_after=...): the host returns at most 100 keys per call and silently clamps larger limits, so every collection read pages with start_after.
• ctx.discord.send_message(..., allowed_mentions=...): the host suppresses every ping unless it is explicitly allowed, so the window-open alert lists the configured role there. Without it the role mention rendered but never notified anyone.

Production cron delivery for pooled plugins (the manifest cron array routed to the matching @plugin.cron function) shipped in SDK 0.8.4; the floor above keeps the plugin off 0.8.3, where the sweep would silently never run.

The manifest declares interaction:respond explicitly. yourbot validate requires it, and the documentation calls an explicit declaration harmless because slash commands auto-add it.

One local CLI diagnostic remains stale through SDK 0.10.0: 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.