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.
These are commands which should theoretically be valid anywhere.
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.
- Adds all quests to the player's Quest Journal.
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:
- Teleporter puzzle in Shadowmirk Level 1 (chests)
- Vidar the Knife takes 75 gold pieces (if possible), or attacks you
- Chest puzzle in Tangletree Ossuary
- Monolith in Goblin Citadel, level 1 (opens doors)
- Torch puzzle in Mysterious Cavern
- Called after accepting Gramuk's offer
- called after Crux placed on pedestal, probably wakes up Chancellor
- Rolls "good" end cinematics
- Chancellor killed, Spire Guards spawn and attack
- Egg Display rack in Shadowmirk
- "Destroyer" rank awarded, "bad" ending cinematic starts
- Drink Pure Water, gain +2 Skill Points to use at next levelup
- Demonic Statue, Goblin Citadel, Level 1 (fire trap)
- Switch at the top of Lighthouse
- Give 10 Hive Larvae to Hesham
- Bottom of Lighthouse stairs, probably what generates goblins
- Non-useable boat outside of the lighthouse
- Script will only continue if the player passes a Spot Hidden check (typically this is triggered by a type 12 object, triggered by proximity).
- Script will only continue if the user isn't at full health (used in healing elixirs).
- 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:
- Toggle 1 (upright)
- Toggle 2 (toggled)
- 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.
- 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:
- Dungeon Fever
- Rusty Knuckles
- Eye Fungus
- Blister Pox
- Insanity Fever
- 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:
- Cat's Eyes: 2
- Haste: 2, 4
- Invisible: 2, 4, 6
- Keensight: 3
- Leatherskin: 2, 4, 6
- Mana Fortified: 3
- Ogre Strength: 3
- Predator Sight: 3
- Poisoned: 3
I've also gotten reports of the following working fine:
- Air Shielded
- Elemental Armor
- Enchanted Weapon
- Enkindled Weapon
- Gravedigger's Flame
- Greater Protection: 3
- Nimbleness: 3
- Off-Balance (This only displays a message, though)
- Paralyzed (This only displays a message, though)
- Reveal Map
These lists may not be exhaustive, of course.
- Opens a dialog to allow the player to pay for divine healing. This will deduct gold if they player agrees.
- Opens a dialog to allow the player to pay for divine de-hexing. This will deduct gold if they player agrees.
- Will curse the player, if the player fails a Wisdom check.
- 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:
- Hostile (This is typically used for monsters)
- 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.
- 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.
- 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
- Divine Light
0. White (other numbers don't seem to change the effect)
- Flare Burst (very much like Flare but bigger, and rotates more)
0. Multicolored (no discernable change on other numbers)
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.
- Destroys this script (one-time use).
- Area NPCs may notice you committing a crime
- Allows access to something which would otherwise be considered a crime.
- 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.
- 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:
- 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.
- Display the in-game time (used in chronometers)
- 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.
- convert <param>
- 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.
- 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.
- 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.
- Removes the used item from inventory
- 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 this switch's position. (Should only be used when there's a toggle switch.)