Selectionator

Selectionator Documentation

Contents

• Setup
• Use
• Example

Setup

Selectionator can be found in the Unity Asset Store, and once downloaded can be imported into your unity project through the asset store window, or through the Assets  Import Package  Custom Package menu option.

Once imported, Selectionator is ready to go and requires no special initialization. Just add using Selectionator; to the top of your script.

However, any class that you want to use Selectionator with (that is to say, any class that you want to be able to select) must implement the ISelectable interface, like so:

public class MyClass : ISelectable
{
        public float SelectionWeight { get; set; }
}

Use

Selectionator will work over any enumerable collection (so Arrays, Lists, ArrayLists, LinkedLists, etc. Basically, if LINQ can touch it, so can Selectionator).

Let's assume that we have an enumerable collection of MyClass objects, where MyClass implements ISelectable. We'll call this collection MySelectableCollection. The first step in getting a selection from this collection is to create a new selector, like so:

 Selector mySelector = new Selector()

An instantiated selector without parameters defaults to SelectionPivot.Mean and SelectionRange.All. If different parameters are supplied, we can change the way the selector handles bonus values. For an in-depth look at how selection pivots and ranges work, please click here.


Now that we have our selector, we can make selections. There are two selection methods: Single and Multiple.


Single takes a collection as its first parameter, and from it returns single item selection, like so:

 var myItem = mySelector.Single(MySelectableCollection);

Without a second parameter, Single will return a selection based only on selection weight. To apply a "sweetener" (a bonus adjustment, such as magic-find), we add a float value as a second parameter:

 var myItem = mySelector.Single(MySelectableCollection, 25.2f);

For a detailed description of how bonus values work, and exactly how they manipulate item weights, please click here.


Multiple works the same way as Single, but it returns an IEnumerable and takes an additional parameter: a quantity integer.

var basicMultiSelection = mySelector.Multiple(MySelectableCollection, 5);
	// returns an IEnumerable<MyClass> with 5 items.
		
var multiSelectionList = mySelector.Multiple(MySelectableCollection, 5).ToList();
	// Casting is often a good idea. This returns a List<MyClass> with 5 items.

var bonusMultiSelection = mySelector.Multiple(MySelectableCollection, 5, 50);
	// returns an IEnumerable<MyClass> with 5 items, using a selection bonus of 50.

Selectionator contains an additional useful function: GetWeightDictionary
This function takes a collection of selectable objects and a bonus value, and returns a Dictionary<T, float>, where T is the type of the collection. The dictionary values represent the selection weights of the items after the bonus has been applied.

 var myWeightDictionary = mySelector.GetWeightDictionary(MySelectableCollection, 10);

Example

    public class SelectionExample
    {
        public List SelectableItems;

        public void Example()
        {
            var SelectableItems = new List
            {
                new ExampleSelectableItem {Data = "Item A", SelectionWeight = 1},       // Selection Weight Notes:
                new ExampleSelectableItem {Data = "Item B", SelectionWeight = 2},       // Overlapping weights...
                new ExampleSelectableItem {Data = "Item C", SelectionWeight = 2},       // ...are valid.
                new ExampleSelectableItem {Data = "Item E", SelectionWeight = 3.3f},    // Explicit decimals are valid as well.
                new ExampleSelectableItem {Data = "Item F", SelectionWeight = 0},       // Values of zero, like this, will never be selected
                new ExampleSelectableItem {Data = "Item H", SelectionWeight = (5*2)},   // Anything that can be parsed as a float, like this...
                new ExampleSelectableItem {Data = "Item I", SelectionWeight = (1/9)},   // ...or like this, is valid.
            };
			
			Selector selector = new Selector();
			float bonus = 25;
			int itemCount = 5;
			
			Debug.Log(selector.Single(SelectableItems).Data);
			Debug.Log(selector.Single(SelectableItems, bonus).Data);
			Debug.Log(string.Join(", ", selector.Multiple(SelectableItems, itemCount).Select(item=>item.Data).ToArray()));
			Debug.Log(string.Join(", ", selector.Multiple(SelectableItems, itemCount, bonus).Select(item=>item.Data).ToArray()));
        }

Support

Provided you've included the Selectionator namespace and your selectable objects implement ISelectable, it'll be difficult to run into problems while using Selectionator. That said, if you've found a bug or need some help, here's how you get in contact: