npc-config-app/PROJECT_STRUCTURE.md

# Cobblemon NPC Creator - Project Structure

## Project Overview

**Cobblemon NPC Creator** is a comprehensive web application designed for creating and customizing Non-Player Characters (NPCs) for the Cobblemon Minecraft mod. This tool provides a visual interface for configuring NPC behavior, dialogue systems, battle configurations, and Pokemon parties, then exports them as JSON files compatible with the Cobblemon mod.

### Purpose

The application simplifies the complex process of creating NPCs for Cobblemon by:
- Providing an intuitive UI for NPC configuration
- Offering real-time validation and error checking
- Supporting visual dialogue tree creation with MoLang expressions
- Integrating with the Pokemon API for accurate Pokemon data
- Generating properly formatted JSON files for mod integration

## Technology Stack

- **Frontend Framework**: React 19.1.1
- **Language**: TypeScript 5.8.3
- **Build Tool**: Vite 7.1.0
- **Styling**: Tailwind CSS 3.4.17 with @tailwindcss/forms plugin
- **Icons**: Lucide React 0.539.0
- **File Handling**: JSZip 3.10.1 (for datapack export), file-saver 2.0.5
- **Linting**: ESLint 9.32.0
- **Node**: 22.12.0 (managed via Volta)

## Project Arborescence

```
npc-config-app/
│
├── public/                          # Static assets
│   └── vite.svg                     # Vite logo
│
├── src/                             # Source code directory
│   ├── components/                  # React components
│   │   ├── ConfigVariablesEditor.tsx    # Editor for MoLang config variables
│   │   ├── DialogueEditor.tsx           # Visual dialogue tree editor
│   │   ├── ImportExport.tsx             # Import/Export functionality with datapack support
│   │   ├── JSONPreview.tsx              # JSON output preview component
│   │   ├── NPCBasicSettings.tsx         # Basic NPC configuration (name, model, etc.)
│   │   ├── NPCBattleConfiguration.tsx   # Battle-related settings (victory, defeat, flee)
│   │   ├── NPCInteractionEditor.tsx     # Interaction system configuration
│   │   ├── NPCPartyBuilder.tsx          # Pokemon party management interface
│   │   ├── PokemonCard.tsx              # Individual Pokemon display card
│   │   ├── PokemonFormSelector.tsx      # Pokemon form/variant selector
│   │   ├── PokemonSelector.tsx          # Pokemon search and selection interface
│   │   └── ValidationPanel.tsx          # Real-time validation and error display
│   │
│   ├── services/                    # External services and APIs
│   │   └── pokemonApi.ts            # Pokemon API integration (PokeAPI)
│   │
│   ├── types/                       # TypeScript type definitions
│   │   └── npc.ts                   # NPC configuration type definitions
│   │
│   ├── utils/                       # Utility functions
│   │   └── validation.ts            # Validation logic for NPC configurations
│   │
│   ├── App.css                      # Application-specific styles
│   ├── App.tsx                      # Main application component
│   ├── index.css                    # Global styles and Tailwind directives
│   ├── main.tsx                     # Application entry point
│   └── vite-env.d.ts               # Vite environment type declarations
│
├── .claude/                         # Claude Code configuration
├── .git/                            # Git repository data
├── .idea/                           # IntelliJ IDEA configuration
│
├── .gitignore                       # Git ignore rules
├── eslint.config.js                 # ESLint configuration
├── index.html                       # HTML entry point
├── package.json                     # Project dependencies and scripts
├── package-lock.json                # Locked dependency versions
├── POKEMON_FEATURES.md              # Pokemon feature documentation
├── postcss.config.js                # PostCSS configuration for Tailwind
├── README.md                        # Project readme and quick start guide
├── tailwind.config.js               # Tailwind CSS configuration
├── tsconfig.json                    # TypeScript configuration (base)
├── tsconfig.app.json                # TypeScript configuration for app
├── tsconfig.node.json               # TypeScript configuration for Node.js
└── vite.config.ts                   # Vite build configuration
```

## Directory Structure Explained

### `/src/components/`
Contains all React components organized by functionality:

**Core Configuration Components:**
- `NPCBasicSettings.tsx` - Handles basic NPC properties like name, model, texture
- `NPCBattleConfiguration.tsx` - Manages battle-related configurations
- `NPCInteractionEditor.tsx` - Controls interaction system setup
- `ConfigVariablesEditor.tsx` - Editor for MoLang configuration variables

**Pokemon Party Components:**
- `NPCPartyBuilder.tsx` - Main interface for building Pokemon teams
- `PokemonSelector.tsx` - Search and select Pokemon from the API
- `PokemonCard.tsx` - Displays individual Pokemon with stats
- `PokemonFormSelector.tsx` - Allows selection of Pokemon forms/variants

**Dialogue & Export Components:**
- `DialogueEditor.tsx` - Visual dialogue tree editor with node-based interface
- `ImportExport.tsx` - JSON export/import with datapack generation
- `JSONPreview.tsx` - Live preview of generated JSON
- `ValidationPanel.tsx` - Real-time validation feedback

### `/src/services/`
External service integrations:
- `pokemonApi.ts` - Interfaces with PokeAPI for Pokemon data (sprites, forms, stats)

### `/src/types/`
TypeScript type definitions:
- `npc.ts` - Complete type definitions for NPC configuration objects

### `/src/utils/`
Utility functions:
- `validation.ts` - Validation rules and error checking for NPC configurations

### Root Configuration Files

- **`package.json`** - Defines project metadata, dependencies, and npm scripts
- **`vite.config.ts`** - Vite bundler configuration
- **`tailwind.config.js`** - Tailwind CSS customization
- **`tsconfig.*.json`** - TypeScript compiler configurations
- **`eslint.config.js`** - Code linting rules
- **`postcss.config.js`** - PostCSS plugins (Tailwind, Autoprefixer)

## Key Features

### 1. NPC Configuration
- Basic settings (name, model, texture, cooldown)
- Battle configuration (victory/defeat/flee scripts)
- Party building with up to 6 Pokemon
- Interaction system setup

### 2. Dialogue System
- Visual tree-based dialogue editor
- Support for MoLang expressions
- Multiple action types per dialogue node
- Import/export dialogue configurations

### 3. Pokemon Integration
- Real-time Pokemon search via PokeAPI
- Form/variant selection
- Automatic sprite loading
- Level and shiny status configuration

### 4. Import/Export
- JSON preview with syntax highlighting
- Export as individual JSON files
- Export as Minecraft datapack (ZIP format)
- Import existing configurations

### 5. Validation
- Real-time error checking
- Warning system for potential issues
- Required field validation
- MoLang expression validation

## Development Workflow

### Available Scripts

```bash
npm run dev      # Start development server (Vite)
npm run build    # Build for production (TypeScript + Vite)
npm run lint     # Run ESLint
npm run preview  # Preview production build
```

### Development Server
- Runs on `http://localhost:5173`
- Hot Module Replacement (HMR) enabled
- TypeScript type checking on save

## Data Flow

1. **User Input** → Components update React state
2. **State Changes** → Validation utils check for errors
3. **Valid Data** → JSON Preview updates in real-time
4. **Export Action** → Files generated via file-saver/JSZip
5. **Pokemon Search** → API service fetches from PokeAPI
6. **Import Action** → JSON parsed and state populated

## Export Formats

### Individual Files
- `<npc-name>.json` - NPC configuration
- `<dialogue-name>.json` - Dialogue configuration (if applicable)

### Datapack Format
```
datapack.zip
└── data/
    └── cobblemon/
        └── npc/
            ├── configuration/
            │   └── <npc-name>.json
            └── dialogues/
                └── <dialogue-name>.json
```

## Future Considerations

Based on the project structure, potential areas for expansion:
- Additional component categories (quests, rewards)
- More sophisticated validation rules
- Custom Pokemon sprite support
- Multi-language dialogue support
- Template system for common NPC types