Scripting Documentation

Table of Contents

Script Framework

onload/action:

each tile has two scripts; one for when the map is entered (onload), and one for when the tile is touched by the player (action). The tile definition starts in onload mode, and can switch back and forth using "onload" and "action". There are two elements that need to be in the onload section; "pix", and "walk". Putting a few "if" statements in would also work. Commands like info, on the other hand, are a bad idea.

[Top]

xy

The "xy" command will switch from defining types of tiles, to specific tiles. For example, you could fill an area with grass, then add something to some of the grass squares. Use ":x, y" to give data for a certain xy coord. (again, the tile starts out in onload mode, and can move to/from action) and the "tiles" command to move back. THIS MAY NOT CURRENTLY WORK.

[Top]

Complete list of working commands:

Each entry gives the syntax, then an example, then some comments on the command. Also see the files in the data directory for working examples of these commands.

[Top]

\

info \
Display line.
Not a real command, but if a line ends with \, it can continue to the next line.

[Top]

~Variable~ embedded variables

set("name_var", "=", "Frank")
info("~name_var~")
(will print Frank)
Also not a real command, but dialog, info, and question commands, when given two "~" characters with a variable between them, will replace it with the actual value of the variable (as returned by var()). As a side note, use ~~ to print the "~" symbol once.

[Top]

battle_bg=filename

battle_bg=underground.png
Note that this only goes between :def and the first tile definition. It specifies which picture to use for the background when in battle. Subdirectories should work, in the same way as tiles. All filenames are relative to images/backgrounds/.

[Top]

hero_bg=String

hero_bg=_raft
Note that this only goes between :def and the first tile definition. If given, then instead of using people/hero_n.png (for example) as the hero picture, people/hero_nString.png will be used. In the _raft example, the file people/hero_n_raft.png would be used whenever the hero moves north.

[Top]

monster=String

monster=Cave Bear
Note that this only goes between :def and the first tile definition. It specifies the monsters available on the map. Use a monster more than once to weight the listings. (ie, Ant, Ant, and Spider will give Ants twice as often as Spiders.)

[Top]

:Letter or Number

:t
Start defining a new tile. Note that case matters.

[Top]

Number

3
returns the given number. Useful for if statements.

[Top]

"String"

"Hi there"
returns the given string. Useful for if statements. Note that all strings must be surrounded by quotes. To insert an actual quote character, use \". Also, \n will create a newline in the dialog and question commands.

[Top]

action

Switch to defining the action scripting, which is called when the player moves into or over the tile. Also see onload.

[Top]

addpix("Filename")

addpix("potion.png")
Places the given picture on top of the current tile. It is recommended to use a tile with transparent areas; otherwise, pix would give the same power with better performance. The same restrictions as the pix command apply.

[Top]

addoverpix("Filename")

addoverpix("tree.png")
Identical to addpix, only it will be placed over the player. The same restrictions as the pix command apply.

[Top]

addskill("String")

addskill("Rage")
Use skill("give", "String") instead.
Gives the player the specified skill. Returns 1 on success, or 0 on failure. (Either through the player already having the skill, or the skill not existing.) Use Rage, Sneak Away, Dismember, Frenzy, or a skill defined in skills.txt.

[Top]

attack("random", "Mapname") OR attack("String")

attack("random", "level4.txt")
attack("Ant")
Attack either a random monster from the map Mapname, or the monster given with String. Returns 1 if the player won, 0 if the player ran, or ends the script and calls endgame.txt if the player loses.

[Top]

damage_monster() OR damage_monster(Number)

damage_monster()
damage_monster(stat("attack"))
Only works in battle. In battle, it attacks the opposing monster, asking the player to select a monster if needed, either with the power of the currently held weapon (as if the player hit the "attack" button in-battle), or at a specified (Command) power. Returns 1 if the attack went through, or 0 if the player cancelled/no enemy exists to attack. It differs from hurt_monster in that it is not reduced by armor.

[Top]

delpix("Filename")

delpix("items/light_healing_potion.png")
Removes the given picture from the tile. Returns 1 if the picture existed, and 0 if the picture did not.

[Top]

dialog("String")

dialog("This message will pop up.")
This displays a message in a dialog box. Useful when giving a lot of information to a user, or when dealing with story information. This command can use ~Variable~ embedded variables.

[Top]

die()

Die. This kills the player, and calls endgame.txt. Automatically called upon hp reaching 0.

[Top]

end()

End processing the script. Note that this not only ends processing the script, but when attached to an item or something for sale in a store, prevents the item from being destroyed on use/paid for.

[Top]

equip("String", "String")

equip("has", "dagger")
equip("in_slot", "boots")
Adjust the equipment of the player. The first string can be "in_slot", "has", "take", or "give". If "in_slot", the second string can be "weapon", "armor", "shield", "helmet", "gloves", or "boots", and will return the name of the the item currently in that slot (or "" if empty).
Otherwise, the second string is the name of the item to adjust. "has" returns 1 if the item is being worn, or 0 otherwise. "take" attempts to remove the item in question from the equipment, destroying it. It returns 1 on success, and 0 on failure (item was not being worn). "give" will place the given item in the equipment (destroying the previous item in that slot). Assuming the item is appropriate, it will always return 1.

[Top]

find("String", "String")

find("light healing potion", "a")
find("gold", 30)
Asks the player if they want to pick up the item. Returns 1 if the item was picked up, or 0 if it failed. The item either needs to be defined in items.txt, or be gold. If gold, list the amount of gold. Otherwise, list either a or an as the second argument. (It is used in the dialog "You found STRING2 STRING1.")
Example:
pix("grass.png")
	 if(var("gold_1"), "=", 0)
		 addpix("items/gold.png")
	 endif
	 walk(1)
	 Action
	 if(var("gold_1"), "=", 0)
		 if(find("gold", 5), "=", 1)
			 set("gold_1", "=", 1)
		 endif
	 endif


[Top]

gamestat("String")

gamestat("loc")
gamestat("difficulty")
gamestat("gamename")
Return the value of per-game variables. possible values for String: loc, difficulty, gamename, x, y, newx, newy, mapname.
Loc returns either "battle", "inventory", "main", or "shop" depending on the current location of the player. As some script commands do not work except in battle, this can be used to prevent errors. Difficulty returns 0 (easy), 1 (normal), or 2 (hard), and can be used to create difficulty levels outside of battles. (Difficulty levels within battles are created automatically.) Gamename will return the name of the game, as given by variables.txt, and displayed in the titlebar. x, y, and mapname return the player's current position, as would be used by the move command. newx and newy are different from x and y in that they return the location the player is moving to when moving, instead of the player's current location.

generic_dialog("String", "String", String", ...)

generic_dialog("Attack?", "no.png", "yes.png")
generic_dialog("Action?", "attack.png", "run.png", "skill.png")
Creates a dialog with the text of the first argument, and a line of buttons as specified in the rest of the arguments. The text argument understands ~Variable~ embedded variables, and \n newlines. The button arguments must be the filename of a button in module name/images/buttons, with a _sel version of the button also existing. There is a limit of 999 buttons, though the screen width also limits this.

[Top]

give("String", number)

give("maxhp", 5)
give("gold", rng(9, 9))
give("name", "Frank")
Adjust stats; possible values for String: name, hp, ep, maxhp, maxep, attack, defense, adj_maxhp, adj_maxep, adj_attack, adj_defense, gold, exp, skillpoints. Note that Number can be either positive or negative.
The exception is name, which must be a string. However, ~Variable~ variables work with name.
The difference between (eg) attack and adj_attack is that attack is permanent, while adj_attack only lasts until the end of battle.

[Top]

hero("Filename minus .png extension")

hero("hero_w")
Give a specific picture to the hero. While any picture can be used (that would work for pix()) it is recommended to use one of the hero_n (s, e, w) pictures. This lasts until the player moves. Filenames are relative to images/tiles/people

[Top]

hurt(Number)

hurt(10)
hurt(rng(5, 5))
Injure the player for Number or Action points, reduced by armor.

[Top]

hurt_monster() OR hurt_monster(Number)

hurt_monster()
hurt_monster(stat("attack"))
Only works in battle. In battle, it attacks the opposing monster, asking the player to select a monster if needed, either with the power of the currently held weapon (as if the player hit the "attack" button in-battle), or at a specified (Command) power. Returns 1 if the attack went through, or 0 if the player cancelled/no enemy exists to attack. It differs from damage_monster in that it is reduced by armor.

[Top]

if(Action1, "Comparison", Action2)
Action3
else
Action4
endif

if(rng(4, 5), ">", 2)
attack("random", "level1.txt")
else
info("A narrow escape")
give("exp", 5)
endif
Performs Action1 and Action2, (These can be any actions, though some are more useful than others) then compares them. (either use =, <, >, <=, >=, or !=) If the comparison is true, then perform Action3. Otherwise, perform Action4. Attack, Item, Rng, Question, Var, and Take are useful for the 1st/2nd actions.
Note that actions 3 and 4 can actually be any number of commands, that beginning whitespace is ignored, the "else" portion does not need to be given, and If commands can be stacked indefinitely. (They should only be limited by Python's maximum stack size)
For actions that may kill the player, (eg: Hurt, give("hp", -5) simply follow the action with others, and don't bother with If, as death ends the script anyway. For Attack, success is defined by destroying the monster, failure by running away. Death simply ends the script. (And calls endgame.txt)
Note that if(12345) is equivalent to if(12345, "==", 1)

[Top]

info("String")

info("String ~variable~")
info("Hi there!")
set("rand_num", "=", rng(5, 5))
info("Your random number is ~rand_num~")
Put the given line into the message scroller. Note that if a line contains ~Variable~, it will be replaced by the value of the variable.

[Top]

inv("String1", "String2")

inv("take", "key")
inv("give", "sword")
Performs various actions with the inventory. String1 can be "has", "take", "give", "use", "type", "quality", "price", "value", "description", "picturename", "hp_bonus", "ep_bonus", "attack_bonus", or "defense_bonus".
If "has", inv() returns 1 if the player has the item in the inventory. If "take", inv() attempts to remove (destroy) an inventory item, returning 1 on success, and 0 on failure. If "give", inv() attempts to give the player an item, returning 1 on success, and 0 on failure (full inventory). If "use", the effect of that item is performed. (This does not require the item to be in the inventory, and does not use it up if it is.)
The rest of the possibilities returns the respective property for the item.
In all cases, String2 gives the item to adjust.

[Top]

inv_spot(Number)

inv_spot(5)
Returns the name of the item in the given location in the inventory. Number must be between 0 and 27. Returns "" if there is nothing in the given spot.

[Top]

is_equipped("String")

is_equipped("Dagger")
Obsolete. Use equip("has", "String") instead.
Checks to see if the given item is being worn, and, if so, returns 1. Otherwise returns 0.

[Top]

item("String")

item("light healing potion")
Obsolete: use inv("give", "String") instead.
Give the player the item specified. (case-insensitive) Fails (returns 0 instead of 1) if the inventory is full, so use with if to prevent trapping the player in an un-win-able state.

[Top]

lose()

Lose the game. Note that this does not call endgame.txt, differing it from die. Use die whenever possible; use lose only in endgame.txt.

[Top]

mapspot("String", Number, Number, "String")

mapspot("map.txt", 4, 3, "walk")
mapspot("map2.txt", 9, 13, "num_of_addpix")
Returns stats for the given tile. First 3 arguments specify a tile using mapname, x, y coords. The last argument gives the variable to return. This can be walk, pix, num_of_dropped, num_of_addpix, num_of_addoverpix, wall_n, wall_s, wall_w, wall_e, within_bounds, y_bound, or x_bound.
walk, and wall_* return either 0 or 1, with the same meaning as the respective function. Pix returns a string, as accepted by pix(). The num_of_* variables return the size of the array in question. They are less useful, but included for completeness. within_bounds returns 1 if the xy coords given exists in the given map, or 0 otherwise. Finally, *_bound returns the size of the given map in the given direction. With this variable, the xy coords are useless.

[Top]

mapstat("String", "String")

mapstat("addmonster", "Ant")
mapstat("delmonster", "Ant")
mapstat("hero_bg", "_raft")
mapstat("hero_bg", "")
mapstat("battle_bg", "underground.png")
Adjust stats for the map. Allowed options for the first string are addmonster, delmonster, hero_bg, battle_bg and change_titlebar. The options for the second string are the same as the options for the relevant command mapstat enhances, with the addition that hero_bg works with an empty string.

[Top]

monster_give_stat(Monster_Sel, "Stat_Name", Number)

monster_give_stat(monster_select(), "attack", -5)
monster_give_stat("all", "defense", 1)
Adjusts the stats of one or more monsters. Monster_Sel is either a number, or "all". If a number, the command applies to the given monster in the group. If "all", the effect will be applied to all monsters in the battle. Stat_Name is either name, hp, maxhp, attack, defense, gold, or exp. If "name", Command is a string, not a command, but ~~ embedded variables will work. Otherwise, if Stat_Name is any of the other strings, the given stat will be increased (or decreased) by the given amount.

[Top]

monster_stat(Monster_Sel, "Stat_Name")

monster_stat("select", "attack")
Returns the stats of a monster. Monster_Sel is a number. (such as monster_select() returns) The "all" option does not work for this command. The command applies to the given monster in the group. Stat_Name is either name, hp, maxhp, attack, or defense. Only usable in battle.

[Top]

monster_select()

monster_select()
Lets the player select a monster (if only one monster exists, returns the only attackable monster). monster_select returns -1 if the user cancelled, or a number suitable for monster_stat or any other command that uses Monster_Sel. Only usable in battle.

[Top]

move("mapname", x, y)

move("town.txt", 4, 6)
Move the player to the given location. mapname is the complete filename of the map, (subdirectories do not work yet) and x and y are the xy coordinates inside the map.

[Top]

onload

Switch to defining the onload scripting, which is called when the player enters the map. Also see the action command. The tile starts in onload mode, so this command gives no extra power, but can help convenience.

[Top]

pass()

Do nothing. Only useful with If.

[Top]

pix("Filename")

pix("rock.png")
Change the picture to the given file. Only .png is supported, and the file must be in the images/tiles directory. One of these in the onload section of a tile is highly recommended. Note that subdirectories are supported.

[Top]

printvars()

printvars()
Used for debugging purposes. Prints out all the current variables to the console. Not pretty, but gives the needed information.

[Top]

question("String")

question("Leave this area?")
This creates a dialog box with a body of String and yes/no buttons. Use with the If command. Yes returns 1, and No returns 0. This command can use ~Variable~ embedded variables.

[Top]

refresh()

Refresh the screen. This is useful if you want to move the player *then* show a dialog box.

[Top]

rng(Number1, Number2)

rng(4, 9)
This creates a random number between 1 and Number2. (ie, if Number2 is 3, the possible values are 1, 2, or 3.) The number is then compared with Number1. If Number1 is higher or equal, the random number is returned. Otherwise, 0 is returned. Note that the probability of >0 returning can be expressed as the fraction Number1/Number2. ie, rng(3, 4) will return True 3/4ths of the time. Also note that rng(5, 5) will return a random number between 1 and 5, which can be used in the give and hurt commands. Finally, note that rng(4, 5) will give a random number between 0 and 4.

[Top]

run("mapname", x, y)

run("town.txt", 4, 6)
This command runs the tile defined.

[Top]

set("String", "Operation", Number/String)

set("have_entered", "=", "yes")
set("num_attacked", "+" 1)
set a variable. Use the var command to compare. This information is saved when saving the game, and is useful for one-time actions. Use either -, +, *, /, %, ^, or = as the Operation (%=modulus, ^=exponent). The binary operators adjust the current value of the variable using the new number given. For example, set("varname", "/", 5) will take the current value of varname, divide it by 5, and store the result in varname. Strings only work when using the = operator; otherwise, a number must be used. Finally, set("varname", 12345) is equivalent to set("varname", "=", 12345)

[Top]

skill("Switch", "String")

skill("give", "Rage")
skill("has", "Cringe")
Performs various actions with skills. Switch can be "has", "take", "give", or "use". If "has", skill() returns 1 if the player has the skill, or 0 otherwise. If "take", skill() attempts to remove a skill, returning 1 on success, and 0 on failure. (Failure is if the player didn't know the skill in the first place.) If "give", skill() attempts to give the player a skill, returning 1 on success, and 0 on failure (skill already known). If "use", the skill is used. This only works in battle, does not cost the player any ep, and does not require the skill to be known.
In all cases, String gives the skill to adjust. Use Rage, Sneak Away, Dismember, Frenzy, or a skill defined in skills.txt.

[Top]

stat("String")

stat("maxhp")
Returns the value of the stat String. Possible values for String: hp, ep, maxhp, maxep, attack, defense, adj_maxhp, adj_maxep, adj_attack, adj_defense, gold, exp, skillpoints. Note that attack (for example) give the base attack value, before any equipment or battle bonuses.

[Top]

store("String")

store("a Weapons Store")
Enter a store. Check shops.txt for the possible values.

[Top]

take("String")

take("Key")
Obsolete: use inv("take", "String") instead.
Remove an item from the inventory. When used with If, can implement keys and the like. Returns 0 on failure, 1 on success.

[Top]

var("String")

var("have_entered")
returns the current value of String, or 0 if String is unset. Use with If.

[Top]

walk(Number)

walk(1)
Set the ability for the player to walk on it. The only values accepted are 1 (can walk) and 0 (cannot walk)

[Top]

wall_Direction(Number)

wall_n(1)
wall_s(1)
wall_e(1)
wall_w(1)
In the case where you have a tile with a wall (with a walk value of 1) and the tile on the other side of the wall has a walk value of 1, to prevent the hero from walking through the wall, you must specify a wall value. So if the tile has a wall to the north, you would specify this with "wall_n(1)". It is not necessary to specify a lack of walls since all wall values default to 0. (Though resetting a wall to 0 does work.) It is also unnecessary (although harmless) to specify a wall when the tile on the other side of the wall is not walkable. The only values accepted are 1 (wall in this direction) and 0 (no wall in this direction).

[Top]

win()

Call wingame.txt.

[Top]

Other information:

When debugging, run the game from the command line. All errors are sent that direction.

To create your own module, create a directory in modules, called whatever you want. (Make it fairly descriptive, though.) Include the needed files (copy-paste from another module would be the easy way to do this, though note that the save/ directory is unneeded) and everything should work.

Note that subdirectories in the tiles/ directory will work.

When drawing buttons, it is possible to change some widths and heights. Make sure the buttons form a rectangle after assembly, and you should be fine.

This file may not be entirely accurate. Check action.py in the code directory for the code behind this file. Tell me about any documentation errors found. (The functions are named script_*, where * is the name of the function in question.)

[Top]