Skip to content

CLAUDE.md

Latest commit

 

History

History
170 lines (136 loc) · 7.27 KB

CLAUDE.md

File metadata and controls

170 lines (136 loc) · 7.27 KB

Project Overview

CommandForgeEditor is a visual scripting tool designed for game developers to create and manage scenario scripts (called "skits") without writing code. It provides an intuitive drag-and-drop interface for assembling sequences of commands that control game flow, dialogue, character actions, and other game events.

Key Features:

  • Visual command arrangement with drag-and-drop functionality
  • Real-time validation of command properties
  • Extensible command system defined in YAML
  • Multi-platform desktop application (Windows, macOS, Linux)
  • Project-based workflow with file system integration
  • Undo/redo, copy/paste, and other productivity features

Target Users: Game developers, scenario writers, and content creators who need to create complex game scripts without programming knowledge.

Essential Commands

Development

cd frontend
npm install           # Install dependencies
npm run dev          # Start development server
npm run tauri:dev    # Start Tauri app in development mode

Testing

cd frontend
npm run test         # Run unit tests
npm run test:watch   # Run tests in watch mode
npm run test:ui      # Run tests with UI
npm run test:e2e     # Run Playwright E2E tests
npm run test:e2e -- --ui  # Run E2E tests in interactive UI mode
npm run test -- --coverage  # Run tests with coverage report

Code Quality

cd frontend
npm run lint         # Run ESLint
npm run build        # Build for production (includes type checking)
npx tsc --noEmit     # Quick type check without building

Build

cd frontend
npm run tauri:build  # Build Tauri app for production

Architecture Overview

This is a desktop application for creating and editing game scenario scripts ("skits") using a no-code approach. The architecture follows a React frontend + Tauri backend pattern:

Core Structure

  • Frontend: React + TypeScript with Vite, located in frontend/
  • Desktop App: Tauri (Rust) wrapper for cross-platform deployment
  • State Management: Zustand with Immer for immutable updates
  • UI: Shadcn UI components with Tailwind CSS
  • Drag & Drop: dnd-kit library for command manipulation
  • Path Aliasing: @/ maps to ./src/ for cleaner imports
  • Validation: AJV for JSON Schema validation of command properties

Key Data Models

  • Commands: Defined in YAML files, represent individual actions/instructions
  • Skits: JSON files containing sequences of commands with metadata
  • Command Definitions: Schema definitions for command types and their properties

Application Flow

  1. Command Loading: commands.yaml defines available command types and their properties
  2. Skit Management: Users create/edit skits by arranging commands in sequences
  3. Real-time Editing: Left panel shows command list, right panel shows selected command properties
  4. File System: Tauri handles file I/O for saving/loading skits and commands

State Management (skitStore.ts)

The main application state includes:

  • skits: All loaded skit files
  • currentSkitId: Currently active skit
  • selectedCommandIds: Multi-select support for commands
  • commandDefinitions: Available command types from YAML
  • validationErrors: Real-time validation feedback
  • history: Undo/redo functionality

Component Hierarchy

App
├── MainLayout
├── Toolbar (undo/redo, save, etc.)
├── CommandList (left panel - skit commands)
├── CommandEditor (right panel - selected command properties)
└── ValidationLog (bottom - error display)

File System Integration

  • Development: Uses sample files via fetch for web preview
  • Production: Tauri APIs for actual file system access
  • Project Structure: commands.yaml + skits/ directory containing JSON files

Reserved Commands

The system includes built-in command types like group_start/group_end for organizing commands into collapsible sections. These are merged with user-defined commands from YAML.

Validation System

Real-time validation using JSON Schema validation (ajv) ensures commands have required properties and correct data types before saving.

i18n System

The project features a dual-layer internationalization system:

  • Fixed translations: UI elements defined in i18n/config.ts
  • Dynamic translations: User-defined command labels loaded from project's i18n/ folder
  • Translation keys: Follow pattern command.<commandId>.property.<propertyKey>.name
  • Custom hook: useCommandTranslation() for command-specific translations
  • Current default: Japanese (lng: 'ja' in config.ts)

Development Notes

  • The project supports both web development (using sample data) and Tauri desktop app modes
  • All file operations must use Tauri APIs in production builds
  • Command definitions are hot-reloadable during development
  • The UI is fully keyboard accessible with shortcut support
  • Multi-select operations (copy/cut/paste/delete) work across command groups
  • Drag and drop reordering maintains proper command relationships
  • Test files are colocated with source files (*.test.ts alongside *.ts)
  • E2E tests include visual regression testing with screenshots
  • Vite base URL changes for GitHub Actions deployment

Documentation

Comprehensive documentation is available in memory-bank/doc/:

  • Overview and architecture details
  • Data models and component structure
  • Development guide and API reference
  • Testing strategy and troubleshooting

Additional specifications in specification/:

  • I18N_SPECIFICATION.md: Complete i18n system design
  • TMP_SUBROUTINE_SPECIFICATION.md: Planned subroutine feature (future)
  • TMP_VARIABLE_SPECIFICATION.md: Planned variable system (future)

MCP Browser Automation

This project can be tested and demonstrated using Playwright MCP (Model Control Protocol) for browser automation. The application runs on http://localhost:5173/ in development mode.

UI Testing with MCP

Available MCP Playwright Operations:

  • mcp__playwright__browser_navigate: Navigate to the development server
  • mcp__playwright__browser_snapshot: Capture accessibility tree for UI analysis
  • mcp__playwright__browser_click: Interact with UI elements
  • mcp__playwright__browser_type: Input text into form fields
  • mcp__playwright__browser_select_option: Choose dropdown options

Key UI Areas for Testing:

  1. Skit List (Left panel): Shows available skits and creation options
  2. Command List (Center panel): Displays numbered commands with drag handles
  3. Command Editor (Right panel): Properties panel for selected commands
  4. Toolbar: Action buttons (add, copy, cut, paste, delete, save)
  5. Language Switcher: i18n language selection dropdown

Important: Please keep the documentation updated when making significant changes to the codebase. This includes:

  • Adding new features or components
  • Changing data models or API interfaces
  • Modifying the build process or dependencies
  • Updating development workflows

Development Best Practices

Implementation Completion Checklist

  • 必ず実行すべきビルドとテストのチェック:
    • 実装が終わったあとは、frontendディレクトリで必ずnpm run buildとnpm run testを実行する
    • これにより、ビルドエラーがないことと、テストがすべてパスすることを確認する