Skip to content

Commit 410ff8f

Browse files
author
RSamaium
committed
Add API references for database, events, maps, media, and settings
- Created `database.md` for CRUD operations on game entities like items, enemies, and variables. - Added `event-examples.md` to provide concrete event patterns for common scenarios. - Introduced `events.md` detailing the events API for creating and managing map events. - Established `maps.md` for map CRUD operations and related functionalities. - Developed `media.md` for media management, including searching and AI generation. - Implemented `settings.md` for project-level settings and configurations.
1 parent b0efde4 commit 410ff8f

File tree

10 files changed

+2062
-1
lines changed

10 files changed

+2062
-1
lines changed

‎readme.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ With RPG JS, we aspire to provide developers with a robust foundation that adapt
1616
## WebSite and Documentation
1717

1818
- Website: [https://rpgjs.dev](https://rpgjs.dev)
19-
- Documentation: [https://v5.rpgjs.dev](https://docs.rpgjs.dev)
19+
- Documentation: [https://v5.rpgjs.dev](https://v5.rpgjs.dev)
2020

2121
## Getting Started
2222

‎skills/rpgjs-studio/SKILL.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
name: rpgjs-studio
3+
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.
4+
---
5+
6+
# RPGJS Studio API Skill
7+
8+
Use this skill to execute content-management tasks against an RPGJS Studio instance.
9+
10+
## Inputs
11+
12+
- Check whether a local `RPGSTUDIO.md` file exists in the current working directory.
13+
- If `RPGSTUDIO.md` exists, treat it as local project context and read it first.
14+
- Use it to recover persistent values such as:
15+
- `BASE_URL`
16+
- `projectId`
17+
- any other project-specific instructions relevant to API usage
18+
- If `RPGSTUDIO.md` does not exist, continue normally.
19+
- Resolve `BASE_URL` from the user if provided.
20+
- Default `BASE_URL` to `https://rpgjs.studio` when the user did not specify another host.
21+
- Read the API key from the environment variable `RPGSTUDIO_API_KEY`.
22+
23+
## Mandatory startup workflow
24+
25+
1. Check whether `RPGSTUDIO_API_KEY` exists before any API call.
26+
2. When checking `RPGSTUDIO_API_KEY`, never print its value in the terminal and never echo it back in the response.
27+
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`.
28+
4. Build authenticated requests with these headers:
29+
30+
```bash
31+
-H "x-api-key:$RPGSTUDIO_API_KEY"
32+
-H "Content-Type: application/json"
33+
```
34+
35+
5. Prefer `curl` for HTTP calls. Use another HTTP client only if there is a clear reason.
36+
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.
37+
7. Read only the reference file that matches the user task:
38+
- `references/database.md`
39+
- `references/maps.md`
40+
- `references/events.md`
41+
- `references/event-examples.md`
42+
- `references/blocks.md`
43+
- `references/media.md`
44+
- `references/settings.md`
45+
46+
## Local memory file
47+
48+
Use `RPGSTUDIO.md` as a lightweight local memory file for the current project.
49+
50+
- Read it at the start if it exists.
51+
- Reuse values already stored there instead of asking again.
52+
- After the task, update or create it with stable, non-secret context discovered during execution.
53+
54+
Typical contents:
55+
56+
- last used `BASE_URL`
57+
- current `projectId`
58+
- project-specific conventions or notes useful for future calls
59+
60+
If `projectId` is still unknown after reading `RPGSTUDIO.md` and the current user request does not provide it:
61+
62+
1. Call the projects listing endpoint first.
63+
2. Present a numbered list with:
64+
- project title
65+
- project identifier
66+
3. Stop the workflow there.
67+
4. Ask the user which project to select.
68+
5. Resume the actual task only after the user chooses a project.
69+
6. Persist the selected `projectId` in `RPGSTUDIO.md` so it does not need to be requested again later.
70+
71+
Never store secrets in this file.
72+
73+
- Do not store `RPGSTUDIO_API_KEY`.
74+
- Do not print `RPGSTUDIO_API_KEY`.
75+
- Do not copy raw secret values into logs, terminal output, or markdown.
76+
77+
## Request pattern
78+
79+
Define the base command once and reuse it:
80+
81+
```bash
82+
BASE_URL="${BASE_URL:-https://rpgjs.studio}"
83+
curl -sS \
84+
-H "x-api-key:$RPGSTUDIO_API_KEY" \
85+
-H "Content-Type: application/json"
86+
```
87+
88+
Use project listing when `projectId` is missing:
89+
90+
```bash
91+
curl -sS "$BASE_URL/api/projects" \
92+
-H "x-api-key:$RPGSTUDIO_API_KEY" \
93+
-H "Content-Type: application/json"
94+
```
95+
96+
For write operations, prefer:
97+
98+
```bash
99+
curl -sS -X POST "$BASE_URL/..." \
100+
-H "x-api-key:$RPGSTUDIO_API_KEY" \
101+
-H "Content-Type: application/json" \
102+
-d '{...}'
103+
```
104+
105+
## Execution rules
106+
107+
- Start by identifying the resource domain, then load the matching reference file.
108+
- Use REST semantics: `GET`, `POST`, `PUT`, `DELETE`.
109+
- Resolve foreign keys before creation or update:
110+
- Search media with `/api/media?query=<search>`.
111+
- Search database records with `/api/database/:type?query=<search>`.
112+
- If a matching dependency exists, reuse its returned `_id`.
113+
- If not found, create it first, then continue with the returned `_id`.
114+
- If `projectId` is missing, list projects, ask the user to choose one, and stop until they answer.
115+
- When the user asks to create game objects, send the smallest valid payload first, then enrich it only if the task requires more fields.
116+
- Reuse IDs returned by the API instead of guessing them.
117+
- If an endpoint shape is uncertain, inspect the response from a nearby `GET` endpoint first and adapt from that live payload.
118+
- Do not continue after an auth failure.
119+
- If a missing dependency would require AI media generation, stop and ask the user whether to spend credits before calling a `/api/media/generate/...` endpoint.
120+
- For `POST /api/maps/generate`, rely on `references/maps.md` for the AI map generation workflow and endpoint-specific failure behavior.
121+
- Summarize the exact records created, updated, or deleted in the final response.
122+
- When a task reveals stable project context such as `BASE_URL` or `projectId`, persist that context into `RPGSTUDIO.md` for future runs.
123+
124+
## Common checks
125+
126+
- `database` task: read [references/database.md](./references/database.md)
127+
- `map` task: read [references/maps.md](./references/maps.md)
128+
- `event` task: read [references/events.md](./references/events.md)
129+
- `event example` task: read [references/event-examples.md](./references/event-examples.md)
130+
- `event workflow block` task: read [references/blocks.md](./references/blocks.md)
131+
- `media` task: read [references/media.md](./references/media.md)
132+
- `settings` task: read [references/settings.md](./references/settings.md)

‎skills/rpgjs-studio/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "RPGJS Studio API"
3+
short_description: "Manage RPGJS Studio via HTTP API"
4+
default_prompt: "Use $rpgjs-studio to create or manage maps, events, database records, media, or project settings through the RPGJS Studio API."

0 commit comments

Comments
 (0)