WizardGenie includes a built-in game preview system so you can run your project while you work. The preview acts like a local browser-ready server for the currently open project: it serves your game page and assets, helps the editor receive runtime errors, and can provide extra scene interaction helpers while you are working in the editor.
What it does
Game Preview & Builds lets you test the active WizardGenie project without setting up your own local server.
When preview starts, WizardGenie serves files from the open project and opens the best available HTML entry for the game. For projects that use a build workflow, WizardGenie prefers the built output when it is available and can attempt a build when the project appears to need one.
The preview system supports common web game workflows, including:
- Local preview of HTML-based games.
- Previewing browser-ready JavaScript projects.
- Previewing TypeScript entry files when the project environment supports on-demand browser bundling.
- Build-aware previewing for projects that generate browser-ready output.
- Automatic selection of a suitable game HTML page.
- Serving images, audio, video, 3D models, fonts, data files, and other common game assets.
- Runtime error forwarding into the WizardGenie editor.
- No-cache serving so saved changes are easier to see after refresh.
- Audio and video range loading for seeking and streaming-style playback.
- Directory listings for folders that do not contain their own HTML entry page.
- Editor scene helpers for camera sync and object manipulation when preview is embedded in editing mode.
Typical workflow
- Open or create a project in WizardGenie.
- Make sure the project has a usable HTML entry page, or that its build output can generate one.
- Save the files you want to test.
- Start preview from WizardGenie.
- Interact with the game in the preview window or embedded preview area.
- Watch for runtime errors reported by the editor.
- If you edit files, save them and refresh preview.
- If your project uses a build step, let WizardGenie rebuild when needed or run your project build manually if a build error needs attention.
How WizardGenie chooses what to open
WizardGenie looks for an HTML file to use as the preview entry. Build output is preferred for build-based projects because the original source page may reference files that are not directly runnable by a static browser preview.
The current priority is:
- A built game page, when present.
- The main project HTML page.
- A public HTML page.
- Another discovered HTML page, if one was found.
For most projects, the simplest setup is to keep a clear main HTML page at the project root. For build-based projects, keep your built output current so preview can open the generated browser-ready page.
If WizardGenie cannot find any suitable HTML entry, preview reports an error such as “No index.html found in project.”
Build-based projects
Some projects need to be built before they can run correctly in a browser. In those projects, the source files are transformed into browser-ready output, and preview should usually run the built version.
When WizardGenie recognizes a supported build-based project, it checks whether the built game page is missing or older than important project files. If the output is missing or appears out of date, WizardGenie attempts to run the project’s build command before opening preview.
What happens during preview
- If the build succeeds, WizardGenie serves the built game page.
- If the built output is already current, WizardGenie serves the existing built page.
- If no supported build command is available, WizardGenie skips the build step and previews the best HTML file it can find.
- If the build fails, WizardGenie reports the build error and may still identify the best available HTML page, but the game may not run correctly until the build issue is fixed.
Build time limit
Preview builds have a time limit. If a build takes too long, WizardGenie stops waiting rather than letting preview hang indefinitely. If this happens, run the build manually, resolve any slow or failing build work, then start preview again.
TypeScript preview behavior
WizardGenie can serve TypeScript-based browser entry files by bundling them on demand when the required project support is available. This is useful when a page references a TypeScript entry directly and the preview environment can turn that entry into browser-ready JavaScript.
If TypeScript bundling fails, the preview sends an error to the browser console and to the editor’s error reporting system. Common causes include:
- Syntax errors.
- Missing imports.
- Packages that are not available to the project.
- Source files that rely on build-time behavior not available during direct preview.
- A project that should be previewed from built output instead of from source files.
For build-based TypeScript projects, the most reliable workflow is to fix the build, generate the built output, and preview the built page.
Served asset types
WizardGenie preview serves common game development file types, including:
- HTML pages.
- JavaScript and browser-served TypeScript files.
- CSS stylesheets.
- JSON, XML, text, CSV, and Markdown files.
- Images: PNG, JPEG, GIF, WebP, SVG, ICO, and BMP.
- Audio: WAV, MP3, OGG, M4A, FLAC, and AAC.
- Video: MP4 and WebM.
- 3D assets: GLB, GLTF, FBX, OBJ, STL, USDZ, MTL, and binary asset files.
- WebAssembly files.
- Fonts: TTF, OTF, WOFF, and WOFF2.
- Source maps and miscellaneous binary files.
Audio and video files support partial loading, which helps browser media controls, seeking, and many game audio/video loaders work correctly.
Error reporting in preview
WizardGenie adds preview error reporting to served HTML pages. This helps surface problems directly in the editor while you test.
Preview can report:
- JavaScript runtime errors.
- Syntax and reference errors.
- Unhandled promise rejections.
- Failed script loads.
- Failed image loads.
- Failed stylesheet loads.
- Error-like console messages.
When an error appears, check the message for the referenced file and line information, then inspect the relevant project file. If the issue is a missing asset, confirm that the asset exists and that the game is requesting it with the correct relative path and capitalization.
Editor scene interaction
When preview is embedded in the editor rather than opened as full play mode, WizardGenie adds scene helpers that allow the editor to communicate with a compatible running 3D scene.
Depending on how your scene is structured, the editor may be able to:
- Synchronize the editor camera with the preview camera.
- Discover selectable scene objects.
- Track object positions while the scene runs.
- Move scene objects from editor tools.
- Rotate scene objects from editor tools.
- Scale scene objects from editor tools.
- Hide scene objects from editor tools.
The preview filters out common non-gameplay objects so selection focuses on likely editable gameplay objects. Filtered objects can include lights, cameras, grids, sky or atmosphere objects, ground and terrain-like objects, particles, debug helpers, very large scene groups, and highly complex groups.
In full play mode, WizardGenie keeps error reporting active but limits editor scene bridge behavior. This avoids unnecessary editor-to-preview communication while you are playing the game.
Directory listings
If you open a folder in the preview and it does not contain its own HTML entry page, WizardGenie displays a directory listing. This is useful for checking whether generated content, asset folders, level packs, or data files are being served correctly.
Directory listings show:
- File and folder names.
- File sizes.
- Modified times.
- A parent-folder link when applicable.
- A count of listed items.
Folders are listed before files, and hidden dotfiles are not shown.
WizardGenie also supports a machine-readable directory listing when explicitly requested by tools that prefer structured folder data. For normal use, the HTML listing is what you will see in the browser.
Caching and refresh behavior
Preview responses are served with no-cache behavior so the browser is instructed to re-check files rather than relying on stale cached copies.
If you still see old behavior:
- Save the file you changed.
- Refresh the preview.
- If your project uses a build step, rebuild or let WizardGenie rebuild on preview.
- If an asset was renamed, verify that the game references the new name exactly.
- If you changed generated output, confirm that the generated files were actually updated.
Common problems and fixes
“No project open” or “No project”
Open or create a WizardGenie project before starting preview. The preview only serves the active project.
“No index.html found in project”
WizardGenie could not find a usable HTML entry page. Add a main HTML page to the project, or build the project so a previewable HTML page is generated.
The project root opens as a file listing instead of the game
The project does not currently have a root HTML entry page available. Open the correct HTML file from the listing, add a main HTML page, or build the project so the generated game page is available.
Build fails before preview
A build-based project may need a successful build before it can run. Check the build error shown by WizardGenie. Common fixes include installing project dependencies, correcting TypeScript or JavaScript errors, fixing invalid project metadata, or adding a valid build command.
Public HTML loads, but the game does not start
Some build-based TypeScript projects have a public HTML page that references source files that cannot be loaded directly in the static preview. Build the project first, then preview the built output.
TypeScript build failed
A TypeScript file could not be bundled for browser preview. Check for syntax errors, missing imports, unavailable packages, or assumptions that only work in the project’s full build process. After fixing the issue, save and refresh preview.
Assets return “Not found”
Confirm that the requested file exists inside the active project and that the path used by your game matches the asset location. Browser paths are often case-sensitive, so check capitalization carefully.
A folder link redirects or changes slightly
Folders are normalized with a trailing slash so relative links resolve correctly. If you manually enter folder URLs, make sure folder paths end with /.
Audio or video does not seek correctly
WizardGenie supports media range loading, but the media file still needs to be browser-compatible. Try a widely supported format such as MP4 for video or MP3, OGG, or WAV for audio, and confirm the file is not corrupted.
Scene objects are not selectable in the editor preview
The scene bridge only works with compatible 3D scenes and filters out many objects that look like environment, helper, light, camera, terrain, particle, or very large group objects. If a gameplay object is not selectable, check whether it is part of a large group or named similarly to an environment/helper object.
FAQ
Do I need to run a separate local server?
No. WizardGenie provides its own preview server for the active project.
Does preview cache my files?
Preview is configured to avoid browser caching. Save your changes and refresh preview to see updated files.
Can preview load assets from folders?
Yes. It serves files from the active project, supports many common game asset types, and can show directory listings for folders without an HTML entry page.
Why does built output take priority?
Build-based projects often transform source files into browser-ready files. The built output is usually the version that can run correctly in preview.
Why do some scene objects not appear as selectable editor objects?
The editor preview bridge filters out common environment, lighting, helper, terrain, particle, and very large or complex scene objects so selection tools focus on likely gameplay objects.
Why does preview behave differently in full play mode?
Full play mode prioritizes running the game with fewer editor interaction helpers. Error reporting remains active, but scene editing communication is reduced to avoid unnecessary overhead while playing.