# 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
```typescript
// 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

```json
{
  "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"
  }
}
```
