Struct PraedaGenerator 

pub struct PraedaGenerator { /* private fields */ }

The main procedural loot generator.

PraedaGenerator creates randomized game items with qualities, types, affixes, and attributes. Configure it with item definitions, qualities (rarity tiers), affixes, and attributes, then call generate_loot to produce items.

Configuration Methods

• Qualities: set_quality_data, has_quality
• Item Types: set_item_type, set_item_subtype
• Item Names: set_item
• Attributes: set_attribute
• Affixes (prefixes/suffixes): set_affix, set_affix_attribute

Generation

• generate_loot - Generate items and return as Vec<Item>
• generate_loot_json - Generate items and return as JSON string

Example

use praeda::{PraedaGenerator, GeneratorOptions};

let mut generator = PraedaGenerator::new();
generator.set_quality_data("common".to_string(), 100);
generator.set_quality_data("rare".to_string(), 30);

generator.set_item_type("weapon".to_string(), 2);
generator.set_item_subtype("weapon".to_string(), "sword".to_string(), 5);

generator.set_item("weapon".to_string(), "sword".to_string(), vec![
    "Iron Sword".to_string(),
    "Steel Sword".to_string(),
]);

let options = GeneratorOptions {
    number_of_items: 5,
    base_level: 10.0,
    level_variance: 2.0,
    affix_chance: 0.25,
    linear: true,
    scaling_factor: 1.5,
};

let items = generator.generate_loot(&options, &Default::default(), "loot_key")?;
for item in items {
    println!("Got: {}", item.name);
}

Implementations

impl PraedaGenerator

pub fn new() -> Self

Creates a new empty generator.

The generator starts with no quality data, item types, or attributes. Configure it using the various setter methods before calling generate_loot.

Example

let mut generator = PraedaGenerator::new();
generator.set_quality_data("common".to_string(), 100);
// ... configure more ...
let items = generator.generate_loot(&options, &Default::default(), "key")?;

pub fn set_quality_data(&mut self, quality: &str, weight: i32)

Adds or updates a quality tier with a relative weight.

Quality tiers define rarity levels (common, rare, legendary, etc.). The weight determines the probability of this quality being selected during generation. Higher weights = more likely to be selected.

Arguments

• quality - Name of the quality tier (e.g., “common”, “rare”, “legendary”)
• weight - Relative weight for selection (e.g., common=100, rare=30, legendary=5)

Example

generator.set_quality_data("common".to_string(), 100);
generator.set_quality_data("uncommon".to_string(), 50);
generator.set_quality_data("rare".to_string(), 20);
generator.set_quality_data("legendary".to_string(), 5);

pub fn get_quality_data(&self) -> &HashMap<String, i32>

Get all quality data

pub fn has_quality(&self, quality: &str) -> bool

Check if a quality exists

pub fn set_item_type(&mut self, type_name: &str, weight: i32)

Adds or updates an item type with a relative weight.

Item types are categories like “weapon”, “armor”, “accessory”, etc. The weight determines the probability of this type being selected during generation.

Arguments

• type_name - Name of the item type
• weight - Relative weight for selection

Example

generator.set_item_type("weapon".to_string(), 3);
generator.set_item_type("armor".to_string(), 2);
generator.set_item_type("accessory".to_string(), 1);

pub fn get_item_type(&self, type_name: &str) -> Option<&ItemType>

Get item type by name

pub fn get_item_types(&self) -> &[ItemType]

Get all item types

pub fn has_item_type(&self, type_name: &str) -> bool

Check if item type exists

pub fn set_item_subtype(&mut self, type_name: &str, subtype: &str, weight: i32)

Adds or updates a subtype within an item type.

Subtypes are more specific categories within a type (e.g., “sword”, “axe” within “weapon”). The weight determines the probability of this subtype being selected when that item type is chosen.

Arguments

• type_name - The parent item type
• subtype - Name of the subtype
• weight - Relative weight for selection within this type

Example

generator.set_item_type("weapon".to_string(), 2);
generator.set_item_subtype("weapon".to_string(), "sword".to_string(), 3);
generator.set_item_subtype("weapon".to_string(), "axe".to_string(), 2);
generator.set_item_subtype("weapon".to_string(), "bow".to_string(), 1);

pub fn has_item_subtype(&self, type_name: &str, subtype: &str) -> bool

Check if subtype exists for a type

pub fn get_subtypes_for_type(&self, item_type: &str) -> Vec<String>

Get all subtypes for a specific item type

pub fn get_weapon_subtypes(&self) -> Vec<String>

Get all weapon subtypes (convenience method for “Weapon” type)

pub fn get_item_names(&self, item_type: &str, subtype: &str) -> Vec<String>

Get item names for a specific type and subtype

pub fn get_item_type_names(&self) -> Vec<String>

Get all item types as a list of strings

pub fn set_subtype_metadata( &mut self, item_type: &str, subtype: &str, key: &str, value: Value, )

Set metadata for a specific subtype

pub fn get_subtype_metadata( &self, item_type: &str, subtype: &str, key: &str, ) -> Option<&Value>

Get metadata for a specific subtype

pub fn get_all_subtype_metadata( &self, item_type: &str, subtype: &str, ) -> Option<&HashMap<String, Value>>

Get all metadata for a specific subtype

pub fn set_item_name_metadata( &mut self, item_type: &str, subtype: &str, item_name: &str, key: &str, value: Value, )

Set metadata for a specific item name

pub fn get_item_name_metadata( &self, item_type: &str, subtype: &str, item_name: &str, key: &str, ) -> Option<&Value>

Get metadata for a specific item name

pub fn get_all_item_name_metadata( &self, item_type: &str, subtype: &str, item_name: &str, ) -> Option<&HashMap<String, Value>>

Get all metadata for a specific item name

pub fn set_attribute( &mut self, type_name: &str, subtype: &str, attribute: ItemAttribute, )

Adds or updates an attribute for a type/subtype.

Attributes are custom properties on items (e.g., damage, defense, health, mana). When an item of this type/subtype is generated, all configured attributes are applied to it.

If an attribute with the same name already exists, its initial value is added to the existing value.

Arguments

• type_name - The item type
• subtype - The item subtype
• attribute - The ItemAttribute to add

Example

let damage_attr = ItemAttribute::new(
    "damage".to_string(),
    5.0,  // initial value
    1.0,  // min
    10.0, // max
    true, // required
    1.0,  // scaling factor
    1.0,  // chance
);
generator.set_attribute("weapon".to_string(), "sword".to_string(), damage_attr);

pub fn has_attribute( &self, type_name: &str, subtype: &str, attr_name: &str, ) -> bool

Check if attribute exists

pub fn set_item(&mut self, type_name: &str, subtype: &str, names: Vec<&str>)

Sets the possible item names for a type/subtype combination.

When an item of this type/subtype is generated, one name is randomly selected from this list. If no names are provided for a type/subtype, the subtype name is used as the item name.

Arguments

• type_name - The item type
• subtype - The item subtype
• names - Vector of possible item names

Example

generator.set_item("weapon".to_string(), "sword".to_string(), vec![
    "Iron Sword".to_string(),
    "Steel Sword".to_string(),
    "Longsword".to_string(),
    "Great Sword".to_string(),
]);

pub fn set_affix_attribute( &mut self, type_name: &str, subtype: &str, is_prefix: bool, affix_name: &str, attribute: ItemAttribute, )

Adds an attribute to a prefix or suffix affix.

Affixes (prefixes and suffixes) are optional name modifiers that can be added to items. Each affix can have multiple attributes that get applied to generated items.

Arguments

• type_name - The item type
• subtype - The item subtype
• is_prefix - true for prefix, false for suffix
• affix_name - Name of the affix (e.g., “Flaming”, “of Strength”)
• attribute - The ItemAttribute this affix applies

Example

generator.set_affix("weapon".to_string(), "sword".to_string());

let fire_damage = ItemAttribute::new(
    "damage".to_string(),
    3.0,  // fire damage bonus
    0.0,
    5.0,
    false,
    1.0,
    1.0,
);

generator.set_affix_attribute(
    "weapon".to_string(),
    "sword".to_string(),
    true,  // is_prefix
    "Flaming".to_string(),
    fire_damage,
);

pub fn set_prefix_attribute( &mut self, type_name: &str, subtype: &str, affix_name: &str, attribute: ItemAttribute, )

Convenience method to add a prefix attribute. Equivalent to calling set_affix_attribute with is_prefix = true.

pub fn set_suffix_attribute( &mut self, type_name: &str, subtype: &str, affix_name: &str, attribute: ItemAttribute, )

Convenience method to add a suffix attribute. Equivalent to calling set_affix_attribute with is_prefix = false.

pub fn get_prefixes(&self, type_name: &str, subtype: &str) -> Vec<Affix>

Get prefixes for a type/subtype

pub fn get_suffixes(&self, type_name: &str, subtype: &str) -> Vec<Affix>

Get suffixes for a type/subtype

pub fn load_data(&mut self, toml_data: &str) -> Result<()>

Loads generator configuration from a TOML string.

TOML is the preferred format for configuration as it’s human-readable and works well with the generator’s structure.

Arguments

• toml_data - TOML configuration string

Example

let toml_str = r#"
[quality_data]
common = 100
rare = 30

[[item_types]]
item_type = "weapon"
weight = 2
"#;

generator.load_data(toml_str)?;

pub fn load_data_from_file(&mut self, path: &str) -> Result<()>

Loads generator configuration from a TOML file.

This is the recommended way to configure a generator - create a TOML file with your loot definitions and load it directly.

Arguments

• path - Path to the TOML configuration file

Example

let mut generator = PraedaGenerator::new();
generator.load_data_from_file("loot_config.toml")?;
let items = generator.generate_loot(&options, &Default::default(), "key")?;

pub fn generate_loot( &mut self, options: &GeneratorOptions, overrides: &GeneratorOverrides, key: &str, ) -> Result<Vec<Item>>

Generates a collection of items based on the provided options.

Creates options.number_of_items items with random qualities, types, affixes, and attributes. The generated items are also stored internally and can be retrieved using get_loot.

Arguments

• options - GeneratorOptions controlling generation parameters
• overrides - GeneratorOverrides for optional per-generation customization
• key - A string key to identify and later retrieve these items

Returns

A Result containing a Vec<Item> with the generated items.

Errors

Returns an error if:

• No item types are configured
• No qualities are configured
• Item type/subtype configuration is incomplete

Example

let options = GeneratorOptions {
    number_of_items: 5,
    base_level: 10.0,
    level_variance: 2.0,
    affix_chance: 0.25,
    linear: true,
    scaling_factor: 1.5,
};

let items = generator.generate_loot(&options, &Default::default(), "bosses_loot")?;

pub fn generate_loot_json( &mut self, options: &GeneratorOptions, overrides: &GeneratorOverrides, key: &str, ) -> Result<String>

Generate loot and return as JSON string

pub fn get_loot(&self, key: &str) -> Vec<Item>

Get previously generated loot by key

pub fn get_loot_json(&self, key: &str) -> Result<String>

Get previously generated loot as JSON by key

Trait Implementations

impl Default for PraedaGenerator

fn default() -> Self

Returns the “default value” for a type.