Implementation:Facebookresearch Habitat lab AppStateTutorial

Knowledge Sources	Facebookresearch_Habitat_lab
Domains	Embodied_AI, Human_in_the_Loop
Last Updated	2026-02-15 00:00 GMT

Overview

AppStateTutorial is an application state class that manages an interactive tutorial experience within the Habitat HITL (Human-in-the-Loop) framework, guiding users through camera-controlled tutorial stages with on-screen help text.

Description

The AppStateTutorial class extends AppState and provides a tutorial flow for HITL applications. Upon entering the tutorial state, it generates a Tutorial object tied to a specific simulation agent, then drives the tutorial through frame-by-frame updates. The tutorial controls the camera transform (look-at matrix) and displays contextual help text and display text on screen using the TextDrawer.

Users can advance through tutorial stages by pressing the SPACE key, or skip all remaining stages by pressing Q. When the tutorial completes, animations are stopped and the camera transform is no longer updated from the tutorial. The class also manually saves keyframes for replay rendering since the environment is not stepped during the tutorial.

Usage

Use AppStateTutorial when you need to present an introductory walkthrough or guided tutorial before the main HITL interaction begins. It is typically entered as an initial app state, and transitions to the main interaction state once the tutorial completes.

Code Reference

Source Location

• Repository: Facebookresearch_Habitat_lab
• File: habitat-hitl/habitat_hitl/app_states/app_state_tutorial.py
• Lines: 1-93

Signature

class AppStateTutorial(AppState):
    def __init__(
        self,
        app_service,
    ):
        ...

    def get_sim(self):
        ...

    def get_gui_controlled_agent_index(self):
        ...

    def on_enter(self, final_eye_pos, final_lookat_pos):
        ...

    def on_environment_reset(self, episode_recorder_dict):
        ...

    def sim_update(self, dt, post_sim_update_dict):
        ...

    def record_state(self):
        ...

Import

from habitat_hitl.app_states.app_state_tutorial import AppStateTutorial

I/O Contract

Inputs

Name	Type	Required	Description
app_service	AppService	Yes	The application service providing access to sim, GUI input, text drawer, and GUI agent controllers.

Key Methods

Method	Parameters	Description
on_enter	final_eye_pos, final_lookat_pos	Initializes the tutorial with a final camera position and look-at target.
sim_update	dt (float), post_sim_update_dict (dict)	Updates the tutorial each frame; sets cam_transform in the post_sim_update_dict.
on_environment_reset	episode_recorder_dict	No-op; environment is not stepped during the tutorial.
record_state	(none)	No-op; no state to record during the tutorial.

Outputs

Name	Type	Description
post_sim_update_dict["cam_transform"]	Matrix4	The camera transform (look-at matrix) for the current tutorial stage.

Usage Examples

Basic Usage

from habitat_hitl.app_states.app_state_tutorial import AppStateTutorial

# Create the tutorial app state with the app service
tutorial_state = AppStateTutorial(app_service=app_service)

# Enter the tutorial with a target camera position
final_eye_pos = mn.Vector3(0.0, 1.5, 3.0)
final_lookat_pos = mn.Vector3(0.0, 0.5, 0.0)
tutorial_state.on_enter(final_eye_pos, final_lookat_pos)

# Each frame, update the tutorial
dt = 1.0 / 60.0
post_sim_update_dict = {}
tutorial_state.sim_update(dt, post_sim_update_dict)
cam_transform = post_sim_update_dict.get("cam_transform")