Using the Quest System

See Also

• Create a Quest Definition

In C#, to interact with Xsolla Backend’s Questing system several objects are used:

OBJECT	DESCRIPTION
CoreSDK	A single interface for the SDK and management for the various service classes
ServiceFactory	Manages instances of Xsolla Backend Service classes
QuestService	Quest Interface to the Server
Quest	Tracks an individual player’s progress for a particular QuestDefinition
QuestDefinitionService	QuestDefinition Interface to the Server
QuestDefinition	Defines the structure of a Quest
EventService	Event Interface to the Server
Event	Defines a single telemetry event
QuestRequirement	Defines a requirement that the user must fulfill in order to complete the quest
QuestProgress	Defines an instance of quest progress

Quest Definition

Before interacting with a Quest, a reference to the QuestDefinition object is required.

In the Admin Console, navigate to GamePlay -> Quests -> Definitions.

Note

If there are no definitions listed, you must first create a QuestDefinition.

Double-click the current quest to view the Quest Definition Edit window and copy the UID field.

• In C#, to interact with the Server, Xsolla Backend Services are used.

• To use any service, a reference to the ServiceFactory is required.

The ServiceFactory can be retrieved from the CoreSDK; it’s common to store this in a member variable:

_serviceFactory = CoreSDK.Service;

A reference to the QuestDefinitionService is required to retrieve the QuestDefinition object. The QuestDefinitionService can be retrieved from the ServiceFactory object:

QuestDefinitionService questDefService = _serviceFactory.GetService<QuestDefinitionService>();

To pull the QuestDefinition object from the service, the FindByID method is used, recommended to be stored in a member variable:

_questDefinition = await questDefService.FindById(
    CoreSDK.LoggedInUser.Uid,
    <quest_definition_uid>);

Unlocking a Quest

Unlocking quests is a common feature among games and apps. A Locked Quest is a quest that cannot be started/progressed.

Note

All quests are locked by default.

In c#, to unlock a quest, a reference to the QuestService is needed. The QuestService can be retrieved from the ServiceFactory object:

QuestService questService = _serviceFactory.GetService<QuestService>();

With the QuestService object, Unlock can be called:

quest = await questService.FindbyId(_personaId, Guid.Parse(QUEST_DEF_ID));

If a quest has no Unlock Requirements, the quest will be unlocked.

In the case of a Quest having Unlock Requirements, they must be fulfilled before the Quest can be unlocked.

To submit an Unlock Requirement, the EventService is used.

The EventService sends Event objects to the server to be used in the EventProcessor. This will be ‘scraped’ into the Quest System, which in turn will update the appropriate Quest object.

An Event object has four properties used by the Quest System:

Property	Description
Type	A string id representing the type of event
UserId	The UID of the User sending the event
PersonaUid	The Persona.UId of the User sending the event
Value	The value of the event

The Type field ensures the Event is routed correctly.

To send an Unlock Requirement Event, the Event.Type must match the Unlock Requirement Type.

To retrieve the Unlock Requirement Type:

1. Go to the Admin Console, then navigate to GamePlay -> Quests -> Definitions

2. Double-click the current quest to view the Quest Definition Edit window

3. Double-click the Unlock Requirements field to enter Edit mode

4. Double-click any requirement in the Unlock Requirements field to view the edit window

5. Copy the value of the Type field

Like the QuestService, the EventService can be retrieved from the ServiceFactory:

EventService eventService = _serviceFactory.GetService<EventService>();

To send an Unlock Requirements Event, the EventService.Create method is used. Similar to earlier:

1. Go to the Admin Console, then navigate to GamePlay -> Quests -> Definitions

2. Double-click the current quest to view the Quest Definition Edit window

3. Double-click the Unlock Requirements field to enter Edit mode

4. Double-click any requirement in the Unlock Requirements field to view the edit window

5. Copy the value of the Type field:

axr.sdk.Models.Event eventObj = new axr.sdk.Models.Event();
eventObj["Type"] = <unlock_requirement_type>;
eventObj["UserId"] = <used_uid>;
eventObj["PersonaUid"] = <persona_uid>;
eventObj["Value"] = <value>;

await eventService.Create(eventObj);

After the event is sent the Quest.Unlocked flag can be checked:

QuestService questService = _serviceFactory.GetService<QuestService>();

quest = await questService.Unlock(_personaId, Guid.Parse(QUEST_DEF_ID));
if (quest.Unlocked)
{
    ...
}

Once a quest has been unlocked, it can be started using the Start method of the QuestService:

quest = await questService.Start(_personaId, Guid.Parse(QUEST_DEF_ID));

However, using the Autostart feature streamlines the functionality; more info below.

Autostart Feature

The Autostart Feature starts a Quest, once one is unlocked.

To enable the Autostart feature:

1. Go to the Admin Console.

2. Navigate to GamePlay -> Quests -> Definitions -> Progress.

3. Double-click the current quest to bring up the Quest Definition Edit window.

4. Double-click Autostart (at the bottom) to enter edit mode.

5. Click the Toggle button -> Save (bottom-right).

The AutoStart feature is now enabled!

If the Autostart flag of a QuestDefinition is ``true`, a Quest is started when it is unlocked.

In this case, Start does not need to be called.

Progressing a Quest

To progress a Quest, the EventService is used.

To send a Requirement Event, the Event.Type must match the Requirement type.

To retrieve the Requirement type, similar to earlier:

1. Go to the Admin Console, then navigate to GamePlay -> Quests -> Definitions

2. Double-click the current quest to view the Quest Definition Edit window

3. Double-click the current quests field to enter Edit mode

4. Double-click the Requirements field to view the edit window

5. Copy the value of the Type field:

The EventService can be retrieved from the ServiceFactory:

EventService eventService = _serviceFactory.GetService<EventService>();

To send a Requirements Event, the EventService.Create method is used:

axr.sdk.Models.Event eventObj = new axr.sdk.Models.Event();
eventObj["Type"] = <requirement_type>;
eventObj["UserId"] = <used_uid>;
eventObj["PersonaUid"] = <persona_uid>;
eventObj["Value"] = <value>;

await eventService.Create(eventObj);

• This will add progress to the Quest object

• Progress is contained within Quest.Progress

Completing a Quest

Once a quest has completed, you can determine the status of quest completion through the completions field of the Quest object:

int questCompletions = _quest.Completions;

Quest.Completions represents the number of times a quest has been completed by an individual persona:

• This is associated with a Quest object that has been pulled, utilizing the user Persona Uid

• To check the status of completion, it’s recommended to store off the completions value when a quest is pulled

This can be done through Quest.Start:

quest = await questService.Start(_personaId, Guid.Parse(QUEST_DEF_ID));
_completions = quest.Completions;

or through Quest.FindById:

quest = await questService.FindById(_personaId, Guid.Parse(QUEST_DEF_ID));
_completions = quest.Completions;

Once QuestProgress has been submitted, completions can be compared against a stored value:

axr.sdk.Models.Event eventObj = new axr.sdk.Models.Event();
eventObj["Type"] = "progress.quest";
eventObj["UserId"] = _user.Uid;
eventObj["PersonaUid"] = _personaId;
eventObj["Value"] = 3;

Quest quest = await GetQuest();
EventService eventService = _serviceFactory.GetService<EventService>();
QuestDefinitionService questDefService = _serviceFactory.GetService<QuestDefinitionService>();

await eventService.Create(eventObj);

await Task.Delay(1000);

quest = await GetQuest();

if(_completions != quest.Completions)
{
    // CHECK REWARDS
}

Receiving a Quest Reward

Quest Rewards are automatically awarded by the server on Quest Completion.

They are distributed via type and are accessible through their related services:

Type	Service
ITEM	PersonaResourceService
PROGRESS	QuestService
QUEST	QuestService

In the case of QuestProgress.Type being ITEM, PersonaResourceService.Type is used:

QuestReward reward = _questDefinition.Rewards[0];
string rewardID = reward.EntityUid.ToString();

if (reward.Type == QuestReward.TYPE_ITEM)
{
    PersonaResourceService resService = _serviceFactory.GetService<PersonaResourceService>();
    PersonaResource resource = await resService.FindById(rewardID);

    if (resource != null)
    {
        // REWARD GRANTED
    }
}