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

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