add project structure file
This commit is contained in:
210
PROJECT_STRUCTURE.md
Normal file
210
PROJECT_STRUCTURE.md
Normal 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
|
||||||
Reference in New Issue
Block a user