Eschalon Savefile Editor

Scripts in Book 1 are found in one of three places: embedded in map tiles, inside items (whenever you can "Use" an item in your inventory), and a script that an entity runs when it dies. In general, most of the script commands that I've found can be run in any of those places, though some commands only make sense in one context.

Commands can be separated with a semicolon, most often with whitespace around them, so to show a message to the player and play a sound effect, you'd do something like "message (You hear a noise!) ; sound (sfx_energize)". There may be some upper limit to how many commands you can run at once, but I don't know that for sure. I suspect that the Book 1 parser has a token limit similar to Book 2, but I have yet to verify that. See the Book 2 scripting notes for more information on tokens.

An example command definition here will be given like so:

gfx (<effect>) <coords> <color>

The parentheses there are part of the actual command; they should be included if you're using the command. Anything in italics and angle brackets is data that you, as a map editor, should replace with the correct values. Whenever you see <coords> in a command, you'll be using a simple number of the form "YYYXX", though you don't need to zero-pad the number. For instance, the coordinate (34, 125) becomes 12534. The coordinate (5, 28) becomes 2805. Note that unlike in Book 2 scripts, there's no way to say "the current square;" you have to know the actual coordinates.

Commands which seem to be only present in Book 1 will be highlighted in blue. Commands which exist in Book 2 but with a different name will be highlighted in yellow.

Note that even though many of these commands are valid in both Book 1 and Book 2, they might behave slightly differently, or have different arguments.

General-Purpose Commands

These are commands which should theoretically be valid anywhere.

Quest-Related

Each quest has a number in Book 1, which I haven't mapped out yet. In addition to the main quests, there appear to be some internal flags which the game stores in "quests" which don't show up in your quest book (for instance, for keeping track of the number of Salamanders killed in Leurik's basement). Each quest has a "state" number associated with it. To put a quest into the player's Quest book, you'd set the state to 1. It looks like a successfully-completed quest will have a state of 9. Also, quests that haven't started yet might have a state of -1.

I've been told that it is possible to use quest numbers up to at least 20,000 as state variables of your own (for more complex custom mapping, for instance), though use caution, since it's unknown what's happening in the program's memory area when that's being done.

quest <questnum> <state>

Set the specified quest to the specified state.

kill_quest <questnum>

Mark the quest as uncompletable (quest must be currently active). Used in a few entity death scripts.

quest_step <questnum>

Increments the quest status by one. Used for the Salamanders in Leurik's basement, the Fungal Slimes for Phillip's quest, and Noximander/Raptor ambush in Shadowmirk Level 2. Note that you can't use this on "real" quests, only on the "counter" type quests. You can't complete a quest using quest_step.

all_quests

Adds all quests to the player's Quest Journal.

Conditional Statements

These are used to conditionally execute scripts. All of these will abort the execution of the script unless the condition is met. There doesn't appear to be any "else" clause or the like - if the condition isn't met, the script execution will simply stop.

condition (<text>) (<yes text>) (<no text>)

Displays a message (on parchment) to the player, with the two given options, and the script will only continue if the user hits "Yes." The last two arguments are usually "Yes" and "No," but it seems they can be just about anything.

cond_item (<itemname>)

Script will terminate unless you have the named item

cond_quest <questnum> <state>

Script will only continue if the specified quest is at the specified state

cond_not_quest <questnum> <state>

Script will only continue if the given quest is NOT at the specified state

cond_special <num>

Special condition, which in Book 1 sometimes triggers actions as well. Probably not very useful to custom map makers. The special conditions seen in the game:

1. Teleporter puzzle in Shadowmirk Level 1 (chests)
2. Vidar the Knife takes 75 gold pieces (if possible), or attacks you
3. Chest puzzle in Tangletree Ossuary
4. Monolith in Goblin Citadel, level 1 (opens doors)
5. Torch puzzle in Mysterious Cavern
6. Called after accepting Gramuk's offer
7. called after Crux placed on pedestal, probably wakes up Chancellor
8. Rolls "good" end cinematics
9. Chancellor killed, Spire Guards spawn and attack
10. Egg Display rack in Shadowmirk
11. "Destroyer" rank awarded, "bad" ending cinematic starts
12. Drink Pure Water, gain +2 Skill Points to use at next levelup
13. Demonic Statue, Goblin Citadel, Level 1 (fire trap)
14. Switch at the top of Lighthouse
15. Give 10 Hive Larvae to Hesham
16. Bottom of Lighthouse stairs, probably what generates goblins
17. Non-useable boat outside of the lighthouse

cond_spot

Script will only continue if the player passes a Spot Hidden check (typically this is triggered by a type 12 object, triggered by proximity).

cond_health

Script will only continue if the user isn't at full health (used in healing elixirs).

cond_mana

Script will only continue if the user isn't at full mana (used in mana potions).

cond_gold <goldamount>

Script will only continue if the user has at least the specified gold.

cond_state <coords> <state>

Script will only continue if the object at the given coordinates is in the state given. This is typically used to check toggle states. Valid states in the game, used by doors, chests, other containers, and toggle switches:

1. Closed
2. Open
3. Broken
4. Toggle 1 (upright)
5. Toggle 2 (toggled)

cond_detected

Unknown - has always returned "true" for me.

Interactions with the Player

give_item (<itemname>)

Place the named item in the player's inventory

remove_item (<itemname>)

Remove the named item from the player's inventory. You may want to call a cond_item first, to be safe.

strip_items

Removes all items from the player's inventory, including torches but excluding gold.

move_player <coords>

Send the player to the given coordinates, within this map.

port_to <coords>

Send the player to the given coordinates, within this map, with some portal effects.

map_port <mapname> / map (<mapname>)

Send the player to the given map name, to the "last visited" coordinates stored with the map. The two forms seem to be basically identical, except that I've only seen map_port used without parens, whereas map I've only seen used with them. Use of map_port is typically followed by a port_to, to move the player to the correct spot.

add_gold <n>

Adds the specified amount of gold directly to the player's inventory

remove_gold <n>

Removes the specified amount of gold from the player's inventory

heal <hp> <hidden>

Heal the given amount of HP; if "hidden" is greater than zero, no message will be shown in the message pane, and the graphical flourishes will be supressed

restore <mp>

Restores the given amount of MP

cure_disease <effectiveness>

Cures diseases. Usually this is associated with a potion, but it doesn't have to be. The effectiveness tends to be either 3 or 6, probably associated with the Cure Disease casting level. Higher numbers are required to cure the higher diseases.

cure_poison <val>

Cures poison. The value I've always seen is 4, I'm not sure what exactly it means. Usually this is associated with a potion, but it doesn't have to be.

poison <hp>

Poisons the character for a total of hp hitpoints, spread out over a number of turns, taking one point of damage at a time.

trauma <hp>

Injures the player by the given HP.

disease <diseasenum>

Give the player the given disease (they have a chance to save versus disease resistance, though). Diseases in the game:

1. Dungeon Fever
2. Rusty Knuckles
3. Eye Fungus
4. Blister Pox
5. Insanity Fever
6. Fleshrot
7. Curse

effect (<effect>) <levelnum>

Used in potions to grant various effects, though it doesn't have to be tied to an item. The levelnum probably refers to an equivalent spell-casting level, though I don't know that for sure. The effects are in english, not numbers. Some of the effects and associated levels (from potions) that I've seen are:

1. Cat's Eyes: 2
2. Haste: 2, 4
3. Invisible: 2, 4, 6
4. Keensight: 3
5. Leatherskin: 2, 4, 6
6. Mana Fortified: 3
7. Ogre Strength: 3
8. Predator Sight: 3
9. Poisoned: 3

I've also gotten reports of the following working fine:

1. Air Shielded
2. Blessed
3. Chameleon
4. Charmed
5. Elemental Armor
6. Enchanted Weapon
7. Enkindled Weapon
8. Entangled
9. Gravedigger's Flame
10. Greater Protection: 3
11. Nimbleness: 3
12. Off-Balance (This only displays a message, though)
13. Paralyzed (This only displays a message, though)
14. Reveal Map
15. Scared
16. Stoneskin
17. Stunned

These lists may not be exhaustive, of course.

cleric_heal

Opens a dialog to allow the player to pay for divine healing. This will deduct gold if they player agrees.

cleric_dehex

Opens a dialog to allow the player to pay for divine de-hexing. This will deduct gold if they player agrees.

curse

Will curse the player, if the player fails a Wisdom check.

full_restore

Cures all diseases and poison. Will leave Curse intact, though.

rename_item <old name> <new name>

Renames the given item in the player's inventory.

rent_room <cost> <coords>

Used for Inn scripting. Will launch a dialog offering a room for the specified cost. If accepted, the player will wake up at coords.

teach_skill (<name>) <skillnum>

Offer to train the player in the specified skill. The player will have to pay the usual fee, and be restricted to the usual Book II training limits. The name argument will just be used to display the name in the initial dialog, and does not have to match any existing NPC.

Interactions with the Map

close_door <coords>

Closes the given door. Note that there doesn't appear to be an open_door.

close_port <coords>

Closes the given portcullis. Note that there doesn't appear to be an open_port in Book 1.

toggle_port <coords>

Toggle the given portcullis

toggle_obj <coords>

Toggle the existance of a given wall - This will work for basically any graphic. Note that objects currently toggled-off when you save the game don't get saved properly in the Book 1 savegame file; on the next load, the wall will be visible but your character will be able to walk through it.

destroy_obj <coords>

Completely destroys the given wall - This will work for basically any graphic.

drop_ent <entnum> <coords>

Drops the given entity at the given coordinates. (Entity Number Lookup)

remove_npc <entnum>

Removes all entities with the given ID from the current map. (Entity Number Lookup)

npc_die <entnum>

Sets the hitpoints for the given entity to zero. Note that in Book 1, this command does not actually kill the entity. They will remain on the map, and not attackable. (Entity Number Lookup)

npc_disp_change <entnum> <disposition>

Changes the disposition of the given NPC entity. Note that this does not appear to work for monsters. Disposition IDs:

1. Hostile (This is typically used for monsters)
2. Friendly
3. Hostile (This is used for NPCs you've attacked, or who have otherwise become hostile. They should theoretically be Charmable back to Friendly)

trigger_talk <entnum>

Triggers a conversation with the given entity ID. The entity must be present somewhere on the map for this to work.

convert_tile <typenum>

Converts the current tile to the given object type. Typically this is "1", to make hidden cave treasure clickable, after a cond_spot. Note that you can technically change to any type, but make sure that a valid object is in place already for the type you're switching to. The only thing that this changes is the Object Type itself.

areacheck

Unknown.

det_keg <coords>

Detonates the powder keg at the given coordinates. If there's no powder keg there, this has no effect.

init_trade <name>

Initiates a trade window with the specified NPC. Note that Book I expects the NPC name here, not an entity ID. The NPC does not need to be present on the map for this to work. If an invalid name is specified, a trade window will be opened with a blank name and zero gold reserves.

remove_barrier <coords>

Allow the player to walk through the given coordinates.

trap <param>

Plays a sound effect as if a trap had been sprung, but has no actual effect on the player or environment.

spell (<spell name>) <level>

Casts the named spell, at the given level. Unknown spell names will crash Eschalon. I haven't found a way to provide target information for this, so it looks like this command can probably only cast spells which don't require targeting, such as defensive spells. This will deduct the appropriate amount of mana from the player's pool, and can cause the player's MP to go below zero.

Other Commands

gfx (<gfx effect>) <coords> <colornum>

Launches a fancy graphical effect at the given coordinates. Effects that I've noted in the game, and the associated colornum values for each:

• Colored Smoke
  
  0. white
  1. green
  2. yellow/orange
  3. blue
  4. grey
  5. black
• Divine Light
  
  0. White (other numbers don't seem to change the effect)
• Flare
  
  0. (invalid)
  1. Red
  2. Green
  3. Blue
  4. White
• Flare Burst (very much like Flare but bigger, and rotates more)
  
  0. (invalid)
  1. Red
  2. Green
  3. Blue
  4. White
• Gibs
  
  0. Red
  1. Green
• Port
  
  0. Multicolored (no discernable change on other numbers)
• Sparks
  
  0. Yellow (no discernable change on other numbers)

message (<message text>)

Displays the given text in the message pane

narrative <narrativenum>

Displays the given narrative. This is accompanied by a little graphical flourish in the message pane, and a sound effect.

kill_narrative <narrativenum>

Tells the game engine not to display the given narrative anymore. Used when a narrative text would no longer be accurate if triggered.

notebox <number>

Displays a piece of parchment with some information. Used for alchemy recipes and the posted notice in the Underground Repository.

activate_qt <quicktravel num>

The player "discovers" the given quicktravel point (this doesn't actually send the player to the quicktravel point, it just makes that point clickable).

book <booknum>

Shows book text. This will sometimes have effects other than just showing the book text.

destroy_script

Destroys this script (one-time use).

commit_crime

Area NPCs may notice you committing a crime

no_crime

Allows access to something which would otherwise be considered a crime.

drama

Unknown - used once in the Vidar the Knife ambush in Northeast Thaermore, but doesn't seem to have any discernable effect when I try it elsewhere.

alert_npcs

Unknown - used once in the Vidar the Knife ambush in Northeast Thaermore, but doesn't seem to have any discernable effect when I try it elsewhere.

sound (<soundname>)

Plays the specified sound. The soundfile name might be case-insensitive. I have seen, for instance, both "SFX_Quaff" and "SFX_quaff". Note that the engine will change the pitch somewhat, so consecutive executions may sound slightly different. The soundfiles that I've seen referenced by the game:

• eat
• ghost_laugh
• mo2_move
• sfx_bell
• sfx_energize
• sfx_heal
• sfx_port_down
• sfx_quaff
• sfx_quaff
• sfx_stash
• sfx_stats_Open
• stairs
• stone_collapse
• stone_slide
• thunder
• war_horn
• water_rush

display (<graphicfile>)

Displays the given graphic file (used primarily for the inventory map). Note that the graphic file referenced lives inside the graphics pak, so you can't add your own graphics.

time

Display the in-game time (used in chronometers)

screen_fade_in
screen_fade_out

These do what you'd expect. Note that the screen will not fade back in unless you explicitly call screen_fade_in, so be careful.

updatezones

Unknown.

convert <param>

Unknown.

delay <turns>

Advances the game time by the specified number of turns. Timed effects will expire, etc.

Usually Only Used in Entity Scripts

These commands are typically found in Entity Death scripts, and often don't make much sense in other contexts. Note that you can call these elsewhere if you want, though.

drop_item (<Item Name>) <percent chance>

Drops the named item with the specified percent chance. Percentage *might* be optional? Set 100 to have it always happen.

drop_loot

Drops a bag of loot. This doesn't seem to actually be used in any of the entities I've seen, but the command does work.

Only Used in Item Scripts

These commands are only found in Item scripts, for when you "Use" them, and will typically not work outside of that context.

learn_book <booknum>

Teaches the player the given skill, used in books. This doesn't seem to work properly when used outside of a book - a message will display saying that the player has learned the skill, but the skill value doesn't actually go up, and shows up in red in the character status screen. If anyone can find a way to make it work outside of books, let me know.

learn

Teaches the player the appropriate spell, based on the name of the Item. The item needs to be named "Scroll of Spell Name", or else the game will crash.

remove

Removes the used item from inventory

to_flask

Used on potions to turn the potion into an empty flask

Only Used in Tiles/Squares

These commands are found in square/tile scripts, and don't make much sense outside of that context.

unlocked_with (<key name>)

Used on locked doors and containers, specifying the key to use.

toggle_switch

Toggle this switch's position. (Should only be used when there's a toggle switch.)