modbison/docs/planning/creator_studio.md

Creator Studio — Extended Authoring Tools

Feature: Creator Studio — Extended Authoring Tools Status: Planning Owner: Platform team

Feature Overview

Extends the in-game world editor (M6) toward a real authoring tool with:

1. Asset import pipeline (glTF models/textures)
2. Script editor with sandboxed API surface exposed clearly
3. Experience publishing flow (draft → review → live)
4. Basic analytics for creators (plays, session length)

User Stories

US-1: Asset Import Pipeline

As a creator, I can import glTF models and textures into my experience so that I can use custom 3D assets.

US-2: Script Editor with Sandboxed API

As a creator, I can write and test scripts in the editor with autocomplete/docs for the available API surface.

US-3: Experience Publishing Flow

As a creator, I can publish my experience through a draft → review → live pipeline so that players can discover and play it.

US-4: Creator Analytics

As a creator, I can see how many plays and average session length my experiences receive so that I can understand player engagement.

---

Task Breakdown

US-1: Asset Import Pipeline

T1.1: Backend — glTF Asset Upload with Metadata Extraction

• Type: implementation
• Files: backend/app/routers/assets.py (extend upload endpoint), backend/app/models/asset.py (add glTF-specific metadata fields)
• Scope: Extend the existing upload_asset_file endpoint in assets.py to detect .glb/.gltf files and extract glTF metadata (mesh_count, vertex_count, has_animation, texture_refs, bounding_box) from the embedded JSON. Store extracted metadata in metadata_json. Add a has_gltf_metadata computed property. The Asset model already has asset_type = MODEL_3D and metadata_json — this task adds the extraction logic.
• Acceptance: POST /api/assets/{id}/upload with a .glb file returns asset with metadata_json containing mesh_count, vertex_count, has_animation, texture_refs. GET lists include these fields. File stored on disk. Non-glTF files are unaffected.
• Dependencies: None (builds on existing asset infrastructure)

T1.2: Backend — Public Asset Catalog Endpoint

• Type: implementation
• Files: backend/app/routers/assets.py (new endpoint)
• Scope: Add GET /api/assets/catalog endpoint that returns all public glTF assets with their metadata (name, thumbnail_url, mesh_count, vertex_count, tags). Add filtering by tags and pagination. This is what the editor's asset palette queries. Uses the existing Asset.is_public field.
• Acceptance: Catalog endpoint returns paginated list of public assets; filtering by tag works; pagination params respected; returns 401 without auth.
• Dependencies: T1.1

T1.3: Godot — glTF Import Utility (Editor-Side)

• Type: implementation
• Files: scripts/gltf_importer.gd (new), scripts/asset_catalog.gd (new)
• Scope: Godot-side utility that connects to the catalog API, downloads glTF files, and converts them to Godot-compatible resources (.res files with embedded mesh data). Provides import_gltf(url: String) -> Resource function. Handles texture extraction and mesh merging. Uses the ApiClient autoload (from client-server-wiring plan) for HTTP.
• Acceptance: import_gltf() downloads a glTF from the catalog, converts mesh to Mesh resource, returns a ready-to-use Godot resource. Texture files stored in user://assets/.
• Dependencies: T1.2, client-server-wiring ApiClient (task 1 from that plan)

US-2: Script Editor with Sandboxed API

Design note from scripting_sandbox.md: Godot 4 has no built-in GDScript sandbox. The recommended approach is a data-driven DSL (JSON/Resource) interpreted by trusted GDScript, not arbitrary code execution. This task follows that recommendation.

T2.1: Backend — Script Model & CRUD Endpoints

• Type: architecture
• Files: backend/app/models/script.py (new), backend/app/routers/scripts.py (new), backend/app/main.py (register router), backend/app/models/__init__.py (export)
• Scope: Create Script model (id, name, world_id, owner_id, source_code TEXT, version INT, script_type ENUM[gdscript, dsl], dsl_payload JSON, created_at, updated_at). Add full CRUD endpoints: POST /api/scripts/ (create), GET /api/scripts/ (list), GET /api/scripts/{id} (get), PUT /api/scripts/{id} (update), DELETE /api/scripts/{id} (delete). Scripts are owned by users and associated with a world. dsl_payload stores the JSON/Resource data for the DSL approach; source_code stores raw GDScript if used.
• Acceptance: All CRUD endpoints work; scripts are owned by creator; list endpoint filters by owner/world; update increments version; DSL and gdscript types supported.
• Dependencies: None (new model + router)

T2.2: Godot — Script API Surface Definition

• Type: architecture
• Files: scripts/editor_script_api.gd (new)
• Scope: Define the public API surface available to creator scripts. This is a RefCounted class that wraps the Godot engine's capabilities into a safe, documented interface. Includes: WorldAPI (get_tile, get_object, set_property), PlayerAPI (get_position, get_health), AudioAPI (play_sound, play_music), NetworkAPI (send_event, broadcast). Each method has documented parameters and return types. Self-documenting via ## doc comments for autocomplete.
• Acceptance: EditorScriptAPI class exposes all documented methods; methods are callable from user scripts; API surface is self-documenting.
• Dependencies: None (standalone definition)

T2.3: Godot — In-Game Script Editor UI

• Type: implementation
• Files: scenes/editor_script_editor.tscn (new), scripts/editor_script_editor.gd (new)
• Scope: A Control-based UI panel that provides a script editor within the game. Features: code editor with syntax highlighting (basic), autocomplete dropdown, run button (calls backend /run endpoint), output console (shows stdout/stderr), API reference panel (shows available methods). Integrates with the existing editor toolbar.
• Acceptance: Editor panel opens from toolbar; code editor accepts input; autocomplete shows API methods; run button executes script and shows output; API reference panel is browsable.
• Dependencies: T2.1, T2.2

US-3: Experience Publishing Flow

T3.1: Backend — Experience Model & Status Transitions

• Type: architecture
• Files: backend/app/models/experience.py (new), backend/app/routers/experiences.py (new), backend/app/main.py (register router), backend/app/models/__init__.py (export)
• Scope: Create Experience model (id, world_id FK→worlds, title, description, status ENUM[DRAFT,SUBMITTED,IN_REVIEW,APPROVED,REJECTED,LIVE], published_at, review_notes, reviewer_id FK→users). Status transitions enforced: DRAFT→SUBMITTED→IN_REVIEW→APPROVED→LIVE; REJECTED→DRAFT (resubmit). Add endpoints: POST /api/experiences/ (create draft), POST /api/experiences/{id}/submit (submit for review), POST /api/experiences/{id}/approve (approve), POST /api/experiences/{id}/reject (reject), GET /api/experiences/ (list with status filter). An experience is a publishing wrapper around a World — the world's visibility is set to PUBLIC when experience goes LIVE.
• Acceptance: All CRUD + transition endpoints work; status transitions enforced; rejected can be resubmitted; list filters by status; approve sets world visibility to PUBLIC; only world owner can submit; only moderators can approve/reject.
• Dependencies: None (new model + router)

T3.2: Backend — Review Queue & Moderation Integration

• Type: implementation
• Files: backend/app/routers/experiences.py (add endpoints)
• Scope: Add review queue endpoint GET /api/experiences/review-queue (returns experiences in IN_REVIEW status). Add POST /api/experiences/{id}/review endpoint for moderators to add review notes and change status. Integrates with content moderation: when an experience is submitted, its world's content flags are computed and attached to the review.
• Acceptance: Review queue returns IN_REVIEW experiences; review endpoint accepts notes and status change; content flags attached on submit; only moderators can review.
• Dependencies: T3.1

T3.3: Godot — Publishing UI Panel

• Type: implementation
• Files: scenes/editor_publish_panel.tscn (new), scripts/editor_publish_panel.gd (new)
• Scope: A Control-based panel in the editor that lets creators manage their experience's publishing state. Features: title/description editor, status badge (DRAFT/SUBMITTED/LIVE), submit button, review notes display, publish history timeline. Integrates with the existing editor toolbar.
• Acceptance: Panel shows current status; submit button calls backend; review notes displayed; publish history shown; status badge updates on refresh.
• Dependencies: T3.1, T3.2

T3.4: Godot — Experience List & Discovery

• Type: implementation
• Files: scenes/experience_list.tscn (new), scripts/experience_list.gd (new)
• Scope: A UI panel that lists all experiences available to the player (LIVE status). Features: search/filter, experience cards (title, description, creator, play count), join button. Queries GET /api/experiences/?status=LIVE and displays results.
• Acceptance: Lists LIVE experiences; search filters by title/description; cards show metadata; join button loads the experience's world.
• Dependencies: T3.1

US-4: Creator Analytics

T4.1: Backend — Session & Play Tracking Models

• Type: architecture
• Files: backend/app/models/analytics.py (new), backend/app/routers/analytics.py (new), backend/app/main.py (register router), backend/app/models/__init__.py (export)
• Scope: Create PlaySession model (id, experience_id FK→experiences, player_id FK→users, started_at, ended_at, duration_seconds, chunk_loads INT, interactions_count INT). Create PlayEvent model (id, experience_id FK→experiences, player_id FK→users, event_type, payload JSON, created_at). Add endpoints: POST /api/analytics/session/start (start session), POST /api/analytics/session/end (end session), POST /api/analytics/event (log event). Note: sessions table is taken by auth tokens; this uses play_sessions table name.
• Acceptance: Session start/end endpoints work; events logged; duration calculated correctly; endpoints accept valid experience/player IDs.
• Dependencies: None (new models + routers)

T4.2: Backend — Creator Dashboard Analytics Endpoint

• Type: implementation
• Files: backend/app/routers/analytics.py (add endpoint)
• Scope: Add GET /api/analytics/experience/{id} endpoint that returns aggregated analytics for an experience: total_plays, unique_players, avg_session_length, total_play_time, plays_over_time (daily breakdown), top_chunks_loaded, top_interactions. Data is aggregated from PlaySession and PlayEvent tables.
• Acceptance: Returns all aggregated metrics; daily breakdown covers last 30 days; only owner or moderator can view; empty experience returns zeros.
• Dependencies: T4.1

T4.3: Godot — Analytics Tracking in Game

• Type: implementation
• Files: scripts/analytics_tracker.gd (new)
• Scope: A singleton-like service that tracks player sessions and events during gameplay. Automatically starts session on world load, tracks chunk loads, interactions, and time spent. Sends periodic heartbeat events to backend. Handles session end on world unload or disconnect.
• Acceptance: Session starts on world load; events logged during play; heartbeat sends every 60s; session ends on world unload; handles disconnect gracefully.
• Dependencies: T4.1

T4.4: Godot — Creator Analytics Dashboard UI

• Type: implementation
• Files: scenes/creator_analytics_panel.tscn (new), scripts/creator_analytics_panel.gd (new)
• Scope: A Control-based panel in the editor that displays analytics for the current experience. Features: total plays counter, avg session length, plays over time chart (simple bar chart), top chunks, top interactions. Queries GET /api/analytics/experience/{id} and renders data.
• Acceptance: Panel shows all metrics; chart renders bar chart of daily plays; data refreshes on button press; handles empty data gracefully.
• Dependencies: T4.2, T4.3

---

Database Migration Plan

New tables needed (in order):

1. scripts — script storage
2. experiences — publishing state (wraps worlds)
3. play_sessions — session tracking (note: sessions table already exists for auth tokens)
4. play_events — granular events

Migration file: backend/alembic/versions/0003_creator_studio.py

---

Task Dependencies Summary

T1.1 (glTF upload) ──→ T1.2 (catalog API) ──→ T1.3 (Godot importer)
T2.1 (script model) ──→ T2.3 (editor UI)
T2.2 (API surface) ──→ T2.3 (editor UI)
T3.1 (experience model) ──→ T3.2 (review queue) ──→ T3.3 (publish UI)
T3.1 ──→ T3.4 (discovery list)
T4.1 (tracking model) ──→ T4.2 (dashboard endpoint) ──→ T4.4 (analytics UI)
T4.1 ──→ T4.3 (game tracker) ──→ T4.4 (analytics UI)

Implementation Order Recommendation

1. T1.1 — Foundation: asset upload with glTF metadata extraction
2. T2.1 — Foundation: script model + CRUD
3. T3.1 — Foundation: experience model + status transitions
4. T4.1 — Foundation: analytics tracking model
5. T1.2 — Asset catalog for editor
6. T2.2 — Script API surface definition
7. T3.2 — Review queue integration
8. T4.2 — Analytics dashboard endpoint
9. T1.3 — Godot glTF importer (depends on ApiClient from client-server-wiring)
10. T2.3 — Script editor UI
11. T3.3 — Publishing UI panel
12. T3.4 — Experience discovery list
13. T4.3 — Analytics tracker in game
14. T4.4 — Analytics dashboard UI