Storyfall

Achievements

Achievements are story-specific badges that readers can earn while playing your story. Use them for milestones like finding a hidden room, completing a character route, winning a hard fight, or seeing a rare ending.

Creating Achievements

  1. Open your story in the Workshop editor.
  2. Click the Achievements tab in the sidebar.
  3. Click Add.
  4. Fill in the achievement details.
  5. Add an Award Achievement effect where the reader should earn it.

Achievement Fields

FieldWhat it does
NameThe badge title readers see after earning it.
DescriptionShort text explaining what the reader accomplished.
Badge ImageUpload or generate a badge image. This uses the same image system as characters, NPCs, and factions.
PointsOptional score value from 0 to 1000.
Secret until earnedHides the achievement details until the reader earns it.
Internal NotesPrivate writer notes. Readers do not see them.

Reordering Achievements

Achievements use the order shown in the Achievements tab. To change that order, drag an achievement by the handle on the left of its row and drop it where you want it. New achievements are added to the end of the list. In the reader’s Journal, earned achievements appear first, then unearned achievements that are not marked Secret until earned, then the hidden secret count. Each group follows your Achievements tab order.

Awarding Achievements

Achievements are earned through the Award Achievement effect. Add the effect to a choice, a scene’s On Enter Effects, a trigger, or any other effects panel.

In the Code Editor, use:

award "First Blood"
if reputation >= 10: award "Diplomat"
25% if gold > 100: award "Lucky Find"

An achievement can only unlock once per character. If the reader restarts the story with the same character, earned achievements stay earned and do not unlock again.

Reader Display

When a reader earns an achievement, Storyfall records it for that character. Earned achievements appear in the reader’s Journal even after the reader restarts the story. Achievements that are not marked Secret until earned also appear in the Journal before the reader earns them, shown as locked badges after the earned group. Achievements marked Secret until earned stay hidden until awarded.

Readers also see story achievements on their own profile badge gallery, grouped by story. Other visitors do not see story achievements on public profile pages.

Published story versions are immutable, so the earned achievement uses the achievement definition from the version the reader played.

Import, Export, And HTML Export

Storyfall JSON exports include achievements, badge image URLs and metadata, and Award Achievement effects. Re-importing a Storyfall JSON file preserves the achievement definitions and remaps award effects to the new story IDs.

ChoiceScript imports recognize *achievement definitions and *achieve commands.

HTML exports support achievement unlocks locally in the exported file. Local unlocks are saved with the exported player’s progress, but they do not sync back to Storyfall. Because the exported file is a self-contained snapshot, every achievement definition travels inside it, including ones marked Secret until earned, so a reader who inspects the file can read those details before earning them. In normal play the unlock still only appears when the reader earns it.

Next Steps