WP Admin RPG

WordPress plugin that replaces the default dashboard with an RPG-style admin overworld (map, avatar, districts) and an optional Posts Tavern view on the posts list screen.

Project layout

Path	Role
wp-admin-rpg.php	Bootstrap, menus, enqueues, overworld + posts tavern markup
assets/admin-rpg.css	Overworld UI, zones, avatar
assets/admin-rpg.js	Avatar movement, zones, arrival transitions
assets/posts-map.css	Posts tavern layout + fullscreen chrome hiding
scripts/zip-plugin.mjs	Builds wp-admin-rpg.zip for distribution

Dolly chat wiring (this plugin)

• UI: Floating “Dolly” button on the overworld and Posts tavern maps opens a chat panel; messages go to POST /wp-json/wp-admin-rpg/v1/dolly-chat (cookie + X-WP-Nonce). Permission defaults to read (same as the RPG admin menu); tighten with wp_admin_rpg_dolly_chat_capability. Jetpack’s jetpack/v4/jetpack-ai-jwt route still requires edit_posts + a user-connected site to attach Authorization automatically.
• Backend: By default the plugin **wp_remote_post**s to https://public-api.wordpress.com/wpcom/v2/ai/agent/dolly (override with WP_ADMIN_RPG_DOLLY_CHAT_URL or wp_admin_rpg_dolly_chat_url; return an empty string from that filter for demo-only sheep replies). For URLs under /wpcom/v2/ai/agent/, the body is agenttic-style message/send JSON-RPC; other URLs get { "message": "..." }. If Jetpack is connected, the plugin tries to attach the Jetpack AI JWT from POST /jetpack/v4/jetpack-ai-jwt (Authorization); override or add headers with wp_admin_rpg_dolly_chat_request_args. Responses: JSON-RPC result.status.message text parts, or reply / message. Filters wp_admin_rpg_dolly_agent_api_base and wp_admin_rpg_dolly_agent_id build the default URL.
• Hooks: wp_admin_rpg_dolly_dispatch can short-circuit the whole handler (return ['reply' => '…'] or a WP_REST_Response). wp_admin_rpg_dolly_chat_request_args receives a fourth argument: the resolved chat URL.

Local development with @wordpress/env

This repo includes WordPress wp-env so you can run WordPress in Docker with the plugin mounted from the project directory.

Prerequisites

• Node.js (LTS recommended)
• Docker Desktop (or another Docker engine wp-env can use)

Setup

cd /path/to/wp-admin-rpg
npm install

Start the environment

npm run wp-env
# or: npm run env:start

First start can take a few minutes while images download and WordPress is installed.

URLs and ports

/.wp-env.json sets port 8890 (tests 8891) and JETPACK_DEV_DEBUG: false for Jurassic Tube / Jetpack.

Why wp-env prints https://…jurassic.tube:8890: @wordpress/env merges your configured port into WP_HOME / WP_SITEURL (see appendPortToWPConfigs in the package). That is correct for http://localhost:8888-style URLs and wrong for Jurassic Tube: the public site is https://SUBDOMAIN.jurassic.tube (HTTPS on 443, no :8890). The tunnel forwards 443 → localhost:8890.

This repo runs scripts/wp-env-after-start-jurassic.sh on lifecycleScripts.afterStart: it removes wp-env’s WP_HOME / WP_SITEURL constants (with the bad :8890) and sets home / siteurl to your public URL. That URL is not hardcoded: you must supply it.

JT_PUBLIC_URL=https://YOUR-SUBDOMAIN.jurassic.tube wp-env start

JT_PUBLIC_URL is also accepted as the first argument if you run the script by hand. If it is missing, wp-env start fails at afterStart with a short message from the script.

Localhost-only: run JT_PUBLIC_URL=http://localhost:8890 wp-env start (or any URL you want in the DB), or remove lifecycleScripts.afterStart from .wp-env.json.

For Jurassic Tube + Jetpack, follow the same idea as big-sky-plugin README.md (Manual Setup): install the Jurassic Tube CLI, point the tunnel at localhost:8890, then browse https://YOUR-SUBDOMAIN.jurassic.tube (HTTPS on 443, no :8890) for wp-admin and Jetpack connect.

Tunnel: from the project root (npm run jt exports JT_PUBLIC_URL as https://${JT_DOMAIN}.jurassic.tube when JT_PUBLIC_URL is not already set):

JT_DOMAIN=YOUR-SUBDOMAIN WPCOM_USERNAME=yourwpcomusername WP_ENV_PORT=8890 npm run jt

You can set JT_PUBLIC_URL explicitly instead if your public URL is not https://$JT_DOMAIN.jurassic.tube.

(npm run jt = wp-env start + wp-env update + jurassictube … -h localhost:8890.) Or only the tunnel if wp-env is already up:

jurassictube -u yourwpcomusername -s YOUR-SUBDOMAIN -h localhost:8890

Ignore the “started at …:8890” line in wp-env’s banner for the Jurassic hostname case; use https://YOUR-SUBDOMAIN.jurassic.tube/wp-admin/ only. Jetpack connect should be done on the .jurassic.tube URL, not through a proxy, per Big Sky’s README.

To tear the tunnel down later: jurassictube -b -s YOUR-SUBDOMAIN (see Big Sky README).

Default admin credentials are the usual wp-env defaults (see wp-env docs; typically admin / password unless you overrode them).

Testing the plugin

1. With Jurassic Tube running as above, open https://YOUR-SUBDOMAIN.jurassic.tube/wp-admin/ and log in.
2. Activate WP Admin RPG under Plugins (the plugin is symlinked/mounted from this repo).
3. Overworld: visiting Dashboard redirects to Admin Adventure unless you add ?skip_admin_rpg=1 to the dashboard URL.
4. Posts tavern: go to Posts → All Posts. The tavern UI replaces the list unless you use ?classic_posts=1 on edit.php for the standard list table.
5. Live asset edits: changes to files under assets/ are picked up from disk; hard-refresh the browser if a CSS/JS update does not appear (caching).

Stop / reset

npm run env:stop      # stop containers
npm run env:destroy   # remove volumes (fresh DB next start)

If Docker reports port already in use, change port / testsPort in .wp-env.json, then run env:destroy and wp-env start again.

Build a distributable zip

npm run zip

Creates wp-admin-rpg.zip in the project root with the plugin files listed in scripts/zip-plugin.mjs.

Manual install (any WordPress site)

1. Copy this folder into wp-content/plugins/wp-admin-rpg/ (or install the zip from npm run zip).
2. Activate WP Admin RPG on the Plugins screen.
3. Visit /wp-admin/ — the dashboard redirects to the RPG overworld (unless ?skip_admin_rpg=1).

Current behavior (summary)

• Top-level admin page Admin Adventure (overworld map).
• Dashboard redirect to that page (skippable via ?skip_admin_rpg=1).
• Map districts link to core admin screens (Posts, Pages, Media, etc.).
• Posts list can use the tavern experience; ?classic_posts=1 restores the default posts list.

Ideas for extension

• Surface live counts (drafts, comments, updates) on the map or quest copy.
• Quest markers / NPC copy tied to real admin tasks.
• Settings to enable the RPG shell per role or per user.