Skip to main content

Project Safety and Support

Polygon Engine keeps authored project files separate from generated recovery, logs and user preferences. This page explains what happens during save, upgrade and support diagnostics.

Document format markers​

projectVersion is the version of your game. It remains editable project metadata. It is not the file-format version.

Polygon Engine uses separate integer fields:

  • projectFormatVersion for polygon.project.json; and
  • sceneFormatVersion for authored scene JSON; and
  • prefabFormatVersion for reusable Prefab assets.

Projects and scenes use the current format marker 3; Prefabs use marker 2. A project or scene without its marker is treated as an older supported document and enters the migration transaction. A document created by a newer, unsupported editor is rejected without being rewritten. Prefabs with an unsupported marker are rejected rather than guessed at.

Migration and backups​

Migration runs only when a project is actually opened. Refreshing the Project Hub reads display metadata but does not migrate or write project files.

Before an upgrade changes an authored document, Polygon Engine copies only the files that need migration to:

ProjectSettings/Backups/<timestamp>-<engine-version>/

Migration is prepared and validated as a complete transaction. Originals are replaced only after all candidate documents pass. A corrupt file, read-only destination or failed write leaves the last valid authored file intact.

Projects should still be kept in source control or an external backup. The migration backup is a safety boundary, not a substitute for project history.

Atomic manual saves​

Projects, scenes, material documents, asset metadata and the asset database use the same write contract:

  1. serialize beside the destination;
  2. close and flush the temporary file;
  3. read it back and validate it; and
  4. replace the destination atomically.

The editor never intentionally truncates the current valid JSON before the replacement is ready.

Scene and Level Builder recovery​

When the open scene is dirty, the editor writes a recovery snapshot every 120 seconds under Library/Recovery. It retains the five newest snapshots for each scene. These are generated recovery files, not authored scenes.

Dirty Level Builder meshes follow the same 120-second interval and retain five snapshots per mesh, even when the Level Builder window is hidden. Their PMSH payloads are written and validated atomically alongside recovery metadata that records the mesh GUID, name, original path and timestamp. Older autosaves from Library/level_builder remain discoverable through the recovery manager.

A successful manual scene save removes obsolete snapshots for that scene. A session marker records the editor process that owns the project. If the process ends unexpectedly, the next open shows:

  • the original scene path;
  • the autosave timestamp; and
  • Restore, Keep Original, and Discard Recovery actions.

For a scene, Restore validates and atomically replaces the original scene. For a Level Builder mesh, Restore opens the recovered mesh as dirty content without overwriting its source; the snapshot remains until a successful manual mesh save. Keep Original closes the prompt while retaining the snapshot. Use Help > Manage Recovery Snapshots... to return to retained scene and mesh snapshots. Discard Recovery deletes only the selected recovery entry.

Polygon Engine refuses to claim a recovery session owned by another running editor process. Do not work on the same project from two editor processes.

Interface scale and layout reset​

Use View > UI Scale to select Auto, 100%, 125%, 150%, or 200%. The preference belongs to the current Windows user, not the project. It scales the font, Windows 95 controls, icons and docking metrics independently of the game preview.

Use View > Reset Layout and UI Scale to restore the default layout and Auto scale. Moving an Auto-scaled window to a display with different DPI updates the effective scale.

Persistent logs​

Editor session logs are stored under:

%LOCALAPPDATA%/Polygon Engine/Logs/

Logs rotate at 5 MB and Polygon Engine retains at most ten files. They remain available when a project cannot open.

Create a private support bundle​

Select Help > Create Support Bundle.... The preview lists every category before the ZIP can be created. The bundle can include:

  • editor version and release channel;
  • Windows, display DPI/UI scale, video driver and GPU;
  • detected controller names;
  • a Toolchain Health summary;
  • the engine release manifest/version;
  • the current session log; and
  • recent PS1 build logs.

It excludes scenes, assets, source files, BIOS files, toolchain payloads, credentials, save data, environment variables, project paths and project content. Polygon Engine creates the ZIP locally and never uploads it. You decide whether to send it.

Send private diagnostics to support@novemtails.com. Use the Polygon Engine Itch.io discussion board for public reports that contain no private files. Novemtails aims to confirm receipt within two business days; confirmation is not a promised resolution date.

Before reporting a build failure, run Build > Toolchain Health Check and review Build Troubleshooting.