Source: Dev.to

Flash‑to‑HTML5 Migration Guide

Adobe Flash is dead. As of December 2020, all major browsers removed Flash support entirely. Yet thousands of Flash applications—educational tools, training simulations, interactive exhibits, and games—still have value. Their content is relevant, their audiences still exist; only the technology is obsolete.

During our founder’s previous tenure at a development agency, we led the migration of The Great Fire of London—an educational game originally built for the Museum of London—from Flash to HTML5. The kicker? The original source code was lost.

That project taught us a comprehensive methodology for Flash‑to‑HTML5 migration that we now apply through our legacy‑modernisation service. This guide covers the full process.

---

1. Audit the Flash Application Thoroughly

If you have the original .fla files and ActionScript source

1. Export the timeline as a frame‑by‑frame reference.
2. Catalogue all assets (vector graphics, bitmap images, audio files, fonts).
3. Document the class structure and state machine.
4. Identify external dependencies (server calls, local storage, third‑party libraries).

If you only have the compiled .swf file (our situation)

1. Use a SWF decompiler – JPEXS Free Flash Decompiler is the best open‑source option – to extract assets and inspect bytecode.
2. Document every screen, interaction, and animation by playing through the application and recording video.
3. Build a behaviour specification – a document describing exactly what the application does, screen by screen, interaction by interaction.
4. Treat the compiled SWF as a “black‑box” reference implementation.

Key Takeaway: If source code is lost, the decompiled output is a reference, not a starting point. Directly porting decompiled ActionScript to JavaScript produces unmaintainable code. Reverse‑engineer the behaviour, then rewrite cleanly.

---

2. Choose the Right HTML5 Technology

For most Flash migrations, Phaser + TypeScript is the sweet spot: lightweight, well‑documented, and it maps naturally to Flash’s display‑list model.

---

3. Transform Flash Assets for the Web

Vector Graphics

Flash’s vector format does not translate directly to web standards. Options:

For The Great Fire of London, we extracted the original vector assets and converted them to optimised sprite sheets. This reduced total asset download size and draw calls compared with rendering individual vectors.

Audio

Flash commonly used proprietary audio formats. Convert to modern web‑friendly formats:

Fonts

Flash applications often embed fonts that may not have web licences.

1. Verify licensing before converting to WOFF2.
2. If the original font is unlicensed for web use, find a visually similar alternative.

---

4. Rewrite, Don’t Port

ActionScript and JavaScript share a common ancestor (ECMAScript), which makes line‑by‑line porting tempting. Resist this temptation.

Why a Direct Port Fails

• Flash’s frame‑based timeline has no analogue in JavaScript.
• Flash’s display‑list model differs from the DOM and Canvas.
• Flash’s event model differs from browser events.
• ActionScript 2 and ActionScript 3 have class systems that don’t map cleanly to modern JavaScript/TypeScript.
• Carrying over Flash‑era patterns yields slow, fragile web code.

Recommended Approach

1. Work from the behaviour specification (Step 1), not the decompiled source.
2. Build a clean TypeScript architecture using modern patterns (modules, services, ECS, etc.).
3. Implement each screen/interaction as an independent module.
4. Test each module against the original Flash application for behavioural parity.

In our migration of The Great Fire of London, we catalogued every interaction, animation timing, and win‑state condition from the Flash version, then wrote modern TypeScript to replicate these behaviours exactly.

---

5. Make the Game Responsive

Flash applications were built for fixed resolutions—typically 800 × 600 or 1024 × 768 (4:3 aspect ratio). Modern devices range from 320 px‑wide phones to 2560 px‑wide monitors (16:9 or taller).

Steps to Decouple UI from the Game World

1. Anchor UI elements to screen edges and corners instead of absolute pixel positions.
2. Use relative units – percentages (%) and viewport units (vw, vh) – instead of fixed pixels.
3. Define breakpoints for phone, tablet, and desktop widths.
4. Test on real devices; responsive design that looks correct in Chrome DevTools can still break on actual hardware.

For The Great Fire of London, we re‑engineered the layout from a 4:3 CRT design to a responsive 16:9 layout, ensuring the game worked on Chromebooks (the primary hardware in UK classrooms), iPads, and desktop browsers.

---

6. Add Modern Input Handling

Flash applications assumed mouse input. Modern devices require touch support.

• Add touch event handlers alongside mouse events.
• Provide larger tap targets (minimum 44 × 44 dp) for finger interaction.
• Consider pointer events (pointerdown, pointerup, etc.) for a unified input model.

---

7. Testing & Quality Assurance

Automated unit tests (Jest) and end‑to‑end tests (Cypress or Playwright) are highly recommended.

---

8. Deployment Considerations

1. Bundle and minify JavaScript/TypeScript with a modern bundler (Vite, Webpack, or Rollup).
2. Serve assets via a CDN with proper caching headers.
3. Use HTTP/2 or HTTP/3 to reduce latency for many small asset requests.
4. Implement a service worker for offline support if the application is used in low‑connectivity environments.

---

9. Summary

• Audit – understand every asset, screen, and interaction.
• Choose the right stack (Phaser + TypeScript is often ideal).
• Convert assets to web‑friendly formats (SVG/PNG, MP3/OGG, WOFF2).
• Rewrite using modern architecture; never port line‑by‑line.
• Make it responsive and add touch support.
• Test thoroughly across devices, browsers, and accessibility requirements.
• Deploy with performance‑optimised bundling and CDN delivery.

By following this methodology, you can breathe new life into legacy Flash applications, preserving their educational and cultural value for modern audiences.

Performance Considerations

• Touch‑target size – minimum 44 × 44 pt (or px) for comfortable tapping.
• Gesture support – add pinch‑to‑zoom for maps, swipe for navigation, etc.

Flash applications ran in a browser plug‑in with their own runtime.
HTML5 runs in the browser’s JavaScript engine, which has different performance characteristics.

---

Common Pitfalls & Solutions

---

Target Hardware Considerations

Educational Flash migrations often target school hardware – Chromebooks, aging Windows desktops, and shared iPads. This hardware is significantly less powerful than consumer devices.

For The Great Fire of London we optimised specifically for:

• Chromebooks with 2–4 GB RAM and integrated graphics.
• Slow school Wi‑Fi with high latency and packet loss.
• Shared devices where the browser cache may be cleared between sessions.

Key Takeaway: Your target hardware defines your performance budget. Educational migrations target the weakest devices in a school’s inventory, not the newest.

---

Testing Protocol

1. Side‑by‑side comparison – run the Flash version (via a standalone Flash Player) alongside the HTML5 version.
2. Interaction audit – verify every clickable element, animation, and state transition.
3. Timing verification – ensure animations play at the same speed (Flash used frame‑based timing; HTML5 uses time‑based).
4. Edge‑case testing – rapid clicking, window resizing, tab switching, network interruption.
5. Accessibility review – add keyboard navigation and screen‑reader support that the Flash version lacked.

---

Migration Timeline

---

Cost Drivers

• Source‑code availability – having the original Flash source dramatically reduces effort.
• Number of unique screens / interactions – more UI elements = more work.
• Target device range – broader hardware support requires extra optimisation and testing.

---

Further Resources

• Great Fire of London – Case Study – Our reverse‑engineering rescue mission
• Legacy Modernisation Services – How we approach legacy migrations
• Fire of London Project Page – The finished product
• Educational Game Development Services – Our approach to serious games and educational content