Comprehensive Analysis: Local Character Data vs Character NFT Data
Data Architecture Overview
Flowchart
Critical Data Flow Analysis
Findings 1. Character Data Sources & Priority
| Data Source | Priority | Use Case | Persistence | |----------------|-------------|--------------|----------------| | Blockchain NFT | Primary | Authenticated characters, permanent storage | Blockchain (immutable) | | AuthContext.selectedCharacter | Runtime | Active game state, immediate updates | Memory (session) | | Local Storage | Deprecated | Migration only, being phased out | Browser (temporary) |
Key Finding: Blockchain-First Architecture
The system has been migrated to blockchain-first architecture:
- No local character persistence - localStorage is being deprecated
- All characters MUST be NFTs to be saved
(CharacterService.saveCharacter() rejects non-NFT characters) - AuthContext is the single source of truth for runtime character state
Findings 2. Character NFT Data Structure & Parsing
NFT Metadata Structure (Recently Updated)
// NEW camelCase structure (Hive-compliant)
{
attributes: [
{ trait_type: "coreInfo", value: JSON.stringify({...}) },
{ trait_type: "combatStats", value: JSON.stringify({...}) },
{ trait_type: "gameData", value: JSON.stringify({...}) }
]
}
Data Conversion Pipeline
- Raw NFT Data →
CharacterNFTDataService.parseNFTData() - Parsed NFT Data →
nftToCharacter() in useCharacterNFT.ts - Character Object → Used across all game modules
Findings 3. Potential Conflicts & Their Impact
🔴 HIGH RISK CONFLICTS
A. Data Synchronization Lag
- Issue: Local character updates vs blockchain sync delays
- Impact: Character state can become temporarily inconsistent
- Affected Modules: All gameplay systems
- Current Mitigation:
// AuthContext immediately updates local state
setSelectedCharacter(updatedCharacter);
// Then syncs to blockchain in background
CharacterSyncService.syncCharacterToBlockchain(character);
B. NFT Property Parsing Failures
- Issue: If NFT metadata is malformed or uses old structure
- Impact: Character data could be lost or incorrectly parsed
- Affected Modules: Character loading, stats display, combat calculations
- Current Mitigation: Robust parsing with fallbacks in
CharacterNFTDataService.parseNFTData()
🟡 MEDIUM RISK CONFLICTS
C. Equipment State Desynchronization
- Issue: Equipped items tracked in multiple places
- Impact: Equipment bonuses may not apply correctly
- Affected Modules: Combat stats, durability tracking, NFT equipment
- Code Evidence:
// Equipment can be in character.equipped AND item.equipped property
const equippedItems = character.inventory.filter(item => item.equipped);
const equippedSlots = character.equipped || {};
D. Experience & Level Inconsistencies
- Issue: XP/level calculations vs NFT stored values
- Impact: Level-based features may malfunction
- Affected Modules: Adventure mode, skill points, quest rewards
- Code Evidence:
// Multiple XP calculation methods
const newLevel = Math.floor(newExperience / 100) + 1; // Adventure mode
const xpForLevel = (level - 1) * 100; // Character display
🟢 LOW RISK CONFLICTS
E. Dragon & Inventory Synchronization
- Issue: NFT dragons vs local dragon data
- Impact: Dragon availability discrepancies
- Affected Modules: Dragon hunting, dragon battles
- Current Mitigation:
NFTInventoryService.syncNFTsWithInventory()
Findings 4. Game Module Integration Analysis
Equipment System Integration
// HIGH DEPENDENCY - Directly affects combat stats
DurabilityTracker.applyDamage() → Updates character.inventory
EquipmentService.equipItem() → Updates character.equipped
CharacterSyncService → Syncs equipment changes to blockchain NFT
Adventure Mode Integration
// MEDIUM DEPENDENCY - Affects character progression
QuestRewardService.applyQuestRewards() → Updates character XP/level
useAdventureMode() → Tracks quest progress against character state
CharacterService.gainExperience() → Deprecated, uses AuthContext now
Land NFT & Dungeon Integration
// LOW DEPENDENCY - Separate NFT system but uses character for access
LandManagementService.mintLandNFT() → Independent of character NFT
DungeonService → Uses character level for access requirements
DurabilityTracker → Applies damage from 'land_dungeon' activities
Dragon System Integration
// HIGH DEPENDENCY - Dragons stored in character data
DragonService.addDragon() → Updates character.dragons array
NFTInventoryService.syncNFTsWithInventory() → Syncs dragon NFTs
Findings 5. Critical Gameplay Mechanics Affected
Character Progression Mechanics
| Mechanic | NFT Dependency | Conflict Risk | Mitigation | |-------------|-------------------|------------------|----------------| | Level Up | High - stored in NFT | Medium - XP calculation variations | AuthContext.gainExperience() with blockchain sync | | Skill Points | High - stored in NFT | Low - Simple addition | Calculated from level | | Equipment Stats | High - affects total stats | High - Multiple tracking methods | Equipment validation service | | Dragon Collection | Medium - NFT + local | Medium - Sync issues | NFTInventoryService sync |
Economy & Fee Structures
Character-Related Fees
// Character NFT Operations
- Character Minting: Requires POB tokens (amount TBD)
- Character Updates: Blockchain transaction fees
- Equipment Sync: Custom JSON broadcast fees
// Land NFT Integration
- Land Minting: 25 POB (5% burned, 95% to game)
- Dungeon Access: Character level requirements
- Equipment Durability: Damage from land_dungeon activities
Adventure Mode Rewards
// XP & Progression Rewards
- Quest XP: 10-100 XP per quest (100 XP = 1 level)
- Skill Points: 2 per level gained
- Equipment Rewards: Common to Rare items
// Token Integration
- POB: Primary game token
- SHARD: Staking token for bonuses
- BEE: Community rewards
- PART: Golem Arena requirements
Findings 6. Equipment NFT System Analysis
Current Equipment NFT Handling
// Equipment NFTs are handled through:
1. NFTInventoryService.getCharacterNFTData() - Fetches equipment NFTs
2. DurabilityTracker - Manages equipment durability (NFT metadata updates)
3. EquipmentService - Local equipment state management
4. ItemNFTService - Updates NFT metadata on blockchain
// Integration Points:
- character.inventory[] - Contains all items (NFT + local)
- character.equipped{} - Tracks equipped slot assignments
- item.isNFT & item.nftId - Identifies NFT equipment
- item.durability - Tracked locally and synced to NFT metadata
Equipment NFT Game Mechanics
- Durability System: NFT equipment loses durability from activities
- Repair Costs: POB tokens required for repair
- Auto-Burn: Destroyed equipment NFTs are automatically burned
- Stat Bonuses: Equipment stats affect character combat calculations
Findings 7. Risk Assessment & Recommendations
⚠️ Critical Issues to Address
Equipment State Fragmentation
- Problem: Equipment tracked in character.equipped AND item.equipped
- Fix: Consolidate to single source of truth
XP Calculation Inconsistencies
- Problem: Multiple XP-to-level formulas throughout codebase
- Fix: Create unified ProgressionService with standard formula
NFT Sync Race Conditions
- Problem: Local updates vs blockchain sync timing
- Fix: Implement optimistic updates with rollback capability
✅ Well-Handled Aspects
- AuthContext Integration: Single runtime state management
- Blockchain-First Architecture: Clear data priority hierarchy
- NFT Data Parsing: Robust error handling and fallbacks
- Equipment Durability: Comprehensive NFT metadata updates
🔧 Recommended Improvements
- Implement State Reconciliation: Regular sync checks between local and blockchain state
- Add Conflict Resolution: Handle cases where NFT data differs from local state
- Create Equipment State Validator: Ensure equipment consistency across systems
- Standardize Progression Formulas: Single XP/level calculation service
Conclusion
The current system has successfully transitioned to a blockchain-first architecture with character NFTs as the primary data source. The main conflicts arise from synchronization timing and state fragmentation rather than fundamental architectural issues. The AuthContext serves as an effective runtime state manager, while CharacterSyncService handles blockchain persistence appropriately.
Most Critical Risk: Equipment state inconsistencies that could affect combat stats and gameplay balance.
Most Well-Handled: Character NFT data parsing and adventure mode integration.
Primary Recommendation: Implement comprehensive state validation and reconciliation systems to ensure data consistency across all game modules.
The game is broken but we of the hive are determined to make this work. Enter at your own risk.
