Dynamic Loot Items + Computed Adventurers Statistics

[ponderingdemocritus]

Here I outline how I think on-chain statistics for the individual Loot items should be stored and computed. This pattern could really be used for any game statistics system.

Loot has ~100 items and since we are creating an on-chain MMO we need an efficient DRY way to store all this information. Then we need an easy way to pull all this information together into one final statistics amount for the Adventurer. Luckily we can leverage the computation of Cairo to do so.

An item could be thought of as having the following properties (this is by no means finished and will require discussion)

struct Item:
    member Id : felt  # item id 1 - 100
    member Class : felt  # loot item class
    member Slot : felt  # head, chest, waist, feet, hands, neck, ring, weapon
    member Agility : felt  # Computed Agility of the item
    member Attack : felt  # Computed Attack of the item
    member Armour : felt  # Computed Armour of the item
    member Wisdom : felt  # Computed Wisdom of the item
    member Vitality : felt  # Computed Vitality of the item
    member Prefix : felt  # Stored value if item has a Prefix
    member Suffix : felt  # Stored value if item has a Suffix
    member Order : felt  # Stored value if item has a Order
    member Bonus : felt  # Stored value if item has a Bonus
    member Level : felt  # Stored value if item has a Level
    member Age : felt  # Timestamp of when item was created
    member XP : felt  # accured XP
end

Since the number of items is infinite, we need to store minimal state but have the ability to compute values on the fly for gameplay.

We can create an easy way to fetch information by mapping every item to an id like so:

namespace ItemIds:
    const Pendant = 1
    const Necklace = 2
    const Amulet = 3
    const SilverRing = 4
    const BronzeRing = 5
    ....
end

Now we have an index mapping above, we can create a new namespace for each base stat like so:

namespace ItemAgility:
    const Pendant = 10
    const Necklace = 10
    const Amulet = 10
    const SilverRing = 10
    const BronzeRing = 10
    const PlatinumRing = 10
    const TitaniumRing = 10
    ....
end

After this, we need a way to fetch each item's computed values which remember are:

struct Item:
   ...
    member Agility : felt # Computed Agility of the item
    member Attack : felt # Computed Attack of the item
    member Armour : felt # Computed Armour of the item
    member Wisdom : felt # Computed Wisdom of the item
    member Vitality : felt # Computed Vitality of the item
    ...
end

See full file here

Cairo has a very nice way of storing information in labels which can be fetched much like an array. The following function takes in the ItemId and will return the agility value of the item.

func base_agility{syscall_ptr : felt*, range_check_ptr}(item_id : felt) -> (agility : felt):
        alloc_locals

        let (type_label) = get_label_location(item_agility)

        return ([type_label + item_id - 1])
        
        # NOTE: The position of the values below matter, these are indexed
        item_agility:
        dw ItemAgility.Pendant # We map the namespace to the index to make it human-readable.
        dw ItemAgility.Necklace
        dw ItemAgility.Amulet
        dw ItemAgility.SilverRing
        ...
end

This pattern can be repeated for each statistic.

Now that we can easily fetch each item's base value we can compute them in any way we need. The following is an example (This function is incomplete so it will not work but hopefully explains my thinking.

    func calculate_item_stats{syscall_ptr : felt*, range_check_ptr}(item : Item) -> (
        Agility, Attack, Armour, Wisdom, Vitality
    ):
        alloc_locals

        # computed
        let (Agility) = base_agility(item.Id)
        let (Attack) = base_attack(item.Id)
        let (Armour) = base_armour(item.Id)
        let (Wisdom) = base_wisdom(item.Id)
        let (Vitality) = base_vitality(item.Id)

        return (Agility, Attack, Armour, Wisdom, Vitality)
    end

Now we have these items' statistics we can create a function in the Adventurers contract that pulls all of this information together according to what values the player has equipped. This final value can then be used for gameplay!

We do need to define an Adventurer struct first

struct Adventurer:
    member Class : felt
    member Agility : felt
    member Attack : felt
    member Armour : felt
    member Wisdom : felt
    member Vitality : felt
    member Neck : felt
    member Weapon : felt
    member Ring : felt
    member Chest : felt
    member Head : felt
    member Waist : felt
    member Feet : felt
    member Hands : felt
    member Age : felt
    member Name : felt
    member XP : felt
end

Then we compute it all together!

    func calculate_adventurer_stats{syscall_ptr : felt*, range_check_ptr}(
        weapon : Item,
        chest : Item,
        head : Item,
        waist : Item,
        feet : Item,
        hands : Item,
        neck : Item,
        ring : Item,
    ) -> (Agility, Attack, Armour, Wisdom, Vitality):
        alloc_locals

        # computed
        let (
            weapon_agility, weapon_attack, weapon_armour, weapon_wisdom, weapon_vitality
        ) = LootItems.calculate_item_stats(weapon)
        let (
            chest_agility, chest_attack, chest_armour, chest_wisdom, chest_vitality
        ) = LootItems.calculate_item_stats(chest)
        let (
            head_agility, head_attack, head_armour, head_wisdom, head_vitality
        ) = LootItems.calculate_item_stats(head)
        let (
            waist_agility, waist_attack, waist_armour, waist_wisdom, waist_vitality
        ) = LootItems.calculate_item_stats(waist)
        let (
            feet_agility, feet_attack, feet_armour, feet_wisdom, feet_vitality
        ) = LootItems.calculate_item_stats(feet)
        let (
            hands_agility, hands_attack, hands_armour, hands_wisdom, hands_vitality
        ) = LootItems.calculate_item_stats(hands)
        let (
            neck_agility, neck_attack, neck_armour, neck_wisdom, neck_vitality
        ) = LootItems.calculate_item_stats(neck)
        let (
            ring_agility, ring_attack, ring_armour, ring_wisdom, ring_vitality
        ) = LootItems.calculate_item_stats(ring)

        let agility = weapon_agility + chest_agility + head_agility + waist_agility + feet_agility + hands_agility + neck_agility + ring_agility
        let attack = weapon_attack + chest_attack + head_attack + waist_attack + feet_attack + hands_attack + neck_attack + ring_attack
        let armour = weapon_armour + chest_armour + head_armour + waist_armour + feet_armour + hands_armour + neck_armour + ring_armour
        let wisdom = weapon_wisdom + chest_wisdom + head_wisdom + waist_wisdom + feet_wisdom + hands_wisdom + neck_wisdom + ring_wisdom
        let vitality = weapon_vitality + chest_vitality + head_vitality + waist_vitality + feet_vitality + hands_vitality + neck_vitality + ring_vitality

        return (agility, attack, armour, wisdom, vitality)
    end

This implementation is by no means complete but is a starting point to creating the structure for a dynamic on-chain statistics system.

See the Loot branch for a deeper dive into the functions and checkout the test suite to see them in action here