Eschalon Savefile Editor

Some of how Eschalon's map files are used may not be immediately obvious, so I figure I'll enumerate some points here.

General Information

Eschalon keeps all its global maps in the "data" directory of the folder where it was installed, in Book 1, or in the main "datapak" for Book 2/3. Once your character enters a new map, the game engine loads in that global map file and from that point on only uses that new copy of the map, which is the version that's saved in your savegame folder when you save the game. The format of the global map files and the savegame map files is slightly different, in the following two ways:

1. For entities, the global map files only specify the type of creature, its facing direction, and a script to execute when the entity is killed. Savegame maps add in a number of other values such as entity friendliness (NPCs are set to "1", monsters to "0"), health level, and a few other values.

2. For containers like chests and bags, the global map files only specify a single string for the item contents. The savegame map files specify a full item structure for each slot.

Because of these differences, our utility won't let you save a global map file as a savegame map file, and vice-versa. If you load in a global map file, it will remain one when you save it. You can see what kind of map you've loaded from inside the "Map Properties" dialog (also the path shown in the bottom status bar will probably be informative enough).

Important note for editing Book 1 maps: In the Map Properties screen there's a "Map ID" field which wasn't editable until version 0.7.2 of the editor. If you're making a "new" map by starting with an existing one and saving with a new name, note that this value must be the same as the filename of the map (minus the ".map" extension), otherwise Eschalon won't save the state of the map properly in savegames, and might actually overwrite the state of the map that you copied from, which could certainly be undesirable. So be careful about that. Book 2/3 doesn't have the Map ID embedded, so it's not an issue there.

The map names for the main "outside" area of Eschalon are named with a two-digit number for Book 1, and a four-digit number for Book 2/3, which correspond to where the map is placed. In Book 1, the first digit is the y-coordinate (or row), and the second is the x-coordinate (or column). In Book 2/3, the first two digits are the x-coordinate, and the second two are the y-coordinate. The first map your character starts out in is 35.map in Book 1, and 5050.map in Book 2/3. The various dungeon level names are, for the most part, pretty obvious. For reference, here are the outside map names:

Book 1	Book 2	Book 3
14 - Barrier Range Region 15 - Northeast Thaermore 22 - Vela 23 - Baron's Thicket 24 - Northern Tangletree Forest 25 - North Parish 32 - Blackwater Region 33 - Western Tanglewood 34 - Central Tangletree Forest 35 - South Parish 41 - Rotwood 42 - Northern Crakamir 43 - Northeastern Crakamir 44 - Western Salted Coast 45 - Eastern Salted Coast 51 - Western Crakamir 52 - Eastern Crakamir 53 - The Gulf of Madria	4447 - Hammerlorne Mountain 4547 - Durnore Region 4647 - Northern Hellice Lake 4648 - Western Hellice Lake 4747 - Northeastern Hellice Lake 4748 - Raven's Gate West Entrance 4848 - Raven's Gate, East Entrance 4849 - Yoma River Headwater 4850 - Eastern Sylphwood Forest 4851 - Northern Harpoon Bay 4858 - Picaroon Isle 4947 - Cape Sorrow 4948 - Fellpine Forest 4949 - Western Kessian Basin 4950 - Greenriven Lake 4957 - Hallows of Abigor 4958 - Brimstone Lava Fields 4959 - Thundersun Grazelands 4960 - Southern Thundersun Grazeland 5047 - Broken Blade 5048 - Eastern Fellpine Forest 5049 - Wolfenwood 5050 - Yoma River Valley 5051 - Yoma Narrows 5059 - Ghar-gha River 5060 - Talushorn 5147 - Mistfell Northen Coast 5148 - Northwest Kessian Basin 5149 - Central Farrock Range 5150 - Southern Kessian Basin 5247 - The Forsaken Coast 5248 - Port Kuudad 5249 - Northern Farrock Range	4849 - Moonrise 4850 - Baasilt Dunes 4948 - Western Astral Range 4949 - Elderoak Forest 4950 - Southern Boglands 5047 - Alundar's Domain 5048 - Warlord's Pass 5049 - Valley of the Wanderer 5050 - Rockhammer 5051 - Deadman's Strand 5052 - Mirkland 5148 - Eastern Astral Range 5149 - Macross Point 5150 - Oceana Lowlands 5151 - Castle by the Sea 5152 - East Mirkland Delta

Tile Info

There's not much to say about the basic tile attributes, actually. There's one unknown value in the "Main Attributes" tab, but I believe it's always been zero for every tile I've ever loaded in.

In Book 1, there are two kinds of walls: ones that you can see through (gravestones, for instance), and ones you can't. Book 2 added another kind of wall which restricts player movement around the wall. For instance, the player at this position in Eastwillow can't move directly North:

If the player attempts to move North, he'll be shifted off Northeast, instead, like so:

The wall graphic shown there is the most common one to feature this type of restricted-movement wall.

Entity Info

As mentioned above, if you're editing a global map file, you'll only be able to edit entity type, orientation, and a post-death script. Savegame files will have extra information like friendliness and health, and a few other values. For the most part, I recommend leaving those other values alone. Two of them I've never seen set to anything other than zero, one appears to get set automatically by the game engine regardless of what you had in there, and the other seems to be either 1 or 0, but I've yet to find any pattern for it.

One value found in a savegame file is the initial starting location of the entity, which I believe entities will gravitate towards if they're not attacking you. The map editor will populate this automatically when you add a new entity.

The "Friendly?" flag is zero for enemies, 1 for NPCs, and 2 for NPCs who are attacking you (having witnessed you commit a crime, for instance).

As I mention on the Entity tab itself, there are a few NPCs who can ONLY face North. If you add one of these facing any other direction, or something in the game causes them to turn, Eschalon will crash. So be careful about that.

Entities added with zero health are "stuck" on the board and can't be attacked, so make sure to give new entities at least 1 health, if you're adding to savegame files.

Object Info

I used to call these "scripts," and internally my code still refers to them as such, but "object" makes much more sense as a name.

There are actually two related values here: an Object Type and an actual Object. Most object types require an associated object to be defined, and some don't.

Book 1 Object Type List

Here's a list of the types which do require an object:

• 1 - Containers with no open/close difference (open barrels, hives, spider egg sacs, coffins, etc)
• 2 - Corpse Containers (chance of disease when examining)
• 3 - Containers with open/close differences (chests, dressers, etc)
• 4 - There's just one single cabinet in the entire game which uses this, in 25_crypt. It'd be best to not use this value
• 5 - Doors
• 6 - Map Links (for cave exits, etc)
• 7 - Wells, Levers, and other misc items
• 9 - Signs which highlight wall decals (plaques, bookcases, etc)
• 10 - Signs which highlight walls (signs, gravestones, etc)
• 11 - Sealed Barrels
• 12 - Miscellaneous Scripts
• 13 - Sconces
• 14 - Traps / Teleporters / Other Tile-triggered scripts
• 15 - Blackpowder Kegs

And then there are some object types which do not require an associated object:

• 25 - Light Source (note that the light produced is actually quite weak)
• 30 - Inn Sound Generator
• 31 - Church Sound Generator (chanting)
• 32 - Windy Rift Sound Generator
• 33 - Running Water Sound Generator
• 34 - Magic Shop Sound Generator
• 35 - Blacksmith Sound Generator
• 36 - Woodland Sound Generator
• 37 - Crowd Sound Generator
• 38 - Waterfall Sound Generator

Book 2 Object Type List

In nearly every case, Book 2 Object Types will always have an associated object, even for the sound and light generators. The one exception seems to be that sometimes a "Zapper" (electric field) won't have an object, though sometimes they do.

• 1 - Containers with no open/close difference (open barrels, etc)
• 2 - Containers with open/close differences (chests, dressers, etc)
• 3 - (broken container type, don't use this one)
• 4 - Bag Containers
• 5 - Doors
• 6 - Map Links (for cave exits, etc)
• 7 - Clickable Actions (Levers, and other misc items)
• 8 - Entrance to Thieves' Arcadia (Only used that once)
• 9 - Signs which highlight wall decals (plaques, bookcases, etc)
• 10 - Signs which highlight walls (signs, gravestones, etc)
• 11 - Sealed Barrels
• 12 - Sconces
• 13 - Area Event (triggered by proximity)
• 14 - Traps / Teleporters / Other Tile-triggered scripts
• 15 - Powder Kegs
• 16 - Well
• 17 - Archery Target
• 18 - Nests / Computer Terminals
• 19 - Zapper (electric field)
• 21 - "Big" Graphics (Hammerlorne Entrance, Docked Ships, etc)
• 25 - Light Source (white)
• 26 - Light Source (red)
• 27 - Light Source (green)
• 28 - Light Source (blue)
• 29 - Light Source (yellow)
• 30 - Sound Generator (Inn)
• 31 - Sound Generator (Church)
• 32 - Sound Generator (Cold Wind)
• 33 - Sound Generator (Dripping Water)
• 34 - Sound Generator (Bubbling Water)
• 35 - Sound Generator (River)
• 36 - Sound Generator (Magic Shop)
• 37 - Sound Generator (Blacksmith)
• 38 - Sound Generator (Swamp Insects)
• 39 - Sound Generator (Busy Street)
• 40 - Sound Generator (Waterfall)
• 41 - Sound Generator (Wind, with Tapping)
• 42 - Sound Generator (Wind)
• 43 - Sound Generator (Swimming Water)
• 44 - Sound Generator (Electric Field)
• 45 - Sound Generator (Electric Throbbing)
• 50 - Breakable Wall

It's worth noting that there is no instance within the game of a tile having an object but no Object Type defined, so bear that in mind.

It's also worth noting that there are three times (over the span of every single map in Eschalon) where a tile has two objects defined. In each case, it looks like the game engine is only recognizing one of the two, so I'm guessing that their presence is just a mistake.

For Object Type 6 (Map Links) in Book 1, the main "Description" field on the Object will be the name of the map to link to, and the "Extra Text" field is the coordinate within the map that the player will be sent to. In Book 2, the linking is handled just within the script, usually as "map_port (mapname) coords ; areacheck".

I mention coordinates there, and you'll also see coordinates mentioned occasionally in various objects' script text. The game has a somewhat odd notation - the coordinate pair (56, 129) would become "12956". The coordinate pair (3, 40) would become "4003". It's a bit counterintuitive but it does work well since the x coordinate can be at most 99.

In Books 2 and 3, an object type of 21 is a "Big" graphic, such as the main (impassable) Hammerlorne Entrance, and the docked ships. It's also used for a couple smaller images like wagons. Tiles with a Big Graphic object must also have a Wall Image ID of 1000, 1001, 1002, or 1003, and that wall ID will get associated with the filename specified by the "Extra Text" section of the Object. From that point on, the engine will only look at the Wall ID to determine which graphic to draw, so there can only be four unique Big Graphic objects on any given map. You can place multiple instances of the same graphic by reusing its ID. For instance, in Oceana Lowlands in Book III, there are multiple sgfx_raft.png objects which all share the Wall ID 1000.

If the "Lock Level" on a container or door is set to zero, then the container isn't locked. Lock levels work a little differently between books 1 and 2. In Book 1, a Lock Level of 1 is the weakest lock, and a Lock Level of 60 is the highest encountered in the game (the door behind Gramuk at the end of the game), though very few locks in the game get above 30. The special lock value of "99" denotes that it's a slider lock. The next field after "Lock Level" on the GUI will store the slider lock combination, and otherwise will be a value from zero to three. I still haven't figured out what that value means when the lock isn't a slider lock. In Book 2, locks have a difficulty from 1 to 10, and if the lock level is set to 12, then it will be a slider lock.

In Book 1, the "Destructible" flag will determine whether or not the player can destroy the object, which is typically only used on chests, doors, and barrels. The "sturdiness" field determines how strong the object is, and seems to just be the starting percentage of "health" that the object starts out with. Almost all objects in the game start with a sturdiness of 89. In Book 2, there's a much more sensible Current and Max "HP" for the object, if it's destructible.

Book 2 has two extra properties in Objects: Loot Level and "On-Empty." Loot Level runs from zero to ten, and notes how good the loot inside the container is, for randomly-generated contents. This is the field which gets used for the slider lock combination. "On-Empty" defines what happens when the container is emptied of its contents. For most containers this is zero, but bags tend to have 1 in here, which denotes that they will disappear once empty. A few other containers have other values, such as the Dragonel nest, Brimstone Spider nest, and computer terminals.

The "contents" section is actually somewhat interesting. As mentioned above, global maps just specify a string. When the map is saved out in a savegame, the file includes a whole Item structure (including things like weight, cost, special abilities, etc). Until a container is actually opened, though, the only field which is populated in that whole structure is the name. Once the user opens the container for the first time, the game engine populates the rest of the item attributes based on the name. That's why you'll see buttons like the one seen in the "Tile Editing - Scripts" section of the map screenshots page. Note that the special name "Random" is used to randomly fill up a container. The "Random" keyword will possibly fill up more than one item, as well, so containers which specify Random shouldn't have anything but the one "Random" item. A similar "Empty" keyword is defined for Book 2, as well.