Add developer API, Prometheus metrics, and community links
This commit is contained in:
66
docs/bedrock-feasibility.md
Normal file
66
docs/bedrock-feasibility.md
Normal file
@@ -0,0 +1,66 @@
|
||||
# Bedrock panorama capture feasibility
|
||||
|
||||
Investigated on 12 October 2026 using Microsoft's current Creator documentation,
|
||||
Context7, and MineGeo's Fabric source.
|
||||
|
||||
## Result
|
||||
|
||||
A self-contained, supported Bedrock add-on cannot currently reproduce MineGeo's
|
||||
Java capture mod. Camera control is available, but the documented Script APIs
|
||||
do not expose the client framebuffer, a screenshot-to-PNG operation, or the
|
||||
square render target that the Java implementation uses. This is a conclusion
|
||||
from the exposed API surface, rather than an explicit promise by Microsoft that
|
||||
these capabilities will never exist.
|
||||
|
||||
No `.mcaddon` release was built or added to the downloads page: a pack that only
|
||||
turns the camera would not deliver the requested working panorama exporter.
|
||||
|
||||
## How Bedrock add-ons differ
|
||||
|
||||
Resource packs supply assets and presentation; behavior packs supply world
|
||||
behavior and can contain JavaScript modules. Pack manifests identify the packs,
|
||||
modules, versions, and dependencies. Imported packs are activated for a world.
|
||||
See [Getting started with add-ons](https://learn.microsoft.com/en-us/minecraft/creator/documents/gettingstarted?view=minecraft-bedrock-stable).
|
||||
|
||||
Bedrock gameplay scripts execute on the world/server side. Installing a local
|
||||
resource pack does not give a player a client-side scripting hook into arbitrary
|
||||
multiplayer servers. A scripted camera helper would need the host to activate
|
||||
its behavior pack. See [Multiplayer script architecture](https://learn.microsoft.com/en-us/minecraft/creator/documents/scripting/multiplayer-scripts?view=minecraft-bedrock-stable).
|
||||
|
||||
## Comparison with MineGeo's Java implementation
|
||||
|
||||
| Required capability | Existing Java implementation | Supported Bedrock add-on surface |
|
||||
| --- | --- | --- |
|
||||
| Aim six views from one position | `Capture.java` overrides render-camera yaw/pitch | Camera position, rotation and FOV controls exist |
|
||||
| Produce six 1024 x 1024 faces | Dedicated square framebuffer with six PNG writes | No documented framebuffer/image capture API |
|
||||
| Save a surface map and capture manifest | `SurfaceDataset.java` writes PNG and JSON files | World data can be inspected, but no documented equivalent PNG/file exporter |
|
||||
| Upload from an ordinary player's game | Java client performs upload | `server-net` HTTP is Dedicated Server only; not game clients or Realms |
|
||||
|
||||
Sources: [Camera API](https://learn.microsoft.com/en-us/minecraft/creator/scriptapi/minecraft/server/camera?view=minecraft-bedrock-stable),
|
||||
[Graphics API](https://learn.microsoft.com/en-us/minecraft/creator/scriptapi/minecraft/server-graphics/minecraft-server-graphics?view=minecraft-bedrock-experimental),
|
||||
[Dimension API](https://learn.microsoft.com/en-us/minecraft/creator/scriptapi/minecraft/server/dimension?view=minecraft-bedrock-stable),
|
||||
and [HTTP module restrictions](https://learn.microsoft.com/en-us/minecraft/creator/scriptapi/minecraft/server-net/minecraft-server-net).
|
||||
|
||||
The graphics module exposes lighting, atmospheric, water and color-grading
|
||||
controls; it does not expose screenshot capture. Built-in screenshots or
|
||||
resource-pack screenshot buttons should not be confused with a script API that
|
||||
returns six image files and metadata to an exporter.
|
||||
|
||||
## Plausible alternative requiring a separate implementation
|
||||
|
||||
A Windows companion could capture the game window while a host-installed
|
||||
behavior pack guides the camera through six views. The companion would own
|
||||
image processing, local files, checksums and upload. Manual screenshots are
|
||||
another possible input. Neither approach is a portable, automatic add-on with
|
||||
the Java mod's existing behavior.
|
||||
|
||||
Before releasing such a companion, an in-game prototype must establish:
|
||||
|
||||
1. Consistent square capture geometry and matching 90-degree cube-face projection.
|
||||
2. Matching face orientation, stable camera position, hidden HUD/hand and loaded terrain.
|
||||
3. A reliable link between coordinates and the captured images, plus camera restoration on cancellation.
|
||||
4. Surface-map export and explicit Bedrock support in MineGeo's dataset validation and upload processing.
|
||||
|
||||
These alternatives have not been implemented or tested in Bedrock. Existing
|
||||
Fabric sources, published Java artifacts, and the production deployment are
|
||||
unchanged by this investigation.
|
||||
69
docs/developer-api.md
Normal file
69
docs/developer-api.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# MineGeo developer API
|
||||
|
||||
The developer key panel is at `/dev/api`; `/api/dev` redirects there. The API reference is part of the existing documentation at `/docs?page=developer-api`, alongside the player guides. Any visitor can read the reference. Any signed-in player can create API keys independently of the account dashboard and without a Moderator or Admin role.
|
||||
|
||||
## Keys and permissions
|
||||
|
||||
Create a named key in the developer panel. A key is shown in full once, remains only in browser memory while the panel is open, and can be copied or hidden. Only a prefix and metadata appear in the key list. The server stores a SHA-256 hash, not the raw key. Keep keys out of source code, public repositories, browser JavaScript and URLs. Store them in a server-side environment variable such as `MINEGEO_API_KEY`.
|
||||
|
||||
An account can hold 5 active keys. Expiration is 1–365 days, default 90. Revoke keys in the panel at any time. Revocation is immediate; an expired or revoked key cannot be recovered. To change permissions, revoke and replace the key.
|
||||
|
||||
| Scope | Access |
|
||||
| -------------------- | ------------------------------------------------------------------ |
|
||||
| `maps:read` | Published catalog and published map metadata. Selected by default. |
|
||||
| `account:read` | Key owner's profile and username appearance. |
|
||||
| `account:maps:read` | Key owner's map metadata, including private maps. |
|
||||
| `account:games:read` | Key owner's game history. |
|
||||
|
||||
Version 1 is read-only. No key grants uploads, edits, publication, moderation or access to other accounts' private data. Contributor upload tokens and Prometheus metrics tokens cannot be used as developer keys.
|
||||
|
||||
## Requests
|
||||
|
||||
Base URL: `https://minegeo.vercel.app/api/dev/v1`
|
||||
|
||||
Every request requires `Authorization: Bearer <developer-key>`. Developer keys start with `mg_dev_`. Browser session cookies do not authenticate these endpoints. No MineGeo SDK is provided.
|
||||
|
||||
Install the Python HTTP library with `python -m pip install requests`, set `MINEGEO_API_KEY` in your environment, and make a request:
|
||||
|
||||
```python
|
||||
import os
|
||||
import requests
|
||||
|
||||
response = requests.get(
|
||||
"https://minegeo.vercel.app/api/dev/v1/maps",
|
||||
headers={"Authorization": f"Bearer {os.environ['MINEGEO_API_KEY']}"},
|
||||
params={"limit": 20, "offset": 0},
|
||||
timeout=20,
|
||||
)
|
||||
response.raise_for_status()
|
||||
print(response.json())
|
||||
```
|
||||
|
||||
| GET path | Required scope | Response |
|
||||
| ------------ | -------------------- | ----------------------------------- |
|
||||
| `/maps` | `maps:read` | `{maps: [...], pagination: {...}}` |
|
||||
| `/maps/{id}` | `maps:read` | `{map: {...}}` |
|
||||
| `/me` | `account:read` | `{account: {...}}` |
|
||||
| `/me/maps` | `account:maps:read` | `{maps: [...], pagination: {...}}` |
|
||||
| `/me/games` | `account:games:read` | `{games: [...], pagination: {...}}` |
|
||||
|
||||
Lists accept `limit` (default 20, maximum 50) and `offset` (default 0, maximum 10000). `/maps` also accepts a map-name search in `q` (up to 80 characters). Unknown or duplicate query parameters return HTTP 400. Pagination contains `limit`, `offset`, `total` and `nextOffset`; `nextOffset: null` marks the end of the supported result window. Narrow the search if you reach the offset cap.
|
||||
|
||||
Map metadata contains `id`, `name`, `description`, `source`, `state`, `bounds`, `panoramaCount`, `createdAt`, `updatedAt` and `url`. The URL is relative to the site origin. It excludes raw storage paths, panorama coordinates and moderation notes.
|
||||
|
||||
`/me` contains `id`, `displayName`, `createdAt` and `appearance` (`nameGlow`, `glowColor`, `bugFinder`, `customPrefix`, `customPrefixIcon`). Email and account roles are excluded. Game records contain `id`, `difficulty`, `createdAt`, `currentRound`, `complete` and `score`. Score is `null` until completion; answer locations are never returned.
|
||||
|
||||
The machine-readable contract is `/api/dev/openapi.json`.
|
||||
|
||||
## Rate limits and errors
|
||||
|
||||
Requests with a valid developer key are limited to 60 per minute per key and 180 per minute shared by all keys belonging to its account. Permission and validation failures consume the authenticated quota. Creating multiple keys does not bypass the account limit.
|
||||
|
||||
- `RateLimit-Limit`: per-key limit.
|
||||
- `RateLimit-Remaining`: remaining per-key quota.
|
||||
- `RateLimit-Reset`: seconds until the current minute window resets.
|
||||
- `X-RateLimit-Reset`: reset time as a Unix timestamp.
|
||||
- `X-RateLimit-Owner-Limit` and `X-RateLimit-Owner-Remaining`: shared account quota.
|
||||
- On HTTP 429, `Retry-After` gives the minimum delay in seconds before retrying.
|
||||
|
||||
Errors use `{"error":{"code":"...","message":"..."}}`. Treat the HTTP status and code as machine-readable; messages may change. Expected statuses include 400 for invalid inputs, 401 for missing or invalid credentials (including expiry or revocation), 403 for a missing scope, 404 for unavailable maps or endpoints, 429 for quota exhaustion, and 500/503 for service failures. Honor retry delays and avoid rapid retry loops.
|
||||
58
docs/forum.md
Normal file
58
docs/forum.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# MineGeo community forum
|
||||
|
||||
Live forum: https://minegeo.discourse.group/
|
||||
|
||||
Created on 12 October 2026 under Pavel's Discourse account. The public forum
|
||||
has Announcements, Maps & creations, Looking for players, and Help & feedback
|
||||
categories, plus Discourse's default General, Site Feedback, and private Staff
|
||||
categories. The pinned welcome and three conversation starters are published.
|
||||
|
||||
The community forum uses Discourse's Free hosted plan. Players sign in with
|
||||
Discourse ID; MineGeo account credentials and permissions are not shared with it.
|
||||
Forum staff permissions are managed separately in Discourse.
|
||||
|
||||
The public destination is stored in `shared/forum.json`. Both the header and
|
||||
footer use it. An optional `MINEGEO_FORUM_URL` environment variable overrides it;
|
||||
an empty or invalid value hides the links. Only HTTPS URLs without credentials
|
||||
or custom ports are accepted. No forum API key is needed for these links.
|
||||
|
||||
## Starter welcome topic
|
||||
|
||||
Welcome to MineGeo! :D
|
||||
|
||||
Play at https://minegeo.vercel.app and find the player guide at
|
||||
https://minegeo.vercel.app/docs.
|
||||
|
||||
This is our place to share maps, find people to play with, ask for help, and
|
||||
suggest what MineGeo should do next. English and Russian are welcome.
|
||||
|
||||
- Be kind. No harassment, spam, or sharing someone's private information.
|
||||
- Share maps and screenshots you have permission to share. Credit creators.
|
||||
- Post a multiplayer room link when looking for players; say when it closes.
|
||||
- Use the site's **Report a bug** button for bugs so support can track them.
|
||||
Never post passwords, tokens, private server addresses, or other secrets here.
|
||||
- Flag posts that need staff attention instead of arguing.
|
||||
|
||||
## Starter categories
|
||||
|
||||
- **Announcements** — MineGeo news and updates.
|
||||
- **Maps & creations** — Show your worlds and share playable map links.
|
||||
- **Looking for players** — Share party links and find your next teammates.
|
||||
- **Help & feedback** — Ask questions and suggest improvements.
|
||||
|
||||
## Conversation starters
|
||||
|
||||
**Show us your Minecraft world**
|
||||
|
||||
Built a castle, a tiny village, or a questionable dirt hut? Show a screenshot
|
||||
and tell us about it. Add your published MineGeo map link if you have one.
|
||||
|
||||
**Find your next MineGeo teammates**
|
||||
|
||||
Share your room link, language, and when you're playing. Let everyone know when
|
||||
the party ends. You don't need to share your real name or contact details.
|
||||
|
||||
**What would make MineGeo more fun?**
|
||||
|
||||
Tell us one thing you'd like to see next and how you'd use it. For a broken
|
||||
feature, please use the site's Report a bug button so you can get support replies.
|
||||
77
docs/prometheus.md
Normal file
77
docs/prometheus.md
Normal file
@@ -0,0 +1,77 @@
|
||||
# Prometheus and Grafana
|
||||
|
||||
Open MineGeo's **Moderation** page while signed in as an **Admin**, then find
|
||||
**Prometheus & Grafana**. Regular Moderators cannot view or change this setup.
|
||||
No new Vercel environment variables or Supabase keys are needed.
|
||||
|
||||
## Connect Prometheus
|
||||
|
||||
1. Click **Generate metrics token**. Copy the generated configuration immediately.
|
||||
Only a token hash is stored; the raw token cannot be recovered after leaving
|
||||
the page or hiding it.
|
||||
2. Paste the configuration into your Prometheus server's `prometheus.yml`.
|
||||
If that file already has `scrape_configs:`, add only the `- job_name: minegeo`
|
||||
entry under that existing section. Do not create two `scrape_configs` keys.
|
||||
3. Validate the configuration with `promtool check config prometheus.yml`, then
|
||||
reload or restart your Prometheus service using its normal deployment process.
|
||||
4. In Prometheus, open **Status → Targets** and check that `minegeo` is **UP**.
|
||||
A successful scrape also appears in MineGeo's **Last successful scrape** field;
|
||||
use **Refresh status** to update it.
|
||||
|
||||
Prometheus must be able to reach MineGeo's public HTTPS address. The endpoint is
|
||||
`https://minegeo.vercel.app/api/metrics`, protected by an Authorization bearer
|
||||
header. Browser login cookies, plugin credentials, and URL query tokens do not
|
||||
grant access. The generated job scrapes once a minute with a 20-second timeout
|
||||
and does not forward credentials through redirects. Keep the configuration
|
||||
private; do not paste it into public Git repositories or forum posts.
|
||||
|
||||
**Rotate metrics token** revokes the previous token immediately. Copy the new
|
||||
configuration and update Prometheus afterward. **Disable metrics access** revokes
|
||||
the current token. Deleting the issuing Admin account or removing its Admin role
|
||||
also invalidates that token. Issuing another token requires a current Admin.
|
||||
|
||||
## Import the Grafana dashboard
|
||||
|
||||
1. In MineGeo, click **Download Grafana dashboard**.
|
||||
2. In Grafana, add a **Prometheus** data source pointing to your Prometheus server
|
||||
(for example, its internal service address). Grafana queries Prometheus;
|
||||
it does not use the MineGeo metrics URL as its data source.
|
||||
3. Open **Dashboards → New → Import**, upload the downloaded JSON, and choose the
|
||||
Prometheus data source when prompted.
|
||||
4. Select the MineGeo instance. Allow one or two scrapes for the first values.
|
||||
|
||||
The dashboard has 15 panels covering scrape health, registered accounts, maps,
|
||||
panoramas, solo games, multiplayer rooms, uploads, bug reports, content reports,
|
||||
Discord delivery, exporter read time, and snapshot age. It requires only the
|
||||
built-in Prometheus source and Grafana stat/time-series panels.
|
||||
|
||||
History begins when your Prometheus instance starts scraping; existing retained
|
||||
records appear in the first snapshot. Prometheus retention controls how long
|
||||
history remains. Set up Prometheus/Grafana on your own server or supported hosted
|
||||
monitoring service; Vercel runs the exporter, not the monitoring servers.
|
||||
|
||||
## Meaning and privacy of metrics
|
||||
|
||||
- All `minegeo_*` values are **gauges**, not monotonic counters. Deleted records,
|
||||
including closed bug reports removed after three days, can lower counts.
|
||||
Do not use `rate()` or `increase()` on these retained inventory gauges.
|
||||
- Games/rooms created in the last 24 hours are rolling-window gauges.
|
||||
- Solo games are complete once `current_round = 5`. Incomplete includes abandoned
|
||||
games. Room lifecycle states describe stored rooms, not currently online users.
|
||||
- Aggregates are collected in one database transaction and cached there for
|
||||
30 seconds to share work across Vercel instances. Failed scrapes return 503,
|
||||
never a fabricated all-zero dataset. Prometheus's `up` series records failures.
|
||||
- Names, IDs, emails, messages, screenshots, credentials, and map content are
|
||||
excluded. Metric labels use fixed state/difficulty values only.
|
||||
- Page views, IP addresses, browser sessions, Vercel CPU/memory, and request latency
|
||||
are not collected by this integration. Vercel Web Analytics remains separate.
|
||||
|
||||
For another installation, apply
|
||||
`supabase/migrations/20261012085217_prometheus_metrics.sql` before deployment.
|
||||
The new table has RLS and service-role-only permissions; the three RPC functions
|
||||
use `security invoker` and explicitly revoke public/anonymous/authenticated access.
|
||||
Verify SQL authorization locally with `node scripts/test-prometheus-sql.mjs` using
|
||||
the same optional PGlite runtime as the existing SQL verification scripts.
|
||||
|
||||
References: [Prometheus scrape configuration](https://prometheus.io/docs/prometheus/latest/configuration/configuration/),
|
||||
[Grafana dashboard imports](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/import-dashboards/).
|
||||
@@ -1,5 +1,16 @@
|
||||
# Deploy MineGeo
|
||||
|
||||
The scoped developer API requires `20261012124943_developer_api_keys.sql`.
|
||||
No additional environment variables are needed. The standalone panel is
|
||||
`/dev/api`, `/api/dev` redirects there, and the versioned read-only API is
|
||||
`/api/dev/v1`. See [Developer API](developer-api.md) for permissions, rate
|
||||
limits, revocation, OpenAPI and Python requests examples.
|
||||
|
||||
Admin-only Prometheus/Grafana setup requires `20261012085217_prometheus_metrics.sql`.
|
||||
No new Vercel variables are needed: Admins generate a dedicated scrape token in
|
||||
Moderation. See [Prometheus and Grafana](prometheus.md) for the copyable config,
|
||||
dashboard import, credential rotation, and metric definitions.
|
||||
|
||||
The portable Windows Electron client and release process are described in
|
||||
[Desktop client](desktop.md). Build and publish the EXE before deploying changes
|
||||
to desktop download links. Public desktop releases are included in the upload;
|
||||
@@ -25,6 +36,10 @@ changing a link. For the hosted site, add the same names as Production Config
|
||||
variables in the MineGeo Vercel project, then redeploy. These values are public
|
||||
destinations; no Discord bot token or Telegram API key is needed.
|
||||
|
||||
The hosted community forum is linked in the header and footer using
|
||||
`shared/forum.json`. `MINEGEO_FORUM_URL` can override its public HTTPS address.
|
||||
See [Community forum](forum.md) for forum ownership and starter content.
|
||||
|
||||
Discord accepts HTTPS links on `discord.gg`, `discord.com`, `www.discord.com`,
|
||||
and `discordapp.com`. Telegram accepts `t.me` and `telegram.me`, including group
|
||||
invite links. Blank, malformed, or unsupported URLs hide the corresponding
|
||||
|
||||
Reference in New Issue
Block a user