@weppy/roblox-mcp 0.1.0

package/plugins/weppy-roblox-mcp/skills/roblox-game-dev/SKILL.md

@@ -0,0 +1,548 @@
+---
+name: roblox-game-dev
+description: Master orchestrator for Roblox game development. Handles sync, planning, development, and re-sync in a unified workflow. Use this when the user requests game creation or major feature development.
+argument-hint: "[game description or feature request]"
+---
+
+# Roblox Game Development Orchestrator
+
+This is the **master orchestrator skill** for Roblox game development. It coordinates the complete workflow from sync to deployment.
+
+**This is the ONLY user-invocable skill for Roblox development.**
+All other skills (sync, planner, task-tracker, templates, mcp-guide) are internal and referenced by this orchestrator.
+
+---
+
+## Workflow State Machine
+
+```
+USER REQUEST
+     │
+     ▼
+┌─────────────────┐
+│  1. SYNC        │  ← Blocking: Must complete before proceeding
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  2. PLAN        │  ← Generate development plan
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  3. APPROVAL    │  ← User must approve before development
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  4. DEVELOP     │  ← Execute tasks with MCP tools
+│  (Loop: tasks)  │◄──┐
+└────────┬────────┘   │
+         │            │
+         └── Next ────┘
+         │
+         ▼
+┌─────────────────┐
+│  5. RESYNC      │  ← Update local cache with Studio state
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  6. COMPLETE    │  ← Summary and next steps
+└─────────────────┘
+```
+
+---
+
+## Phase 1: SYNC (Blocking)
+
+**This phase MUST complete before any other actions.**
+
+### Pre-Check
+
+```bash
+./.claude/skills/roblox-sync/scripts/pre-check.sh --check-only
+```
+
+**Exit Code Handling:**
+
+| Exit | STATUS | Action |
+|------|--------|--------|
+| 0 | `synced` | Proceed to Phase 2 |
+| 0 | `needs_sync` | Execute full sync |
+| 11 | - | **STOP** - Studio not connected |
+
+### Full Sync
+
+**Refer to:** `.claude/skills/roblox-sync/SKILL.md`
+
+The sync skill handles:
+- MCP tool loading
+- Service structure fetching (all 7 services)
+- Script source extraction
+- Cache directory creation
+- Verification
+
+**Wait for VERIFICATION=passed before proceeding.**
+
+---
+
+## Phase 2: PLAN
+
+### Project State Analysis
+
+**Refer to:** `.claude/skills/roblox-planner/SKILL.md` → "Project State Detection & Template Usage"
+
+Based on sync data, determine project state:
+- **Empty project** → Use templates actively
+- **Existing content** → Follow user intent, reference templates only when needed
+
+### Plan Generation
+
+**Refer to:** `.claude/skills/roblox-planner/SKILL.md` → "Workflow" sections
+
+The planner skill handles:
+- Requirements gathering
+- Plan document creation
+- Task breakdown
+- Template/asset concept references (no hardcoded IDs)
+
+### Plan Document Location
+
+```
+.roblox-cache/plans/{plan-id}.md
+.roblox-cache/tasks/{plan-id}-tasks.md
+```
+
+---
+
+## Phase 3: APPROVAL
+
+**User approval is REQUIRED before development.**
+
+Present plan summary:
+
+```markdown
+## Proposed Development Plan
+
+### {Game Name}
+{Brief vision}
+
+### Phases & Tasks
+
+| Phase | Focus | Tasks |
+|-------|-------|-------|
+| 1 | Foundation | {count} |
+| 2 | Core Mechanics | {count} |
+| 3 | Content | {count} |
+| 4 | Polish | {count} |
+
+---
+
+**Do you approve this plan?**
+- Yes → Start development
+- Modify → Tell me what to change
+- Cancel → Abort
+```
+
+On approval:
+```bash
+echo "{plan-id}" > .roblox-cache/current-plan.txt
+```
+
+---
+
+## Phase 4: DEVELOP (Task Loop)
+
+### MCP Tools
+
+**Refer to:** `.claude/skills/roblox-mcp-guide/SKILL.md`
+
+Load tools as needed using ToolSearch:
+```
+ToolSearch: "+robloxstudio create_instance"
+ToolSearch: "+robloxstudio create_script"
+ToolSearch: "+robloxstudio focus_camera"
+```
+
+### Quota-Aware Workflow
+
+**IMPORTANT:** Before starting development, check Pro tool quota status.
+
+```
+ToolSearch: "select:mcp__weppy-roblox-mcp__get_usage_status"
+get_usage_status({})
+```
+
+**Response handling:**
+
+| canUsePro | Action |
+|-----------|--------|
+| `true` | Use Pro tools normally |
+| `false` | Use free tool alternatives, inform user |
+
+**When quota is exhausted (canUsePro=false):**
+
+1. Inform user: "Pro 도구를 사용할 수 없어 대안을 찾아보겠습니다."
+2. Use free alternatives (see table below)
+3. If task requires Pro-only features, inform user: "이 작업에는 Pro 도구가 필요합니다. 할당량이 리셋되면 계속하거나, Pro로 업그레이드하면 제한 없이 사용할 수 있습니다."
+
+**Pro → Free Tool Alternatives:**
+
+| Pro Tool | Free Alternative | Notes |
+|----------|------------------|-------|
+| `mass_create_instances` | `create_instance` loop | Slower but functional |
+| `terrain_generate` | `terrain_fill_block` combinations | Manual setup required |
+| `insert_free_model` | `create_instance_with_properties` | Build manually |
+| `batch_execute` | Sequential individual calls | More API calls |
+| `set_lighting` / `set_atmosphere` | Individual property sets | Use `set_property` |
+
+### Camera Focus Policy
+
+**IMPORTANT:** Camera focus is NEVER automatic. Always use `focus_camera` explicitly after creating objects or terrain.
+
+| Action | Camera Focus Required |
+|--------|----------------------|
+| Terrain created | `focus_camera` on cameraFocus from terrain-presets.json |
+| Map inserted | `focus_camera` on cameraFocus from maps.json |
+| Model/Asset inserted | `focus_camera` on inserted instance |
+| Major structure created | `focus_camera` for overview |
+| Phase completed | `focus_camera` for summary view |
+
+**`respectAutoFocusSetting` Option:**
+
+When calling `focus_camera` from skills, always set `respectAutoFocusSetting: true` to respect the user's Auto Focus Camera plugin setting:
+
+```typescript
+// This allows users to disable auto-focus via plugin settings
+await mcp.focus_camera({
+    targetPath: "game.Workspace.MyModel",
+    respectAutoFocusSetting: true,  // Always true in skills
+    distance: 50,  // Absolute distance in studs
+    offset: { x: 30, y: 20, z: 30 }  // Offset in studs for lookAt calculation
+});
+```
+
+**Understanding distance and offset:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `distance` | studs | **Absolute distance** from target (minimum: 10 studs) |
+| `offset` | studs | **Camera offset in studs** from target for lookAt calculation |
+
+**Using focusView from maps.json / terrain-presets.json:**
+
+For maps and terrain, use the predefined `focusView`:
+
+```typescript
+// After creating terrain from preset
+const preset = terrainPresets.presets["mountain_valley"];
+await mcp.focus_camera({
+    targetPath: "game.Workspace.Terrain",
+    respectAutoFocusSetting: true,
+    distance: preset.focusView.distance,  // e.g., 686 studs
+    offset: preset.focusView.offset       // e.g., { x: -400, y: 300, z: -350 } studs
+});
+
+// After inserting a map
+const map = maps.assets.find(m => m.id === 123456);
+await mcp.focus_camera({
+    targetPath: result.path,
+    respectAutoFocusSetting: true,
+    distance: map.focusView.distance,
+    offset: map.focusView.offset
+});
+```
+
+**Standard Camera Focus Patterns:**
+
+```typescript
+// After terrain creation (512x512 map) - use preset's focusView
+await mcp.focus_camera({
+    targetPath: "game.Workspace.Terrain",
+    respectAutoFocusSetting: true,
+    distance: 686,  // studs - covers ~512 stud terrain
+    offset: { x: -400, y: 300, z: -350 }  // studs offset for lookAt
+});
+
+// After creating a model/folder structure (medium size ~50 studs)
+await mcp.focus_camera({
+    targetPath: "game.Workspace.GameFolder",
+    respectAutoFocusSetting: true,
+    distance: 100,  // studs
+    offset: { x: 60, y: 40, z: 60 }  // studs offset for lookAt
+});
+
+// After inserting an asset (small ~10 studs)
+await mcp.focus_camera({
+    targetPath: result.path,  // Path returned from insert_free_model
+    respectAutoFocusSetting: true,
+    distance: 30,  // studs
+    offset: { x: 20, y: 10, z: 18 }  // studs offset for lookAt
+});
+```
+
+### Asset Selection
+
+**Refer to:** `.claude/skills/roblox-templates/SKILL.md`
+
+When tasks require assets:
+1. Read `roblox-templates/references/{game-type}.md`
+2. Read `roblox-templates/assets/{category}.json`
+3. Select assets matching the concept defined in task
+4. Insert via MCP
+5. **Call `focus_camera` on inserted asset**
+
+### Script Generation
+
+For complex scripts, delegate to `roblox-engineer` agent:
+
+```
+Task({
+  subagent_type: "roblox-engineer",
+  prompt: "[GENERATE SCRIPT] {script name} for {location}.
+           Requirements: {requirements}
+           Return only the Luau source code."
+})
+```
+
+Then use returned code with MCP `create_script`.
+
+### Development Visualization
+
+**IMPORTANT:** When configuring spawn positions, zones, or markers, use the Development Visualization MCP tools for real-time preview in `Workspace.DevPreview`.
+
+#### Visualization MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `visualization_create_area` | Create semi-transparent box for zone visualization |
+| `visualization_create_marker` | Create spawn point marker with optional asset preview |
+| `visualization_remove` | Remove specific visualization by ID |
+| `visualization_clear` | Remove all preview objects |
+| `visualization_focus` | Focus camera on specific element |
+| `visualization_get_status` | Get current visualization state |
+
+#### visualization_create_marker Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | string | Unique identifier (required) |
+| `label` | string | Text shown on marker label (required) |
+| `position` | {x,y,z} | Marker position (required) |
+| `markerType` | string | Marker type (determines color) |
+| `assetId` | number | **Roblox Asset ID for model preview** |
+| `assetName` | string | Asset name (shown in label) |
+| `count` | number | Spawn count (shown as "x5" in label) |
+| `area` | {x,y,z} | Optional area indicator size |
+| `color` | {r,g,b} | Custom color (when markerType is "custom") |
+| `focusCamera` | boolean | Focus camera on creation (default: true) |
+
+#### Workflow: Monster Spawn Configuration
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  1. CREATE SPAWN ZONE AREA                                  │
+│     MCP: visualization_create_area                          │
+│     → Creates transparent area box in DevPreview            │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│  2. CREATE SPAWN MARKERS WITH ASSET PREVIEW                 │
+│     MCP: visualization_create_marker (with assetId)         │
+│     → Creates marker + actual monster model preview         │
+│     → Camera auto-focuses for placement verification        │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│  3. USER CONFIRMATION                                       │
+│     Review and adjust positions                             │
+│     Use visualization_remove to delete unwanted markers     │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│  4. CREATE SPAWN SCRIPT & CLEANUP                           │
+│     Create spawn script with confirmed positions            │
+│     Call visualization_clear to remove all previews         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### Implementation Pattern
+
+```typescript
+// Step 1: Create spawn zone area visualization
+await mcp.visualization_create_area({
+    id: "forest_zone",
+    name: "Forest Zone",
+    center: { x: 100, y: 25, z: 100 },
+    size: { x: 200, y: 50, z: 200 },
+    color: { r: 0, g: 255, b: 0 }  // Green
+});
+
+// Step 2: Create monster spawn markers with asset preview
+await mcp.visualization_create_marker({
+    id: "zombie_spawn_1",
+    label: "Zombie x5",
+    position: { x: 80, y: 5, z: 80 },
+    markerType: "monster",
+    assetId: 3375251681,      // Actual Zombie asset ID
+    assetName: "Zombie",
+    count: 5,
+    area: { x: 30, y: 10, z: 30 }
+});
+
+await mcp.visualization_create_marker({
+    id: "orc_spawn_1",
+    label: "Orc Warrior x3",
+    position: { x: 120, y: 5, z: 120 },
+    markerType: "monster",
+    assetId: 71129266059717,  // Orc Warrior asset ID
+    assetName: "Orc Warrior",
+    count: 3
+});
+
+// Step 3: User reviews, adjust if needed
+// Remove marker if necessary:
+await mcp.visualization_remove({ id: "orc_spawn_1" });
+
+// Step 4: After confirmation, create spawn script and cleanup
+await mcp.visualization_clear();
+```
+
+#### Marker Types
+
+| Type | Color | Use Case |
+|------|-------|----------|
+| `monster` | Red | Monster/enemy spawn points |
+| `player` | Green | Player spawn locations |
+| `npc` | Blue | NPC positions |
+| `item` | Yellow | Item/loot spawn points |
+| `custom` | Gray (or custom color) | Other markers |
+
+#### Preview Folder Structure
+
+```
+Workspace/
+└── DevPreview/              ← Auto-created by visualization tools
+    ├── Area_forest_zone         ← Semi-transparent zone box
+    ├── Marker_zombie_spawn_1    ← Marker + asset preview
+    │   ├── Cylinder             ← Position indicator cylinder
+    │   ├── Label                ← BillboardGui label
+    │   └── AssetPreview         ← Actual monster model (when assetId provided)
+    └── Marker_orc_spawn_1
+```
+
+#### Key Points
+
+| Rule | Description |
+|------|-------------|
+| **Unique IDs** | Each visualization must have a unique `id` |
+| **Asset Preview** | Providing `assetId` inserts actual model preview |
+| **Auto camera focus** | Respects `autoFocusOnVisualization` setting |
+| **Cleanup after use** | Always call `visualization_clear` when done |
+| **DevPreview is temp** | Never use for permanent game objects |
+
+### Progress Tracking
+
+**Refer to:** `.claude/skills/roblox-task-tracker/SKILL.md`
+
+Update task status in `.roblox-cache/tasks/{plan-id}-tasks.md`:
+- `pending` → `in-progress` → `completed`
+
+Report progress after each phase.
+
+---
+
+## Phase 5: RESYNC
+
+After development, sync Studio state back to local cache.
+
+**Refer to:** `.claude/skills/roblox-sync/SKILL.md` → Steps 3-6
+
+Re-fetch affected services and verify.
+
+---
+
+## Phase 6: COMPLETE
+
+### Summary Report
+
+```markdown
+## Development Complete
+
+### {Game Name}
+
+**Tasks Completed:** {count}/{total}
+
+### What Was Created
+- Instances: {list}
+- Scripts: {list}
+- Assets: {list}
+
+### Next Steps
+1. Playtest the game in Studio
+2. Adjust balance/difficulty
+3. Publish when ready
+```
+
+### Update Plan Status
+
+Mark plan as completed in `.roblox-cache/plans/{plan-id}.md`
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| MCP not responding | Guide user to reconnect Studio |
+| Task failure | Log error, mark as failed, continue if possible |
+| User interruption | Save progress, allow resume later |
+
+---
+
+## Related Skills (Internal Reference Only)
+
+| Skill | Purpose | When Referenced |
+|-------|---------|-----------------|
+| `roblox-sync` | Studio ↔ Cache synchronization | Phase 1, Phase 5 |
+| `roblox-planner` | Plan creation & state detection | Phase 2 |
+| `roblox-task-tracker` | Progress tracking & handoffs | Phase 4 |
+| `roblox-templates` | Asset concepts & game references | Phase 4 (development) |
+| `roblox-mcp-guide` | MCP tool documentation | Phase 4 (development) |
+
+**Users cannot invoke these skills directly.** This orchestrator manages all coordination.
+
+---
+
+## Quick Reference
+
+### Essential Commands
+
+```bash
+# Pre-sync check
+./.claude/skills/roblox-sync/scripts/pre-check.sh --check-only
+
+# Post-sync verification
+./.claude/skills/roblox-sync/scripts/post-verify.sh
+
+# Plan verification
+./.claude/skills/roblox-planner/scripts/verify-plan.sh <plan-id>
+```
+
+### Cache Structure
+
+```
+.roblox-cache/
+├── current-plan.txt          # Active plan ID
+├── plans/                    # Plan documents
+├── tasks/                    # Task lists
+└── logs/                     # Activity logs
+
+roblox-studio-sync/
+├── explorer/                 # Studio state cache
+└── last-sync.txt            # Sync timestamp
+```