> For the complete documentation index, see [llms.txt](https://infinitypbr.gitbook.io/magic-pig-games/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://infinitypbr.gitbook.io/magic-pig-games/game-modules-4/module-documentation/dictionaries/dictionaries-methods.md).

# Dictionaries Methods

Getting and setting values in a Dictionaries object is simple and straightforward. There are also additional helper methods, such as getting a random value from a list of items.

## Getting Values

Getting values generally will utilize the `Value<T>()` method shown below. By default, the method returns the first item in the list -- often it may be the only item. However, you can provide a specific index, or even grab a random value from the list.

{% hint style="success" %}
In most use cases, the `Value<T>()` method will be the only method needed at runtime, unless you are actively storing data in the Dictionaries structure.
{% endhint %}

```csharp
public T Value<T>(string key, bool random = false, int index = 0)

// Grab the "Flavor Text" of an item object
FlavorText.text = itemObject.dictionaries.Value<string>("Flavor Text");

// Choose a random portrait from a set of available Sprites
// In this example the "class" of a player is stored as an ItemAttribute
var playerPortrait = selectedClass.dictionaries.Value<Sprite>("Portraits", true);
```

#### Safely Getting a Value

Calling `Value<T>()` may throw an error if the key is not present in the dictionary. You can avoid this, and add any missing Keys automatically, by using `ValueSafe<T>()`.

```csharp
public T ValueSafe<T>(string key, bool random = false, int index = 0)
```

#### Additional "Get" Methods

```csharp
// Get a KeyValue object
var foundKeyValue = dictionaries.Key(key);

// Count the items
var numberOfKeyValues = dictionaries.Count(key);
var totalKeyValues = dictionaries.Count(); // No key provided, so counts all KeyValues
```

## Get All Values

Get an Array of all values with `Values<T>()`

```csharp
public List<Stat> stats 
    = dictionaries.Key("Starting Skills").Values<Stat>().ToList();
```

## Adding Values

You can add new information at runtime.

```csharp
// Add an empty KeyValue. This returns the new KeyValue object.
var newKeyValue = dictionaries.AddNewKeyValue(key);

// Clone an existing KeyValue
var clonedKeyValue = dictionaries.AddNewKeyValue(keyValueToClone);
```

## Add To Value

For `int` and `float` values, the AddToValue() method provides an easy way to add and subtract from the current values.

```csharp
// Here we will add "1" to the value on the "Key Name" key. Note that Key(keyName, true)
// will add the key to the dictionary if it doesn't exist. If so, the value will be
// 0 at the start, and will be 1 after this operation.
string keyName = "Key Name";
int value = 1;
dictionaries.Key(keyName, true).AddToValue<int>(value);

// Works for explicit float values too
float value = 1.5f;
dictionaries.Key(keyName, true).AddToValue<float>(value);

// Real World example from my own game. This method will track how many times
// a specific Card is played. The Card has a unique identifier on it, and this
// value along with "Card Played - " is used as the "Key". 

// This is the only line
// required to make this entire operation work -- the Key will be added automatically
// if it doesn't exist, and the value will be added appropriately. The first time this
// is run, the key will be added and the value of "1" will be added, meaning the 
// card has been played one time.

// I confirm the results using the "Game Modules Viewer" component on my object.
public void AddCardPlayed(Card card, int value = 1)
{
     dictionaries.Key($"Card Played - {card.Uid}", true).AddToValue<int>(value);
}
```

{% content-ref url="/pages/-MisFXdET-UKbmCOU2BM" %}
[KeyValue Methods](/magic-pig-games/game-modules-4/module-documentation/dictionaries/code-examples.md)
{% endcontent-ref %}