cursebreaker readme update

2026-01-12 04:32:20 +00:00
parent 8403e84cef
commit 45a1f5f7dd
1 changed files with 183 additions and 22 deletions
--- a/cursebreaker-parser/README.md
+++ b/cursebreaker-parser/README.md
@@ -6,7 +6,8 @@ A Rust library for parsing and managing game data from the Cursebreaker game. Th

 Cursebreaker Parser is designed to:
 - Parse Unity scenes and extract game objects using the unity-parser library
- Load game data from XML files (Items, NPCs, Quests, Harvestables, Loot tables)
+- Load game data from XML files (Items, NPCs, Quests, Harvestables, Loot tables, Maps, Fast Travel, Player Houses, Traits, Shops)
+- Process and compress minimap tiles and item images
 - Provide in-memory databases for efficient querying of game data
 - Serialize game data to SQL format for database storage

@@ -17,8 +18,16 @@ Cursebreaker Parser is designed to:
 - **Quest Database**: Handle quest definitions, phases, and rewards
 - **Harvestable Database**: Track harvestable resources and their drop tables
 - **Loot Database**: Manage loot tables and drop configurations
+- **Map Database**: Handle map data and navigation
+- **Fast Travel Database**: Manage fast travel locations and connections
+- **Player House Database**: Track player houses and their locations
+- **Trait Database**: Handle character traits and their effects
+- **Shop Database**: Manage shop inventories and pricing
+- **Minimap Database**: Process and manage minimap tiles with multiple zoom levels
 - **XML Parsing**: Robust XML parsing with error handling
 - **SQL Export**: Prepare data for SQL database insertion
+- **Image Processing**: Process and compress minimap tiles and item icons
+- **Unity Scene Parsing**: Extract game objects and world resources from Unity scenes

 ## Binaries

@@ -33,8 +42,10 @@ The project provides multiple binaries to handle different parsing tasks. This a
   cargo run --bin xml-parser
   ```

-2. **scene-parser** - Parses Unity scenes and extracts game objects
+2. **scene-parser** - Parses Unity scenes and extracts world resource locations
   - Slow execution (Unity project initialization)
+   - Extracts InteractableResource components and their positions
+   - Saves to `world_resources` table (item_id and 2D coordinates)
   - Run this when scene files change
   ```bash
   cargo run --bin scene-parser
@@ -56,6 +67,26 @@ The project provides multiple binaries to handle different parsing tasks. This a
   cargo run
   ```

+5. **verify-db** - Verifies database contents and shows basic statistics
+   ```bash
+   cargo run --bin verify-db
+   ```
+
+6. **verify-expanded-db** - Verifies expanded database schema with items, recipes, and stats
+   ```bash
+   cargo run --bin verify-expanded-db
+   ```
+
+7. **verify-images** - Verifies item images and shows storage statistics
+   ```bash
+   cargo run --bin verify-images
+   ```
+
+8. **verify-stats** - Verifies item stats and shows breakdown by type
+   ```bash
+   cargo run --bin verify-stats
+   ```
+
 ### Building for Production

 Build specific binaries for release:
@@ -122,6 +153,91 @@ for (id, name, json) in sql_data.iter().take(5) {
 }
 ```

+### Querying World Resources
+
+```rust
+use diesel::prelude::*;
+use diesel::sqlite::SqliteConnection;
+
+// Connect to database
+let mut conn = SqliteConnection::establish("../cursebreaker.db")?;
+
+// Define the structure
+#[derive(Queryable, Debug)]
+struct WorldResource {
+    item_id: i32,
+    pos_x: f32,
+    pos_y: f32,
+}
+
+// Query resources by item ID
+use cursebreaker_parser::schema::world_resources::dsl::*;
+
+let copper_ore = world_resources
+    .filter(item_id.eq(2))
+    .load::<WorldResource>(&mut conn)?;
+
+println!("Found {} copper ore nodes", copper_ore.len());
+for resource in copper_ore {
+    println!("  Position: ({:.2}, {:.2})", resource.pos_x, resource.pos_y);
+}
+```
+
+See `examples/query_world_resources.rs` for a complete example.
+
+### Additional Databases
+
+Similar APIs are available for other game data types:
+
+```rust
+use cursebreaker_parser::{
+    MapDatabase, FastTravelDatabase, PlayerHouseDatabase,
+    TraitDatabase, ShopDatabase, MinimapDatabase
+};
+
+// Load maps, fast travel points, player houses, etc.
+let map_db = MapDatabase::load_from_xml("Data/XMLs/Maps/Map.xml")?;
+// ... similar usage patterns
+```
+
+See the examples directory for usage of each database type.
+
+### Database Verification
+
+After parsing data, you can verify the database contents using the verification binaries:
+
+```bash
+# Basic database verification
+cargo run --bin verify-db
+
+# Verify expanded schema with recipes and stats
+cargo run --bin verify-expanded-db
+
+# Check item images and storage usage
+cargo run --bin verify-images
+
+# Analyze item stats breakdown
+cargo run --bin verify-stats
+```
+
+### Examples
+
+The project includes several example programs demonstrating different aspects of the parser:
+
+- **game_data_demo.rs** - Comprehensive demo loading and querying all game data types (Items, NPCs, Quests, Harvestables, Loot)
+- **item_database_demo.rs** - Focused on item database operations
+- **query_world_resources.rs** - Querying world resource locations from the database
+- **fast_travel_example.rs** - Working with fast travel locations
+- **maps_example.rs** - Map data handling
+- **player_houses_example.rs** - Player house management
+- **shops_example.rs** - Shop inventory and pricing
+- **traits_example.rs** - Character traits and effects
+
+Run any example with:
+```bash
+cargo run --example <example_name>
+```
+
 ## Project Structure

 ```
@@ -132,27 +248,61 @@ cursebreaker-parser/
 │   ├── bin/                      # Separate parser binaries
 │   │   ├── xml-parser.rs         # XML parsing only
 │   │   ├── scene-parser.rs       # Unity scene parsing only
-│   │   └── image-parser.rs # Image processing only
+│   │   ├── image-parser.rs       # Image processing only
+│   │   ├── verify-db.rs          # Database verification
+│   │   ├── verify-expanded-db.rs # Expanded database verification
+│   │   ├── verify-images.rs      # Image verification
+│   │   └── verify-stats.rs       # Stats verification
 │   ├── xml_parser.rs             # XML parsing utilities
 │   ├── image_processor.rs        # Image processing utilities
 │   ├── item_loader.rs            # Item loading logic
+│   ├── schema.rs                 # Database schema definitions
 │   ├── databases/                # Database implementations
 │   │   ├── item_database.rs
 │   │   ├── npc_database.rs
 │   │   ├── quest_database.rs
 │   │   ├── harvestable_database.rs
 │   │   ├── loot_database.rs
+│   │   ├── map_database.rs
+│   │   ├── fast_travel_database.rs
+│   │   ├── player_house_database.rs
+│   │   ├── trait_database.rs
+│   │   ├── shop_database.rs
 │   │   └── minimap_database.rs
 │   └── types/                    # Type definitions
 │       ├── cursebreaker/         # Game-specific types (Items, NPCs, Quests, etc.)
 │       └── monobehaviours/       # Unity MonoBehaviour types
 ├── examples/                     # Example usage
+│   ├── fast_travel_example.rs
+│   ├── game_data_demo.rs
+│   ├── item_database_demo.rs
+│   ├── maps_example.rs
+│   ├── player_houses_example.rs
+│   ├── query_world_resources.rs
+│   ├── shops_example.rs
+│   └── traits_example.rs
 ├── migrations/                   # Database migrations
 ├── Cargo.toml                   # Package configuration
-└── XML_PARSING.md         # XML parsing documentation
+├── XML_PARSING.md               # XML parsing documentation
+└── README.md                    # This file

 ```

+## Database Schema
+
+The parser uses Diesel for database operations with SQLite. Database migrations are located in the `migrations/` directory and handle:
+
+- Item data with stats, images, and crafting recipes
+- NPC information and loot tables
+- Quest definitions and phases
+- Harvestable resources and drop tables
+- World resource locations from Unity scenes
+- Minimap tiles and metadata
+- Shop inventories and pricing
+- Player houses and locations
+- Fast travel points
+- Character traits
+
 ## Dependencies

 - **unity-parser**: For parsing Unity scene files
@@ -161,7 +311,8 @@ cursebreaker-parser/
 - **serde_json**: JSON support
 - **serde_yaml**: YAML support
 - **sparsey**: ECS (Entity Component System) support
- **diesel**: Optional SQL database support
+- **diesel**: SQL database support with SQLite
+- **image**: Image processing and WebP compression
 - **thiserror**: Error handling

 ## Building
@@ -173,8 +324,18 @@ cargo build
 # Run tests
 cargo test

-# Build with SQL support
-cargo build --features diesel
+# Build specific binaries
+cargo build --bin xml-parser
+cargo build --bin scene-parser
+cargo build --bin image-parser
+cargo build --bin verify-db
+
+# Run examples
+cargo run --example game_data_demo
+cargo run --example item_database_demo
+
+# Build for release
+cargo build --release
 ```

 ## Documentation