Scene Manager lets you split your Scratch project
into multiple .sb3 files and seamlessly switch between them at runtime —
just like loading a new level or screen.
Scratch Everywhere
All .sb3 files directly inside the scratch-everywhere folder appear in the SE! menu.
Set Root Folder tells Scene Manager which folder acts as that root folder while
you're developing in Scratch/Turbowarp/ScratchBox/Mistwarp or any other SE! compatible editor.
Only MyGame.sb3 is visible in the game-selection menu.
It uses Scene Manager blocks to load the actual levels from the
scenes/ subfolder, those files stay private inside the SE! menu.
Use subfolder-prefixed paths in the scene blocks: open scenes/Level1.sb3
Scene Manager navigates into the subfolder automatically.
In Scratch Everywhere this corresponds to the
scratch-everywhere/ folder, where all your .sb3 files are located.
Put your launcher project in the root and keep scene files in a subfolder.
You theoretically don't have to put all your scenes inside a subfolder, but it is recommended.
`;
box.querySelector('#sm-ok-btn').onclick = () => close(null);
});
}
/**
* If no root folder is set, prompts the user to select one.
* Returns true if a folder is now available, false if cancelled.
*/
async _requireFolder(action) {
return openModal((box, close) => {
box.innerHTML = `
Root folder required
${this._esc(action)} needs to know
where your .sb3 files are stored.
Select your scratch-everywhere/ folder (or any folder containing your projects).
After selecting, the action will continue automatically.
`;
box.querySelector('#sm-cancel-btn').onclick = () => close(false);
box.querySelector('#sm-select-btn').onclick = async () => {
const handle = await this._pickDirectory();
if (handle) { rootDirectoryHandle = handle; currentFileHandle = null; close(true); }
else close(false);
};
});
}
/** Recursively scans a directory for .sb3 files. Returns [{path, handle}]. */
async _scanSb3(dirHandle, prefix = '') {
const results = [];
for await (const [name, handle] of dirHandle.entries()) {
const rel = prefix ? `${prefix}/${name}` : name;
if (handle.kind === 'file' && name.toLowerCase().endsWith('.sb3')) {
results.push({ path: rel, handle });
} else if (handle.kind === 'directory') {
results.push(...await this._scanSb3(handle, rel));
}
}
return results.sort((a, b) => a.path.localeCompare(b.path));
}
/**
* Resolves a relative path (e.g. "scenes/Level2" or "scenes/Level2.sb3")
* to a FileSystemFileHandle inside rootDirectoryHandle.
*/
async _getFileHandle(relativePath) {
if (!rootDirectoryHandle) {
const ok = await this._requireFolder('A scene block tried to load a file');
if (!ok) return null;
}
// Normalise: strip trailing .sb3, then re-add
const clean = relativePath.replace(/\.sb3$/i, '');
const parts = clean.split('/').filter(Boolean);
const fileName = parts[parts.length - 1] + '.sb3';
let handle = rootDirectoryHandle;
try {
for (let i = 0; i < parts.length - 1; i++) {
handle = await handle.getDirectoryHandle(parts[i]);
}
return await handle.getFileHandle(fileName);
} catch {
await this._showError(`File not found: ${clean}.sb3`);
return null;
}
}
/** Core loading routine used by both the scene blocks and the project browser. */
async _loadScene(filePath, dataToPass, fromBrowser = false) {
const display = filePath.replace(/\.sb3$/i, '') + '.sb3';
// Confirm
const confirmed = await openModal((box, close) => {
const saveRow = currentFileHandle
? ``
: ``;
box.innerHTML = `
Switch scene
Load ${this._esc(display)}?
Unsaved changes in the current project will be lost.
${currentFileHandle ? 'You can save first using the button below.' : ''}
${saveRow}
${currentFileHandle ? `` : ''}
`;
box.querySelector('#sm-cancel-btn').onclick = () => close('cancel');
const switchBtn = box.querySelector('#sm-switch-btn');
if (switchBtn) switchBtn.onclick = () => close('switch');
const saveBtn = box.querySelector('#sm-save-btn');
if (saveBtn) saveBtn.onclick = () => close('save-and-switch');
});
if (!confirmed || confirmed === 'cancel') return;
// Optionally save current project back to its file
if (confirmed === 'save-and-switch' && currentFileHandle) {
try {
const blob = await Scratch.vm.saveProjectSb3();
const writable = await currentFileHandle.createWritable();
await writable.write(blob);
await writable.close();
showToast(`Saved: ${currentFileHandle.name}`, 'ok');
} catch (e) {
console.error('[SceneManager] Save failed:', e);
showToast('Save failed — switching anyway.', 'err');
}
}
// Resolve file
const fh = await this._getFileHandle(filePath);
if (!fh) return;
// Load
try {
const file = await fh.getFile();
const buf = await file.arrayBuffer();
sessionStorage.setItem('scenemanager_data', dataToPass);
currentFileHandle = fh;
await Scratch.vm.loadProject(buf);
Scratch.vm.greenFlag();
} catch (e) {
console.error('[SceneManager] Load failed:', e);
await this._showError('Could not load the project. Is it a valid .sb3 file?');
}
}
async _showError(msg) {
await openModal((box, close) => {
box.innerHTML = `