string id pattern

Guide for string id pattern

String ID Migration Pattern

Overview

This document describes the pattern for migrating from numeric (u32) item IDs to string-based identifiers across the Legends of Hastinapur codebase.

Motivation

Consistency: The quest system established String IDs as the standard pattern. Skills systems were still using u32, creating inconsistency.

Readability: String IDs like "copper_ore" are more readable than numeric IDs like 1001.

Flexibility: String IDs allow for semantic naming and easier data management without ID collision concerns.

Migration Steps

Step 1: Identify Struct Fields

Find all struct fields that reference item IDs as u32:

grep -r "item_id.*u32" src/

Step 2: Update Rust Structs

Change the field type from u32 to String:

Before:

#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct RockData {
    pub rock_id: String,
    pub name: String,
    pub level_req: u8,
    pub respawn_time: f32,
    pub rock_xp: f32,
    pub ore_item_id: u32,  // ❌ Numeric ID
}

After:

#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct RockData {
    pub rock_id: String,
    pub name: String,
    pub level_req: u8,
    pub respawn_time: f32,
    pub rock_xp: f32,
    pub ore_item_id: String,  // ✅ String ID
}

Step 3: Update Usage Sites

Find all places where the struct is used and update item ID handling:

Before:

add_item_events.send(AddItemEvent {
    entity: event.player,
    item: ItemId(rock_data.ore_item_id),  // u32 wrapped directly
    quantity: 1,
});

After:

add_item_events.send(AddItemEvent {
    entity: event.player,
    item: item_id(&rock_data.ore_item_id),  // String converted via helper
    quantity: 1,
});

Note: The item_id() helper function converts String IDs to ItemId structs. This is defined in src/systems/player/inventory.rs.

Step 4: Verify JSON Data

Ensure JSON data files already use string IDs (they typically do):

{
    "rock_id": "copper_rock",
    "name": "Copper Rock",
    "level_req": 1,
    "respawn_time": 5.0,
    "rock_xp": 17.5,
    "ore_item_id": "copper_ore"  // ✅ Already a string
}

Step 5: Test Compilation

cargo check

Resolve any remaining type mismatches.

Examples

Mining System

File: src/systems/skills/mining.rs

Change: Line 22

- pub ore_item_id: u32,
+ pub ore_item_id: String,

Usage Update: Line 154

  add_item_events.send(AddItemEvent {
      entity: event.player,
-     item: ItemId(rock_data.ore_item_id),
+     item: item_id(&rock_data.ore_item_id),
      quantity: 1,
  });

Woodcutting System

File: src/systems/skills/woodcutting.rs

Change: Line 22

- pub log_item_id: u32,
+ pub log_item_id: String,

Usage Update: Line 175

  add_item_events.send(AddItemEvent {
      entity: event.player,
-     item: ItemId(tree_data.log_item_id),
+     item: item_id(&tree_data.log_item_id),
      quantity: 1,
  });

Tutorial System

File: src/systems/tutorial.rs

Change: Line 39

  pub enum CompletionTrigger {
      OpenInventory,
      EquipItem,
      AttackEnemy,
-     UseItem { item_id: u32 },
+     UseItem { item_id: String },
      TalkToNPC { npc_id: String },
      ReachLocation { x: f32, z: f32, radius: f32 },
      GainXP { skill: String, amount: i32 },
      Custom { event_id: String },
  }

JSON Update: data/tutorials.json

{
    "completion_trigger": {
        "UseItem": {
            "item_id": "rohu"
        }
    }
}

Common Pitfalls

Pitfall 1: Direct ItemId Construction

Wrong:

item: ItemId(string_id),  // ❌ ItemId expects u32

Correct:

item: item_id(&string_id),  // ✅ Use helper function

Pitfall 2: Missing Import

Ensure you import the item_id helper:

use crate::systems::player::inventory::{AddItemEvent, ItemId, item_id};

Pitfall 3: JSON Numeric IDs

If JSON still has numeric IDs, update them:

// ❌ Wrong
{"item_id": 1001}

// ✅ Correct
{"item_id": "copper_ore"}

Verification

After migration, verify:

cargo check passes without type errors
JSON parsing succeeds (check logs for "Loaded X items" messages)
Game runs without panics related to item IDs
Item spawning works correctly in-game

Quest System: See loh_quest_system_refactor KI for the original String ID pattern
Item Database: See src/systems/data/items.rs for item ID lookup implementation