Creating challenges
The basic concept of a challenge is pretty simple: You set a goal and ask the user to reach that goal within a certain
period. Goals must be measurable with one simple integer. Every active challenge has a current state which is also an
integer. A simple challenge for example is: “Invite 5 other users”. The goal here is 5
, the current state will be 0
when the challenge is activated. After the user invited one other user an event is sent to SCILL. SCILL will process
that event and increases the counter of the current state by 1
. SCILL cloud will then notify your backend by calling
a Webhook (if defined) and will notify any connected clients of this user to reflect this change in the user interface
in real time.
It’s simpler to describe how to work with SCILL on a concrete example or product. For this guide, we have selected an open-source Tetris game called: Mimstris.
Create an app
Create a game in the Admin Panel:

Adding a game in the Admin Panel
After that, select the new app from the app selection in the top bar and navigate to “API Keys” to add an API key for the new game:

Adding an api key for our new game
Defining events and challenges
Now, that we have set up the app in SCILL, we need to figure our which events we have in the game and what challenges we can create based on those events. We recommend getting started by defining obvious events and challenges for your game to get started. Once you have done that, you’ll figure our other interesting challenges which might require some other events. It’s a bit a back and forth process, but a lot of fun and as it’s an iterative process you can always start with something simple to get more complicated down the road.
SCILL events are preconfigured for you. You can find the complete list of event types in our Event Types list in this documentation.
By digging through the list, we found these events that we can pretty easily define and implement for this game:
This event has a couple of properties that we can set. One of those properties is item_id
. We can use that to distinguish
events with the same event name. In total, we’ll use three different values for item_id
.
- line
- Is used for a “standard” Tetris row
- sameColor
- Describes a line where all pieces in the line have the same color
- block
- A block of four lines, cleaned at once
Every event has a couple of parameters that can be attached to the event. Some of them are required, others are optional. The documentation describes all those parameters in detail.
Based on those events, some challenges are obvious:
- Complete 10 lines (listens on the item_id
line
) - 4 Lines at once (listens on the item_id
block
) - 5 lines with same color (listens on the item_id
sameColor
)
Of course, these are simple challenges, but especially the “5 lines with same color” challenge is completely changing the game. How many times have you played Tetris, and did you ever try to create lines with the same color? By just adding this simple challenge, the game is completely different and it’s fun to see different people figuring out different strategies to solve that problem.
Setting up challenges
In the Admin Panel, make sure the app is selected from the list and click on “Challenges” in the menu. First, we need to create category. Challenges are organized into categories.

Adding Basic Challenges category
You can enable and disable categories. This way, you can create many challenges in advance and unlock them anytime. You could create “Christmas” challenges and unlock them at christmas or you could organize your challenges in seasons and switching them every month. If you add great rewards to some challenges, users will be forced to manage challenges in time which also drives users retention.
Let’s create our first, simple challenge. For this, choose the Challenges tab in the Personal Challenges section of the Admin Panel and click on Add Challenge.

Adding the 5 Lines with same color challenge
- Name
- This is the description/name of the challenge. This is the action plan the user must follow to achieve this challenge. Keep it short and precise.
- Category
- This is the category the challenge is attached to. In this case, choose the “Basic Challenge” category created before.
- Challenge-Type
- Choose the event that this challenge will track. The challenge will wait for events coming in of this type and process
them. You can further specify which events are processed in the Meta Data section below. We’ll come to that later. In
this case we choose the
destroy-item
event type. - Reward Type
- You can set different types of rewards. There is no logic within SCILL for rewards, it’s up to you to unlock rewards,
but using our options it’s easier to organize your data. Choose an item from the list. Within the API response or SDK
this will be available as
reward_type_name
in the Challenge object. In this case we selectedItem
. - Reward
- Enter any string you like. This will be returned as
reward_amount
in the Challenge object. In this case the user will get another type of piece which looks like anH
. - Repeatable
- Challenges have a duration and need to be unlocked/activated. This setting defines what happens if the Challenge has been lost (timed out) or won (achieved within time constraint). If it’s set to be repeatable, it will be reset and available for another round. If it’s not repeatable this challenge will not be available for the user again. In this case we set it to be repeatable.
- Difficulty Level
- You can set an integer here. You can use this value to sort challenges on your end for example. We set it to 1 in this case.
- Live Date
- We leave this field blank, which means, we don’t set any date. You can create challenges and assign a date when they should “go live”. I.e. create a Halloween challenge and set to October 31th and this challenge will automatically pop up.
- Challenge Icon
- You can set any string here. In a web game, we just set it to the name of an image provided in the games asset folder.
We set to
h-piece.png
which is an image of a tile the user wins if he achieves this challenge. - Challenge Icon HD
- Same as Challenge Icon, but allows you to set a high res image, for example for some teasers or for Desktop version of your game, while you use the Challenge Icon for the mobile version with a much denser UI. We leave that out in this example.
- Duration
- Set the time limit for the challenge in minutes. We set it to 30 minutes in this case.
- Goal
- This is the goal as an integer value of the challenge. As we want to have 10 kills, we set it to 5.
- Challenge Goal Condition
- This can be set to 0 or 1. If 0, than the challenge is achieved if you increment the counter greater or equal than the goal. I.e. we set the goal to 10, and the challenge requires to kill at least 10 enemies, so we set this to 0. We could also create a challenge: “Don’t get hit more than 5 times”, then we would need to set this to 1, because in this case the challenge will only be achieved if we stay below 5.
- Price and XP
- These are integer values that you can set and use as you like. We don’t make use of them right now, so just leave them blank.
- Meta-Data
- Here, we choose the property
item_id
and set the condition toAND
. You can also set that toOR
as we will only provide one possible value. In the value field, enter the valuesameColor
and press return to add that value to the list. This challenge will only track events hat have the same value initem_id
. You could provide multiple values to make challenges respond to both (AND) or any of those (OR).
Save the challenge. Congratulations, we just created our first challenge. Time to play around with the challenge in SCILL Playground Application.