Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 agent-bot
|
41fcbe746e |
@@ -1,462 +0,0 @@
|
||||
# Avatar Component System & glTF Attachment Spec
|
||||
|
||||
> **Status:** Proposed
|
||||
> **Owner:** Platform team
|
||||
> **Related:** Server authority + client prediction, world chunk data format
|
||||
|
||||
## 1. Overview
|
||||
|
||||
This document specifies the **avatar component system** for **agp-game**, a
|
||||
Godot-based multiplayer game. It defines:
|
||||
|
||||
- How an avatar is decomposed into **body parts** and **attachment slots**.
|
||||
- How **cosmetic attachments** (clothing, accessories, gear) mount onto the
|
||||
base body.
|
||||
- The **glTF/GLB format requirements** that all avatar assets must satisfy so
|
||||
they can be loaded, skinned, and networked consistently.
|
||||
|
||||
The goal is a **modular, data-driven avatar pipeline**: a single base body rig
|
||||
plus swappable attachments, all authored in glTF and consumed by a shared Godot
|
||||
runtime. This enables player customization, cosmetic monetization, and
|
||||
server-authoritative validation of what a player is wearing.
|
||||
|
||||
### 1.1 Design Goals
|
||||
|
||||
- **Modularity:** Body parts and attachments are independent assets that can be
|
||||
combined at runtime without re-exporting.
|
||||
- **Consistency:** A single, well-defined skeleton and slot convention so any
|
||||
attachment fits any base body.
|
||||
- **Networkability:** The avatar's composition is expressed as a compact,
|
||||
serializable **loadout** that the server can validate and replicate.
|
||||
- **Performance:** Attachments are skinned to the same skeleton and share
|
||||
materials where possible to minimize draw calls and skinning cost.
|
||||
- **Tooling-friendly:** Assets are authored in standard glTF 2.0 and validated
|
||||
by a build-time checker.
|
||||
|
||||
---
|
||||
|
||||
## 2. Avatar Decomposition
|
||||
|
||||
### 2.1 The Base Body
|
||||
|
||||
Every avatar is built on a **base body** — a single glTF asset containing:
|
||||
|
||||
- A **skeleton** (the canonical rig, see §3).
|
||||
- A **base mesh** for the skin/body (head, torso, arms, legs).
|
||||
- **Attachment points** (empty nodes) that define where accessories mount.
|
||||
|
||||
The base body is the only asset that carries the skeleton. Attachments reference
|
||||
the skeleton by **bone name** and are skinned to it; they never carry their own
|
||||
rig.
|
||||
|
||||
### 2.2 Body Parts vs. Attachments
|
||||
|
||||
Two distinct concepts:
|
||||
|
||||
| Concept | Definition | Example |
|
||||
|----------------|-------------------------------------------------------------------------|----------------------------------|
|
||||
| **Body part** | A mesh that replaces part of the base body's skin (e.g., a different head, a tail, wings). | Alternate head, cybernetic arm |
|
||||
| **Attachment** | A mesh that mounts *on top of* the body without replacing it (clothing, accessories). | Shirt, hat, glasses, backpack |
|
||||
|
||||
The distinction matters for **slot exclusivity** and **layering**:
|
||||
|
||||
- **Body parts** are *exclusive* per slot — only one head can be equipped.
|
||||
- **Attachments** are *layered* — a hat and glasses can coexist, and both sit
|
||||
above the head mesh.
|
||||
|
||||
---
|
||||
|
||||
## 3. Skeleton & Slot Convention
|
||||
|
||||
### 3.1 Canonical Skeleton
|
||||
|
||||
All avatars share a **canonical skeleton** with a fixed set of bone names. This
|
||||
is the contract that lets any attachment fit any body. The skeleton follows a
|
||||
humanoid convention (Godot's `Humanoid` profile / glTF VRM-style naming).
|
||||
|
||||
Required bones (subset of the full rig):
|
||||
|
||||
```
|
||||
Root
|
||||
├── Hips
|
||||
│ ├── Spine
|
||||
│ │ ├── Chest
|
||||
│ │ │ ├── Neck
|
||||
│ │ │ │ └── Head
|
||||
│ │ │ │ ├── HeadTop # hat / hair mount
|
||||
│ │ │ │ ├── Jaw # face accessories
|
||||
│ │ │ │ └── LeftEye / RightEye
|
||||
│ │ │ ├── LeftShoulder
|
||||
│ │ │ │ └── LeftUpperArm
|
||||
│ │ │ │ └── LeftLowerArm
|
||||
│ │ │ │ └── LeftHand
|
||||
│ │ │ └── RightShoulder
|
||||
│ │ │ └── RightUpperArm
|
||||
│ │ │ └── RightLowerArm
|
||||
│ │ │ └── RightHand
|
||||
│ │ └── (Chest children for torso attachments)
|
||||
│ ├── LeftUpperLeg
|
||||
│ │ └── LeftLowerLeg
|
||||
│ │ └── LeftFoot
|
||||
│ └── RightUpperLeg
|
||||
│ └── RightLowerLeg
|
||||
│ └── RightFoot
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
|
||||
- Bone names are **case-sensitive** and must match exactly.
|
||||
- The skeleton is **T-pose** at rest for consistent skinning.
|
||||
- Attachments must be skinned to **at least** the bones they deform; static
|
||||
accessories may be parented to a single bone (e.g., a hat parented to `Head`).
|
||||
|
||||
### 3.2 Attachment Slots
|
||||
|
||||
Slots are the **logical mount points** for body parts and attachments. Each slot
|
||||
maps to one or more bones and defines what can be equipped there.
|
||||
|
||||
| Slot ID | Category | Mount bone(s) | Exclusivity | Example assets |
|
||||
|----------------|--------------|--------------------|-------------|-------------------------------|
|
||||
| `head` | body part | `Head` | exclusive | alternate head, face |
|
||||
| `hair` | attachment | `HeadTop` | exclusive | hairstyles, hats |
|
||||
| `face` | attachment | `Jaw` | exclusive | glasses, masks, beards |
|
||||
| `torso` | body part | `Chest` | exclusive | alternate torso |
|
||||
| `chest` | attachment | `Chest` | exclusive | shirts, armor, chest gear |
|
||||
| `back` | attachment | `Chest` (back) | exclusive | backpacks, wings, capes |
|
||||
| `left_arm` | body part | `LeftUpperArm` | exclusive | alternate arm |
|
||||
| `right_arm` | body part | `RightUpperArm` | exclusive | alternate arm |
|
||||
| `left_hand` | attachment | `LeftHand` | exclusive | gloves, weapons (held) |
|
||||
| `right_hand` | attachment | `RightHand` | exclusive | gloves, weapons (held) |
|
||||
| `legs` | body part | `Hips` | exclusive | alternate legs |
|
||||
| `pants` | attachment | `Hips` | exclusive | pants, skirts |
|
||||
| `left_foot` | attachment | `LeftFoot` | exclusive | shoes |
|
||||
| `right_foot` | attachment | `RightFoot` | exclusive | shoes |
|
||||
| `accessory` | attachment | `Root` (free) | multiple | belts, jewelry, floating items|
|
||||
|
||||
**Slot semantics:**
|
||||
|
||||
- **`exclusive`** slots allow at most one equipped item at a time.
|
||||
- The **`accessory`** slot is *multi-slot* — multiple accessories may be equipped
|
||||
simultaneously (bounded by a configurable limit, e.g., 8).
|
||||
- **Body-part slots** (`head`, `torso`, `legs`, `left_arm`, `right_arm`) replace
|
||||
the corresponding base mesh. When a body part is equipped, the base mesh for
|
||||
that region is hidden.
|
||||
- **Attachment slots** layer on top of the base mesh and never hide it.
|
||||
|
||||
### 3.3 Slot → Bone Mapping
|
||||
|
||||
Each slot declares a **primary mount bone** and an optional **secondary bone
|
||||
list** for skinning. The runtime uses this to:
|
||||
|
||||
1. Parent static accessories to the mount bone.
|
||||
2. Skin skinned attachments to the union of the slot's bones.
|
||||
|
||||
---
|
||||
|
||||
## 4. glTF/GLB Format Requirements
|
||||
|
||||
All avatar assets (base bodies, body parts, attachments) are distributed as
|
||||
**glTF 2.0** (`.gltf` + external buffers/textures) or **GLB** (`.glb`, binary
|
||||
container). GLB is the preferred distribution format for runtime loading.
|
||||
|
||||
### 4.1 Required Conventions
|
||||
|
||||
| Concern | Requirement |
|
||||
|--------------------|------------------------------------------------------------------------------|
|
||||
| **Format** | glTF 2.0 (`.gltf` or `.glb`). GLB preferred for runtime. |
|
||||
| **Coordinate system** | glTF standard: **+Y up, +Z forward, right-handed**. Godot converts to its own convention on import. |
|
||||
| **Units** | Meters. Avatar height ~1.8 m at the `Root` bone. |
|
||||
| **Skeleton** | Single skeleton per asset; bone names per §3.1. |
|
||||
| **Skinning** | `skins` + `nodes` with `JOINTS_0` / `WEIGHTS_0` accessors. |
|
||||
| **Pose** | T-pose at rest. |
|
||||
| **Materials** | PBR metallic-roughness. Use `KHR_materials_unlit` for emissive/UI-only items. |
|
||||
| **Textures** | Max 2048×2048; power-of-two preferred. Use `KHR_texture_basisu` (BasisU) for runtime. |
|
||||
| **Animation** | Optional. If present, must not rename or remove canonical bones. |
|
||||
|
||||
### 4.2 Asset Metadata (extras)
|
||||
|
||||
Each asset **must** declare its slot and identity in the glTF `asset.extras`
|
||||
object. This is the machine-readable contract consumed by the build pipeline and
|
||||
runtime.
|
||||
|
||||
```json
|
||||
{
|
||||
"asset": {
|
||||
"version": "2.0",
|
||||
"extras": {
|
||||
"agp": {
|
||||
"type": "attachment", // "base_body" | "body_part" | "attachment"
|
||||
"slot": "chest", // slot ID from §3.2
|
||||
"id": "shirt_bandit_01", // globally unique asset id
|
||||
"display_name": "Bandit Shirt",
|
||||
"version": "1.0.0",
|
||||
"mount_bone": "Chest", // primary mount bone
|
||||
"skin_bones": ["Chest", "Spine", "LeftUpperArm", "RightUpperArm"],
|
||||
"exclusive": true, // matches slot exclusivity
|
||||
"tags": ["cloth", "common"],
|
||||
"author": "platform-team"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Validation rules for `extras.agp`:**
|
||||
|
||||
- `type` must be one of `base_body`, `body_part`, `attachment`.
|
||||
- `slot` must be a known slot ID (§3.2).
|
||||
- `mount_bone` must exist in the canonical skeleton.
|
||||
- `skin_bones` must all exist in the canonical skeleton.
|
||||
- `exclusive` must match the slot's declared exclusivity.
|
||||
- `id` must be unique across the asset catalog.
|
||||
|
||||
### 4.3 Node Naming Convention
|
||||
|
||||
To make assets self-describing and mergeable, nodes follow a convention:
|
||||
|
||||
- **Base body:** the mesh node is named `Body`; the skeleton root is `Root`.
|
||||
- **Body part:** the mesh node is named `<SlotID>_Mesh` (e.g., `head_Mesh`).
|
||||
- **Attachment:** the mesh node is named `<SlotID>_<AssetID>` (e.g.,
|
||||
`chest_shirt_bandit_01`).
|
||||
- **Attachment points** (empty nodes) on the base body are named
|
||||
`attach_<slot>` (e.g., `attach_head`, `attach_left_hand`).
|
||||
|
||||
### 4.4 Material & Texture Requirements
|
||||
|
||||
- All materials use the **metallic-roughness** PBR model.
|
||||
- Textures are embedded in the GLB or referenced as external files; external
|
||||
references must be relative paths within the asset package.
|
||||
- **Color customization** is supported via a `baseColorFactor` tint applied at
|
||||
runtime (multiplied over the albedo). Assets should use a neutral albedo
|
||||
(white/gray) where tinting is intended.
|
||||
- **Masked/transparent** materials must set the correct alpha mode
|
||||
(`MASK` or `BLEND`) and `alphaCutoff`.
|
||||
|
||||
### 4.5 Skeleton Merging at Runtime
|
||||
|
||||
When an attachment is loaded, the runtime **merges** it onto the base body:
|
||||
|
||||
1. Load the base body (skeleton + base meshes).
|
||||
2. Load each equipped attachment.
|
||||
3. For each attachment, **re-target its skin** to the base body's skeleton by
|
||||
bone name (no re-export needed).
|
||||
4. Parent static accessories to their `mount_bone`.
|
||||
5. Hide base meshes for any equipped body-part slots.
|
||||
6. Apply material tints and merge into the render tree.
|
||||
|
||||
The merge is **name-based** — bone names must match exactly (§3.1). This is the
|
||||
core reason for the strict naming contract.
|
||||
|
||||
---
|
||||
|
||||
## 5. Loadout Model (Network & Persistence)
|
||||
|
||||
The avatar's composition is serialized as a **loadout** — a compact, ordered
|
||||
list of equipped asset IDs. This is what the server validates, persists, and
|
||||
replicates.
|
||||
|
||||
### 5.1 Loadout JSON
|
||||
|
||||
```json
|
||||
{
|
||||
"base_body": "base_human_male_01",
|
||||
"slots": {
|
||||
"head": "head_cyber_01",
|
||||
"hair": "hair_mohawk_01",
|
||||
"face": null,
|
||||
"torso": null,
|
||||
"chest": "chest_bandit_01",
|
||||
"back": "backpack_01",
|
||||
"left_arm": null,
|
||||
"right_arm": null,
|
||||
"left_hand": "glove_leather_01",
|
||||
"right_hand": "glove_leather_01",
|
||||
"legs": null,
|
||||
"pants": "pants_cargo_01",
|
||||
"left_foot": "shoe_boot_01",
|
||||
"right_foot": "shoe_boot_01",
|
||||
"accessory": ["belt_01", "necklace_01"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
|
||||
- `base_body` is required and must reference a valid `base_body` asset.
|
||||
- Each exclusive slot holds **at most one** asset id (or `null`).
|
||||
- `accessory` is an array (0..N, bounded).
|
||||
- The server validates that every id exists in the catalog and that slot
|
||||
exclusivity is respected.
|
||||
|
||||
### 5.2 Network Replication
|
||||
|
||||
The loadout is replicated as part of the player's spawn/state data:
|
||||
|
||||
```
|
||||
spawn_entity:
|
||||
entity_id: uint32
|
||||
type: player
|
||||
transform: { x, y, rot }
|
||||
props:
|
||||
loadout_hash: uint32 # hash of the loadout for change detection
|
||||
loadout: { ... } # full loadout on spawn / on change
|
||||
```
|
||||
|
||||
- The **full loadout** is sent on spawn and whenever it changes (reliable).
|
||||
- A **`loadout_hash`** lets clients skip re-resolving assets if unchanged.
|
||||
- The server is the **authority** on the loadout; clients send *requests* to
|
||||
change equipment, and the server validates and broadcasts the result.
|
||||
|
||||
### 5.3 Server-Side Validation
|
||||
|
||||
The server rejects a loadout if:
|
||||
|
||||
- `base_body` is missing or unknown.
|
||||
- Any slot references an unknown asset id.
|
||||
- An exclusive slot has more than one item.
|
||||
- An asset's declared `slot` does not match the slot it is placed in.
|
||||
- The accessory list exceeds the configured limit.
|
||||
- The asset is not owned/unlocked by the player (for gated cosmetics).
|
||||
|
||||
---
|
||||
|
||||
## 6. Godot Runtime Architecture
|
||||
|
||||
### 6.1 Node Structure
|
||||
|
||||
```
|
||||
Avatar (Node3D)
|
||||
├── Skeleton3D # canonical skeleton (from base body)
|
||||
├── BodyMeshes # base body meshes (skinned to Skeleton3D)
|
||||
│ ├── head_Mesh
|
||||
│ ├── torso_Mesh
|
||||
│ └── ...
|
||||
├── Attachments # equipped attachments
|
||||
│ ├── chest_shirt_bandit_01
|
||||
│ ├── hair_mohawk_01
|
||||
│ └── ...
|
||||
└── AttachmentPoints # empty nodes for dynamic mounting
|
||||
├── attach_head
|
||||
├── attach_left_hand
|
||||
└── ...
|
||||
```
|
||||
|
||||
### 6.2 Core Classes
|
||||
|
||||
| Class | Responsibility |
|
||||
|--------------------------|-------------------------------------------------------------|
|
||||
| `AvatarSystem` | Loads base body + attachments, resolves loadouts, owns the avatar node. |
|
||||
| `AvatarLoader` | glTF/GLB import, skeleton merge, skin re-targeting. |
|
||||
| `AvatarSlotRegistry` | Static registry of slot definitions (id, bones, exclusivity).|
|
||||
| `AvatarLoadout` | Serializable loadout model + validation. |
|
||||
| `AvatarCatalog` | Asset catalog (id → asset metadata + resource path). |
|
||||
| `AvatarVisualizer` | Builds the render tree from a loadout. |
|
||||
|
||||
### 6.3 Loading Pipeline
|
||||
|
||||
```
|
||||
loadout JSON
|
||||
│
|
||||
▼
|
||||
AvatarCatalog.resolve(loadout) # id → asset metadata + GLB path
|
||||
│
|
||||
▼
|
||||
AvatarLoader.load_base_body() # import GLB, extract skeleton + base meshes
|
||||
│
|
||||
▼
|
||||
for each equipped slot:
|
||||
AvatarLoader.load_attachment()# import GLB, re-target skin to skeleton
|
||||
│
|
||||
▼
|
||||
AvatarVisualizer.assemble() # parent, hide replaced parts, apply tints
|
||||
│
|
||||
▼
|
||||
Avatar node ready for render
|
||||
```
|
||||
|
||||
### 6.4 Performance Considerations
|
||||
|
||||
- **Shared skeleton:** All meshes skin to one `Skeleton3D`, so skinning is
|
||||
computed once per frame.
|
||||
- **Material batching:** Attachments that share a material are merged into a
|
||||
single mesh where possible (static accessories).
|
||||
- **LOD:** Optional LOD variants per asset; the runtime selects based on
|
||||
distance.
|
||||
- **Caching:** Resolved loadouts and imported GLB resources are cached by
|
||||
`AvatarCatalog` to avoid re-importing on respawn or re-join.
|
||||
|
||||
---
|
||||
|
||||
## 7. Asset Pipeline & Validation
|
||||
|
||||
### 7.1 Build-Time Validation
|
||||
|
||||
A build-time checker validates every asset before it enters the catalog:
|
||||
|
||||
1. **Format check:** valid glTF 2.0 / GLB.
|
||||
2. **Metadata check:** `extras.agp` present and valid (§4.2).
|
||||
3. **Skeleton check:** all `skin_bones` exist in the canonical skeleton.
|
||||
4. **Slot check:** `slot` is known and `exclusive` matches.
|
||||
5. **Mesh check:** meshes are skinned (or static accessories parented to a bone).
|
||||
6. **Texture check:** sizes, formats, and alpha modes are valid.
|
||||
7. **Uniqueness check:** `id` is unique.
|
||||
|
||||
### 7.2 Catalog Manifest
|
||||
|
||||
The catalog is a JSON manifest mapping asset ids to metadata and resource paths:
|
||||
|
||||
```json
|
||||
{
|
||||
"assets": {
|
||||
"base_human_male_01": {
|
||||
"type": "base_body",
|
||||
"path": "res://assets/avatars/base_human_male_01.glb",
|
||||
"version": "1.0.0"
|
||||
},
|
||||
"chest_bandit_01": {
|
||||
"type": "attachment",
|
||||
"slot": "chest",
|
||||
"path": "res://assets/avatars/chest_bandit_01.glb",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Security & Anti-Cheat
|
||||
|
||||
- **Server-authoritative loadouts:** Clients only *request* equipment changes;
|
||||
the server validates against the catalog and the player's owned items.
|
||||
- **No client asset injection:** Clients cannot send arbitrary GLB data; they
|
||||
reference catalog ids only.
|
||||
- **Rate limiting:** Equipment-change requests are rate-limited per peer.
|
||||
- **Hash verification:** The `loadout_hash` lets the server detect tampered or
|
||||
stale loadout state.
|
||||
|
||||
---
|
||||
|
||||
## 9. Open Questions / Future Work
|
||||
|
||||
- **Morph targets / blendshapes:** Support for facial expressions and body
|
||||
morphs (e.g., height, muscle) via glTF morph targets.
|
||||
- **Physics attachments:** Cloth simulation for capes/skirts (Godot cloth).
|
||||
- **Dynamic tinting UI:** A color-picker that writes `baseColorFactor` tints.
|
||||
- **VRM compatibility:** Consider supporting VRM (a glTF extension for
|
||||
humanoid avatars) as an import source.
|
||||
- **Attachment LOD streaming:** Streaming high-res attachments on demand.
|
||||
|
||||
---
|
||||
|
||||
## 10. Summary
|
||||
|
||||
| Concern | Decision |
|
||||
|------------------------|-------------------------------------------------------|
|
||||
| Format | glTF 2.0 / GLB (GLB preferred for runtime) |
|
||||
| Skeleton | Single canonical humanoid skeleton, name-based merge |
|
||||
| Slots | Fixed slot registry; exclusive body parts + layered attachments |
|
||||
| Loadout | Compact JSON; server-authoritative and validated |
|
||||
| Replication | Full loadout on spawn/change + `loadout_hash` |
|
||||
| Runtime | Godot `Skeleton3D` + name-based skin re-targeting |
|
||||
| Validation | Build-time asset checker + runtime catalog validation |
|
||||
@@ -0,0 +1,426 @@
|
||||
# Content Moderation & Age Verification Architecture
|
||||
|
||||
> **Status:** Proposed
|
||||
> **Owner:** Platform team
|
||||
> **Related:** Server authority + client prediction, avatar component system, backend auth (JWT)
|
||||
|
||||
## 1. Overview
|
||||
|
||||
This document specifies the **content moderation** and **age verification**
|
||||
architecture for **agp-game**, a Godot-based multiplayer game built by
|
||||
autonomous agents. It defines:
|
||||
|
||||
- How **content flags** propagate through the system across the three primary
|
||||
content types: **assets**, **rooms**, and **scripts**.
|
||||
- How flags are **evaluated, aggregated, and enforced** at load time, at
|
||||
runtime, and at the network boundary.
|
||||
- The **age verification flow**, combining a lightweight **self-declaration**
|
||||
with an optional **ID check hook** for higher-assurance verification.
|
||||
|
||||
The goal is a **single, consistent moderation pipeline** that applies the same
|
||||
rules to user-generated content (UGC) regardless of whether it is a 3D asset, a
|
||||
room definition, or a script, and that gates access to mature content behind a
|
||||
verifiable age gate.
|
||||
|
||||
### 1.1 Design Goals
|
||||
|
||||
- **Uniformity:** One flag vocabulary and one propagation mechanism across
|
||||
assets, rooms, and scripts.
|
||||
- **Composability:** Flags on a room aggregate the flags of the assets and
|
||||
scripts it contains; flags on a world aggregate the flags of its rooms.
|
||||
- **Enforcement at the boundary:** The server is authoritative for what content
|
||||
a client may load or receive, mirroring the server-authoritative networking
|
||||
model.
|
||||
- **Privacy-preserving age checks:** Self-declaration requires no PII; the ID
|
||||
check hook is optional, pluggable, and never stores raw identity documents.
|
||||
- **Auditability:** Every flag decision is logged with a reason, an actor, and
|
||||
a timestamp so moderation actions are reviewable.
|
||||
|
||||
---
|
||||
|
||||
## 2. Content Flag Vocabulary
|
||||
|
||||
All content carries a set of **content flags**. A flag is a typed, immutable
|
||||
label with a **severity** and a **scope**. Flags are the atomic unit of
|
||||
moderation; everything else (aggregation, enforcement, gating) operates on
|
||||
flags.
|
||||
|
||||
### 2.1 Flag Definition
|
||||
|
||||
A flag is a structured record:
|
||||
|
||||
| Field | Type | Description |
|
||||
|------------|-----------|--------------------------------------------------------------------------|
|
||||
| `id` | `string` | Stable machine-readable identifier, e.g. `violence.gore`. |
|
||||
| `label` | `string` | Human-readable name, e.g. "Graphic Gore". |
|
||||
| `category` | `enum` | One of `violence`, `sexual`, `language`, `substance`, `gambling`, `horror`, `hate`, `custom`. |
|
||||
| `severity` | `enum` | One of `none`, `mild`, `moderate`, `severe`. |
|
||||
| `scope` | `enum` | One of `visual`, `audio`, `text`, `behavior`, `interaction`. |
|
||||
| `mature` | `bool` | Whether this flag triggers the age gate (see §5). |
|
||||
| `reason` | `string` | Free-text justification supplied by the flagger. |
|
||||
| `source` | `enum` | One of `author`, `moderator`, `automated`, `community`. |
|
||||
|
||||
### 2.2 Canonical Flag Set
|
||||
|
||||
The platform defines a **canonical registry** of flags so that different
|
||||
content types and different flaggers use the same vocabulary. Examples:
|
||||
|
||||
| id | category | severity | scope | mature |
|
||||
|-----------------------------|------------|-----------|--------------|--------|
|
||||
| `violence.none` | violence | none | visual | false |
|
||||
| `violence.mild` | violence | mild | visual | false |
|
||||
| `violence.gore` | violence | severe | visual | true |
|
||||
| `sexual.suggestive` | sexual | mild | visual | true |
|
||||
| `sexual.explicit` | sexual | severe | visual | true |
|
||||
| `language.mild` | language | mild | text | false |
|
||||
| `language.profanity` | language | moderate | text | false |
|
||||
| `substance.references` | substance | mild | text | false |
|
||||
| `gambling.simulated` | gambling | moderate | behavior | true |
|
||||
| `horror.jumpscare` | horror | mild | audio/visual | false |
|
||||
| `hate.hateful` | hate | severe | text | true |
|
||||
|
||||
The registry is **data-driven** (a JSON/YAML manifest shipped with the server)
|
||||
so new flags can be added without code changes.
|
||||
|
||||
---
|
||||
|
||||
## 3. Flag Propagation Model
|
||||
|
||||
Flags propagate through the system along the **content dependency graph**. The
|
||||
three content types form a hierarchy:
|
||||
|
||||
```
|
||||
World
|
||||
└── Room
|
||||
├── Asset (mesh, texture, audio, animation, material)
|
||||
└── Script (behavior, dialogue, event logic)
|
||||
```
|
||||
|
||||
### 3.1 Propagation Rules
|
||||
|
||||
1. **Explicit flags** are set directly on a content item by its author or a
|
||||
moderator.
|
||||
2. **Inherited flags** flow upward: a room's effective flag set is the **union**
|
||||
of its own explicit flags and the flags of every asset and script it
|
||||
references.
|
||||
3. **Aggregation** uses the **maximum severity** per category across all
|
||||
contributing items. A room containing one `violence.gore` asset and one
|
||||
`violence.none` asset is `violence.severe`.
|
||||
4. **Maturity is monotonic:** if any contributing item is `mature`, the
|
||||
containing room and world are `mature`.
|
||||
5. **Cycles are impossible** by construction: content references form a DAG
|
||||
(an asset cannot contain a room; a room cannot contain itself).
|
||||
|
||||
### 3.2 Propagation Through the Pipeline
|
||||
|
||||
Flags are attached at **authoring time** and carried through every stage:
|
||||
|
||||
```
|
||||
Authoring ──► Upload ──► Validation ──► Storage ──► Distribution ──► Runtime
|
||||
│ │ │ │ │ │
|
||||
│ flag │ flag │ automated │ flag │ flag │ flag
|
||||
│ declared │ preserved │ scan adds │ indexed │ re-checked │ enforced
|
||||
│ │ │ flags │ │ │
|
||||
```
|
||||
|
||||
| Stage | Responsibility |
|
||||
|--------------|-------------------------------------------------------------------------|
|
||||
| **Authoring**| Author declares flags in the editor/upload UI. |
|
||||
| **Upload** | Flags are validated against the canonical registry; unknown flags rejected. |
|
||||
| **Validation**| Automated scanner (hash-based + heuristic) adds flags for detected content. |
|
||||
| **Storage** | Flags are stored alongside the content record and indexed for queries. |
|
||||
| **Distribution**| Flags are re-checked against the current registry before serving. |
|
||||
| **Runtime** | The client enforces flags before loading content (see §4). |
|
||||
|
||||
### 3.3 Data Model
|
||||
|
||||
Flags are stored as a **normalized join table** so they can be queried and
|
||||
aggregated efficiently:
|
||||
|
||||
```
|
||||
content_item (id, type, owner_id, ...)
|
||||
content_flag (content_id, flag_id, source, reason, created_at, actor_id)
|
||||
flag_registry (id, category, severity, scope, mature, ...)
|
||||
```
|
||||
|
||||
Aggregation is computed by a SQL view / query that joins a content item's
|
||||
transitive dependencies. Because the graph is a DAG, this is a bounded
|
||||
recursive query (PostgreSQL `WITH RECURSIVE`).
|
||||
|
||||
---
|
||||
|
||||
## 4. Enforcement
|
||||
|
||||
Enforcement happens at three layers, in order:
|
||||
|
||||
### 4.1 Load-Time Enforcement (Server)
|
||||
|
||||
Before a client is allowed to **request** content, the server evaluates the
|
||||
content's effective flag set against the requesting account's **content
|
||||
preferences** and **age verification status**:
|
||||
|
||||
- If the content is `mature` and the account is **not age-verified**, the
|
||||
request is **rejected** with a `403 MATURE_CONTENT_REQUIRES_VERIFICATION`.
|
||||
- If the content's flags exceed the account's **content filter** (a per-account
|
||||
severity threshold per category), the request is rejected or the offending
|
||||
content is **stripped** (e.g., audio muted, mesh hidden, script not loaded).
|
||||
|
||||
### 4.2 Runtime Enforcement (Client)
|
||||
|
||||
The client receives a **manifest** of allowed content from the server. It never
|
||||
loads content that is not in the manifest. This prevents a malicious or buggy
|
||||
client from bypassing the server's filter by loading content directly.
|
||||
|
||||
- Assets not in the manifest are **not instantiated**.
|
||||
- Scripts not in the manifest are **not executed**.
|
||||
- Rooms not in the manifest are **not entered**.
|
||||
|
||||
### 4.3 Network Boundary Enforcement
|
||||
|
||||
The server **filters replication** based on flags:
|
||||
|
||||
- Mature or filtered content is **not replicated** to clients that cannot
|
||||
receive it.
|
||||
- A room's flag set is broadcast in the room metadata so clients can show a
|
||||
warning before entry.
|
||||
|
||||
### 4.4 Enforcement Decision Flow
|
||||
|
||||
```
|
||||
Client requests content C for account A
|
||||
│
|
||||
▼
|
||||
Compute effective flags F(C) [union + max-severity aggregation]
|
||||
│
|
||||
▼
|
||||
Is A age-verified? ──no──► Is F(C).mature? ──yes──► REJECT (403)
|
||||
│ yes │ no
|
||||
▼ ▼
|
||||
Does F(C) exceed A's filter? ──► yes ──► REJECT or STRIP
|
||||
│ no
|
||||
▼
|
||||
Serve content + manifest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Age Verification Flow
|
||||
|
||||
Age verification is a **two-tier** system:
|
||||
|
||||
- **Tier 1 — Self-declaration:** The user asserts their date of birth. This is
|
||||
fast, requires no PII beyond a birthdate, and is sufficient for most content.
|
||||
- **Tier 2 — ID check (optional hook):** A pluggable identity-verification
|
||||
provider confirms the user is an adult. This raises the account's assurance
|
||||
level and unlocks the highest maturity tier.
|
||||
|
||||
### 5.1 Verification States
|
||||
|
||||
An account has an **age verification status**:
|
||||
|
||||
| Status | Meaning |
|
||||
|-------------------|----------------------------------------------------------------------|
|
||||
| `unverified` | No declaration on file. |
|
||||
| `self_declared` | User declared a birthdate; **not** independently confirmed. |
|
||||
| `id_verified` | User passed the ID check hook; independently confirmed adult. |
|
||||
| `rejected` | ID check failed or declaration was inconsistent. |
|
||||
|
||||
### 5.2 Tier 1 — Self-Declaration Flow
|
||||
|
||||
```
|
||||
User submits { date_of_birth }
|
||||
│
|
||||
▼
|
||||
Server validates format & plausibility (age 13–120, not in future)
|
||||
│
|
||||
▼
|
||||
Compute age from DOB
|
||||
│
|
||||
▼
|
||||
age >= 18 ──► status = self_declared (adult)
|
||||
age >= 13 ──► status = self_declared (minor, restricted)
|
||||
age < 13 ──► status = rejected (below minimum platform age)
|
||||
```
|
||||
|
||||
- The DOB is stored **encrypted at rest** and is **never exposed** to other
|
||||
players.
|
||||
- A user may **upgrade** from `self_declared` to `id_verified` at any time via
|
||||
Tier 2.
|
||||
|
||||
### 5.3 Tier 2 — ID Check Hook
|
||||
|
||||
The ID check is an **optional, pluggable hook**. The platform defines an
|
||||
interface; concrete providers (e.g., a third-party KYC service) implement it.
|
||||
|
||||
```
|
||||
User requests ID verification
|
||||
│
|
||||
▼
|
||||
Server creates a verification session (idempotent, expiring)
|
||||
│
|
||||
▼
|
||||
Server calls provider hook: verify(identity_token) -> { adult: bool, ref: string }
|
||||
│
|
||||
▼
|
||||
adult == true ──► status = id_verified, store provider ref (not raw doc)
|
||||
adult == false ─► status = rejected
|
||||
provider error ──► status unchanged, retry allowed
|
||||
```
|
||||
|
||||
**Privacy guarantees:**
|
||||
|
||||
- The platform **never stores** the raw identity document or image.
|
||||
- Only the provider's **opaque reference** and the boolean `adult` result are
|
||||
persisted.
|
||||
- The hook is **asynchronous and idempotent**; a session can be retried without
|
||||
double-charging or double-verifying.
|
||||
|
||||
### 5.4 Hook Interface
|
||||
|
||||
The ID check hook is defined as a backend interface (FastAPI dependency /
|
||||
abstract service):
|
||||
|
||||
```python
|
||||
class IdentityVerificationProvider(Protocol):
|
||||
def create_session(self, user_id: str) -> VerificationSession: ...
|
||||
def verify(self, session_id: str, identity_token: str) -> VerificationResult: ...
|
||||
|
||||
class VerificationResult:
|
||||
adult: bool
|
||||
provider_ref: str | None
|
||||
error: str | None
|
||||
```
|
||||
|
||||
A default **no-op provider** returns `adult=False` with a clear error, so the
|
||||
system runs without any third-party integration until one is configured.
|
||||
|
||||
### 5.5 Age Gate Enforcement
|
||||
|
||||
The age gate is enforced at **load time** (see §4.1):
|
||||
|
||||
| Verification status | Can access `mature` content? |
|
||||
|---------------------|------------------------------|
|
||||
| `unverified` | No |
|
||||
| `self_declared` | Yes (adult) / No (minor) |
|
||||
| `id_verified` | Yes |
|
||||
| `rejected` | No |
|
||||
|
||||
---
|
||||
|
||||
## 6. Moderation Workflow
|
||||
|
||||
### 6.1 Flagging Sources
|
||||
|
||||
Content can be flagged by:
|
||||
|
||||
- **Author** (self-declared at upload).
|
||||
- **Automated scanner** (hash-based detection, heuristic analysis).
|
||||
- **Community** (players report content; reports become flags after review).
|
||||
- **Moderator** (manual review and override).
|
||||
|
||||
### 6.2 Review Queue
|
||||
|
||||
Community and automated flags enter a **review queue**. A moderator either:
|
||||
|
||||
- **Approves** the flag (it becomes authoritative), or
|
||||
- **Rejects** the flag (it is discarded), or
|
||||
- **Escalates** to a senior moderator for severe/hate flags.
|
||||
|
||||
### 6.3 Actions
|
||||
|
||||
Once a flag is authoritative, a moderator can take actions:
|
||||
|
||||
| Action | Effect |
|
||||
|-----------------|---------------------------------------------------------------|
|
||||
| `warn` | Notify the author; content remains. |
|
||||
| `restrict` | Content hidden from users below a filter threshold. |
|
||||
| `age_gate` | Content marked `mature`; requires age verification. |
|
||||
| `remove` | Content taken down; not served. |
|
||||
| `ban_author` | Author's upload privileges suspended. |
|
||||
|
||||
### 6.4 Audit Log
|
||||
|
||||
Every flag and action is written to an **audit log**:
|
||||
|
||||
```
|
||||
audit_event (id, content_id, actor_id, action, flag_id, reason, created_at)
|
||||
```
|
||||
|
||||
This log is append-only and used for transparency and dispute resolution.
|
||||
|
||||
---
|
||||
|
||||
## 7. Client-Side Integration (Godot)
|
||||
|
||||
### 7.1 Content Manifest
|
||||
|
||||
The server sends each client a **content manifest** — the set of content the
|
||||
client is permitted to load, derived from the account's verification status and
|
||||
filter. The Godot client:
|
||||
|
||||
- Loads only manifest-listed assets.
|
||||
- Executes only manifest-listed scripts.
|
||||
- Shows a **maturity warning** dialog before entering a room whose effective
|
||||
flags include `mature` content.
|
||||
|
||||
### 7.2 Flag Metadata on Content
|
||||
|
||||
Each content resource carries a `content_flags` metadata field (a Godot
|
||||
`Dictionary` or custom `Resource`). The client uses this for local UI decisions
|
||||
(e.g., showing a warning icon) but **never** as the authority for whether to
|
||||
load — the server manifest is authoritative.
|
||||
|
||||
### 7.3 Age Verification UI
|
||||
|
||||
The client exposes an **age verification screen**:
|
||||
|
||||
- Tier 1: a date-of-birth picker.
|
||||
- Tier 2: a button that opens the ID check provider flow (deep link / webview).
|
||||
|
||||
The client calls the backend endpoints (§8) and reflects the resulting status.
|
||||
|
||||
---
|
||||
|
||||
## 8. Backend API Surface
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|-----------------------------------|------------------------------------------------|
|
||||
| `POST` | `/v1/age/declare` | Submit self-declared DOB (Tier 1). |
|
||||
| `POST` | `/v1/age/verify/session` | Create an ID-check session (Tier 2). |
|
||||
| `POST` | `/v1/age/verify/confirm` | Confirm an ID-check session with a token. |
|
||||
| `GET` | `/v1/age/status` | Return the account's verification status. |
|
||||
| `GET` | `/v1/content/{id}/flags` | Return a content item's effective flags. |
|
||||
| `POST` | `/v1/content/{id}/flags` | Add a flag (author/community). |
|
||||
| `POST` | `/v1/moderation/review/{flag_id}` | Moderator approve/reject/escalate. |
|
||||
| `POST` | `/v1/moderation/action` | Apply a moderation action. |
|
||||
| `GET` | `/v1/manifest` | Return the client's permitted content manifest.|
|
||||
|
||||
All endpoints require a valid **JWT** (matching the existing auth stack). The
|
||||
age endpoints additionally require the account to be in a non-`rejected` state.
|
||||
|
||||
---
|
||||
|
||||
## 9. Security & Privacy Considerations
|
||||
|
||||
- **DOB encryption:** Self-declared birthdates are encrypted at rest; only the
|
||||
derived age and verification status are used in authorization decisions.
|
||||
- **No raw identity storage:** The ID check hook persists only a provider
|
||||
reference and a boolean result.
|
||||
- **Server authority:** The client manifest prevents bypass; the client never
|
||||
trusts its own flag metadata for access decisions.
|
||||
- **Rate limiting:** Age-declaration and ID-check endpoints are rate-limited to
|
||||
prevent abuse and enumeration.
|
||||
- **Auditability:** All flag and verification events are logged append-only.
|
||||
|
||||
---
|
||||
|
||||
## 10. Open Questions / Future Work
|
||||
|
||||
- **Regional age thresholds:** Different jurisdictions may require different
|
||||
minimum ages; the threshold should be configurable per region.
|
||||
- **Parental controls:** A future feature may let a parent set a content filter
|
||||
on a minor's account.
|
||||
- **Automated scanner accuracy:** The heuristic scanner may produce false
|
||||
positives; a confidence score should be attached to automated flags.
|
||||
- **Offline / local content:** How flags apply to locally-authored content that
|
||||
is never uploaded remains to be defined.
|
||||
Reference in New Issue
Block a user