Skip to main content
FORGEJO ERA / ISSUE #619

Offer tutorial and onboarding markers in their own preference category

closedOpened by MelanX on

Original description​

By MelanX · October 23, 2026

Crate: ephervex-options, ephervex-gui and tools/minecraft-options

Commit: 2b2af1e4f8166d02e4732d19e040a53745d97a51

Behavior

Client-owned progress markers are handled inconsistently by the preference catalog:

  • tutorialStep, joinedFirstServer and startedCleanly are in EXCLUSIONS, so a user cannot set them at all.
  • onboardAccessibility has no exclusion and ships as an ordinary language_and_accessibility toggle with no translation key and no help text.

The categories are a closed set (CATEGORIES in preferences.py, mirrored by PreferenceCategory in crates/options/src/catalog.rs), so there is no place for markers a user may legitimately want to set. For disposable bug-reproduction instances the useful ones are exactly these: starting with the tutorial hint set to none and the accessibility onboarding already dismissed avoids first-launch screens that get in the way of a reproduction.

Expected behavior

A dedicated category (name to be decided, for example "Onboarding") holds markers that are client-owned state but safe and useful to set. Each carries a durable description saying what it controls. At least tutorialStep (enum token, none disables the hints), onboardAccessibility and joinedFirstServer are candidates. startedCleanly stays excluded because it is crash-recovery state, not something to set. The category is added in the generator, in PreferenceCategory, and in the settings UI, and docs and the README describe it.

Impact

Today onboardAccessibility appears among accessibility settings without a label, and the tutorial and first-launch markers cannot be controlled at all, so fresh instances open with first-launch screens.

Locations

  • tools/minecraft-options/preferences.py CATEGORIES, EXCLUSIONS
  • crates/options/src/catalog.rs PreferenceCategory
  • crates/options/data/minecraft-preferences.json
  • the settings screens that list categories in ephervex-gui

Validation and limitations

Read the generator, the committed catalog and the Rust enum. The meaning of onboardAccessibility (shown-once marker, default true) and of tutorialStep none is from knowledge of the game and should be checked against the bytecode before the descriptors are written. Which markers belong in the category, and how the UI should present them, is a product decision.