rpgjs-studio

name	rpgjs-studio
description	Use the RPGJS Studio HTTP API to create or manage a 2D RPG game. Trigger this skill when Codex needs to CRUD maps, map events, database records, media assets, or general project settings in RPGJS Studio, especially when the task should be done through `curl` or another HTTP client with an API key and configurable base URL.

RPGJS Studio API Skill

Use this skill to execute content-management tasks against an RPGJS Studio instance.

Inputs

• Check whether a local RPGSTUDIO.md file exists in the current working directory.
• If RPGSTUDIO.md exists, treat it as local project context and read it first.
• Use it to recover persistent values such as:
  • BASE_URL
  • any other project-specific instructions relevant to API usage
• Do not recover, request, or persist a projectId. The API key is scoped to the RPGJS Studio project, so work directly on the user's requested resource.
• If RPGSTUDIO.md does not exist, continue normally.
• Resolve BASE_URL from the user if provided.
• Default BASE_URL to https://rpgjs.studio when the user did not specify another host.
• Read the API key from the environment variable RPGSTUDIO_API_KEY.

Mandatory startup workflow

1. Check whether RPGSTUDIO_API_KEY exists before any API call.
2. When checking RPGSTUDIO_API_KEY, never print its value in the terminal and never echo it back in the response.
3. If the variable is missing or empty, stop and tell the user to create an API key first on ${BASE_URL}/api-keys, then export RPGSTUDIO_API_KEY.
4. Build authenticated requests with these headers:

-H "x-api-key:$RPGSTUDIO_API_KEY"
-H "Content-Type: application/json"

5. Prefer curl for HTTP calls. Use another HTTP client only if there is a clear reason.
6. Fail fast on authentication errors. If the API returns an invalid-key style response, 401, or 403, stop the task and tell the user to verify the key or contact support.
7. Read only the reference file that matches the user task:
   • references/database.md
   • references/maps.md
   • references/events.md
   • references/event-examples.md

• references/blocks.md
• references/media.md
• references/settings.md
• references/project-env.md
• references/mmorpg.md

Local memory file

Use RPGSTUDIO.md as a lightweight local memory file for the current project.

• Read it at the start if it exists.
• Reuse values already stored there instead of asking again.
• After the task, update or create it with stable, non-secret context discovered during execution.

Typical contents:

• last used BASE_URL
• project-specific conventions or notes useful for future calls

Do not use RPGSTUDIO.md to select a project. The current RPGSTUDIO_API_KEY already identifies the target project, so proceed directly with the user's request.

Never store secrets in this file.

• Do not store RPGSTUDIO_API_KEY.
• Do not print RPGSTUDIO_API_KEY.
• Do not copy raw secret values into logs, terminal output, or markdown.

Request pattern

Define the base command once and reuse it:

BASE_URL="${BASE_URL:-https://rpgjs.studio}"
curl -sS \
  -H "x-api-key:$RPGSTUDIO_API_KEY" \
  -H "Content-Type: application/json"

For write operations, prefer:

curl -sS -X POST "$BASE_URL/..." \
  -H "x-api-key:$RPGSTUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

Execution rules

• Start by identifying the resource domain, then load the matching reference file.
• Use REST semantics: GET, POST, PUT, DELETE.
• Resolve foreign keys before creation or update:
  • Search media with /api/media?query=<search>.
  • Search database records with /api/database/:type?query=<search>.
  • If a matching dependency exists, reuse its returned _id.
  • If not found, create it first, then continue with the returned _id.
• Never call a project listing endpoint just to choose a project. The API key determines the project context.
• When the user asks to create game objects, send the smallest valid payload first, then enrich it only if the task requires more fields.
• Reuse IDs returned by the API instead of guessing them.
• When the user provides a database _id for a read, update, or delete task, call GET /api/database/:type/:id first and inspect the existing record before deciding the payload or reporting the content.
• If an endpoint shape is uncertain, inspect the response from a nearby GET endpoint first and adapt from that live payload.
• Do not continue after an auth failure.
• If a missing dependency would require AI media generation, always call the unified media generation endpoint with action: "estimate" first.
• After the estimate, report the required credits to the user and ask for confirmation before calling action: "execute".
• Never start an AI media generation directly without this estimate and confirmation step.
• For POST /api/maps/generate, rely on references/maps.md for the AI map generation workflow and endpoint-specific failure behavior.
• Summarize the exact records created, updated, or deleted in the final response.
• When a task reveals stable project context such as BASE_URL or local conventions, persist that non-secret context into RPGSTUDIO.md for future runs.

Common checks

• database task: read references/database.md
• map task: read references/maps.md
• event task: read references/events.md
• event example task: read references/event-examples.md
• event workflow block task: read references/blocks.md
• media task: read references/media.md
• settings task: read references/settings.md
• project env task: read references/project-env.md
• MMORPG publication task: read references/mmorpg.md

Current schema notes

• An authenticated Studio session can publish the current project with POST /api/mmorpg/publish. Publication prepares every map before sending any update. Failures return a stable code, stage, and optional resourceId; see references/mmorpg.md for the response contract.
• show_text blocks may set inputEnabled: true and must then provide inputVariableId, the _id of a database variable receiving the submitted string or number. Cancelling the input stores null; see references/blocks.md for the typed input options.
• Maps, events, block collections, and database records support multilingual semantic search through their existing list endpoints with query. The optional minScore parameter accepts 0..1 and defaults to 0.40; see the matching resource reference for endpoint-specific filters and response shapes.
• Project environment variables are managed with authenticated project routes: GET /api/projects/:projectId/env, PUT /api/projects/:projectId/env/:name, and DELETE /api/projects/:projectId/env/:name. Plain values are returned in responses; secret values expose only isSet and must never be logged or printed.
• Playable characters are database Actors under /api/database/actors. The public runtime database includes Actors and the public project exposes mainActorId so a new game can preselect the project hero.
• Playable identities are database Classes under /api/database/classes. New Actors require a valid classId; existing legacy Actors without one remain readable. Classes own name, description, icon, and level-gated skills, while Actors own appearance, statistics, inventory, and equipment. A Class assigned to any Actor cannot be deleted until those Actors are reassigned.
• Character spritesheet metadata can contain illustration, the media _id of a transparent 4:5 JRPG character illustration inherited by every Actor using that spritesheet. AI generation type illustration costs 5 credits.
• Database create and update validation treats null from non-nullable form fields as an omitted value. When the JSON Schema declares a , that default is applied instead; explicit values and explicitly nullable fields are preserved. Optional object groups containing only omitted values, such as , are omitted as well. A validation identifies the first invalid field with a dotted path in , for example .