The Eden World Builder File Format

This page describes my investigation of the data files produced by the iOS app "Eden — World Builder".

NOTE: I have no affiliation with Kingly Games (the creators of Eden World Builder). No "jailbreaking" or any other unauthorized activity was involved in this project. The Eden files are uncompressed and unencrypted, and iTunes copies all needed data to your hard drive when you back up your iOS device.

This article is intended as an educational resource, a tutorial and example of techniques for data analysis and recovery. These techniques are useful if (for example), a software program no longer functions properly, but it is important to recover valuable data or convert it to a new format.

Contents

Preliminaries

Circumstantial Evidence

Initial Investigation

(Back to Eden main page)

Preliminaries

Before embarking on a project like this, it helps to be familiar with other related file formats. The Minecraft file format is well-known and has been used for third-party mapping programs and other purposes. I myself figured out the Mooncraft-Lunacraft file format in order to make maps for that game.

It also helps to be an experienced computer programmer, although I think most of what is needed can be learned pretty quickly.

Getting Game Data

If you use your Mac or PC to back up your iPad (or other iOS device¹) using iTunes, then it is easy to get your saved game data. No "jailbreaking" or any other unauthorized activity is required.

When you do a backup, iTunes copies the saved-game data along with any other files that were created on the device into a directory. (It does not copy your iTunes music, TV shows and movies, because these were not created on the device, but it does copy photos and videos that you took with the camera.)

For this purpose make sure iTunes is making unencrypted backups (once you have your game data you can turn encryption back on).

The location of your iPhone/iPad backups will be:

On a Mac: (your-home-directory)/Library/Application Support/MobileSync/Backup/(something-long)
In Windows XP: C:\Documents and Settings\(username)\Application Data\Apple Computer\MobileSync\Backup\(something-long)
In Windows Vista and Windows 7: C:\Users\(username)\AppData\Roaming\Apple Computer\MobileSync\Backup\(something-long)

The part called "(something-long)" will be a bunch of letters and numbers, like "18d8e52579d25c981891058dd6ed51da43081e2e". If you have more than one Apple device, there will be more than one directory like this.

After saving your Eden world, connect your iPad to iTunes and do a backup. Then search within your .../MobileSync/Backup directory for the biggest file with a very recent modification date; this is probably the world you just saved. The name of the file will be another long string of characters like "891058dd6ed51da43081e2e18d8e52579d25c981".

Once you determine the location and name of this file, it will (usually) stay the same during subsequent iTunes backups. But if you delete your world and then re-download it from the Shared Worlds, or if you share it and load it into another device, the filename usually changes.

Examining Game Data

Programmers should have a variety of tools for inspecting files. On UNIX systems like Mac OS X and Linux, and in the Cygwin (UNIX for Windows) environment, the most useful commands are probably hexdump (also called od), diff and strings. It may be necessary to write your own programs to examine data files; such programs then often become the beginning of a useful utility for viewing or converting the game data into something else, like a JPG image containing a map.

Circumstantial Evidence

The first thing to do is to wander around the world and explore limits, and look for evidence of how the world is subdivided by the program.

Vertical Measurement

By digging and building, you can count the number of blocks and discover the vertical limits. This tells us what to expect when we examine the save files:

Counting blocks above ground: the game allows building 31 blocks above ground level in a "flat" world.

Counting blocks below ground: In a "flat" world there is always one block of "Bedrock"/"Adminium", 15 blocks of Rock, 16 blocks of Dirt, and 1 block of Grass.

Horizontal Measurements

When walking around a world in Eden, one occasionally sees a "Loading..." message, and then new parts of the world appear. Often, the "edge" of what is currently in memory is easily visible:

Edge of the world cuts off the suspension bridge.

The edge is not always in the same place:

Suspension bridge is cut off in a different place.

In this case, the edge is 16 blocks further to the right in the first picture. In similar situations, I have found that it is always some multiple of 16.

Another horizontal measurement that is more difficult to show involves lighting (in Eden 1.7, which had shadow effects; Eden 2.0 does not). There are subtle changes in the drawing of shadows that one can see while building. I noticed that when building something long and straight like a wall, lighting changes happen every 16 blocks.

Evidence for 16x16x16 Blocks

In Mega City Tokyo (pretty nearly all versions), in a certain place you can find this glitch:

A bottomless glitch block in Mega City Tokyo.

The first time I found this, I fell into the hole and landed in the street (which is far overhead in this photo). "Falling through the bottom of the world" is also seen in other games of this type.

I filled in the hole, and counted the blocks:

Floor of the glitch block filled in with glass. The hole is 16x16 blocks in size.

I also noticed several blocks of strange types and colors hovering in mid-air. There is also a rather distinct flat ceiling. Measuring vertically, we can see that the height of the glitch is also 16 blocks:

The glitch block is 16 blocks high.

Amount of Map Data in Memory

By placing a row of blocks and observing from a distance, like this, we can count the distance to all edges of the visible part of the world:

Measuring to the edge of the world

I have measured the total size of the piece of terrain that is being shown at any given time. This is always a square 192 blocks on each side. In terms of 16×16 chunks, that's a 12×12 arrangement of chunks each of which is 16×16 blocks. (In Eden 2.0, the visible area is 18×18 chunks or 288×288 blocks, which is only 50% bigger in any direction but seems like much more.)

There are 58 types of blocks in the game, and 55 types of coloring:

All block types and colors in Eden version 1.7

There are 56 block-types pictured, but in addition there are: a type of grass with "weeds" which cannot be placed, the "Bedrock" or "Adminium" block, the empty space or "air" block, and versions of water and lava that are 1/4, 1/2 and 3/4 the height of a regular block; thus there are 56+3+6 = 65 total types of block. In addition to the 54 colors shown, if you place a block and do not color it, it sometimes looks different. Therefore "original color" counts as a 55^th color.

With 65 blocks and 55 colors there are 3575 combinations. This is too many to store in a single byte, so it's likely the game needs to save two bytes of information per block.

Combining all the measurements described here, we would expect a new world to have (16 x 16 x 64) x (12 x 12) x 2 bytes of data. This works out to 4718592 bytes.

Initial Investigation

Knowing all of the above, I then looked at the save file for a brand-new "flat" world. The data file was 4733088 bytes, which is only a little bigger than the number 4718592 we just computed.

Furthermore, when making small changes (like digging out one block of grass and replacing it with brick) the save file did not change in size.

The next thing to do was to look at the data contents with od:

od -v -t xC data/w3-3.eden 0000000 00 00 00 00 ad 09 80 47 33 b3 67 42 7f 02 80 47 0000020 00 04 80 47 00 00 58 42 00 04 80 47 d1 65 b2 42 0000040 a0 2f 54 00 00 00 00 00 57 6f 72 6c 64 20 33 00 0000060 ... 0000140 62 36 38 33 ... ... 0000260 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0c 00 0000300 01 02 02 02 02 02 02 02 02 02 02 02 02 02 02 02 0000320 01 02 02 02 02 02 02 02 02 02 02 02 02 02 02 02 0000340 01 02 02 02 02 02 02 02 02 02 02 02 02 02 02 02 ...

The first 300₈ = 192 bytes include some text in ASCII. I found "57 6f 72 6c 64 20 33", which is "World 3" in ASCII, the name of my world. I also found 32 hexadecimal digits starting with "62 36 38 33 ..." and an unknown purpose (possibly personal, which is why I'm not showing it here).

Starting at 00000300₈ is a block of data looking like "01 02 02 02 02 02 02 02 02 02 02 02 02 02 02 02". There are exactly 256 lines of this, ending at 00010277₈:

0010260 01 02 02 02 02 02 02 02 02 02 02 02 02 02 02 02 0010300 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0010320 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0010340 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

10300₈ - 300₈ is 4096₁₀, which is 16×16×16. So we have a 16x16x16 chunk of blocks, and the pattern of 01 followed by 15 copies of 02 makes it look like this is the block of Adminium and 15 blocks of rock at the bottom of the world. The block data is arranged in vertical columns.

Following this was 4096 bytes of 0's starting at 00010300₈, then at 00020300₈ there is 4096 bytes of 3's. Then another 4096 zeros, and then at 00040300₈ we find 4096 bytes consisting of 256 copies of "08 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00". Then a bunch more zeros, then at 00080300₈ the whole thing repeats again.

I came up with the theory that I was indeed looking at chunk data, and that the blocks of 4096 bytes of 0's are the color information. Each 16×16 piece of the world is stored as eight blocks of 16×16×16 = 4096 bytes, for a total of 32768 bytes.

In order for this to work, there must be a "table of contents" telling where each piece of the map is stored in the data file. This table should contain X and Y coordinates and pointers to file locations, like 00000300₈ and 00080300₈. Here is what the end of the file looks like:

... 25000300 a3 1b 80 47 00 20 04 42 23 d0 7f 47 2d b3 7b b6 25000320 00 00 00 00 ab 3a bd 37 ee 65 c5 40 03 00 00 00 25000340 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 25000360 00 00 00 00 00 00 00 00 00 00 00 00 6a 13 80 47 ... 25027560 2a ce d0 bd 00 00 00 00 bd fb c1 bc 23 20 06 40 25027600 ff ff ff ff 00 00 00 00 00 00 80 3f 00 00 00 00 25027620 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 25027640 02 10 00 00 fd 0f 00 00 c0 00 30 00 00 00 00 00 25027660 06 10 00 00 fa 0f 00 00 c0 00 4c 00 00 00 00 00 25027700 00 10 00 00 fd 0f 00 00 c0 80 45 00 00 00 00 00 25027720 06 10 00 00 01 10 00 00 c0 80 4b 00 00 00 00 00 ... 25035020 00 10 00 00 fb 0f 00 00 c0 80 1c 00 00 00 00 00 25035040

The rows starting at 25027640₈ look promising. "c0 00 30 00" is 003000c0₁₆, which is 14000300₈, the beginning of one of the 32768-byte chunk data blocks. "c0 00 4c 00", "c0 80 45 00", etc. also translate into valid chunk addresses. And there were exactly 12×12 = 144 rows of this data. So the other data in the rows, like "02 10" and "fd 0f", must be the X and Y coordinates.

Looking back at the 192-byte header, we can now see the value: "a0 2f 54 00" which is 00542FA0₁₆ = 25027640₈, the beginning of the chunk pointers section.

I wrote a simple program to scan this information in and attempt to render it as a plain ASCII text map of the middle of the test world. In the following image, the top is a photo (screen-shot) taken in the game of the middle of my world, with some shapes made out of different types of blocks. The bottom shows my very first map program, displaying that part of the world with ASCII graphics.

data format verified

SUCCESS!

First Real Maps

Once the format was verified, all that remained was to write a more serious program that scans everything in and generates full-color graphical output. Here is a map of one of my early Eden worlds generated by my program:

My first Eden map as a JPG image

Here is an overhead view of the same world taken from within the game:

Overhead view of my test world "mrob2". North is to upper-left.

The trees, clouds, my ice-slides, and other features are easy to see in the map image.

I spent a while carefully adjusting the colours, and making the program show tall structures as if viewed from a slight angle (using "axonometric projection").

The program works on almost all of the worlds I've tried. Here's a map of the central part of DJ Asian Tech's "Mega City Tokyo V4" (03/27/2013) :

DJ Asian Tech'sTokyo

click here for full size
or here if that link does not work

My maps have been useful on the Eden wikia, where I have posted maps of the very popular worlds and of my own creations. I have also created maps for the Direct City team.

What I have described so far is enough to make maps of all of my own Eden worlds and most of those I have downloaded from others. However, it would be fun to know a little more about the 192 (octal 0300) bytes at the beginning of the file. Here again are the first 48 bytes of the example used above:

0000000 00 00 00 00 ad 09 80 47 33 b3 67 42 7f 02 80 47 0000020 00 04 80 47 00 00 58 42 00 04 80 47 d1 65 b2 42 0000040 a0 2f 54 00 00 00 00 00 57 6f 72 6c 64 20 33 00 ...

As already described, the 57 6f 72 6c 64 20 33 00 part is simply "World 3" in ASCII, and a0 2f 54 00 is the pointer 00542FA0₁₆ = 25027640₈, indicating the beginning of the chunk pointers "table of contents" which is near the end of the whole file.

We also know that the game needs to save the player's location (X, Y and Z coordinates) and direction (which way you're facing) plus a home location (another X, Y, Z). To see if these are in the header, I took the following steps:

Create a new flat world. Make an enclosed square area with an ice floor and any normal block (like fence or stone) for walls. Under the "southwest" corner dig a hole, then climb back out and restore the ice floor. Slide into the southwest corner. Save the game. Examine the header of the savefile.
Turn to face a different direction. Save the game and examine the header of the savefile.
Slide north. Save the game and examine the header of the savefile.
Slide back into southwest corner, then slide east. Save the game and examine the header of the savefile.
Slide back into southwest corner, then face down and break the block. Save the game and examine the header of the savefile.
Climb back up, restore the block broken in previous step. Slide back into southwest corner. Set home location. Save the game and examine the header of the savefile.
Slide north. Set home location. Save the game and examine the header of the savefile.
Slide back into southwest corner, then slide east. Set home location. Save the game and examine the header of the savefile.
Slide back into southwest corner, then face down and break the block. Set home location. Save the game and examine the header of the savefile.

By looking carefully at the header each time it was easy to determine each of the following:

4 bytes starting at byte 4 is current east-west position
4 bytes starting at byte 8 is current z (vertical) position
4 bytes starting at byte 12 is current north-south position
4 bytes starting at byte 16 is east-west position of Home location
4 bytes starting at byte 20 is vertical position of Home location
4 bytes starting at byte 24 is north-south position of Home location
4 bytes starting at byte 28 is rotation

All of these 4-byte values are little-endian 32-bit floating point values. For example, we see a 00 04 80 47 which is the 32-bit value 47800400, which is the floating-point value 65544.0.

One additional value was fairly easy to deduce: the four bytes at the very start. By comparing various worlds it is clear that 'flat' worlds have 00 00 00 00 in those 4 bytes, and worlds with 'normal' terrain have some other value. Also, when downloading different versions of the same world created by different people (such as the variants of the "Mega City Tokyo" worlds) all of them have the same 4 bytes (ab c1 01 00 in the case of the Tokyo variants). It seems that this value is the 'seed' used in the terrain-generation algorithm (though to test this, one would need to change the value and see if terrain is generated differently as a result).

Source Code

The source code for my implementation of Eden mapping is here:

Source code: la-map.c

Detailed instructions are provided in the block header comment at the top of the source code. It works on UNIX, Linux, MacOS X, and Cygwin (a free UNIX that runs within Windows).

(If you like this kind of thing, I also figured out the Lunacraft/Mooncraft file format.)

Footnotes

1 : I refer to all iOS devices (iPad, iPhone and iPod Touch) as "iPad" in this article.

Links

List of My Shared Worlds (mostly versions of "Mega City Tokyo Unified")

Vuenc's Program

Based on my analysis of the Eden file format, and one or two hints from Ari (one of the Eden developers), Vuenc has created a program "for reading Eden-files and manipulating them". It can perform manipulations like turning all dirt/grass into water to create a huge ocean world.

Read about it here on the Eden forum: Vuenctools for Eden

This page was written in the "embarrassingly readable" markup language RHTF, and was last updated on 2020 May 12.

s.27