aethex-studio/docs/FEATURE_ARCHITECTURE.md

AeThex Studio - Feature Architecture

Immediate Priority Features (Next Sprint)

---

1. VISUAL SCRIPTING SYSTEM

Why It's Critical

• 70% of Roblox creators prefer visual tools
• Lowers barrier to entry massively
• Differentiator from text-only IDEs

Architecture

src/
├── components/
│   └── visual-scripting/
│       ├── VisualScriptingCanvas.tsx    # Main React Flow canvas
│       ├── NodePalette.tsx              # Draggable node library
│       ├── nodes/
│       │   ├── EventNodes.tsx           # OnPlayerJoin, OnTouch, etc.
│       │   ├── LogicNodes.tsx           # If, Loop, Wait, etc.
│       │   ├── ActionNodes.tsx          # SetProperty, Destroy, etc.
│       │   ├── DataNodes.tsx            # Variables, Math, etc.
│       │   └── CustomNodes.tsx          # User-defined functions
│       ├── NodeInspector.tsx            # Edit node properties
│       ├── ConnectionLine.tsx           # Custom edge rendering
│       └── CodePreview.tsx              # Live Lua/Verse output
├── lib/
│   └── visual-scripting/
│       ├── node-definitions.ts          # All node type definitions
│       ├── code-generator.ts            # Nodes → Code conversion
│       ├── code-parser.ts               # Code → Nodes (reverse)
│       └── validation.ts                # Check for errors

Node Types

// Event Nodes (Green) - Entry points
- OnPlayerJoin
- OnPlayerLeave
- OnPartTouch
- OnClick
- OnKeyPress
- OnTimer
- OnValueChange

// Logic Nodes (Blue) - Control flow
- If/Else
- For Loop
- While Loop
- Wait/Delay
- Random Branch
- Switch/Case

// Action Nodes (Purple) - Do things
- Print/Log
- SetProperty
- CreatePart
- DestroyObject
- PlaySound
- TweenProperty
- FireEvent
- CallFunction

// Data Nodes (Orange) - Values
- Number
- String
- Boolean
- Variable (Get/Set)
- MathOperation
- StringOperation
- TableOperation

// Reference Nodes (Yellow) - Game objects
- GetPlayer
- GetPart
- FindFirstChild
- GetService
- GetChildren

Tech Stack

• React Flow - Node canvas library
• Zustand - State management for nodes
• Monaco - Side-by-side code preview

---

2. LIVE GAME PREVIEW

Why It's Critical

• Can't test without leaving IDE = friction
• Immediate feedback loop is essential
• See changes in real-time

Architecture

src/
├── components/
│   └── preview/
│       ├── GamePreview.tsx              # Main preview container
│       ├── PreviewCanvas.tsx            # Three.js 3D viewport
│       ├── PreviewControls.tsx          # Play/Pause/Reset
│       ├── PreviewConsole.tsx           # Output logs
│       ├── DeviceFrame.tsx              # Phone/tablet mockup
│       └── PlayerSimulator.tsx          # Fake player for testing
├── lib/
│   └── preview/
│       ├── lua-interpreter.ts           # Run Lua in browser (Fengari)
│       ├── roblox-api-mock.ts           # Mock Roblox APIs
│       ├── scene-manager.ts             # 3D scene setup
│       └── hot-reload.ts                # Update without restart

Capabilities

┌─────────────────────────────────────────────────────┐
│ Preview                              [▶️] [⏸️] [🔄] │
├─────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────┐ │
│ │                                                 │ │
│ │              3D Game View                       │ │
│ │                                                 │ │
│ │     [Cube]          [Player]                    │ │
│ │                                                 │ │
│ └─────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────┤
│ Console:                                            │
│ > Player touched Part1                              │
│ > Score updated: 10                                 │
│ > [Error] Line 15: attempt to index nil             │
└─────────────────────────────────────────────────────┘

Tech Stack

• Three.js - 3D rendering
• Fengari - Lua interpreter in JS
• Roblox API Mocks - Simulate game.Players, workspace, etc.

---

3. ASSET LIBRARY

Why It's Critical

• Games need more than code
• Models, textures, sounds
• Professional workflow

Architecture

src/
├── components/
│   └── assets/
│       ├── AssetLibrary.tsx             # Main panel
│       ├── AssetBrowser.tsx             # Grid/list view
│       ├── AssetUploader.tsx            # Drag-drop upload
│       ├── AssetPreview.tsx             # 3D/2D/audio preview
│       ├── AssetInspector.tsx           # Metadata, tags
│       └── AssetSearch.tsx              # Search + filters
├── lib/
│   └── assets/
│       ├── asset-types.ts               # Type definitions
│       ├── asset-processor.ts           # Optimize on upload
│       ├── format-converter.ts          # GLB→FBX, etc.
│       └── storage.ts                   # IndexedDB + cloud sync

Supported Formats

3D Models:    .glb, .gltf, .fbx, .obj
Textures:     .png, .jpg, .webp, .svg
Audio:        .mp3, .wav, .ogg
Data:         .json, .csv
Animations:   .fbx (with anims), .bvh

Features

• Drag-drop upload
• Auto-optimization per platform
• AI tagging (auto-detect "sword", "tree", etc.)
• Version history
• Cloud sync across devices
• Platform-specific export (Roblox mesh → UEFN static mesh)

---

4. REAL-TIME COLLABORATION

Why It's Critical

• Teams are the norm now
• Remote work is standard
• Google Docs set the expectation

Architecture

src/
├── components/
│   └── collaboration/
│       ├── PresenceCursors.tsx          # See teammate cursors
│       ├── CollabPanel.tsx              # Who's online
│       ├── VoiceChat.tsx                # Audio (optional)
│       ├── ChatSidebar.tsx              # Text chat
│       └── CommentThread.tsx            # Inline comments
├── lib/
│   └── collaboration/
│       ├── crdt.ts                      # Conflict-free sync (Yjs)
│       ├── presence.ts                  # Cursor positions
│       ├── awareness.ts                 # Who's editing what
│       └── websocket.ts                 # Real-time connection

Tech Stack

• Yjs - CRDT for conflict-free editing
• Liveblocks or PartyKit - Real-time infrastructure
• WebRTC - Voice chat (optional)

---

5. MARKETPLACE

Why It's Critical

• Monetization for creators
• Shortcuts for developers
• Platform stickiness (they stay for the ecosystem)

Architecture

src/
├── components/
│   └── marketplace/
│       ├── MarketplaceBrowser.tsx       # Browse listings
│       ├── ListingCard.tsx              # Product preview
│       ├── ListingDetail.tsx            # Full product page
│       ├── SellerDashboard.tsx          # For sellers
│       ├── PurchaseFlow.tsx             # Buy flow
│       └── ReviewSection.tsx            # Ratings
├── lib/
│   └── marketplace/
│       ├── types.ts                     # Listing, Purchase, etc.
│       ├── search.ts                    # Algolia/Meilisearch
│       ├── payments.ts                  # Stripe integration
│       └── licensing.ts                 # License management

Categories

Scripts & Systems
├── Combat Systems
├── Vehicle Physics
├── Inventory Systems
├── Dialogue Systems
├── Economy/Shop Systems
└── Admin Tools

3D Assets
├── Characters
├── Environments
├── Props
├── Vehicles
└── Effects

UI Kits
├── Menus
├── HUDs
├── Shops
└── Inventory UIs

Audio
├── Music
├── Sound Effects
└── Ambient

---

6. AI CODE GENERATION V2

Why It's Critical

• Current AI is just translation
• "Build me X" is the dream
• Massive productivity boost

Architecture

src/
├── lib/
│   └── ai/
│       ├── code-generator.ts            # Generate from prompt
│       ├── code-explainer.ts            # Explain code
│       ├── bug-detector.ts              # Find issues
│       ├── optimizer.ts                 # Suggest improvements
│       ├── documentation.ts             # Auto-generate docs
│       └── prompts/
│           ├── roblox-system.md         # Roblox context
│           ├── uefn-system.md           # UEFN context
│           └── generation-templates.md  # Structured output

Capabilities

User: "Create a round-based game with teams"

AI generates:
├── RoundManager.lua
│   ├── startRound()
│   ├── endRound()
│   ├── checkWinCondition()
│   └── Configuration (roundTime, teamSize)
├── TeamManager.lua
│   ├── assignTeams()
│   ├── balanceTeams()
│   └── getTeamScore()
├── ScoreboardUI.lua
│   └── Full UI with team scores
└── README.md
    └── Setup instructions

[All files connected and working together]

---

7. ONE-CLICK DEPLOY

Why It's Critical

• Getting code into games is painful
• Manual copy-paste is error-prone
• Professional workflow needs automation

Architecture

src/
├── components/
│   └── deploy/
│       ├── DeployPanel.tsx              # Main deploy UI
│       ├── PlatformConnection.tsx       # OAuth with platforms
│       ├── DeployProgress.tsx           # Real-time status
│       ├── DeployHistory.tsx            # Past deployments
│       └── RollbackButton.tsx           # Revert if needed
├── lib/
│   └── deploy/
│       ├── roblox-deploy.ts             # Roblox Open Cloud API
│       ├── uefn-deploy.ts               # UEFN deployment
│       ├── spatial-deploy.ts            # Spatial deployment
│       ├── validator.ts                 # Pre-deploy checks
│       └── optimizer.ts                 # Platform optimization

Flow

1. Connect accounts (OAuth)
   └── Roblox: Open Cloud API key
   └── UEFN: Epic Games login
   └── Spatial: API token

2. Select target
   └── Which game/experience
   └── Which environment (staging/production)

3. Validate
   └── Syntax check
   └── Platform compatibility
   └── Security scan

4. Deploy
   └── Optimize code
   └── Upload assets
   └── Update game

5. Verify
   └── Health check
   └── Rollback if failed

---

Implementation Priority Matrix

Feature	Impact	Effort	Priority
Visual Scripting	🔥🔥🔥	⚡⚡⚡	P0
Live Preview	🔥🔥🔥	⚡⚡	P0
Asset Library	🔥🔥	⚡⚡	P1
Real-time Collab	🔥🔥🔥	⚡⚡⚡	P1
AI Generation v2	🔥🔥🔥	⚡⚡	P1
Marketplace	🔥🔥🔥	⚡⚡⚡	P2
One-Click Deploy	🔥🔥	⚡⚡⚡	P2

---

File Structure After Implementation

src/
├── components/
│   ├── ui/                     # Primitives (existing)
│   ├── editor/                 # Code editor (existing)
│   ├── visual-scripting/       # NEW: Node editor
│   ├── preview/                # NEW: Game preview
│   ├── assets/                 # NEW: Asset management
│   ├── collaboration/          # NEW: Real-time collab
│   ├── marketplace/            # NEW: Asset store
│   ├── deploy/                 # NEW: Deployment
│   └── avatar/                 # EXISTS: Avatar toolkit
├── lib/
│   ├── platforms.ts            # Existing
│   ├── templates.ts            # Existing
│   ├── avatar-*.ts             # Existing
│   ├── visual-scripting/       # NEW
│   ├── preview/                # NEW
│   ├── assets/                 # NEW
│   ├── collaboration/          # NEW
│   ├── marketplace/            # NEW
│   ├── deploy/                 # NEW
│   └── ai/                     # NEW: Enhanced AI
├── hooks/
│   ├── use-visual-script.ts    # NEW
│   ├── use-preview.ts          # NEW
│   ├── use-collaboration.ts    # NEW
│   └── use-assets.ts           # NEW
└── stores/
    ├── editor-store.ts         # Existing (Zustand)
    ├── visual-script-store.ts  # NEW
    ├── asset-store.ts          # NEW
    └── collab-store.ts         # NEW

---

Dependencies to Add

{
  "dependencies": {
    // Visual Scripting
    "reactflow": "^11.10.0",

    // 3D Preview
    "@react-three/fiber": "^8.15.0",
    "@react-three/drei": "^9.88.0",
    "three": "^0.159.0",

    // Lua Interpreter
    "fengari-web": "^0.1.4",

    // Real-time Collaboration
    "yjs": "^13.6.0",
    "@liveblocks/client": "^1.4.0",
    "@liveblocks/react": "^1.4.0",

    // Search
    "meilisearch": "^0.35.0",

    // Payments
    "@stripe/stripe-js": "^2.2.0",

    // State Management
    "zustand": "^4.4.0",
    "immer": "^10.0.0"
  }
}