'); -->

# Queries

## Why should I care?

Queries are a new feature that has been introduced in Mad Level Manager 2.1.0.

Query is a single expression that can be used to:

- Count available levels
- Count completed levels
- Count number of available stars (or other collectables)
- Count number of collected stars (or other collectables)
- Summarize levels scores
- Unlock levels
- Lock levels

In other words, you should care :-)

## First query

Queries can be constructed using the MadLevelQuery class. It exists in MadLevelManager namespace, so please make sure that your C# source file contains:

    using MadLevelManager;

or if you prefer UnityScript then all your MadLevelQuery calls should look like this:

    MadLevelManager.MadLevelQuery.DoSomething();

The simplest possible query will be counting all levels that are defined in Level Configuration. Here’s the example code:

    int numberOfLevels = new MadLevelQuery().CountLevels();

for UnityScript:

    var numberOfLevels = new MadLevelManager.MadLevelQuery.DoSomething();

## Defining range

You can define a range of levels that you want to query. By default ALL levels are queried. To define a smaller range you can use one of the following methods:

- ForGroup()
- ForLevel()
- OfType()

### ForGroup()

ForGroup() allows you to narrow down the range to selected group(s). You can use it with MadLevel.currentGroupName to query levels that are assigned to the group that the player is currently in.

    int numberOfLevels = new MadLevelQuery().ForGroup(MadLevel.currentGroupName).CountLevels();

Or you can just pass group names as strings:

    int numberOfLevels = new MadLevelQuery().ForGroup("group1", "group2").CountLevels();

### ForLevel()

Similar as before you can narrow down the range to one or many levels by name. You can use MadLevel.currentLevelName along with it. Counting number of levels in this case will be rather a stupid idea, but I think you’ve got the point :-)

### OfType()

OfType() filters the levels that you are querying only to a single type. Let’s say you want to count only levels of type Level (playable):

    int numberOfPlayableLevels = new MadLevelQuery().OfType(MadLevel.Type.Level).CountLevels();

You can mix For…() methods along with OfType() to better define your query range.

## More level operation examples

### Counting

    int locked = new MadLevelQuery().CountLocked();
    int unlocked = new MadLevelQuery().CountUnlocked();
    int completed = new MadLevelQuery().CountCompleted();
    int notCompleted = new MadLevelQuery().CountNotCompleted();

### Changing levels state

    new MadLevelQuery().SetLocked(false); // unlock all levels
    new MadLevelQuery().SetCompleted(true); // complete the game

## Querying properties

You can use MadLevelQuery to query many properties at once. Query execute is an operations only for a defined level range. For these levels you can specify the range or properties that you want to execute your query on. Please note that property queries can be only executed on level-scoped properties properties.

To define a group of properties you have to use the SelectProperty() method. You can use it with the CountProperties() method.

    int propertiesCount = new MadLevelQuery().SelectProperty("star_1", "star_2", "star_3").CountProperties();

This method is little awkward because the only thing it does is counting the levels and multiplying the level count by number of SelectProperty() arguments. Anyway, this is just an example.

## Operation on properties

Here’s a short list of operations you can perform on properties. That list may be incomplete, so please check the MadLevelQuery API to get the latest documentation.

- CountProperties()
- CountEnabled()
- CountDisabled()
- SetEnabled()
- SetDisabled()
- SumIntegers()
- SumFloats()

### CountEnabled() and CountDisabled()

These two can be used to count the number of stars (for instance). Here’s a more complete example of how to count stars for levels of type Level in the current group. These methods are working only on boolean properties.

    int starsGained = new MadLevelQuery()
        .ForGroup(MadLevel.currentGroupName)
        .OfLevelType(MadLevel.Type.Level)
        .SelectProperty("star_1", "star_2", "star_3")
        .CountEnabled();

### SetEnabled() and SetDistabled()

You can set all boolean properties to true (enabled) or false disabled.

    new MadLevelQuery().SelectProperty("medal").SetDisabled(); // no medals for you, ha ha ha!

### SumIntegers() and SumFloats()

If your game is score-based, it is very likely that you may want to summarize scores of each level and display them to the player. SumIntegers() will work only for integer properties and SumFloats() will work only for float properties.

    int scoreTotal = new MadLevelQuery().SelectProperty("score").SumIntegers();

## Querying different profiles

If you want to query a different profile than the one you’re currently on, you have to switch the profile using MadLevelProfile.profile property like this:

    MadLevelProfile.profile = "John";
    int johnScore = new MadLevelQuery().SelectProperty("score").SumIntegers();
    MadLevelProfile.profile = "Daisy";

## Working example

If you open Mad Level Manager/Examples/Scenes/GridExampleScene scene, then you will find a label in its corner. It uses MadLevelQueryExample.cs script to count the number of levels and the number of stars in current level configuration. Make sure to check it out!