From 724d95843763ee07696253495f4c5b9ea11378e2 Mon Sep 17 00:00:00 2001 From: Matthieu Date: Wed, 29 Oct 2025 08:33:12 +0100 Subject: [PATCH] add project structure file --- PROJECT_STRUCTURE.md | 210 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 210 insertions(+) create mode 100644 PROJECT_STRUCTURE.md diff --git a/PROJECT_STRUCTURE.md b/PROJECT_STRUCTURE.md new file mode 100644 index 0000000..160e289 --- /dev/null +++ b/PROJECT_STRUCTURE.md @@ -0,0 +1,210 @@ +# 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 +- `.json` - NPC configuration +- `.json` - Dialogue configuration (if applicable) + +### Datapack Format +``` +datapack.zip +└── data/ + └── cobblemon/ + └── npc/ + ├── configuration/ + │ └── .json + └── dialogues/ + └── .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