Project Archive

A project archive is your whole project in one file: every content table (items, mobs, quests, NPCs, zones, world settings…), every map's chunks and events, and the media they use. It comes in two formats:

• ZIP (.ed5.zip) carries the media files too. Use it to back up a world before a big change, to move a project between the desktop Studio and Studio Web, or to copy a world into a fresh project.
• Text (.ed5.txt) is one readable file you can commit to git and compare line by line. Media is referenced by its content, not included, so the file stays small.

Unlike the JSON export on the Standard tab, an archive carries the maps and the media too, and it can make the target project match the archive exactly.

Export a project#

1. Open Import/Export → Project Archive.
2. Pick a Format: ZIP (includes media files) or Text (diffable, media by hash).
3. Leave Include live-world data unticked unless you also want player characters, inventories, guilds and player houses (see the fields below).
4. Click Export Project Archive. Large worlds take a minute to pack; the download starts when it is ready.

The file is named <your-game>-project-<date>.ed5.zip (or .ed5.txt).

Import an archive#

1. Open Import/Export → Project Archive in the project you want to import into.
2. Choose the .ed5.zip or .ed5.txt and pick a mode (see below).
3. Click Preview import. The Studio runs the whole import and then throws it away, so nothing changes yet. You get one row per table:
   • In archive — rows in the file.
   • New — rows this project doesn't have yet.
   • Conflicts — rows with the same id as one you already have. The archive's version wins.
   • Replaced — rows that share a unique value (for example the same name) with a different row here. Yours is removed and the archive's takes its place.
   • Deleted — Mirror mode only: rows you have that the archive doesn't.
4. Read the warnings under the table (columns or tables this project doesn't have, missing media).
5. Click Apply import. The import runs as one step — if anything fails, nothing is changed.
6. Publish so a running server picks up the new content.

Keep your project in git#

The text archive is built to be diffed:

• Every table is a sorted, pretty-printed JSON section; rows are in id order and keys in alphabetical order, so the same project always exports to exactly the same file.
• Each map chunk and each zone's events have a section of their own. Painting one tile changes a couple of lines in one chunk, not the whole map.
• Cached data the Studio rebuilds on its own (baked map images) is left out.

1. Export with Format: Text and save the file into your git repository (overwrite the previous one).
2. Commit it. git diff now shows exactly what changed since the last export.
3. To go back to a version, check that file out and import it in Mirror mode (preview first).

Importing a text archive puts the project back exactly: export → import into an empty project → export gives the same file byte for byte.

Compare two versions#

Compare shows what an archive would change before you import it, or what changed between two exports. It never writes anything.

1. Open Import/Export → Project Archive and scroll to Compare.
2. Choose the archive (.ed5.zip or .ed5.txt).
3. Pick what to compare it against: this project, or another (older) archive — then choose that second file.
4. Click Compare. You get a total (tables that differ, rows added / removed / changed, media added / removed) and one line per table that differs. Open a table to see:
   • Added — rows the archive has and the other side does not (listed by id).
   • Removed — rows the other side has and the archive does not.
   • Changed — each changed row with every changed field, before and after. Inside map data and event lists the change is shown down to the exact entry (for example tiles.12.3 or pages.0.list.4).

Fields#

Gotchas#

• Preview always comes first. Apply only appears after a successful preview of the same file and mode.
• A big ZIP goes to a hosted project in two parts. Your project's storage takes one file of up to 50 MB, and most of an archive is its media. So for a bigger .ed5.zip the Studio first sends each media file the project doesn't have yet, one by one, and then uploads the rest — the maps and tables. A line under the buttons counts the files as they go. Keep the tab open until the preview appears; a world built on the starter art takes a few minutes the first time and seconds after that, because files the project already has are skipped. The files sent ahead are only used once you press Apply import.
• What still has a 50 MB limit on a hosted project: an archive that is over 50 MB even without its media (a very large world — import that one in the desktop Studio), a text archive, and Compare, which needs the whole file in one piece. Each tells you the file's size, the limit and the way round.
• Media is copied into the target project. Files are stored by content, so importing the same archive twice does not duplicate them.
• Links to outside media (a YouTube link, another site's image) stay links; they are not downloaded into the archive.
• An archive from a newer Studio may carry fields this project doesn't know yet. They are dropped, and the preview warns you — update the Studio to keep them.
• Tables without an id can only be restored in Mirror mode; Merge skips them and says so.
• Mirror deletes. Export a backup of the target first if you're not sure.
• Publish afterwards — an import changes the project, not the live game, until you publish.
• A text archive does not carry media files. Importing one looks each file up in the target project's media library by its content. Into the same project, or a project that already imported the ZIP once, everything is found. Anything that isn't is cleared, and the preview warns you — import the .ed5.zip once to bring the files across.
• Small previews stay in the text file. Media thumbnails, and very old media saved inside the database rather than as a file, are written as they are.
• Comparing against a ZIP reads every media file in this project, so it takes longer than comparing against a text archive. Compare text against text when you can.
• Long lists are cut short. Compare lists up to 50 rows per table in each of Added, Removed and Changed (and 25 field changes per row); the counts are always exact.
• Compare an archive against itself and you get "No differences." The same media under a different file extension, or once in a ZIP and once in a text archive, is not counted as a change.

For tools and AI assistants#

The archive is available at /api/ai/project-archive. POST { op: "export" } builds an archive and returns a download link plus the row count of every table. POST { op: "import", mode, dryRun: true } returns the same per-table preview the page shows (new, conflicts, replaced, deleted) and writes nothing; without dryRun it imports in one transaction and records an audit entry. Hosted projects first call { op: "request-upload" } and upload the file to the signed location it returns, then import by storagePath; local projects send the file as archiveBase64. A hosted upload is one file of up to 50 MB: for a bigger ZIP, ask { op: "missing-media", names } which of its media files (named <sha256>.<ext>, as they are in the archive) the project lacks, put those into the project's media library, and upload the ZIP without them — each one's entry in media/index.json marked "referenced": true.

POST { op: "export", format: "text" } builds the text archive instead of the ZIP. POST { op: "diff" } compares an archive (storagePath on hosted, archiveBase64 locally) with this project (against: "current", the default) or with a second archive (against: "archive" plus againstStoragePath / againstBase64); optional tables limits it to some tables and maxRows (1–500) sets how many rows are listed per table. It is read-only and answers { dryRun: true, summary, diff } — the same per-table added / removed / changed rows and field changes the Compare box shows. Import accepts both formats.