ADR-164: Quests PoC

More details about this document
Latest published version:
GitHub decentraland/adr (pull requests, new issue, open issues)
Edit this documentation:
GitHub View commits View commits on


The Quests System is an important feature that facilitates users to explore the world, unlock achievements and potentially receive rewards. A quest is a series of steps or tasks that a user has to complete. Each step or task has an acceptance criteria to consider it as done. A quest designer has to define the steps and the order or the path to the end, so the quest is finished when those steps are completed.

Context, Reach & Prioritization

Users usually to complain that when they enter the world and after a certain time, they don't know what to do, or where to go and feel lost. This problem impacts directly on user retention because of a possible bad first impressions on the platform.

Having a Quests System can solve part of the problem, giving users a reason to stay and have a nice time. This feature would also allow content creators to creatively increase engagement.

The last sentence is important to remark on since it makes it different to any other Quest System you may know from video games, where the quests are defined by the owners or internal teams. In this case, we're opening the doors to creators to design their own quests and to developers to create tools to improve quests ecosystem.

On the other side, the system (backend) should be in charge of tracking and validating the progress and accepting new quest deployments.

Having said that, there are three well-known actors with corresponding components:

For the sake of fast iteration and discovery, this document will explore the boundaries and scope of a Proof of Concept for the described Quests System.

Solution Space Exploration

The following sections will describe what would be necessary, including some alternatives, for a Proof of Concept where designers can submit quests and users can experience them while the system exposes some metrics.

Quest definition

A Quest definition will include steps/tasks required for completion. It would be defined technically speaking as a graph, since it may have a non-linear complexity.

Defining a valid quest definition in the form of a graph requires the following conditions:


A minimal global UI for quest tracking and receiving real-time notifications about the progress requires the following:

This UI may be developed using the SDK to build reusable UI components to be used in any Explorer implementation.


A communication channel with the system, built in the Kernel, notifying events that happen in world and receiving updates is required to keep the Explorer up to date. The responsibilities of this Kernel module are the following:


A set of predefined actions may be provided to the designers and users, in order to define the Quests steps and make progress.

Quest Designer

Build a tool/CLI to easily design Quests, without conflicting with existing definitions.

Using the predefined actions, the designer should be able to create a Quest definition with steps and requirements. The output of a quest definition is a graph which will be persisted in a convenient form.


Content creator is the user who would be applicable to create, edit or delete quests. This user would typically manage scenes somehow in order to add logic associated with the quests to them, but this might not be a mandatory trait in the future.


The Quests System will expose an API with convenient endpoints for Designers and Users.

It also will process all events received from Explorer/Kernel sessions and make progress to corresponding Quest instances.

Users may ask for quests state and metrics, but completed Quests may be stored for a certain time if the system needs space or it may grow indefinitely.

The system will have the following requirements:

Workflows: User and quests interaction

Start Quest

There would be several ways to discover a Quest. The user may be interested to start any of them.

    Quest Discovery-->>Explorer/Kernel: New quest available
    Explorer/Kernel->>Quest Server: Send start quest request 
    Quest Server ->> Explorer/Kernel: Send start quest response
        Quest Server -->> Explorer/Kernel: Send quest updates

Track Progress

Client should make progress by sending verified events

    Explorer/Kernel ->> Catalyst: Ask for signed event 
    Explorer/Kernel ->> Quest Server: Send signed event
        Quest Server -->> Explorer/Kernel: Send quest updates

Real time updates

Once the API is defined, the system may expose different ways to query quest states, one of them is to use some long living channel (let's say WebSockets).

    Explorer/Kernel ->> Quest Server: Send subscription request
        Quest Server -->> Explorer/Kernel: Send quest updates

Workflows: Quest Designer

Deploy new quest or modify existing quest

When the quest definition is ready, the Quest Designer tool would be able to send the new or modified version to the Quest Server. The request should include the author signature.

    Quest Designer ->> Quest Designer: Quest Definition 
    Quest Designer ->> Quest Server: Send Quest definition and signature
    Quest Server ->> Quest Designer: Send Quest submission response 

When a quest is modified, one of the following options should happen:

Retrieve quest stats

The quest author may be interested in their quest stats, how many users started or completed them and other information like starting and ending times.

    Quest Designer ->> Quest Server: Query Quest state (include signature to validate authorship)
    Quest Server ->> Quest Designer: Send Quest state 


This section describes the technical details on how the Quests systems should be implemented. Each part of the quests system has alternatives to discuss and choose from.

Communication between the System and Kernel

In order to receive real time updates to keep the user updated on the quests they're interested, there are two options to handle the communication:

Having a bidirectional stream connection would allow users to receive updates async.

Quest Model persistence

When a Quest definition is deployed to the System, it should be persisted in some form, the alternatives are:

Also, the location of the persisted quests is important, for example:

Quest Designer

Designing a quest should be a good experience, without friction and intuitive.

The solution should take into account the possibility of editing the quests visually, deployment them easily and having an easy to use and accessibile interface. To fulfill these requirements, the following can be done:

Authenticating designers may be required, so the alternatives are:


To provide a robust system, the services should be scalable, easy to deploy and provide metrics.

Scalability must be thought from the beginning:

It should be easy to deploy:

It should provide observability:


The system should be decentralized in one way or another:

RFC 2119 and RFC 8174

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.


Copyright and related rights waived via CC0-1.0. Draft