Merge pull request #14 from theprototype-app/docs-36-int-124

[docs] 1.24: characters, Race, Edit Mesh ops + Boolean, checkpoints, recording + gallery, community, VR HUD + VR AI (36-int-124)

Author: AlexZ005

docs/ai/assistant.md

@@ -36,6 +36,35 @@ Once the assistant is enabled and a provider is set, a round **✨ button** appe
 bottom-left of the viewport (just below the **＋** add button). Click it to open or close
 the assistant window — the same window the quick prompt bar opens into.
 
+### In VR
+
+Radial menu ▸ **Tools ▸ AI** opens the same conversation on a panel in the headset, where you can type or hold a button
+and talk — see [The AI assistant in VR](../vr.md#the-ai-assistant-in-vr).
+
+## Voice typing
+
+Talk to the assistant instead of typing. Set up a speech-to-text provider in **Settings ▸ AI ▸ Voice typing provider**
+(search *voice*, *whisper* or *dictation*):
+
+| Setting | Default | Notes |
+|---|---|---|
+| **Provider** | OpenAI | **OpenAI** (`whisper-1`), **Groq** (`whisper-large-v3`), or **Self-hosted** — any OpenAI-compatible `/audio/transcriptions` server, such as faster-whisper |
+| **Base URL / API key / Model** | from the preset | OpenAI and Groq need a key; a self-hosted server only its URL |
+| **Language hint** | blank (detect) | for example `en` |
+| **Test connection** | — | sends half a second of silence; *Connected* means the server accepted it |
+
+![Voice typing set to Groq](../img/ai/voice-typing-settings.png)
+
+The assistant window then has a **mic** button next to **Send**: click to listen, click again to stop. The words land in
+the input, so you can fix them before sending. (In VR they are sent as soon as you let go.)
+
+![The assistant window with the mic button next to Send](../img/ai/assistant-mic.png)
+
+- The voice key is stored on this device only, like the AI provider key ([Where keys are stored](providers.md#where-keys-are-stored)).
+- If voice chat is on, the assistant uses the same microphone without opening a second one, and voice chat keeps
+  working.
+- Voice needs a browser that can record audio and microphone permission. A recording stops itself after 60 seconds.
+
 ## What you can ask for
 
 The assistant works with the building blocks the app already has:

docs/avatars.md

@@ -0,0 +1,58 @@
+# Your Character
+
+Since 1.24 everyone in a session appears as a **rigged, animated character** instead of a floating head. The body
+stands under the person's viewpoint, **walks, runs, strafes, jumps and idles** with the way they move, turns to face
+where they look, and — when they are in **VR** — reaches for their controllers with its arms. The classic floating head
+is still there as a choice.
+
+![Another person's character, a Knight, standing where their camera is](img/avatars/peer-character.png)
+
+## The characters
+
+Nine characters ship with the app: **Knight**, **Mage**, **Rogue**, **Hooded rogue**, **Barbarian**, **Skeleton**,
+**Skeleton warrior**, **Skeleton mage** and **Skeleton rogue**, from Kay Lousberg's free CC0 KayKit packs.
+
+![The nine characters](img/avatars/characters.png)
+
+If you never pick one, you get **Surprise me**: a character chosen from your id, so everyone sees the same one for you.
+The same characters are also an Explorer pack, **Packs ▸ Adventurers**, that you can place in a scene as animated
+models (see [Packs](packs.md#adventurers-124)).
+
+## Customize Character
+
+Profile menu (your picture, top right) ▸ **Customize Character** — also **Settings ▸ Interface ▸ Avatars ▸ Customize
+character…**. A side panel opens and the camera moves to **your own character**, standing where you are, so you see
+yourself the way other people do.
+
+![The Customize character panel with the camera on your own character](img/avatars/customize-panel.png)
+
+| Section | What you choose |
+|---|---|
+| **Character** | one of the nine — step through them with ‹ › — or **Surprise me** or **Classic head** |
+| **Head** | the character's own head, a stylised **Sphere**, **Box**, **Capsule** or **Cone** in your colour, or **My photo** (your profile picture on a card; needs a profile photo) |
+| **Hat** | None, Cap, Top hat or Crown — it sits on whatever head you chose |
+| **Colours** | **Outfit** recolours the character's clothes (skin and face keep theirs; **Original** puts them back); **Head** colours a stylised head or the classic avatar |
+| **Show my name above me** | your name label |
+| **Ping** | the colour and chime of *your* [pings](notifications.md#pinging); **Preview** pings beside your character (only you see and hear it) |
+
+Every change shows on your character at once; nothing reaches other people until you press **Apply**, which saves it and
+shows it to everyone. **Cancel**, <kbd>Esc</kbd> or ✕ throw the changes away. Either way the camera flies back to where
+you were.
+
+## Showing everyone as classic heads
+
+**Settings ▸ Interface ▸ Avatars ▸ Show everyone as classic heads** draws other people as the floating head instead of
+their character — on **this device only**, and lighter on a headset with many people in the room. They still see your
+character.
+
+## In VR
+
+A VR user's character follows their head, and its arms reach for their controllers; a hand held out of the arm's reach
+falls back to the floating controller marker. Pointing at an object puts the character's hand on it.
+
+## Limits
+
+- The bodies are stylised (big heads): a character is about 2.2 m tall so its eyes sit where the person's are.
+- In the editor, a character follows the editor camera — flying the camera makes the body float.
+- Characters add no network traffic: each screen works the bodies out from the position and hand data already shared.
+- Each character is at most about 6,000 triangles with one material, so eight people stay inside a Quest's budget.

docs/checkpoints.md

@@ -0,0 +1,51 @@
+# Checkpoints
+
+A **checkpoint** is a copy of the scene as it is right now — objects, node graphs, HUD, sky, physics, the camera — kept
+**on this device**, with a name, an optional note, a picture and a time. [Autosave](saving.md#autosave) only remembers
+the *last* state; checkpoints let you go back to *any* earlier one.
+
+![The Checkpoints timeline comparing two checkpoints with the swipe slider](img/checkpoints/timeline-compare.png)
+
+## Saving a checkpoint
+
+**Menu** (the logo button) ▸ **Save checkpoint…**, or press <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>S</kbd>. Type a name and, if you like,
+a note ("before lighting", "try the red version next"), then press **Save checkpoint**.
+
+## The timeline
+
+**Menu ▸ Checkpoints** lists every checkpoint, newest first, grouped by day. In it you can:
+
+| Action | How |
+|---|---|
+| **Restore** | replaces the open scene with the checkpoint. The scene you leave is kept in the timeline as **"Before restoring …"**, so a restore can itself be undone. With people connected, they are asked to accept first (the same as opening a saved session) |
+| **Rename** | double-click the name |
+| **Note** | click the note line to edit it (<kbd>Ctrl</kbd>+<kbd>Enter</kbd> saves) |
+| **Pin** | a pinned checkpoint is never removed to make room |
+| **Delete** | removes the checkpoint |
+| **Compare** | press **Compare**, then tick two checkpoints: their pictures sit on top of each other with a swipe slider, plus what changed (object count, size, time apart, "same content"). Tick just one to compare it with the scene as it is now |
+
+Two filters narrow the list: show only **This scene**'s checkpoints, or hide the **Automatic** ones.
+
+## Automatic checkpoints
+
+While you work, autosave also adds an **automatic** checkpoint every few minutes — only when the scene actually changed
+since the last one, and never while a scene is loading or a simulation is running.
+
+## Settings
+
+**Settings ▸ Scene ▸ Checkpoints**:
+
+| Setting | Default | What it does |
+|---|---|---|
+| Keep automatic checkpoints | on | autosave adds rows to the timeline |
+| Automatic checkpoint every | 10 min | 5 / 10 / 30 / 60 min — the shortest gap between two |
+| Checkpoint storage | 250 MB | 100 MB / 250 MB / 500 MB / 1 GB that this device may use |
+
+## Limits
+
+- Checkpoints stay on this device (this browser). They are not shared with other people and are not part of a project
+  file — use **Save** and scene versions ([Saving & Sessions](saving.md)) for that.
+- When a new checkpoint would not fit, the **oldest unpinned** ones are removed — automatic ones before named ones. If
+  even that is not enough (everything else is pinned), the save is refused and a message says so. At most 60 checkpoints
+  are kept.
+- A scene larger than the storage limit cannot be checkpointed.

docs/community.md

@@ -41,13 +41,18 @@ Publish again from the same scene and the dialog offers **Update "‹title›" 
 
 There is no unpublish button in the app yet.
 
+When you publish or update a game, the dialog also shows a **This game: …** line with its visits — see
+[Your games & stats](#your-games-stats).
+
 ### The GitHub gallery destination
 
-Choosing **GitHub gallery** downloads `‹slug›-gallery-entry.zip` (the scene, a thumbnail and an `entry.json`) and opens the gallery repository: fork it, add the folder and a row to `gallery.json`, open a pull request. Contest entries need the Community destination, and the dialog says so if you pick both.
+Choosing **GitHub gallery** builds the same submission zip as the **Community gallery** tab of Publish / Export, with
+the same two GitHub steps — see [The Community gallery tab](publish-export.md#the-community-gallery-tab). Contest entries
+need the Community destination, and the dialog says so if you pick both.
 
 ## A scene's page
 
-Every published scene has a page at `/s/‹id›`: the hero shot, the title, the author's `@handle`, the license, a **♥** like button (sign in to use it), the summary, the tags, and four actions:
+Every published scene has a page at `/s/‹id›`: the hero shot, the title, the author's `@handle`, the license, a **♥** like button (sign in to use it; the same like as the [hearts in the app](#hearts)), the summary, the tags, and four actions:
 
 - **▶ Play** — opens the app with the scene loaded and Play mode already running.
 - **Open in ThePrototype** — the same, in the editor.
@@ -58,7 +63,8 @@ A public scene also has an **Embed** button — see [Embedding a scene](#embeddi
 
 Below that: what the scene includes, its lineage (*Remix of … by @handle*, and how many remixes it has), and comments. **Report this scene** is at the bottom — see [Reporting](#reporting).
 
-`/community` is the browse page: **Featured**, **Recent** and **Top**, tag chips, and a strip for the contest that is open.
+`/community` is the browse page: **Featured**, **Recent** and **Top**, tag chips, a **Mine** chip while you are signed in
+(see [below](#mine)), and a strip for the contest that is open.
 
 ### Links that open the app
 
@@ -78,14 +84,55 @@ The flag lasts for the life of the page.
 
 **The editor is the player.** Play opens the real app with the full scene, not a preview: the game's HUD, its flow graph, its physics and its sound all run, and a click on the viewport takes the pointer.
 
-**Remix is a local load.** Nothing is created on the server until you publish. When you do, the dialog shows a ticked *Remix of "‹title›" by @handle* line and the new scene carries that lineage on its page. Every license in the picker allows this; a remix of your own scene is simply a new scene, with no lineage line.
+**Remix is a local load.** Nothing is created on the server until you publish. When you do, the dialog shows a ticked *Remix of "‹title›" by @handle* line and the new scene carries that lineage on its page. Every license in the picker allows this; a remix of your own scene is simply a new scene, with no lineage line. A remix is also a **new game** with its own [game id](#one-game-one-count).
 
 ## The Community tab in Templates
 
 **Menu ▸ Templates ▸ Community** lists published scenes inside the app — featured ones first, then the most recent — with the author's handle, the license, the size and the like count on each card. Tag chips narrow the list; **Clear** resets it. Clicking a card loads the scene through the ordinary template path: a backup of your current scene is stashed first, and connected peers are asked before anything changes. The small button in a card's corner saves the scene to your Library instead, without loading it.
 
 When a contest is open a notice row says so (*Contest: Make a mirror — 9 days left*) with a **More** link to its page, and the tab's **Publish yours** link opens the Publish dialog.
 
+### Hearts
+
+Like a published scene without leaving the app: the **heart** button sits on every card in **Templates ▸ Community**, on
+the start card of a **play link** (`/p/‹id›`) and in a published game's **pause menu** (<kbd>Esc</kbd>, top right).
+Press it and the count updates at once (and goes back if the like could not be saved). Signed out, it asks you to sign in
+(profile menu, top right). It is the same like as the ♥ on the scene's page — one like per person per scene.
+
+![The heart on a play link's start card, beside Play](img/community/play-link-heart.png)
+
+![The heart in a published game's pause menu](img/community/pause-menu-heart.png)
+
+### Mine
+
+While you are signed in, the **Mine** chip in **Templates ▸ Community** (and on theprototype.app/community) shows only
+your own published scenes — unlisted ones too. A scene staff hid shows *Hidden by moderation: ‹reason›*, so you know why.
+
+## Your games & stats
+
+Profile menu ▸ **📈 Your games & stats** shows how many people arrived from the **Made with ThePrototype** badge in your
+play links, embeds and exported builds — for the last **7 days**, **30 days** or **all time**, split by source (play
+link, itch.io, static host, embed). The [Publish](#publish) dialog shows the same count for the game you are publishing
+or updating.
+
+![Your games: visits over 30 days, one row per game, with a moderation notice](img/community/your-games.png)
+
+### One game, one count
+
+Every scene gets a permanent **game id** the first time you save, export or publish it. Re-exporting, a new itch.io build
+and the play link all count toward the **same game** — including visits from before you published it. A **copy**
+(Explorer ▸ Duplicate, Save to Library) or a **remix** of someone else's scene becomes a **new game**.
+
+- Visits are counted per game, never per visitor: no cookies, no IP addresses.
+- Builds exported before 1.24 count under their own old id.
+- Exports made while signed out still count, but show in your stats only once the game is published or exported again
+  while you are signed in.
+
+### If a scene of yours is hidden
+
+If staff hide or remove one of your scenes, **Your games** (and the Publish dialog, when you update it) says *Hidden by
+moderation: ‹reason›*. Press **Ask for a review** — once a day, with an optional note — and staff get it in their queue.
+
 ## Contests
 
 A contest is a brief, a starter scene, a two-week window and a page at `/c/‹slug›`: the rules, a live countdown, the starter, the entries, and the results once it ends. The first two are **Make a mirror** and **Follow the beat**; windows overlap by a week, so there is always one open and one closing.
@@ -106,4 +153,7 @@ The site and the app share one sign-in. **Sign in** in the site header offers th
 
 ## Reporting
 
-Every scene page ends with **Report this scene**: pick a reason — **Spam**, **Not safe for work**, **Stolen work**, **Illegal content** or **Other** — add a note if you like, and send it (this needs a sign-in, and counts once per person per scene). A scene reported by three different people is hidden from every list and page until a maintainer has looked at it. Assets an author had no right to license are exactly what *Stolen work* is for: the license picker cannot express "all rights reserved", so a report and a takedown are how that is handled.
+Every scene page ends with **Report this scene**: pick a reason — **Spam**, **Not safe for work**, **Stolen work**, **Illegal content** or **Other** — add a note if you like, and send it (this needs a sign-in, and counts once per person per scene). A scene reported by three different people — counting only accounts older than three days — is hidden from every list and page until a maintainer has looked at it.
+
+Staff accounts have a **Staff · Insights & moderation** entry in the profile menu for the report queue and the visit
+totals; it is not shown to anyone else. Assets an author had no right to license are exactly what *Stolen work* is for: the license picker cannot express "all rights reserved", so a report and a takedown are how that is handled.