Radicade/docs/WEEKLY-CHALLENGES.md

# Weekly challenges and RadAdmin



The player routes are GET `api/challenge/v2/getCurrent` and POST

`api/challenge/v2/updateProgress`, also under `econ/`. Both require player auth.

The server stores progress in `WeeklyChallenges`, keyed by player and map ID.

The new `20261008120000_AddWeeklyChallenges` migration is applied by the existing

server startup migration step. This work has not been deployed or game-tested.



## Add-A-Challenge



RadAdmin's Challenges page saves library entries through the existing

`/admin/panel/challenges` CRUD API. A gameplay preset generates the client config;

names, descriptions and tooltips are editable. The initial supported presets are

single-event goals: finish an activity, tag a player, defeat an AI enemy, capture

a flag, and block with a shield. Count/streak and arbitrary legacy configs are

not yet supported by the weekly validator.



## Publishing a weekly



Open **Challenges**, choose the current week or one of the next three weeks, and:



1. Enter the display title and duplicate-item token amount (1–10,000).

2. Search Equipment skins or Avatar items and select the exact catalog item.

3. Select three to five library challenges. Create any missing goals with New challenge.

4. Leave Published checked and click Publish weekly. Uncheck it and save to disable the week.



An unscheduled week has no challenges or reward. There is no built-in lineup or reward

rotation. Existing saved schedules remain supported. Publish the current week after

upgrading if it previously used the old automatic rotation.



GET `/admin/panel/weekly-challenges` returns four `weeks`, with map IDs, dates,

content and `Revision`. GET `/admin/panel/weekly-challenges/rewards` returns searchable

catalog choices with `key`, `kind`, `name`, and `detail`. POST the schedule:



```json

{

  "ChallengeMapId": 100000,

  "Revision": "revision from GET, or empty for a new schedule",

  "Title": "Weekly Challenges",

  "Enabled": true,

  "ChallengeIds": [1, 2, 3],

  "RewardKey": "exact key returned by the reward catalog endpoint",

  "FallbackTokens": 300

}

```



All admin routes use existing admin-key validation and RadAdmin's same-origin proxy.

The server resolves the reward against its loaded catalog; arbitrary gift payloads

are not accepted. A stale revision returns HTTP 409; reload before publishing again.

Schedules are stored as JSON in SQL `ServerConfig` under `WeeklyChallengeMap:{id}`.

No additional database migration is needed for schedule fields.



## Schedule, progress and rewards



- Reset remains Wednesday 00:00 UTC. The admin page displays local time.

- Completing any three goals awards the selected skin or avatar item once.

  Three is the installed client's completion threshold, not configurable content.

- Owned or pending rewards use the configured token fallback.

- Library edits do not change a published snapshot until it is published again.

- Current-week edits preserve progress when the challenge ID and gameplay definition

  match. Changed goals reset. Already-earned rewards remain earned and cannot be

  awarded twice. Players may need to reopen their challenge screen after an edit.

- Disabled weeks expose no player challenges and reject progress updates.

- SQL schedule and player-state locks serialize saves/completion. Gift creation and

  progress commit together; consumed boxes are not recreated.

- `WeeklyCompleteButHaveSkin` does not create a second award.



Progress comes from the authenticated client's event system. The server validates

map/goal identity, immutable predicates and completion consistency; it does not

independently prove gameplay events. SQL concurrency still needs integration testing

against SQL Server; automated state tests use EF InMemory.



## Client evidence



Inspected installed Windows build 20230831, RecNet.Runtime and

RecRoom.Challenges.Runtime. Local `artifacts/weekly-*.txt` native dumps establish:



- FEPKIMEALDP serializer: ChallengeMapId, ChallengeThemeString, Challenges, Gift,

  FallbackGiftName, StartAt, EndAt, ServerTime, CompletedRequired.

- BGJILCJGENL serializer: ChallengeId, Name, Config (JSON **string**), Description,

  Tooltip, Complete.

- BEODGPKOFEI::ALKHLDNCPHD posts ChallengeMapId, ChallengeId, Config, Complete.

- WeeklyChallengeManager::get_CompletedRequired counts three completions.

- Challenge types: ct=0 composite with rc required predicates; ct=6 event filter,

  vs accepted values. Event IDs 2/4/5/8/10 correspond to the starter goals.



## Verification



37 weekly/admin scheduling and existing gift-flow/persistence tests passed.

Admin JavaScript self-test checks generated presets, selection bounds, scheduling

payload, success/error handling and matching HTML element IDs.



Game check after deploying both projects: publish the current week, reopen the weekly

board, complete a goal, and relog to verify progress. Complete three and open the

chosen reward. Verify a second player who owns the item receives the configured

tokens. Check both avatar and skin rewards. Live client behavior has not been tested.