Progress

1. Mental model

The progression rules live in the package; the specific state of each learner lives outside the package. The course can declare “this activity is required” or “this unit unlocks after passing another,” while the platform maintains who has viewed, completed, or approved each activity.

2. Available properties

3. Required and blocked are not the same

required affects whether the course is considered completed. gateFollowing affects navigation: prevents subsequent brothers from advancing. An activity can be mandatory without blocking the following, or it can block the following until it is completed.

4. Prerequisites with unlockWhen

unlockWhen contains exactly one of these two forms: all, when all conditions must be met, or any, when one is enough. Each condition references an existing unit or activity and may require a status and a minimum score.

workspace.setProgression('advanced-activity', {
  unlockWhen: {
    all: [
      { entity: 'intro-activity', status: 'completed' },
      { entity: 'quiz-1', status: 'passed', minScore: 70 },
    ],
  },
});

5. Example of a mandatory activity

This example requires passing the activity with a minimum grade and keeps subsequent elements blocked until the condition is met.

workspace.setProgression('quiz-final', {
  required: true,
  gateFollowing: true,
  completionRequirement: 'passed',
  minScore: 70,
});

In this example the quiz is required, must pass with at least 70%, and keeps subsequent items blocked until the condition is met.

6. Validations that the Toolkit avoids

• minScore outside the range 0–100.
• minScore applied to an entity that is not an activity.
• gateFollowing at the root of the course.
• unlockWhen empty, with all and any at the same time, or with references that do not exist.
• Cycles of dependencies, for example A depends on B and B depends again on A.

7. What the Player does during playback

1. Rendering.When an activity is rendered, the Player can mark the status viewed.
2. Activity.The scoring and completion events update the status of the activity.
3. Rules.The Player recalculates locks and prerequisites after relevant changes.
4. Persistence.If the Host Adapter exists, it loads the state on startup and saves changes using the platform.
5. Notification.Emits p2lrn:progressionchange when the progression result changes.

8. What exactly does the progression status save?

He .p2lrn contains the rules; The platform preserves the result of applying them to each learner. Progression snapshot uses version p2lrn-progression-state/1 and maintains one entry per affected entity.

{
  "version": "p2lrn-progression-state/1",
  "entities": {
    "urn:uuid:activity-1": {
      "viewed": true,
      "completed": true,
      "passed": true,
      "scorePercent": 82.5,
      "updatedAt": "2026-10-16T08:30:00.000Z"
    }
  }
}

viewed can be activated when rendering; completed upon completion; passed and scorePercent They are updated when a score provides that data. The Player saves this snapshot using the Host Adapter with a progression context separate from the internal states of the activities.

9. How to convert progression into metrics

No utilices p2lrn:progress as a percentage of the course: that event can represent, for example, questions answered within a questionnaire. For course reports, combine the package rules with the progression status and decide in your platform which aggregates you want to show.

For notes and detailed interaction of questionnaires, SCORM and H5P consult Metrics and analytics. For persistence using Host Adapter see Integration.