Tasks

Introduction

In out framework, tasks define specific objectives for players to complete using smart home devices. Tasks simulate both achievable and intentionally unachievable scenarios to study user behavior, decision-making, and system understanding Each task defines:

The objective (what needs to be achieved)
The context (environment and device setup)
The constraints (e.g., time limits or system conflicts)
The expected conditions for success (goals)

Tasks can be configured globally (e.g., timing, order, abortability) and individually (e.g., task-specific timers, goals, device states).

JSON Schema

Loading ....

JSON Schema Code

Task Schema

{
  "title": "Task",
  "description": "A task in the game",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The task ID"
    },
    "description": {
      "type": "string",
      "description": "The description of the task to be displayed to the player"
    },
    "timer": {
      "type": "number",
      "description": "The time in seconds to complete the task until it expires"
    },
    "delay": {
      "type": "number",
      "description": "The delay in seconds before the task's action is executed"
    },
    "abortable": {
      "type": "boolean",
      "description": "Whether this specific task can be aborted by the player"
    },
    "abortionOptions": {
      "type": "array",
      "description": "List of abortion reason options presented to the player",
      "items": {
        "type": "string"
      }
    },
    "environment": {
      "type": "array",
      "description": "The environment variables of the task to be displayed to the player",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the environment variable"
          },
          "value": {
            "type": [
              "number",
              "string"
            ],
            "description": "The value of the environment variable"
          }
        },
        "required": [
          "name",
          "value"
        ]
      }
    },
    "defaultDeviceProperties": {
      "type": "array",
      "description": "The default properties of the device that is set when the task starts",
      "items": {
        "type": "object",
        "properties": {
          "device": {
            "type": "string",
            "description": "The name/ID of the device"
          },
          "properties": {
            "type": "array",
            "description": "The properties to be overridden in the device",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "The name of the property"
                },
                "value": {
                  "type": [
                    "number",
                    "boolean"
                  ],
                  "description": "The value of the property"
                }
              },
              "required": [
                "name",
                "value"
              ]
            }
          }
        },
        "required": [
          "device",
          "properties"
        ]
      }
    },
    "goals": {
      "type": "array",
      "description": "The goals of the task to be completed by the player. All goals must be completed to finish the task",
      "items": {
        "type": "object",
        "properties": {
          "device": {
            "type": "string",
            "description": "The name of the device"
          },
          "condition": {
            "type": "object",
            "description": "The condition to be met for this goal",
            "properties": {
              "name": {
                "type": "string",
                "description": "The name of the property to check"
              },
              "operator": {
                "type": "string",
                "enum": [
                  "<=",
                  ">",
                  "<",
                  ">=",
                  "==",
                  "!="
                ],
                "description": "The operator to compare the property value"
              },
              "value": {
                "type": [
                  "string",
                  "number",
                  "boolean"
                ],
                "description": "The value to compare against"
              }
            },
            "required": [
              "name",
              "operator",
              "value"
            ]
          }
        },
        "required": [
          "device",
          "condition"
        ]
      },
      "minItems": 1
    }
  },
  "required": [
    "id",
    "description",
    "environment",
    "defaultDeviceProperties",
    "goals"
  ]
}

Top-Level Properties

Property	Type	Required	Description
`id`	`string`	Yes	A unique, machine-readable identifier for the task. This is used for logging, tracking progress, and referencing the task in game logic.
`description`	`string`	Yes	The player-facing text that describes the objective. This is the main instruction displayed to the participant in the UI.
`timer`	`number`	No	An optional time limit in seconds for the task. If the timer expires before the goals are met, the task is considered failed or expired. This can override any global timer settings.
`delay`	`number`	No	An optional delay in seconds before the task officially begins after it has been loaded. This can be used to sequence events or pace the gameplay.
`abortable`	`boolean`	No	A flag to specify if this particular task can be aborted by the player. This overrides any global `abortable` setting, allowing for fine-grained control over which tasks can be skipped.
`abortionOptions`	`array`	No	A list of predefined string options presented to the player when they choose to abort a task. This is only effective if `abortable` is set to `true`. It is useful for gathering data on why a player gave up.
`environment`	`array`	Yes	An array of key-value objects that define the contextual state for the duration of the task. These variables can be read by the rules engine to influence device behavior and create dynamic scenarios.
`defaultDeviceProperties`	`array`	Yes	An array of objects that sets the initial state of one or more devices at the very beginning of the task. This is crucial for ensuring a consistent starting point and for configuring impossible scenarios.
`goals`	`array`	Yes	An array of goal objects that define the specific success conditions for the task. All goals in the array must be met for the task to be considered complete. A task must have at least one goal.

Global Task Configuration

Global task properties apply to all tasks unless overridden. These are useful for setting:

Task order (sequential or random)
A shared default timer
Global abortability behavior We’ll start with ordered. Here’s a refined documentation block:

Tasks have four primary global properties that control their presentation, timing, and the optional ability to abort the task: ordered, timer, abortable, and tasks.

Property: Order

The ordered flag determines whether tasks should be presented to players in a fixed sequence or in randomized order.

{
    "ordered": "true",
    "tasks": [
        { "id": "task_a", "description": "First task" },
        { "id": "task_b", "description": "Second task" },
        { "id": "task_c", "description": "Third task" }
    ]
}

Order Behavior

When ordered: "true":

Tasks will be presented in the order they appear in the array.
You must explicitly define the desired order by arranging tasks accordingly.

When ordered: "false" (or omitted):

Tasks will be randomized each time the task list is loaded.

Choosing Task Order

Use ordered tasks when:

Tasks follow a logical progression (e.g., build on prior knowledge or steps)
Later tasks depend on context from earlier ones
You are assessing learning or sequential reasoning

Use random order when:

Tasks are independent of each other
You want to reduce learning effects or ordering bias

Property: Timer

The global timer property sets a default time limit (in seconds) for each task. This value applies to all tasks unless explicitly overridden by an individual task’s timer.

{
    "timer": 300,  // Global 5-minute timer
    "tasks": [...]
}

Override Behavior

If a task defines its own timer, it will override the global timer:

{
    "id": "prepare_coffee",
    "description": "Prepare a cup of coffee",
    "timer": 120  // This task will have a 2-minute limit
}

Global vs Local Timers

Use a global timer to maintain consistent task duration across similar tasks.
Use per-task timers to fine-tune time limits based on complexity, length, or experiment design.

Property: Abortable

The global abortable flag controls whether tasks can be skipped by participants using the in-game abort button.

{
    "abortable": true,
    "tasks": [...]
}

If abortable: true, participants may choose to skip any task. This setting applies to all tasks unless individually overridden (See Task-Level Aborting Setting)

Individual Task Configuration

Each task in the tasks array defines its own behavior, goals, and constraints. These task-level properties can override global settings and allow for detailed customization per task.

Core Properties

Defines the basic identity and display information for a task.

{
    "id": "make_coffee",
    "description": "Make 5 coffees using the coffee machine",
}

Property	Type	Description
`id`	`string`	Unique identifier of the task. Required.
`description`	`string`	Text shown to the user describing the goal of the task. Required.

Task-Level Aborting Setting

Each task can override the global abort setting by specifying its own abortable value:

{
    "id": "deep_fryer_task",
    "abortable": false,  // This task cannot be aborted even if global setting allows it
    "abortionOptions": [
        "I believe this task is impossible.",
        "I want to skip this task."
    ]
}

abortable: Boolean that overrides the global abortable setting for this specific task
abortionOptions: Array of strings providing predefined reasons for task abortion

If a task is abortable, you may optionally define a list of abortionOptions, preset reasons that are shown to the participant when they choose to abort:

Abortability Rules

If a task sets abortable: false, the aborting button is not displayed during that task.
If abortable: true but no abortionOptions are provided, participants can skip without stating a reason.
If abortionOptions are provided, participants must select one to proceed.

Environment Variables

Environment variables define the contextual conditions under which a task takes place. They help simulate realistic smart home situations and serve as triggers for behavior rules, dynamic explanations, or device responses.

Each task can define one or more environment variables using a name and a value. These variables exist only within the scope of the task and do not persist globally.

{
    "environment": [
        { "name": "Weather", "value": "Sunny" },
        { "name": "Temperature", "value": 20 },
        { "name": "RoomOccupied", "value": true }
    ]
}

Structure

Each environment variable is defined as an object with the following keys:

Field	Type	Description
name	string	Name of the environment variable
value	string / number / boolean	Value of the variable (text, numeric, or boolean)

Usage

Environment variables can trigger explanation rules, automated smart home behaviors, or conditional device states.
They allow tasks to reflect realistic and dynamic home scenarios (e.g., different weather or presence conditions).
You can define as many variables as needed per task.

Best Practices

Use consistent naming conventions across tasks.
Define variables that match the logic of your rules and explanations.

Default Device Properties

Default device properties define the initial state of specific devices at the start of a task. This ensures consistent and controlled environments for each task scenario.

These properties are set per task and override any global or previously configured device states.

{
    "defaultDeviceProperties": [
        {
            "device": "coffee_machine",
            "properties": [
                { "name": "Power", "value": false },
                { "name": "Roasting", "value": true }
            ]
        }
    ]
}

Field	Type	Description
device	string	The unique name or ID of the device whose properties will be initialized.
properties	array of objects	List of properties to be applied to this device.
→ name	string	Name of the property to override (e.g., "Power", "Brightness").
→ value	number / boolean	New value to assign (e.g., `true`, `false`, `100`).

Purpose

Ensure devices start in a known state
Avoid unintended carry-over effects between tasks
Simulate specific environmental or behavioral conditions

Goals

Goals define the success criteria for each task. A task is marked as completed when all its goals are satisfied. Each goal checks a condition on a specific device property. Each task must have at least one goal.

Goals can also be used to define impossible tasks by setting conditions that cannot be met due to conflicting rules, device limitations, or initial states.

{
    "goals": [
        {
            "device": "coffee_machine",
            "condition": {
                "name": "Number of Coffees Made",
                "operator": ">=",
                "value": 5
            }
        }
    ]
}

This example defines two goals:

The number of coffees made must be at least 5.
The coffee machine must be powered on.

All conditions must be satisfied for the task to be considered successful.

Goal Structure

Field	Type	Description
device	string	ID of the device to check the condition on
condition	object	The condition that must be met
→ name	string	Name of the property to evaluate (e.g., "Power", "Temperature")
→ operator	string	Comparison operator (e.g., `==`, `>=`, `<`, `!=`, etc.)
→ value	string / number / boolean	Value to compare against

Goal Definition Tip

Use precise and measurable device states.
Combine multiple goals to create realistic and challenging tasks.
For impossible tasks, ensure that goal conditions cannot be satisfied based on the environment or rules.
Even for impossible tasks:
- Define clear, measurable objectives
- Use precise operators and values
- Make the goal requirements obvious to participants

Debugging

While goals are required in the schema (minItems: 1), for internal testing you may temporarily leave the array empty to allow task progression without condition checks.

Complete Example

Here's a complete example showing the updated task structure:

{
    "ordered": "true",
    "timer": 120,
    "abortable": true,
    "tasks": [
        {
            "id": "deep_fryer",
            "description": "Turn on the deep fryer",
            "timer": 120,
            "abortable": false,
            "abortionOptions": [
                "I believe this task is impossible.",
                "I want to skip this task."
            ],
            "environment": [
                { "name": "Weather", "value": "Rainy" },
                { "name": "Temperature", "value": 13 }
            ],
            "defaultDeviceProperties": [
                {
                    "device": "deep_fryer",
                    "properties": [
                        { "name": "Power", "value": false }
                    ]
                }
            ],
            "goals": [
                {
                    "device": "deep_fryer",
                    "condition": {
                        "name": "Power",
                        "operator": "==",
                        "value": true
                    }
                }
            ]
        }
    ]
}

Best Practices

Task Description
- Write clear, unambiguous instructions that are easy to understand for participants.
- If a task is intentionally impossible, avoid hinting at its impossibility.
- Use consistent terminology across all tasks to prevent confusion.
Timer Management
- Set appropriate time limits based on task complexity.
- Ensure enough time is given for trial-and-error, especially in exploratory or deceptive tasks.
- Avoid overly long timers to prevent participant fatigue or disengagement.
Abortion Control
- Use task-level abortable settings to selectively allow skipping tasks.
- Provide carefully worded abortionOptions to capture participants’ reasoning when they give up.
- Consider how abortion opportunities affect participant behavior, engagement, and data quality.
Environment Design
- Use environment variables to simulate dynamic contexts like temperature, occupancy, or external conditions.
- Design environments that logically support the goals or contribute to task difficulty.
Device State Initialization
- Use defaultDeviceProperties to reset device states before each task.
- Ensure consistent starting conditions across sessions and participants.
- Design initial states to align with or counteract rule behavior intentionally.
Goal Definition
- Use precise, measurable, and logically achievable (or unachievable) goal conditions.
- Combine multiple goals to simulate complex tasks.
- For impossible tasks, ensure the defined goals appear achievable but are logically blocked by the environment or rules.

Introduction​

JSON Schema​

Task Schema

Top-Level Properties​

Global Task Configuration​

Property: Order​

Order Behavior​

Property: Timer​

Override Behavior​

Property: Abortable​

Individual Task Configuration​

Core Properties​

Task-Level Aborting Setting​

Environment Variables​

Structure​

Usage​

Default Device Properties​

Purpose​

Goals​

Goal Structure​

Complete Example​

Best Practices​

Introduction

JSON Schema

Top-Level Properties

Global Task Configuration

Property: Order

Order Behavior

Property: Timer

Override Behavior

Property: Abortable

Individual Task Configuration

Core Properties

Task-Level Aborting Setting

Environment Variables

Structure

Usage

Default Device Properties

Purpose

Goals

Goal Structure

Complete Example

Best Practices