Scripting Documentation
Table of Contents
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]
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]
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]
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=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=_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]
level_under=town1.txt
Note that this only goes between :def and the first tile definition.
It specifies the level that is "underneath" the current level. Basically, the
game will draw the given level, then draw the current level on top of it, as
if you specified the given level as the appropriate pix() commands, then the
pix() commands of the current level as addpix() commands. For this to be useful,
some of the tiles in the current level need to be transparent. Either not
including a pix command, or setting the pix command to be a completely
transparent tile (null.png is included for this) will make the level given
here show through that tile. Also, note that there is a refresh problem when
the player moves onto a square that has transparent areas in the current level.
(This occurs when changing direction without moving.)
[Top]
level_down=level2.txt
Note that this only goes between :def and the first tile definition.
It specifies the level that will be to the North, Northwest, West, Southwest...
of the current level. You can use level_up, level_down, level_left, level_right,
level_upleft, level_upright, level_downleft, level_downright.
The bordering levels that are specified using this method will replace the
normal off-map areas, (which are a repeat of the closest tile) and will actually
appear on the appropriate border of the level, just as if the two levels were
one. The intended purpose for this command(s) is to allow the creation of
worldmaps; areas that must function as a single map, but are too large to be
held comfortably in memory.
Note that scripting on the very edge of levels will not run using this method.
Make sure not to put anything important on the borders of maps using this.
[Top]
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]
:t
Start defining a new tile. Note that case matters.
[Top]
3
returns the given number. Useful for if statements.
[Top]
"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]
Switch to defining the action scripting, which is called when the player
moves into or over the tile. Also see onload.
[Top]
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("tree.png")
Identical to addpix, only it will be placed over the player.
The same restrictions as the pix command apply.
[Top]
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", "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()
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("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("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. This kills the player, and calls endgame.txt. Automatically called upon
hp reaching 0.
[Top]
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("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]
fade(0)
Fades to black. Note that the single argument must be 0 for now.
[Top]
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("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 returns 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("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. This function returns an int, starting at 0.
[Top]
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("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(10)
hurt(rng(5, 5))
Injure the player for Number or Action points, reduced by armor.
[Top]
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(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 ~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("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(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("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("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 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("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("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_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("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()
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("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]
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]
Do nothing. Only useful with If.
[Top]
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()
Used for debugging purposes. Prints out all the current variables to the
console. Not pretty, but gives the needed information.
[Top]
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 the screen. This is useful if you want to move the player *then*
show a dialog box.
[Top]
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("town.txt", 4, 6)
This command runs the tile defined.
[Top]
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("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("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, level, skillpoints, name. Note that attack (for example) give the
base attack value, before any equipment or battle bonuses, while adj_attack
returns the modified attack value, as used in battle.
[Top]
store("a Weapons Store")
Enter a store. Check shops.txt for the possible values.
[Top]
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("have_entered")
returns the current value of String, or 0 if String is unset. Use with If.
[Top]
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_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]
Call wingame.txt.
[Top]
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]