matthieu/npc-config-app
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

add project structure file

Browse Source
This commit is contained in:
Matthieu
2025-10-29 08:33:12 +01:00
parent fb9443d79c
commit 724d958437
1 changed files with 210 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

210
PROJECT_STRUCTURE.md Normal file
View File

@@ -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
- `<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