@weppy/roblox-mcp 0.1.0

package/plugins/weppy-roblox-mcp/skills/roblox-mcp-guide/scripts/check-mcp.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+# =============================================================================
+# check-mcp.sh - Check MCP/Studio connection status
+# =============================================================================
+# Quick check for MCP connection. Used by agent hooks.
+#
+# Exit codes:
+#   0  = Connected or unknown (allow proceed)
+#   1  = Definitely disconnected (block)
+#
+# Output (machine-readable):
+#   STATUS=connected|disconnected|unknown
+#   MESSAGE=<description>
+# =============================================================================
+
+SYNC_DIR="${1:-roblox-studio-sync}"
+CONNECTION_FILE="$SYNC_DIR/connection-status.txt"
+ACTIVITY_LOG="$SYNC_DIR/activity.log"
+MAX_AGE=60  # Connection status valid for 60 seconds
+
+# Ensure sync directory exists
+mkdir -p "$SYNC_DIR"
+
+# Method 1: Check for recent MCP activity (most reliable)
+if [ -f "$ACTIVITY_LOG" ]; then
+  # Check if activity log was modified in last 5 minutes
+  if [ "$(find "$ACTIVITY_LOG" -mmin -5 2>/dev/null)" ]; then
+    echo "STATUS=connected"
+    echo "MESSAGE=Recent MCP activity detected"
+    exit 0
+  fi
+fi
+
+# Method 2: Check cached connection status
+if [ -f "$CONNECTION_FILE" ]; then
+  LAST_STATUS=$(cat "$CONNECTION_FILE" 2>/dev/null | head -1)
+
+  # Get file age (macOS compatible)
+  FILE_MOD=$(stat -f %m "$CONNECTION_FILE" 2>/dev/null || stat -c %Y "$CONNECTION_FILE" 2>/dev/null || echo "0")
+  NOW=$(date +%s)
+  FILE_AGE=$((NOW - FILE_MOD))
+
+  if [ "$FILE_AGE" -lt "$MAX_AGE" ] && [ "$LAST_STATUS" = "connected" ]; then
+    echo "STATUS=connected"
+    echo "MESSAGE=Connection verified recently (${FILE_AGE}s ago)"
+    exit 0
+  fi
+fi
+
+# Method 3: Check if Studio plugin port is responding
+MCP_PORT="${MCP_PORT:-21496}"
+
+if command -v nc &> /dev/null; then
+  if nc -z -w 2 localhost "$MCP_PORT" 2>/dev/null; then
+    echo "connected" > "$CONNECTION_FILE"
+    echo "STATUS=connected"
+    echo "MESSAGE=Studio plugin responding on port $MCP_PORT"
+    exit 0
+  else
+    echo "disconnected" > "$CONNECTION_FILE"
+    echo "STATUS=disconnected"
+    echo "MESSAGE=Studio plugin not responding on port $MCP_PORT"
+    echo ""
+    echo "GUIDE=Please check:"
+    echo "  1. Roblox Studio is running"
+    echo "  2. MCP plugin is installed and enabled"
+    echo "  3. Plugin shows 'Connected' status"
+    exit 1
+  fi
+fi
+
+# Method 4: Try curl as fallback
+if command -v curl &> /dev/null; then
+  if curl -s --connect-timeout 2 "http://localhost:$MCP_PORT" >/dev/null 2>&1; then
+    echo "connected" > "$CONNECTION_FILE"
+    echo "STATUS=connected"
+    echo "MESSAGE=Studio plugin responding"
+    exit 0
+  fi
+fi
+
+# Cannot verify - allow but warn
+echo "STATUS=unknown"
+echo "MESSAGE=Cannot verify connection (nc/curl not available)"
+echo "GUIDE=Ensure Roblox Studio is open with MCP plugin installed"
+exit 0

package/plugins/weppy-roblox-mcp/skills/roblox-planner/SKILL.md

@@ -0,0 +1,588 @@
+---
+name: roblox-planner
+description: Plan Roblox game development projects. Use when starting a new game, planning features, breaking down development tasks, or creating roadmaps. Helps structure game development into actionable phases.
+argument-hint: "[game-description or feature-request]"
+user-invocable: false
+---
+
+# Roblox Game Planner
+
+This skill helps plan and structure Roblox game development projects by clarifying requirements, breaking down features into tasks, and creating actionable development plans.
+
+## Prerequisites
+
+**This skill assumes sync is already complete.**
+
+This skill is called internally by `/roblox-game-dev` orchestrator only.
+Users cannot invoke this skill directly.
+
+## Project State Detection & Template Usage
+
+### Project State Detection
+
+After sync completes, analyze `roblox-studio-sync/explorer/` data to determine project state:
+
+**Empty Project Criteria:**
+```typescript
+function isEmptyProject(syncData): boolean {
+  const workspace = syncData["Workspace/_index.json"];
+
+  // Only default instances present (Camera, Terrain, SpawnLocation)
+  if (workspace.childCount <= 3) return true;
+
+  // No folder structure exists
+  const hasFolders = workspace.children.some(c =>
+    ["Folder", "Model"].includes(c.className) && c.name !== "Camera"
+  );
+  if (!hasFolders) return true;
+
+  // No scripts present
+  const hasScripts = checkForScripts(syncData);
+  if (!hasScripts) return true;
+
+  return false;
+}
+```
+
+### Template Usage Rules
+
+| Project State | Template Usage | Description |
+|--------------|----------------|-------------|
+| **Empty** | **Active use** | Select assets from templates (maps, monsters, weapons) |
+| **Existing content** | **User intent first** | Plan to match existing style, reference templates only when needed |
+| **Extension/Feature add** | **Selective use** | Judge based on user request |
+
+### Empty Project Workflow
+
+```
+1. Analyze sync data → Determine project state
+2. If empty project:
+   - Read roblox-templates/references/{game-type}.md
+   - Reference asset concepts from roblox-templates/assets/*.json
+   - Specify asset concepts in tasks (no hardcoded IDs)
+3. If existing content:
+   - Analyze existing structure
+   - Plan extensions/modifications per user request
+   - Use templates for reference only
+```
+
+### Existing Project Workflow
+
+```
+1. Understand existing structure from sync data
+   - What folder structure is used?
+   - What code style is used?
+   - What existing assets/models are present?
+2. Analyze user request
+   - Modifying existing functionality?
+   - Adding new features?
+3. Plan according to existing style
+   - Do not force template usage
+   - Plan in the direction user wants
+```
+
+## Cache Directory
+
+All plans stored in `.roblox-cache/`:
+
+```
+.roblox-cache/
+├── plans/                    # Development plans
+│   └── {plan-id}.md
+├── tasks/                    # Task lists with status
+│   └── {plan-id}-tasks.md
+└── current-plan.txt          # Active plan ID
+```
+
+## Workflow
+
+### Phase 1: Gather Requirements
+
+When user requests a game or feature:
+
+**Essential Questions:**
+
+1. **Game Type**
+   - "What type of game? (Obby, Tycoon, Simulator, RPG, Battle Royale, etc.)"
+
+2. **Core Mechanics**
+   - "What are the main gameplay mechanics?"
+   - "What does the player do moment-to-moment?"
+
+3. **Multiplayer**
+   - "Single player, multiplayer, or both?"
+   - "How do players interact?"
+
+4. **Scope**
+   - "How large is the map/world?"
+   - "How many levels/areas?"
+
+5. **Visual Style**
+   - "What's the art style? (Realistic, cartoony, low-poly)"
+   - "What's the theme? (Medieval, futuristic, nature)"
+
+6. **Target Audience**
+   - "Who is this game for?"
+   - "What's the complexity level?"
+
+**Example Clarification Dialog:**
+```
+I'd like to understand your game better:
+
+1. Game Type: What genre is this? (Obby, Tycoon, Simulator, etc.)
+2. Core Loop: What does a player do in a typical session?
+3. Scale: How big should the world be?
+4. Theme: What visual style are you going for?
+5. Complexity: Beginner-friendly or advanced players?
+
+Please share any reference games or inspirations!
+```
+
+### Phase 2: Create Plan Document
+
+**Generate Plan ID:** `plan-{YYYYMMDD}-{short-name}`
+Example: `plan-20250128-sky-obby`
+
+**Plan Document Structure:**
+
+```markdown
+# Plan: {Game Name}
+
+**ID:** {plan-id}
+**Created:** {date}
+**Status:** draft
+
+## Vision
+
+{2-3 sentence description of the game and what makes it unique}
+
+## Game Overview
+
+### Type
+{Genre: Obby, Tycoon, Simulator, etc.}
+
+### Core Loop
+1. {Primary action}
+2. {Secondary action}
+3. {Reward/progression}
+
+### Target Audience
+{Who will play this game}
+
+## Requirements
+
+### Must Have
+- [ ] {Critical feature 1}
+- [ ] {Critical feature 2}
+- [ ] {Critical feature 3}
+
+### Should Have
+- [ ] {Important feature 1}
+- [ ] {Important feature 2}
+
+### Nice to Have
+- [ ] {Optional feature 1}
+- [ ] {Optional feature 2}
+
+## Technical Specifications
+
+### Map Size
+{Approximate dimensions and structure}
+
+### Performance Targets
+- Max parts: {estimate}
+- Target FPS: 60
+- Mobile support: {yes/no}
+
+### Services Used
+- [ ] DataStoreService (saving)
+- [ ] MarketplaceService (purchases)
+- [ ] TeleportService (multiple places)
+
+## Development Phases
+
+### Phase 1: Foundation ({X} tasks)
+Core infrastructure and basic setup
+
+### Phase 2: Core Mechanics ({Y} tasks)
+Main gameplay implementation
+
+### Phase 3: Content ({Z} tasks)
+Levels, items, environments
+
+### Phase 4: Polish ({W} tasks)
+UI, effects, sounds, optimization
+
+### Phase 5: Launch ({V} tasks)
+Testing, fixes, deployment
+
+## Risks & Mitigations
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| {Risk 1} | {High/Med/Low} | {Strategy} |
+| {Risk 2} | {High/Med/Low} | {Strategy} |
+
+## Success Criteria
+
+- [ ] {Measurable outcome 1}
+- [ ] {Measurable outcome 2}
+- [ ] {Measurable outcome 3}
+```
+
+### Phase 3: Break Down Tasks
+
+For each phase, create detailed task breakdown:
+
+**Task Template:**
+```markdown
+### TASK-{NNN}: {Title}
+- **Phase:** {Phase number}
+- **Complexity:** simple | medium | complex
+- **Executor:** roblox-engineer | manual
+- **Dependencies:** none | TASK-XXX, TASK-YYY
+- **Description:** {What needs to be done}
+- **Acceptance Criteria:**
+  - [ ] {Criterion 1}
+  - [ ] {Criterion 2}
+- **MCP Tools:** {Relevant tools to use}
+```
+
+**Task Categories:**
+
+| Category | Example Tasks |
+|----------|--------------|
+| **Structure** | Create folders, organize hierarchy |
+| **Environment** | Terrain, lighting, atmosphere |
+| **Building** | Platforms, obstacles, decorations |
+| **Scripting** | Game logic, player systems |
+| **UI** | Menus, HUD, popups |
+| **Data** | Saving, leaderboards, stats |
+| **Effects** | Particles, sounds, animations |
+| **Testing** | Playtesting, bug fixes |
+
+### Phase 4: Present Plan
+
+**Always get user confirmation before proceeding:**
+
+```markdown
+## Proposed Development Plan
+
+### {Game Name}
+{Brief vision statement}
+
+### Scope Summary
+- **Phases:** {count}
+- **Total Tasks:** {count}
+- **Estimated Complexity:** {Low/Medium/High}
+
+### Phase Breakdown
+
+| Phase | Focus | Tasks |
+|-------|-------|-------|
+| 1. Foundation | Setup, structure | {count} |
+| 2. Core | Main mechanics | {count} |
+| 3. Content | Levels, items | {count} |
+| 4. Polish | UI, effects | {count} |
+| 5. Launch | Testing, deploy | {count} |
+
+### Key Features
+1. {Feature 1}
+2. {Feature 2}
+3. {Feature 3}
+
+### Risks Identified
+- {Risk 1 and mitigation}
+- {Risk 2 and mitigation}
+
+---
+
+**Do you approve this plan?**
+- Yes, start development
+- Modify scope (tell me what to change)
+- Add more detail to specific phase
+```
+
+### Phase 5: Save Plan
+
+On approval:
+
+### Phase 6: Plan File Verification
+
+**After saving plan files, verify they were created correctly:**
+
+```bash
+./.claude/skills/roblox-planner/scripts/verify-plan.sh <plan-id>
+
+# Example
+./.claude/skills/roblox-planner/scripts/verify-plan.sh plan-20250128-rpg
+```
+
+**Verification Checks:**
+1. Directory structure (`.roblox-cache/plans/`, `.roblox-cache/tasks/`)
+2. Plan file exists and has required sections (Vision, Requirements, Development Phases)
+3. Tasks file exists and has TASK entries with Phase/Complexity fields
+4. `current-plan.txt` points to the correct plan ID
+
+**Exit codes:**
+- `0` = All checks passed
+- `1` = Verification failed (missing files or invalid content)
+
+---
+
+On approval (continued):
+
+```bash
+# 1. Create cache directories
+mkdir -p .roblox-cache/plans .roblox-cache/tasks
+
+# 2. Save plan document
+# Write to .roblox-cache/plans/{plan-id}.md
+
+# 3. Create task list
+# Write to .roblox-cache/tasks/{plan-id}-tasks.md
+
+# 4. Set as active plan
+echo "{plan-id}" > .roblox-cache/current-plan.txt
+```
+
+---
+
+## Game Type Templates
+
+### Obby (Obstacle Course)
+
+**Typical Structure:**
+```
+Phase 1: Foundation
+- TASK-001: Create spawn area
+- TASK-002: Set up checkpoint system
+- TASK-003: Configure respawn logic
+
+Phase 2: Core Mechanics
+- TASK-004: Build tutorial section
+- TASK-005: Create obstacle types (jumps, moving, timed)
+- TASK-006: Implement difficulty zones
+
+Phase 3: Content
+- TASK-007: Build easy levels (1-5)
+- TASK-008: Build medium levels (6-10)
+- TASK-009: Build hard levels (11-15)
+
+Phase 4: Polish
+- TASK-010: Add particle effects
+- TASK-011: Create win celebration
+- TASK-012: Add leaderboard
+```
+
+### Tycoon
+
+**Typical Structure:**
+```
+Phase 1: Foundation
+- TASK-001: Create tycoon plot template
+- TASK-002: Set up currency system
+- TASK-003: Implement dropper/collector basics
+
+Phase 2: Core Mechanics
+- TASK-004: Build purchase buttons
+- TASK-005: Create upgrade paths
+- TASK-006: Implement rebirth system
+
+Phase 3: Content
+- TASK-007: Design 3 tycoon themes
+- TASK-008: Create 20+ purchasable items
+- TASK-009: Add premium upgrades
+
+Phase 4: Polish
+- TASK-010: Create tycoon UI
+- TASK-011: Add money animations
+- TASK-012: Implement data saving
+```
+
+### Simulator
+
+**Typical Structure:**
+```
+Phase 1: Foundation
+- TASK-001: Create collection mechanics
+- TASK-002: Set up stats system
+- TASK-003: Implement inventory
+
+Phase 2: Core Mechanics
+- TASK-004: Build tool/pet system
+- TASK-005: Create upgrade mechanics
+- TASK-006: Implement zones/worlds
+
+Phase 3: Content
+- TASK-007: Design 5 zones
+- TASK-008: Create 50+ collectibles
+- TASK-009: Add rare items/pets
+
+Phase 4: Polish
+- TASK-010: Create progression UI
+- TASK-011: Add VFX for collection
+- TASK-012: Implement trading
+```
+
+### RPG (Role Playing Game)
+
+**Map Theme Selection:**
+RPG 맵은 다음 테마 중 랜덤으로 선택됩니다:
+- `forest` - 숲 속 빈터 (beginner)
+- `volcanic` - 화산 분화구 (intermediate)
+- `island` - 열대 섬 (intermediate)
+- `dungeon` - 던전/동굴 (intermediate)
+- `desert` - 사막 오아시스 (intermediate)
+
+**Typical Structure:**
+```
+Phase 1: World Setup (맵 생성 우선)
+- TASK-001: Create/insert map first (terrain_generate or insert_free_model)
+  - Select random theme from maps.json environments
+  - Focus camera on created world
+- TASK-002: Configure player SpawnLocation based on map's spawnZones
+- TASK-003: Create game folder structure (Monsters, NPCs, Items, Weapons)
+- TASK-004: Configure lighting and atmosphere to match theme
+
+Phase 2: Spawn Configuration (스폰 영역 설정)
+- TASK-005: Analyze spawnable areas using find_spawn_positions/find_ground
+- TASK-006: Define spawn zones in script (coordinates from maps.json spawnZones)
+- TASK-007: Select monsters from assets/monsters.json based on theme/difficulty
+- TASK-008: Create MonsterSpawner script with hardcoded zone coordinates
+- TASK-009: Visualize spawn zones using visualization_create_area/visualization_create_marker (if available)
+
+Phase 3: Core Mechanics
+- TASK-010: Set up player stats system (HP, MP, Level, EXP)
+- TASK-011: Implement combat system (attack, damage calculation)
+- TASK-012: Create monster AI (patrol, chase, attack)
+- TASK-013: Implement level/experience system
+- TASK-014: Create death/respawn mechanics
+
+Phase 4: Content & UI
+- TASK-015: Create HP/MP/EXP UI (ScreenGui with bars)
+- TASK-016: Place weapons/items (refer to assets/weapons.json, items.json)
+- TASK-017: Place NPCs if needed (refer to assets/npcs.json)
+- TASK-018: Add combat effects (hit, death particles)
+- TASK-019: Implement damage numbers and sound effects
+
+Phase 5: Data & Launch
+- TASK-020: Implement data saving (player stats, inventory)
+- TASK-021: Create leaderboard
+- TASK-022: Playtesting and balance adjustments
+- TASK-023: Clear visualization (visualization_clear) before publish
+```
+
+**Spawn Configuration Workflow:**
+```
+1. Map Created
+      ↓
+2. Read spawnZones from maps.json for selected environment
+      ↓
+3. Verify each zone with find_ground (check for water/invalid terrain)
+      ↓
+4. Select monsters from monsters.json (match theme/difficulty)
+      ↓
+5. Write spawn script with SPAWN_ZONES table (hardcoded coordinates)
+      ↓
+6. (Optional) Visualize with visualization_create_marker/area for debugging
+      ↓
+7. Clear visualizations before game publish
+```
+
+---
+
+## Estimation Guidelines
+
+### Complexity Levels
+
+| Level | Description | Typical Duration |
+|-------|-------------|-----------------|
+| **Simple** | Single instance, basic property | 5-10 min |
+| **Medium** | Multiple parts, scripting | 15-30 min |
+| **Complex** | Systems, multi-file | 30-60 min |
+
+### MCP Tool Mapping
+
+| Task Type | Primary Tools |
+|-----------|--------------|
+| **Structure** | create_instance, move_instance, rename_instance |
+| **Building** | create_instance_with_properties, mass_create_instances |
+| **Terrain** | terrain_fill_*, terrain_generate |
+| **Lighting** | set_lighting, set_atmosphere, set_sky |
+| **Scripting** | create_script, set_script_source |
+| **Properties** | set_property, set_multiple_properties |
+| **Search** | search_by_*, find_first_descendant |
+
+---
+
+## Best Practices
+
+### Planning
+- Start with MVP (minimum viable product)
+- Break tasks into 15-30 minute chunks
+- Make dependencies explicit
+- Leave buffer for unexpected issues
+
+### Prioritization
+- Core loop first, polish last
+- Test early, test often
+- Mobile compatibility from start if needed
+
+### Communication
+- Confirm understanding before planning
+- Get explicit approval before execution
+- Report progress at phase boundaries
+
+---
+
+## Asset Selection Rule
+
+**The planner does NOT hardcode asset IDs, names, or stats.**
+
+Tasks requiring assets specify **concepts only**, and at execution time the `roblox-templates` skill selects matching assets.
+
+### Principles
+
+1. **Planner role**: Define concepts (theme, difficulty, category, quantity)
+2. **Templates role**: Provide assets (ID, name, stats, coordinates)
+3. **No dependencies**: Planner does not depend on specific asset IDs/names
+
+### Task Writing Format
+
+```markdown
+# Correct example (concepts only)
+### TASK-009: Place monsters
+- **Concept**: 3 beginner-difficulty monster types
+- **Quantity**: 3-5 each
+- **Asset source**: roblox-templates/assets/monsters.json → filter by difficulty "beginner"
+- **Placement**: Determined by find_spawn_positions
+
+### TASK-001: Insert map
+- **Concept**: RPG-suitable theme (randomly selected from: forest, volcanic, island, dungeon, desert)
+- **Asset source**: roblox-templates/assets/maps/maps.json → filter by recommended.rpg_adventure OR random theme
+- **Selection**: Randomly pick one environment from matched results
+
+# Incorrect example (hardcoding)
+### TASK-009: Place monsters
+- Slime (83110489) x5       ← ❌ Hardcoded ID
+- Zombie (3375251681) x3    ← ❌ Hardcoded name/ID
+```
+
+### Asset Selection Workflow
+
+```
+1. Planner: Record concepts in task (theme, difficulty, category)
+2. Executor: Read roblox-templates/references/{game-type}.md
+3. Executor: Match concepts in roblox-templates/assets/{category}.json
+4. Executor: Randomly select from matched assets and insert via MCP
+```
+
+### Game Type → Reference Mapping
+
+| Game Type | Reference File | Asset Categories |
+|-----------|----------------|------------------|
+| RPG | references/rpg.md | maps, monsters, weapons, npcs, items |
+| Obby | references/obby.md | obstacles, checkpoints, effects |
+| Tycoon | references/tycoon.md | droppers, buttons, upgraders |
+| Simulator | references/simulator.md | tools, pets, zones |