From 557ffa7e5318c3c1ba31ec518f0a5b4bbe4a90d1 Mon Sep 17 00:00:00 2001 From: Connor Date: Mon, 12 Jan 2026 04:32:20 +0000 Subject: [PATCH] cursebreaker readme update --- cursebreaker-parser/README.md | 205 ++++++++++++++++++++++++++++++---- 1 file changed, 183 insertions(+), 22 deletions(-) diff --git a/cursebreaker-parser/README.md b/cursebreaker-parser/README.md index 514d9d9..a4d0e1f 100644 --- 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,37 +153,156 @@ 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::(&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 +``` + ## Project Structure ``` cursebreaker-parser/ ├── src/ -│ ├── lib.rs # Library entry point and public API -│ ├── main.rs # Main binary (all-in-one parser) -│ ├── bin/ # Separate parser binaries -│ │ ├── xml-parser.rs # XML parsing only -│ │ ├── scene-parser.rs # Unity scene parsing only -│ │ └── image-parser.rs # Image processing only -│ ├── xml_parser.rs # XML parsing utilities -│ ├── image_processor.rs # Image processing utilities -│ ├── item_loader.rs # Item loading logic -│ ├── databases/ # Database implementations +│ ├── lib.rs # Library entry point and public API +│ ├── main.rs # Main binary (all-in-one parser) +│ ├── bin/ # Separate parser binaries +│ │ ├── xml-parser.rs # XML parsing only +│ │ ├── scene-parser.rs # Unity scene parsing 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 -├── migrations/ # Database migrations -├── Cargo.toml # Package configuration -└── XML_PARSING.md # XML parsing documentation +│ └── 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 +└── 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