How to Migrate Scroll States When Converting a Microapp from Builder 1.0 to 2.0

Overview

When you convert a Builder 1.0 microapp that contains scroll states or scroll tiles, an assisted migration flow automatically maps your 1.0 scroll configurations to their Builder 2.0 equivalents — preserving state names, scroll offsets, navigation behavior, and child tile structure.

The conversion either completes successfully or reports an error — there is no post-conversion report listing what was migrated. Once conversion completes, validate the result yourself using the Scroll States panel and the notes you took before converting (see the preparation checklist below).

Important: The conversion from Builder 1.0 to Builder 2.0 is irreversible on the converted microapp. Always duplicate your original 1.0 microapp and keep the copy before converting. Do not delete the duplicate until you have fully validated the converted microapp.

What the Migration Does Automatically

Step	What happens
Scroll state detection	All scroll states in the 1.0 microapp are identified — names, offsets, and page assignments
State mapping	Each 1.0 scroll state is mapped to a Builder 2.0 Scroll State with an equivalent offset, name, and page assignment
Click event retargeting	Click events that targeted a 1.0 scroll state are retargeted to the corresponding 2.0 scroll state by name
Scroll tile conversion	Builder 1.0 scroll tiles are converted to Builder 2.0 scroll containers, preserving child tiles, scroll direction, and content

Before You Convert — Preparation Checklist

Complete these steps before starting the conversion to give yourself a reliable reference and a rollback option:

1. List all scroll states in the 1.0 microapp — record their names and approximate scroll offsets.

2. Note all click events that target scroll states — which tile triggers each one and which state it targets.

3. Take screenshots of the microapp in Preview and the Viewer as a visual reference for post-migration comparison.

4. Duplicate the microapp in the Library and keep the original 1.0 copy. This is your rollback if anything goes wrong.

How to Convert

1. Open the 1.0 microapp in the Tiled Library.

2. Select Convert to Builder 2.0 from the microapp actions menu.

3. Confirm the conversion. The migration flow runs automatically and either completes successfully or reports an error.

4. Open the converted microapp in Builder 2.0 and open the Scroll States panel.

5. Verify all expected scroll states are listed with the correct names and offsets, using your preparation notes as a reference.

6. Check all click events that previously targeted scroll states and confirm their retargeting is correct.

Validating the Converted MicroappStructure

• All pages are present in the converted microapp.

• All scroll states appear in the Scroll States panel with correct names and offsets.

• All scroll containers (formerly scroll tiles) are present with correct content and scroll direction.

• All click events targeting scroll states reference the correct Builder 2.0 state names.

Behavior

• Preview the converted microapp — scroll through all pages with scroll states and confirm they activate at the expected positions.

• Trigger all click events that navigate to scroll states and confirm each one lands at the correct state.

• Open in the Viewer and repeat the behavior checks.

• Open via a Share Link and repeat the behavior checks.

• Compare against your pre-migration screenshots — flag any visual differences.

If Validation Reveals Gaps

If your validation reveals missing or incorrect scroll states:

1. Note the specific gap — which state is affected and what the expected versus actual behavior is.

2. Manually create or adjust the scroll state in Builder 2.0 to match the intended behavior.

3. Do not delete your 1.0 duplicate until all gaps are resolved and the converted microapp is fully validated.

4. If you encounter a consistent or reproducible issue, contact Tiled Support with details.

Common Questions

Can I undo the conversion if something goes wrong?

The conversion is irreversible on the converted microapp — this is why duplicating the original before converting is essential. If the converted microapp has issues, your 1.0 duplicate is your fallback.

What if a scroll state doesn't appear after conversion?

If a scroll state from your 1.0 microapp is missing from the converted microapp, check the Scroll States panel in Builder 2.0 and compare against your pre-migration notes. If the state is genuinely missing, create it manually and contact support if the issue appears consistent.

Do I need to redo my click events manually?

In most cases, no — click events targeting scroll states are retargeted automatically by name. Validate each click event as part of your post-migration checks to confirm.

When is it safe to delete the 1.0 duplicate?

Only after you have completed the full validation checklist — structure, behavior in Preview, Viewer, and Share Link — and resolved any migration gaps. Keep the duplicate until you're confident the converted microapp is correct.