Plotscripting Dictionary

variable := value

This command assigns a new value to a variable. If you do not specify the new value, the variable will be reset to zero. This command works exactly the same for global and local variables.

increment (variable,amount)

This command adds an amount to the current value of a variable. If you do not specify the amount, then the variable will be incremented by one. This command works exactly the same for global and local variables.
You can also increment variables by writing variable += amount

decrement (variable,amount)

This command subtracts an amount from the current value of a variable. If you do not specify the amount, then the variable will be decremented by one. This command works exactly the same for global and local variables.
You can also decrement variables by writing variable -= amount

read global (id)

A function that returns the value of a global variable using its ID number instead of its name. Why would you want to do a silly thing like that? Because it allows you to simulate simple fake arrays, in the old C-pointer style.

write global (id,value)

A function that writes a value into a global variable using its ID number instead of its name. Why would you want to do a silly thing like that? Because it allows you to simulate simple fake arrays, in the old C-pointer style

leader

Returns the hero ID number (as given in the Edit Hero Stats menu) of the current caterpillar party leader.

find hero (who)

Searches through your (battle) party to see if the specified hero is there, and returns the position where the hero was found, or -1 if the hero was not found. The position in the party is needed by most commands operating on heroes. You can use the names defined in your HSI file in the format hero:name for the ID number of the hero (as it has in the Edit Hero Stats menu). Not only does this tell you if a hero is in your party, but you can also use it to tell whether or not the hero is in your active party. find hero will return 0, 1, 2 or 3 if the hero is in the active party, and 4 or higher if the hero is in the reserve. Note that position in the battle party is not the same as position in the caterpillar: the leader is not necessarily hero 0. The opposite to find hero is hero by slot.

hero by slot (where)

This command is the reverse of find hero. Given a position in your party, it will tell you which hero is in that slot, or -1 if no hero is in that slot. The number returned can be compared with the names defined in your HSI file in the format hero:name.

rank in caterpillar (who)

Searches through your active party to see if the specified hero is there, and returns the position int the walkabout caterpillar where the hero was found, or -1 if the hero was not found. Use the names defined in your HSI file in the format hero:name. This is particularly useful if you need to use a command like walk hero but you are not sure which position the hero is in.

hero by rank (where)

This command is the reverse of rank in caterpillar. Given a position in your walkabout party, it will tell you which hero is in that position, or -1 if no hero is in that position. The number returned can be compared with the names defined in your HSI file in the format hero:name.

room in active party

A function that returns the number of available spaces in your active party. It will return zero or false if there is no room.

add hero (who)

Puts the named hero in your party. If there is no room, the hero will be added to your reserve. Use the constants defined in your HSI file. They are in the form of hero:name. This command returns the party slot that the hero was added to, or -1 if both the active and reserve parties are completely full.

delete hero (who)

Removes the named hero from your party. If you have more than one copy of the hero in your party, only the first one will be deleted. Use the constants defined in your HSI file. They are in the form of hero:name

swap in hero (who)

Moves the named hero in your from your reserves to your active party. If there is no room in your active party, the hero will not be moved. Use the constants defined in your HSI file. They are in the form of hero:name

swap out hero (who)

Moves the named hero from your active party into your reserve. Use the constants defined in your HSI file. They are in the form of hero:name

lock hero (who)

Locking a hero prevents the player from moving the hero on the party menu. Locked heroes in the active party cannot be moved into the reserve, and locked heroes in the reserve are completely hidden. Also prevents a hero from being moved by swap in hero or swap out hero. Use the constants defined in your HSI file. They are in the form of hero:name

unlock hero (who)

Reverses lock hero, and makes it possible to move a hero in and out of the active party again. Use the constants defined in your HSI file. They are in the form of hero:name

swap by name (name,name)

Swaps two named heroes in your party no matter what position they are in. Use the names defined in your HSI file in the form hero:name

swap by position (position,position)

Swaps two heroes in your party based on their positions in the party

get item (item,number)

Adds the specified number of the specified item to your inventory. If you do not specify a number, only one will be added. You can refer to the item by number, or you can use the constants defined in your HSI file, which are in the form of item:name

delete item (item,number)

Removes the specified number of the specified item from your inventory. If you do not specify a number, only one will be removed. You can refer to the item by number, or you can use the constants defined in your HSI file, which are in the form of item:name

item in slot (slot)

Return a the item ID number at a specific slot in your inventory. If the inventory slot is empty, it will return -1. Slots are numbered from 0 to get inventory size-1.

set item in slot (slot, item)

Change the item ID number at a specific slot in your inventory. The slot argument is the position in your inventory screen (slots are numbered from 0 to get inventory size-1), and the item argument is the item ID number, or one of the item:name constants defined in your .hsi file. If you want to erase and item slot, use -1 as the item ID. If the slot was empty, one copy of the item will be placed in it. Otherwise the original item count is preserved. If the maximum stack size of the new item type is less than the number of items in that slot, the extra items will be removed from that slot and placed whereever there is room.

item count in slot (slot)

Return a the count of items at a specific slot in your inventory, or 0 if that slot is empty. Slots are numbered from 0 to get inventory size-1.

set item count in slot (slot, count)

Change the count of items at a specific slot in your inventory. The count argument is the new number of items from 1 up to the maximum count (which is dependent on the item, but no more than 99; see get item maximum stack size), or 0 if you want to delete any items currently in the slot. If the slot is empty or if the item count is out of bounds, this command will fail.

use item in slot(slot)

Attempts to use whatever item is in a given inventory slot as if you had selected it in the items menu. The argument is the inventory slot number. This command will only work if there is actually an item in the slot, and the item can be used outside of battle, either as a cure attack, or to teach a hero a spell, or to trigger a text box. The return value is true if you successfully used the item, or false if the item was unusable or the user cancelled.

If the item causes an attack to happen which kills all the heroes in the party (outside of battles a hero isn't counted as dead if their maximum HP is zero or negative), a normal game over occurs: the game over script is run if there is one, otherwise the game ends. However the game over won't happen until the next wait command (such as wait).

inventory (item)

Returns a count of how many of the specified item are in your inventory. If you do not have the item, it returns zero or false. You can refer to the item by number, or you can use the constants defined in your HSI file, which are in the form of item:name

get inventory size

Returns the number of inventory slots.

set inventory size (new size)

Changes the number of inventory slots that are available. Use the constant inv:max to restore the maximum value. The number you give will be rounded up to the nearest multiple of 3.

get item maximum stack size (item)

Returns the maximum allowed size of a stack of items in the inventory. The item argument is an item ID; you can refer to the item by number, or you can use the constants defined in your .hsi file, which are in the form of item:name. If the item uses the default stack size, then the default value is returned.

unequip (hero,slot)

Removes the item that the specified hero has equipped in the specified slot. The first argument is the position of the hero in your party, 0-3 for the active party, 4-40 for the reserve. (Use find hero if you want to refer to the hero by name). The second argument is the slot to unequip. Use the slot:weapon, slot:armor, etc. constants from your .hsi file.

When a hero's equipment changes, the current values of all stats other than HP and MP for the hero are reset to their new maximum values. The current values of the HP and MP stats are capped to the new maximums but not otherwise changed, so you might like to check and scale up the HP and MP of the hero (see set hero stat) if the new max is more than the old one.

force equip (hero,slot,item)

Forces a hero to equip an item, even if it is not normally equipable. The first argument is the position of the hero in your party, 0-3 for the active party, 4-40 for the reserve. (Use find hero if you want to refer to the hero by name). The second argument is the slot to equip. Use the slot:weapon, slot:armor, etc. constants from your .hsi file. The third argument is the item to equip. You can use the item's number or the item:name constants from your .hsi file.

When a hero's equipment changes, the current values of all stats other than HP and MP for the hero are reset to their new maximum values. The current values of the HP and MP stats are capped to the new maximums but not otherwise changed, so you might like to check and scale up the HP and MP of the hero (see set hero stat) if the new max is more than the old one.

equip where (hero,item)

Returns the number of the slot that a hero can equip an item in (a constant of the form slot:weapon, etc, in your .hsi file), or false if the hero cannot equip it. The first argument is the position of the hero in your party, 0-3 for the active party, 4-40 for the reserve. (Use find hero if you want to refer to the hero by name). The second argument is the item to check the equipability of. You can use the item's number or the item:name constants from your .hsi file.

check equipment (hero,slot)

Returns the number of the item that the specified hero has equipped in the specified slot, or -1 if there is nothing equipped there. The first argument is the position of the hero in your party, 0-3 for the active party, 4-40 for the reserve. (Use find hero if you want to refer to the hero by name). The second argument is the slot to check. Use the slot:weapon, slot:armor, etc. constants from your .hsi file.

get default weapon (hero)

Returns the number of the item that the specified hero uses as a default weapon when no other weapon is equipped. The argument is the position of the hero in your party, 0-3 for the active party, 4-40 for the reserve. (Use find hero if you want to refer to the hero by name).

set default weapon (hero,item)

Changes the item that the specified hero uses as a default weapon when no other weapon is equipped. The first argument is the position of the hero in your party, 0-3 for the active party, 4-40 for the reserve. (Use find hero if you want to refer to the hero by name). The second argument is the item to use as the new default weapon. You can use the item's number or the item:name constants from your .HSI file.

play song (song)

Plays the specified song. Use the constants defined in your HSI file. They appear in the form of song:name

current song

Returns the number of the currently playing song, or -1 if none.

stop song

Stops whatever music is currently playing.

set victory music (song)

Changes the after-battle victory music to the specified song. Use the constants defined in your HSI file. They appear in the form of song:name

get victory music

Returns the number of the after-battle victory music. Compare with the constants defined in your HSI file. They appear in the form of song:name

set ambient music (song)

Plays a song and sets it as the map's ambient music, that is the song that is played when you enter the map (if you call save map state with mapstate:all or mapstate:mapsettings) or after a textbox with 'restore music' set. Unless you save the mapstate, the effect goes away if you change maps or fight a battle. You can use the constants song: silence and song: same as last map for song, the default is silence.

get ambient music

Returns the song number of the map's ambient music, either a song ID or the constants song: silence or song: same as last map.

set music volume (volume)

Sets the volume at which music is played, volume being a number on the scale of 0 to 255, 0 being silent, 255 loudest. If you want to manipulate the sound (e.g. fading out the music) you should take note of the original volume that the player has set and return to this. The default volume is not the maximum 255, so you should not hardcode fades to begin at volume 255.

The actual resolution at which the volume is set is not necessarily 1/255th of full volume but depends on your implementation. For example, music_sdl only supports 128 different volume levels. So if you set the volume and then read it back, it might change slightly.

get music volume

Returns the volume at which music is played, on a scale of 0 to 255, 0 being silent, 255 loudest.

fade screen out (red,green,blue)

Fades the screen to a solid color. If you do not specify any arguments, the screen will fade to black. The red, green, blue values are numbers from 0 to 63 that tell how bright that particular color should be. (63,0,0) would be blood red. (40,0,40) would be purple. (63,63,63) would be bright white. The screen will remain faded out until you run fade screen in, fight a battle, or use a door.

fade screen in

Fades the screen back to normal after a fade screen out command, or applies the changes made with other palette commands such as greyscale palette, tweak palette, reset palette, and write color.

load palette (palette number)

Loads a different master palette (one of the palettes on the "View Master Palettes..." menu), and the user interface colors for that palette. Use this if a backdrop or entire map was imported/drawn with a palette other than the default. Changes to the palette do not take effect until you call update palette or fade screen in, however the UI colors are changed immediately.

update palette

Instantly returns from fade screen out, and applies changes made by other palette command such as greyscale palette, tweak palette, reset palette, and write color.

greyscale palette (first, last)

Converts a section of the master palette from color to greyscale. The two arguments determine what range of colors will be affected. If called with no arguments, the entire palette is affected. Changes do not take effect until you call update palette or fade screen in. Changes to the master palette last as long as you are playing, but are not stored in saved-games. If you need to make master-palette changes persist in saved-games you will have to use the on-load plotscript trigger.

tweak palette (red, green, blue, first, last)

Color-adjusts a section of the master palette. The first three arguments are the changes to make to the red, green, and blue values of each palette color. For example, tweak palette (20,-30,0) would redden everything, and drop out most of the green. These arguments expect values in the range -63 to 63, NOT -255 to 255. The last two arguments determine what range of colors will be affected. If they are left out, the entire palette is affected. Changes do not take effect until you call update palette or fade screen in. Changes to the master palette last as long as you are playing, but are not stored in saved-games. If you need to make master-palette changes persist in saved-games you will have to use the on-load plotscript trigger.

reset palette

Reloads the default master palette and its user interface colors, undoing any changes you have made with other palette-altering commands such as tweak palette or greyscale palette. Changes to the palette do not take effect until you call update palette or fade screen in. However the UI color indices (those in the 'Change User-Interface Colors' menu) are changed immediately (if you're not using multiple master palettes, then UI color indices never change).

read color (index, element)

Returns a color value from the master palette. The first argument is the index in the palette to read from, 0 to 255. The second argument is the color value to read, red, green, or blue. You can use 0,1, and 2, or you can use the predefined constants color:red, color:green, and color:blue. The counterpart to this is write color.

This command operates on values from 0-63. For operation on full color values (0-255), used get color.

write color (index, element, value)

Writes a color value into the master palette. The first argument is the index in the palette to write to, 0 to 255. The second argument is the color value to write, red, green, or blue. You can use 0, 1, and 2, or you can use the predefined constants color:red, color:green, and color:blue. The third argument is the color value to write. It should be in the range of 0 to 63, NOT 0 to 255 as is used in nearly all computer programs. Use set color if you want to set color values in the 0-255 range. Changes do not take effect until you call update palette or fade screen in. Changes to the master palette last as long as you are playing, but are not stored in saved-games. If you need to make master-palette changes persist in saved-games you will have to use the on-loadgame plotscript trigger.

get color (index)

Returns a color value from the master palette. The argument is which index in the palette to return. The value is a 32-bit number representing the red, green and blue components of the palette entry. See RGB for more details on its format.

set color (index, value)

Updates the master palette with a new 32-bit color. The value, a 32-bit number representing the red, green and blue components of the color, can come from RGB or get color. Changes do not take effect until you call update palette or fade screen in. Changes to the master palette last as long as you are playing, but are not stored in saved-games. If you need to make master-palette changes persist in saved-games you will have to use the on-loadgame plotscript trigger.

RGB (red, green, blue)

Combines the individual red, green and blue components of a color into a single 32-bit number. The formula used is "red * 256 * 256 + green * 256 + blue". The highest byte is unused, but reserved for future potential use for alpha transparency.

extract color (color, component)

Takes a 32-bit color value (as returned by get color), and extracts the red, green or blue component, based on the component parameter. You may use the color:red, color:green and color:blue parameters to choose which one.

play sound (num,loop,preempt)

Plays or resumes a sound effect. Pass true to loop if you want the sound effect to start over when it finishes instead of stopping. Pass true to preempt if you want to automatically stop the sound before playing it. If preempt is false, and the sound is already playing, this command will do nothing.

stop sound (num)

Stops a sound effect. If the sound is not playing, nothing will happen.

pause sound (num)

Temporarily stops a sound effect. It can be resumed with play sound, wherein it will continue from whence it left off.

sound is playing (num)

Checks to see whether a sound effect is playing or not. Useful for synchronization, etc.

wait for sound (num)

Waits until a sound effect has finished playing. Useful for synchronization, etc.

set hero picture (who,picture,type)

Permanently changes a hero's picture. The first argument is the hero's position in the party. (Use find hero if you want refer to the hero by name.) The second argument is the index number of the picture to use, and the last argument is a constant inside battle or outside battle or hero portrait, which determines if you are changing the hero's battle picture or their walkabout picture or their portrait. If the last argument is left out, outside battle is assumed.

set hero palette (who,palette,type)

Permanently changes a hero's 16-color palette. The first argument is the hero's position in the party. (Use find hero if you want refer to the hero by name.) The second argument is the index number of the 16-color palette to use, and the last argument is a constant inside battle or outside battle or hero portrait, which determines if you are changing the hero's battle palette or their walkabout palette or their portrait palette. If the last argument is left out, outside battle is assumed.

get hero picture (who,type)

A function that returns the index number of a hero's picture. The first argument is the hero's position in the party as returned by find hero. The second argument is a constant inside battle or outside battle or hero portrait, which determines if you are checking the hero's battle picture or their walkabout picture or their portrait. If the second argument is left out, outside battle is assumed.

get hero palette (who,type)

A function that returns the index number of a hero's 16-color palette. The first argument is the hero's position in the party as returned by find hero. The second argument is a constant inside battle or outside battle or hero portrait, which determines if you are checking the hero's battle palette or their walkabout palette or their portrait palette. If the second argument is left out, outside battle is assumed.

reset hero picture (who,type)

Resets a hero's picture that was previously changed with set hero picture back to the default picture. The first argument is the hero's position in the party. (Use find hero if you want refer to the hero by name). The second argument is a constant inside battle or outside battle or hero portrait, which determines if you are resetting the hero's battle picture or their walkabout picture or their portrait. If the last argument is left out, outside battle is assumed.

reset hero palette (who,type)

Resets a hero's palette that was previously changed with set hero palette back to the default palette. The first argument is the hero's position in the party. (Use find hero if you want refer to the hero by name.) The second argument is a constant inside battle or outside battle or hero portrait, which determines if you are resetting the hero's battle palette or their walkabout palette or their portrait palette. If the last argument is left out, outside battle is assumed.

get hero hand x (who,frame)

Get the x position of a hero's weapon hand in battle. The position is in pixels relative to the top left corner of the hero's battle sprite. The first argument is the hero's position in the party. The second argument is the attack frame. You can use the constants hand:Attack A and hand:Attack B

get hero hand y (who,frame)

Get the y position of a hero's weapon hand in battle. The position is in pixels relative to the top left corner of the hero's battle sprite. The first argument is the hero's position in the party. The second argument is the attack frame. You can use the constants hand:Attack A and hand:Attack B

set hero hand x (who, frame, new x)

Change the x position of a hero's weapon hand in battle. The position is in pixels relative to the top left corner of the hero's battle sprite. The first argument is the hero's position in the party. The second argument is the attack frame. You can use the constants hand:Attack A and hand:Attack B The third argument is the new x position.

set hero hand y (who, frame, new y)

Change the y position of a hero's weapon hand in battle. The position is in pixels relative to the top left corner of the hero's battle sprite. The first argument is the hero's position in the party. The second argument is the attack frame. You can use the constants hand:Attack A and hand:Attack B The third argument is the new y position.

get default hero hand x (who,frame)

Get the original x position of a hero's weapon hand in battle as specified in the hero editor. The position is in pixels relative to the top left corner of the hero's battle sprite. The first argument is the hero's position in the party. The second argument is the attack frame. You can use the constants hand:Attack A and hand:Attack B

get default hero hand y (who,frame)

Get the original y position of a hero's weapon hand in battle as specified in the hero editor. The position is in pixels relative to the top left corner of the hero's battle sprite. The first argument is the hero's position in the party. The second argument is the attack frame. You can use the constants hand:Attack A and hand:Attack B

get hero stat (who,stat,type)

A function that returns one of a hero's stats. The first argument is the position of the hero you want to check in your party as as returned by find hero. The second argument is the name of the stat that you want to check. The names of the stats are defined in your HSI file in the form stat:name. The third argument is either current stat or maximum stat or base stat. Follow those links for explanations. If you leave out the type, current stat will be assumed.

set hero stat (who,stat,value,type)

A command that changes one of a hero's stats. The first argument is the position of the hero you want to change in your party as returned by find hero. The second argument is the name of the stat that you want to change. The names of the stats are defined in your HSI file in the form stat:name. The third argument is the new value of the stat. The last argument is either current stat or maximum stat or base stat. Follow those links for explanations. If you leave the last argument blank, current stat will be assumed. You can set the current value of a stat to more than the maximum value. If you want to permanently change a stat you would change both the current value and just one of either the maximum value or the base value.

Cap stats are ignored by this command. Use set capped hero stat if you want to limit the current or maximum value of a stat to a cap. But the stat will be capped later due to certain events such as equipping or unequipping an item, levelling up, or using set hero stat cap. Caps don't apply to base stats.

The maximum and base values of a stat are tied together. Modifying the max will always modify the other by the same amount.

# Use this script to reset a stat to its max value
script, reset stat, hero slot, stat, begin
  set hero stat(hero slot, stat, get hero stat(hero slot, stat, maximum stat), current stat) 
end

# Use this script to permanently increase (or decrease, if amount is negative) a stat, without violating stat caps
script, adjust stat, hero slot, stat, amount, begin 
  set capped hero stat(hero slot, stat, get hero stat(hero slot, stat, current stat) + amount, current stat) 
  set hero stat(hero slot, stat, get hero stat(hero slot, stat, base stat) + amount, base stat) 
end

set capped hero stat (who,stat,value,type)

A command that changes one of a hero's stats. The first argument is the position of the hero you want to change in your party as returned by find hero. The second argument is the name of the stat that you want to change. The names of the stats are defined in your HSI file in the form stat:name. The third argument is the new value of the stat. Unlike set hero stat, if you try to set a stat to a value larger than the stat cap it will be reduced to the stat cap (without an error). The last argument is either current stat or maximum stat (base stat will also work but will not be capped). If you leave the last argument out, current stat will be assumed.

get hero stat cap (stat)

A function that returns the maximum allowed value for a hero stat (as set in the Stat Caps menu in Custom). The argument is the stat you want to check; one of the stat:name constants defined in your HSI file. If the return value is 0 or false there is no stat cap for that stat.

set hero stat cap (stat, value)

Set the maximum allowed value for a hero stat. The stat argument is the stat to affect; one of the stat:name constants defined in your HSI file. The value argument should be either greater than zero to set a cap, or 0/false to remove the cap for that stat.

The new cap comes into immediate force: the current and maximum values of all stats of all heroes in the party are capped according to the caps. In addition, the current values of all stats other than HP and MP for all heroes are reset to their new maximum values. The current values of the HP and MP stats are not otherwise changed aside from being capped, so you might like to check and scale up HP and MP of heroes if the new max is more than the old cap.

get level MP (who, mp level slot, type)

Returns a hero's level MP (FF1-style MP). The argument who is the hero's position in the party, as returned by find hero. The argument mp level slot is a number from 0 to 7 that represents a row of spells in the hero's spell list. The optional third argument is either current stat or maximum stat. If you leave out the type current stat will be assumed. Pass maximum stat instead to get the hero's maximum amount of level MP for that slot. The maximum depends only on the hero's experience level.

set level MP (who, mp level slot, new value)

Changes a hero's level MP (FF1-style MP). The argument who is the hero's position in the party, as returned by find hero. The argument mp level slot is a number from 0 to 7 that represents a row of spells in the hero's spell list. The argument new value is the new number of level MP points. Each point represents one spell from that row.

hero base elemental resist as int (who, element)

Gets the 'intrinsic' amount of damage that a hero receives from attacks of a certain element, as a percentage of normal. (That is, the value entered in the 'Elemental Resistances' menu in Custom. Equipment elemental modifiers are added onto this value.) The argument who is the hero's position in the party, as returned by find hero. The argument element is a number from 0 to whatever the highest enabled element is. The result is rounded to the nearest integer. For example, if the hero takes 2.6% damage (1/40 normal), then the result will be 3.

When floating point support is added to HamsterSpeak, an alternative to this command will be added.

set hero base elemental resist (who, element, percent)

Sets the 'intrinsic' amount of damage that a hero receives from attacks of a certain element, as a percentage of normal. (That is, the value entered in the 'Elemental Resistances' menu in Custom. Equipment elemental modifiers are added onto this value.) The argument who is the hero's position in the party, as returned by find hero. The argument element is a number from 0 to whatever the highest enabled element is. The argument percent is the percentage (written without a percent sign). For example -50 means the hero is healed by 50% of the attack damage instead of being hurt.

Unlike the elemental resist editors in Custom, you can't use fractions of a percent here.

hero total elemental resist as int (who, element)

Gets the amount of damage that a hero receives from attacks of a certain element, as a percentage of normal. The argument who is the hero's position in the party, as returned by find hero. The argument element is a number from 0 to whatever the highest enabled element is. The result is rounded to the nearest integer. For example, if the hero takes 2.6% damage (1/40 normal), then the result will be 3. This is the value calculated from the hero's 'intrinsic' resistances combined with the equipment they are wearing.

When floating point support is added to HamsterSpeak, an alternative to this command will be added.

get hero level (who)

A function that returns a hero's current level. The argument is the position of the hero you want to check in your party as as returned by find hero. The return value with be your current level, from 0 to 99

set hero level (who, level, forgetspells)

A command that sets a hero's current level. The first argument is the position of the hero you want to change in your party as as returned by find hero. You can specify any hero in the active or reserve party and any (non-negative) level (even above the level cap). Unlike old workarounds, this command teaches the hero any spells they would have learnt by that level and correctly sets the experience to next level-up (experience gained to the current next level is lost). You can also decrease the hero's level, which will cause spells to be forgotten, unless the optional 3rd argument (defaulting to true) is set as false.

set experience (who, experience, allowforget)

Sets a hero's total experience and updates their experience level, stats and spell list. The argument is the position of the hero you want to check in your party as as returned by find hero. To decrease a hero's level without forgetting spells which are learnt at a certain experience level, pass false as the optional third argument. Heroes won't level beyond the level cap (which is 99 usually), though you can temporarily raise the cap using set level cap to get around this.

hero levelled (who)

Returns the number of levels the specified hero gained. who is the hero's position in the battle party. If you want to use hero:Name you should use find hero. This command only applies to the most recent battle or give experience, set hero level or set experience command that targeted either this hero (or who party) - levels gained from previous battles or commands are forgotten. If the hero lost levels, the result is negative. In other words, this does not return true or false, but can be be used in an if statement like:

give experience (party, 50)
if (herolevelled (find hero (hero: Bob))) then (
  $31="Bob gained "
  append number(31, hero levelled (find hero (hero: Bob)))
  $31+" level(s)!"
  show textbox (233) # ${S31} :show string 31
)

total experience (who)

Returns a hero's total experience. The argument is the position of the hero you want to check in your party as as returned by find hero.

experience to next level (who)

Returns experience required by a hero to reach the next level. The argument is the position of the hero you want to check in your party as as returned by find hero.

experience to level (level)

Returns the total experience required to reach a specified level from level 0.

give experience (hero,amount)

Gives experience to either a hero by position in party (use result returned by find hero command if you want to give experience by name or ID) or the whole party, if the constant party is passed as first argument. If you give experience to the whole party, then it will be split amongst the heroes as it is in battle; dead heroes get experience depending on whether the "Dead heroes gain share of experience" general bitset is set, and swapped out heroes gain according to the options in the Battle System Options menu. This command can cause heroes to level up and learn spells but does not inform the player or trigger any effects. See hero levelled and spells learned for dealing with this. This command can give negative experience, but it will never cause a hero to delevel. You should use set experience to remove experience in a way that allows delevelling. You can't give experience to heroes with level equal to or greater than the level cap (which is 99 usually), though you can temporarily raise the cap using set level cap to get around this.

teach spell (hero,attack)

Tries to teach a hero a spell. This only works when the spell is set to "learned from item" in one of the hero's spell lists; it will not work for spells learned based on level. The first argument is the hero's position in the party (as returned by find hero). The second argument is the attack to learn. You can use the names defined in your .HSI file in the form atk:attackname. (You may also use the attack's ID number. This is the number you see in the attack editor + 1.) If the hero was taught the spell, teach spell will return true, or if the hero cannot learn the spell (perhaps because they already know it) it will return false. Use write spell to add a spell to a spell list without restriction.

forget spell (hero,attack)

Causes a hero to forget a spell. The first argument is the hero's position in the party (as returned by find hero). The second argument is the attack to forget. You can use the names defined in your .HSI file in the form atk:attackname (You may also use the attack's ID number. This is the number you see in the attack editor + 1). If the hero does not know the spell, nothing happens.

read spell (hero,list,slot)

Returns the ID number of a chosen spell slot, or 0 (false) if there is no spell in that slot. The first argument is the hero's position in the party (as returned by find hero). The second argument is the number of the spell list to check. This is a value from 0 to 3. The third argument is the slot to check. This is a number from 0 to 23. Spell slots are numbered in rows, so the first row is 0,1,2 the second row is 3,4,5, and so-on.

write spell (hero,list,slot,attack)

Forces a hero to learn a particular spell. The first argument is the hero's position in the party (as returned by find hero). The second argument is the spell list to put the spell in. This is a number from 0 to 3. The third argument is the slot to put the spell in. This is a number from 0 to 23. Spell slots are numbered in rows, so the first row is 0,1,2 the second row is 3,4,5, and so-on. The last argument is the attack to put in the spell list. You can use the names defined in your .HSI file in the form atk:attackname (You may also use the attack's ID number. This is the number you see in the attack editor + 1). You can also erase a spell by writing 0 or none as the attack ID. Note that this command will overwrite and replace any spell that is already in that slot. If you overwrite a slot that can normally learn another spell, you will never learn that other spell (unless you first erase the spell you wrote there)

knows spell (hero,attack)

Checks to see if a hero already knows a spell. The first argument is the hero's position in the party (as returned by find hero). The second argument is the attack to check for. You can use the names defined in your .HSI file in the form atk:attackname (You may also use the attack's ID number. This is the number you see in the attack editor + 1). If the hero knows the spell, knows spell will return true. If the hero does not know the spell, it will return false

can learn spell (hero,attack)

Checks to see if a hero is capable of learning a spell from an item or from the teach spell command. The first argument is the hero's position in the party (as returned by find hero). The second argument is the attack to check for. You can use the names defined in your .HSI file in the form atk:attackname (You may also use the attack's ID number. This is the number you see in the attack editor + 1). If the hero can learn the spell, can learn spell will return true. If the hero cannot learn the spell (or learns it from level-ups), it will return false

spells learnt (hero,number)

This is deprecated, do not use it. It is identical to spells learned except it returns the id numbers of spells, instead of the id numbers +1. The attack constants exported in your .hsi file are all +1 the attack IDs in Custom.

spells learned (hero,number)

Returns the id numbers (+1) of spells the hero learned from the last battle or give experience, set hero level or set experience command that targeted either this hero or the whole party. If the second argument is get count then the number of spells that the hero learned is returned. Pass 0 for number to get the first spell learnt, 1 to get the second, etc. You can use a loop and strings to list to the player all the spells a hero learned:

If you want to use this command with attack ID numbers, you must add 1 to the ID number.

# the following script uses strings 0, 1, 2 for its use (will be overwritten)
plotscript, print learned spells, who=0, begin
  variable(i)
  get hero name (1, who) # construct the static part of the text in string 1
  $1+" learned spell "
  for (i, 0, spells learned (who, get count) -- 1) do (
    read attack name (2, spells learned (who, i))  # get the i-th spell learnt
    0 $= 1  # copy the static part to the displayed string
    0 $+ 2  # combine with the spell name
    show string at (0, 160, 100)
    wait for keypress (anykey)
  )
  hide string (0)
end

update level up learning(who, allowforget)

Update a hero to make sure they know the spells they are supposed to have learned for their current level. The who is the hero's position in the battle party. You can optionally pass false as the allowforget argument if you want to make sure the hero will not forget any spells that they are not supposed to know yet. This command is most useful for situations where you are manipulating the hero's level, and for some reason do not want to use set hero level which automatically handles spell learning. This command can also be handy when playtesting a game in progress, since it can be used to make sure that heroes loaded from a saved-game will learn spells that did not exist yet at the time when they got their last level-ups.

outside battle cure

map cure (attack, target, attacker)

Uses an attack on a hero outside of battle as if you had used it from an item or cast it as a spell. In spite of the name, it works for both cure spells and damage spells. The first argument, attack is name of the attack from your HSI file in the form atk:name. (You may also use the attack's ID number. This is the number you see in the attack editor + 1.) The second argument, target is the position in the party of the hero to cure (or harm). The third optional argument, attacker is the position in the party of the hero who is using the attack. If this argument is omitted or set to -1, then the average stats of the active party will be used, just like when the attack is used from an item. The return value is true if the cure/attack succeeded, and false if it did nothing.

The map cure command replaces the old command outside battle cure which had a bug which required you to use atk:name -- 1 instead of atk:name for the attack argument.

If the attack results in all the heroes in the party being dead (outside of battles a hero isn't counted as dead if their maximum HP is zero or negative), a normal game over occurs: the game over script is run if there is one, otherwise the game ends. However the game over won't happen until the next wait command (such as wait).

add enemy to formation (formation, enemy id, x, y, slot)

Adds an enemy with given enemy id (use the constants of the form enemy:name in your exported .hsi file) to the specified formation. x (up to 230) and y (up to 199) give the position of the center of the bottom edge of the enemy - approximately where it appears to stand. slot (0 to 7) is an optional argument, if given then the enemy is created in the suggested slot if empty. Otherwise it's put in the first empty slot. The actual slot number used is returned, or -1 if the enemy couldn't be added.

Changes to enemy formations are temporary: they are not saved in save files.

delete enemy from formation (formation, slot)

Deletes an enemy in the given slot (as returned by find enemy in formation for example) in the formation.

Changes to enemy formations are temporary: they are not saved in save files.

find enemy in formation (formation, enemy id, copy number)

Searches for an enemy in a formation, returning the slot number, or -1 if not found. copy number is optional, use 0 or greater specify which enemy to return if there is more than one, or the constant get count. The first (searching the slots sequentially) enemy copy is number 0. The number of specified enemies in the formation is returned if the constant get count is used. enemy id can be either an enemy id, or the constant any enemy, which searches for any enemy (the first enemy in the formation by default), or the total number of enemies with get count.

plotscript, look at formation, formation, begin
  # In this example, we'll pick a random enemy from a formation, and check if there are any plips.
  # You'll need an enemy named plip to try this out, or change the "enemy:plip" constant below to something else
  variable (number of enemies, random enemy slot)

  # The total number of enemies
  number of enemies := find enemy in formation (formation, any enemy, get count)
  # Pick an enemy at random
  random enemy slot := find enemy in formation (formation, any enemy, random(0, number of enemies -- 1))

  $30 = "There is a "
  # Here we append the enemy's name to string 30
  get enemy name (formation slot enemy (formation, random enemy slot), 30)
  $30 + " in this formation"
  show string (30)

  # Let's check whether there is at least one plip in this formation
  variable (number, plip slot)
  number := find enemy in formation (formation, enemy:plip, get count)
  if (number > 0) then (
    # We'll put a string onscreen where the plip appears in battle
    $31 = "Plip!"
    plip slot := find enemy in formation (formation, enemy:plip)
    center string at (31, formation slot x (formation, plip slot), formation slot y (formation, plip slot) -- 20)
  )
end

formation slot enemy (formation, slot)

Returns the ID number of the enemy in the specified formation slot (0 to 7), or -1 if the slot is empty.

formation slot x (formation, slot)

Returns the x position of the center of the enemy in the specified formation slot (0 to 7). An enemies position is the center of the bottom edge of the enemy - approximately where it appears to stand.

formation slot y (formation, slot)

Returns the y position of the bottom edge of the enemy sprite in the specified formation slot (0 to 7). An enemies position is the center of the bottom edge of the enemy - approximately where it appears to stand.

set formation background (formation, background, animation frames, animation ticks)

Sets the background and the background animation for a formation. The animation arguments do not need to be given, producing a static background. animation frames, optional, is the number of frames (1 to 50) to use for the background animation. 1 is non-animating. animation ticks, also optional, is the number of ticks to display each backdrop for. The engine normally (but not reliably) runs at 18 ticks per second.

Changes to enemy formations are temporary: they are not saved in save files.

get formation background (formation, background)

Gets the background used by a formation. If the backdrop is animated, this returns the ID of the first backdrop (the one set in Custom).

set formation song (formation, song)

Changes an enemy formation to use song as its music. Use the constants of the form song:songname from your exported .hsi file, or the special constants song: silence or song: same as map

Changes to enemy formations are temporary: they are not saved in save files.

get formation song (formation)

Returns the song associated with formation. Compare the result with the constants of the form song:songname from your exported .hsi file, or the special constants song: silence or song: same as map.

last formation

Returns the last formation fought. If the player hasn't fought any formations yet (since starting or loading the game), it returns -1.

random formation (formation set)

Picks a formation randomly from the given formation set (1 to 255).

formation set frequency (formation set)

Returns the formation frequency (from 0 to 99) of a formation set (1 to 255). Note that the frequency is not actually a probability (as a percentage) of a battle occurring each step, but is roughly the number of battles per 80 steps, spaced semi-randomly.

formation probability (formation set, formation)

Returns the probability of a particular formation in a formation set being fought, as a percentage from 0 to 100. This does take the number of times the formation appears in the formation set into account.

key is pressed (scancode)

Returns true if the keyboard or joystick key with the specified scancode is being pressed (either held down or pressed since last tick), or false if it is not. The argument is a scancode, NOT the up key, down key, etc used with wait for key.

Since Zenzizenzic, keyboard support has been improved: some keys (such as key:down and key:numpad 2) which were previously the same scancode are now distinct (read scancode.hsi for the complete list). However for backwards compatibility, the old behaviour is emulated (so you won't be able to tell the two keys apart even if recompile and use the new, distinct scancodes) unless you turn on the "Enable better scancodes for scripts" Preference Bitset in the General Game Settings menu.

You can't rely on the behaviour of the caps-, scroll- and num-lock keys. They might report on/off state instead of pressed/not pressed, depending on the graphics backend, operating system, and engine version.

You can NOT wait for the player to press a key by continually polling key is pressed unless you stick a wait in your while loop. That's because key is pressed does not return real time data, but the state of the keyboard at the beginning of the current game tick.

• key:Esc
• key:F1
• key:F2
• key:F3
• ...
• key:F15

• key:Num Lock
• key:Scroll Lock
• key:Caps Lock

• key:Print Screen
• key:Pause

• key:1
• key:Exclamation
• key:2
• key:At Sign
• key:3
• key:Hash
• key:4
• key:Dollar Sign
• key:5
• key:6
• key:Circumflex
• key:7
• key:Ampersand
• key:8
• key:Asterisk
• key:9
• key:Left Parenthesis
• key:0
• key:Right Parenthesis
• key:Minus
• key:Underscore
• key:Equals
• key:Plus
• key:Backspace

• key:A
• key:B
• key:C
• ...
• key:Z

• key:Left Bracket # [
• key:Left Brace # {
• key:Right Bracket # ]
• key:Right Brace # }
• key:Semicolon # ;
• key:Colon # :
• key:Quote # '
• key:Doublequote # "
• key:Apostrophe # '
• key:Backquote # `
• key:Tilde # ~
• key:Backslash # \
• key:Pipe # |
• key:Comma # ,
• key:Left Caret # <
• key:Period # .
• key:Right Caret # >
• key:Slash # /
• key:Question Mark # ?
• key:Enter
• key:Space
• key:Tab

• key:Home
• key:End
• key:Page Up
• key:Page Down
• key:Insert
• key:Delete

• key:Up
• key:Left
• key:Right
• key:Down

• key:Left Win Logo # equal to key:Left Command
• key:Right Win Logo # equal to key:Right Command
• key:Context
• key:Left Command # Macintosh, equal to key:Left Win Logo
• key:Right Command # Macintosh, equal to key:Right Win Logo

• key:Alt # either Alt key pressed
• key:Left Alt
• key:Right Alt
• key:Filtered Alt # either Alt key pressed, unless a key combinations like Alt+Tab is pressed, however key presses are delayed until key release.
• key:Ctrl # either Ctrl key pressed
• key:Left Ctrl
• key:Right Ctrl
• key:Shift # either Shift key pressed
• key:Left Shift
• key:Right Shift

• key:Numpad 0
• key:Numpad 1
• key:Numpad 2
• key:Numpad 3
• key:Numpad 4
• key:Numpad 5
• key:Numpad 6
• key:Numpad 7
• key:Numpad 8
• key:Numpad 9
• key:Numpad Period
• key:Numpad Asterisk
• key:Numpad Slash
• key:Numpad Plus
• key:Numpad Minus
• key:Numpad Enter

• joy:button 1
• joy:button 2
• joy:button 3
• ...
• joy:button 16
• joy:x left
• joy:x right
• joy:y up
• joy:y down

Previously it was necessary to include, scancode.hsi to use the key: constants, but no longer.

keyval (scancode)

Returns a bitmask for the state of the specified key. The argument is a scancode, see key is pressed. The first (least significant) bit is whether the key was depressed at the beginning of the current tick. The second bit is whether the key was pushed down by the player since the start of the previous tick (or when the key starts to repeatedly trigger after being held down for a while). It can therefore return 0, 1, 2 or 3:

0 = not pressed
1 = key held down since last tick, but is not a new press
2 = the player pressed the key and released it, all in the same tick
3 = new keypress (or typematic repeat)

Just like key is pressed, this command does not return real time data, but the situation at the beginning of the current game tick.

The joystick scancodes described in key is pressed aren't fully supported for keyval: the return value will be 3 if the key is down, or 0 if it isn't. In other words, no additional information over key is pressed.

Don't rely on the key repeat rate for things that affect gameplay such as the rate at which you can shoot bullets! The repeat rate is once every 55 milliseconds (18 times a second), independent of the frames per second (fps) that the game is running at. Suppose you use key repeat (e.g. keyval(key:X)>1) to shoot bullets and your game runs at 36 fps, then a bullet will be fired every other frame. But if played on a really slow computer that only ran the game at 18 fps, a bullet will be fired every frame!

last ascii

This command is obsolete. Use get input text instead, if possible.
Returns the character code of any currently pressed key, or 0 if none are. If more than one key corresponding to an ascii character is being pressed, then only one can be returned.

enable input text (enable)

This command needs to be called before get input text can be used. If the optional argument is true or not given then get input text is enabled, otherwise it is disabled. Enabling get input text may cause some of the keys on international keyboards ("combining" keys, which are usually punctuation keys) to go "dead" --- that is, commands such as key is pressed and wait for key will stop showing that they are pressed. For that reason, get input text is disabled by default. You don't need to use this command before calling input string.

get input text (string id)

Places in the specified string any text that the player has typed since the last tick. (The string will be empty if nothing has been.) Textual input must be enabled using enable input text before this command can be used! See that command for details. You will normally call this every tick in a loop and use concatenate strings to read the player's complete input. However it is much easier to call the input string function instead, which does this for you.

input string (ID, maxlength, use current, center, position x, position y)

Allows the player to type in a string (until they press ENTER). Returns false if they press ESC to cancel. ID is the string you want to use. All other arguments are optional: maxlen is the length of input, if left blank the limit will be set to 40 (max visible onscreen length). use current is whether you want to add to the existing string, or clear the string before typing. The default is to clear the string before typing, valid arguments are true or false. The string will be centered (see center string at unless center is false. If the string is not visible, then it will automatically be placed onscreen (centered if not specified) and hidden when done. position x and position y are optional (defaulting to the center of the screen), and are the position at which the string will be shown as it is being typed; otherwise the string will use its current positioning if already visible.

input string with virtual keyboard (ID, maxlength, onlyplayer)

Allows the player to input a string using a virtual keyboard The exact appearance and behavior of the virtual keyboard will vary on different platforms, for example, on Android a touch-screen keyboard will appear, but when playing on a console, the virtual keyboard will be controlled with the d-pad and buttons. You have no control over what portion of the screen is obscured by the virtual keyboard. The virtual keyboard will vanish when the command is finished. ID is the string you want to use. All other arguments are optional: maxlen is the length of input, if left blank the limit will be set to 40 (max visible onscreen length). The onlyplayer is optional. It only matters when the game is played on a console with multiple gamepads configured. It can be a number from 0 to 3, being that only that specific player has control over the virtual keyboard. By default onlyplayer is -1, which means that any player can control it.

show virtual gamepad

Defined in the Platform Specific section.

hide virtual gamepad

Defined in the Platform Specific section.

auto virtual gamepad

Defined in the Platform Specific section.

joystick button (button, joystick)

Returns true or false depending on whether button #button on joystick #joystick is pressed. button can be from 1-16 (assuming the joystick has that many buttons), and joystick can be from 0-7. Most of the time, you will want to use joystick #0, so that is what joystick defaults to.

joystick axis (axis, multiplier, joystick)

Returns the position of the joystick along the X or Y axis on joystick #joystick. axis can be one of the constants x axis or y axis. multiplier is slightly complicated: The position of the joystick is actually a decimal between -1 and 1. Since plotscripting can't handle decimals, this position must be multiplied and rounded off until it is within plotscripting's capabilities. By default, it is 100 (so it will return -100 - 100). joystick can be from 0-7. Most of the time, you will want to use joystick #0, so that is what joystick defaults to.

init mouse

Informs the engine that you intend to use the mouse. This command should be run before any mouse functions are be used. It causes the normal mouse cursor to be hidden when over the game's window, and causes mouse buttons to trigger on-keypress scripts. Therefore, it is a good idea to place this command in the newgame and loadgame scripts if you are going to use the mouse.

Running this command does not draw a cursor onscreen. Either you can enable the default mouse cursor with unhidemousecursor, or your script may display the cursor itself by placing a slice at the appropriate location. If you use a slice, your cursor will appear below menus and text and strings shown with show value, show string at, etc., which is currently unavoidable.

#Simple Mouse cursor example

plotscript, display mouse, begin

  # Hide the normal mouse cursor
  init mouse
  # Re-enables the normal mouse cursor
  unhide mouse cursor

end

#Custom Mouse cursor example

plotscript, display mouse, begin

  # Hides the normal mouse cursor
  init mouse

  # Use a small enemy sprite (ID 1) slice as a mouse cursor
  variable (cursor)
  cursor := load small enemy sprite (1)
  # The following is optional: causes the mouse to be displayed
  # above textboxes and above all other slices (it still appears behind menus though)
  move slice above (cursor, lookup slice (sl:textbox layer))

  # Loop while the game is running
  while (true) do, begin
    put slice (cursor, mouse pixel x, mouse pixel y)
    wait (1)
  end
end

mouse pixel X

Returns the X coordinate in pixels of the mouse on the screen.

mouse pixel Y

Returns the Y coordinate in pixels of the mouse on the screen.

mouse button (which)

Returns true if the specified mouse button is currently pressed down. You can use the constants left button and right button to specify the button.

Just like keyboard commands such as key is pressed, you can not wait for the player to click the mouse with a while loop that doesn't contain a wait command, because the mouse state is only updated one per frame.

mouse click (which)

Returns true if the specified mouse button has been 'clicked' down in the last tick. Returns true even if the mouse button is still down. You can use the constants left button and right button to specify the button.

Just like keyboard commands such as key is pressed, you can not wait for the player to click the mouse with a while loop that doesn't contain a wait command, because the mouse state is only updated one per frame.

put mouse (X, Y)

Changes the location of the mouse on the screen, in pixels. Note that this function might do nothing, if the game's window is not active. init mouse should be called before this command is used.

mouse region (x min, x max, y min, y max)

Constricts the mouse to a rectangular part of the window/screen, such as a choice selection box. It is recommend you do not use this command, as it is very annoying in windowed mode. The maximum values are inclusive. Call without arguments to free the mouse to leave the window. init mouse should be called before this command is used.

input string with mouse keyboard (ID, maxlength)

Allows the player to input a string using a virtual keyboard that respons to mouse clicks or touchscreen touches. You have no control over what portion of the screen is obscured by the virtual keyboard. The virtual keyboard will vanish when the command is finished. ID is the string you want to use. All other arguments are optional: maxlen is the length of input, if left blank the limit will be set to 40 (max visible onscreen length).

unhide mouse cursor

Causes the normal OS mouse cursor to be displayed. You may want to run this command right after init mouse unless you plan to use a customized mouse cursor. Note that this command has no effect if the game is running on Android, because a mouse cursor is usually inappropriate on a touch screen.

hide mouse cursor

Causes the normal OS mouse cursor to be hidden. This command is seldom needed, because the cursor is hidden by default when you run init mouse.

show mouse cursor

camera pixel X

Defined in the The Camera section.

camera pixel Y

Defined in the The Camera section.

slice at pixel (parent, x, y, number, check descendants, visible only)

Defined in the Slice Collision Testing section.

slice collide point (handle, x, y)

Defined in the Slice Collision Testing section.

NPC at pixel (x, y, number)

Defined in the Moving NPCs section.

$id="some text"

Sets the contents of a string variable given by id, which can be a constant like 0 or 1, a variable, or even an expression like a call to a script, to a piece of text. The previous contents are erased. The whole statement must be on a single line; you can't split the text onto multiple lines (use multiple $id+"..." statements instead). The value of the whole statement is equal to id for convenience (see the example). The text (which is called a string literal) can contain certain escape codes:
\\ turns into a single \
\" turns into a single " without signalling the end of the literal
\n is a new line character, which is useful in a textslice but doesn't cause a new line in textboxes or on-screen strings.
\t is a tab character (which isn't useful at all as it doesn't actually cause a tab)
\x## where ## is a two digit hexidecimal number adds an ASCII character to the string. For example \x4b is the letter K.

# This displays Some text! in the corner of the screen
$1 = "Some text!"
showstring(1)

# This displays "A quote" in the corner of the screen
showstring($1="\"A quote\"")

$id+"some text"

Appends a string literal to a string variable. This is the same as $id="...", except that the existing contents of the string are preserved and appended to.

clear string(ID)

Erases the string buffer #ID to the empty string (""). That's all.

append ascii (ID, char)

Appends the character with ASCII code 'ascii' to the string with ID #ID. The font editor lists ASCII codes. For example numbers are 48 - 57, uppercase letters are 65 - 90, lowercase letters are 97 - 122.

append number (ID, number)

Appends the textual representation of number to the string with ID #ID. For example, append number(1,65) will append "65", not "A".

string sprintf (dest string ID, format string ID, arguments...)

Builds a string from a template (given by format string ID) and zero or more additional arguments, and puts the result in the string dest string ID. This is a restricted version of the sprintf function in other programming languages. This function takes at least 2 arguments. The format string is a mix of regular text and codes like %d. For each code, one argument is read and used to substitute for the code. The codes are:
%d: substituted with a number, printed as a decimal.
%x: substituted with a number, printed as a unsigned 32 bit hexidecimal, in lower case and without a leading 0x.
%s: substituted with a string. The argument should be a valid string ID.
%c: substituted with a single character. The argument should be an ASCII code (that is, a number between 0 and 255).
%%: substituted with a single %. In this case an argument is NOT used up.
More sophisticated formatting codes like %-04d that are possible in other programming languages are not supported yet.

# This displays some text like "HP: 30  MP: 12  $: 104" at the bottom of the screen
$1 = "HP: %d  MP: %d  $: %d"
string sprintf(0, 1, getherostat(me, stat:HP), getherostat(me, stat:MP), partymoney)
show string(0)

# This displays some text like "Ah Bob! You've brought me 5 apples."
# in the centre of the screen, and waits for the player to press a key.
$10 = "Ah %s! You've brought me %d apples."
getheroname(11, findhero(leader))
string sprintf(12, 10, 11, inventory(item:apple))
center string at(12, 160, 100)
wait for key(anykey)
hide string(12)

# This displays "1abcdef ffffffff A%"
# Notice that the expression '$1="%x %x %c%%"' returns the string ID 1 as a side effect.
string sprintf(0, $1="%x %x %c%%", 28036591, -1, 65)
show string(0)

number from string (ID, default)

Try to read the string specified by ID as a number and return it. Blank spaces at the beginning of the string will be ignored, and the string can start with a - sign for negatives. No other characters except numerical digits can appear in the string. You can also provide an optional default value that will be returned if the string is not a valid number (for example, if it contains a non-numeric letter)

copy string (dest, source)

Copies the text from string #source to string #dest, overwriting the existing string completely.
If you prefer, you can write dest $= source instead. You must supply string id numbers, not strings, as arguments.

concatenate strings (dest, source)

Copies the text from string #source to string #dest. However, unlike copy string, the text is appended to the end of dest.
If you prefer, you can write dest $+ source instead. You must supply string id numbers, not strings, as arguments.

string length (ID)

Returns the length of string #ID.

string compare (ID1, ID2)

Returns true if the two strings #ID1 and #ID2 are identical, case sensitive.

replace char (ID, position, char)

Replaces the character at position in string #ID with a character with ascii code char. The first position of the string is 1, and the last position of the string is the same as string length.

delete char (ID, position)

This deletes the character at position in string #ID, causing all the following characters to move over a slot. The first position of the string is 1, and the last position of the string is the same as string length.

ascii from string (ID, position)

Returns the ascii code of the character at position in string #ID. The first position of the string is 1, and the last position of the string is the same as string length. If you pass 0 as the position or a position past the end of the string, 0 will be returned.

get hero name (ID, hero)

This command will take the name of the hero in the party slot #hero, and stick it in string #ID, overwriting its contents.

Remember that this command expects the hero's position in the party, not the hero:name constants nor the hero's position in the walkabout party. If you want to get the name of a hero according to their position in the walkabout party, you should use hero by rank and find hero

# This example gets the name of the leader and stores it in string ID 1

get hero name (1, find hero (leader))

set hero name (ID, hero)

This command changes the name of the hero in party slot #hero (as returned by find hero) to the contents of string #ID. The length is not limited by the hero's Max Name Length setting.

get enemy name (enemyid, stringid)

Defined in the Enemy and Formation Functions section.

set enemy name (enemyid, stringid)

Defined in the Enemy and Formation Functions section.

get map name (ID, map)

This command will take the name of map #map and stick it in string #ID, overwriting its contents.

get attack name

read attack name (ID, attack)

This command will take the name of attack and stick it in string #ID, overwriting its contents. Use the atk:name constants from your HSI file.

If you want to use this command with attack ID numbers, you must add 1 to the ID number.

This command replaces the old get attack name which required you to use atk:name -- 2 or the attack id number -- 1

get attack caption (ID, attack)

This command will take the caption of attack and stick it in string #ID, overwriting its contents. Use the atk:name constants from your HSI file.

If you want to use this command with attack ID numbers, you must add 1 to the ID number.

get song name (ID, song)

Gets the name of song #song and puts it in string #ID.

string from textbox (ID, textbox, line, ignored)

Defined in the Text Boxes section.

textbox line (string ID, textbox, line, expand, strip)

Defined in the Text Boxes section.

show string at (ID, x, y)

Displays string #ID on the screen, positioning its top left corner at the given (x,y) coordinates. Unlike show string, changes to the string will be displayed in real-time.

center string at (ID, x, y)

Displays string #ID on the screen, positioning its top-middle at the given (x,y) coordinates. Unlike show string, changes to the string will be displayed in real-time.

The string is not re-centered automatically if its length changes. If you change the string and want to keep it centered, call showstringat again. Otherwise, its topleft corner will stay fixed.

hide string (ID)

Makes a string previously displayed with show string at or center string at disappear. Has no effect on strings displayed with show string

string is visible (ID)

Returns true if a string is being displayed by show string at or center string at. Otherwise, returns false. Is not effected by show string

string style (ID, style)

Changes the appearance of a string. Use this in conjunction with (before or after) show string at or center string at. Choice of style is string:outline and string:flat. string:outline is the style of string you are familiar with in textboxes: they are outlined with colour 0 (black). string:flat have no outline but can have a solid rectangular background of any colour displayed behind the string.

string color (ID, foreground color, background color)

Changes the color of a string. Use this in conjunction with (before or after) show string at or center string at. Foreground color is the colour of the text itself. Background color has no meaning for style:outline strings (the outline is always black). For style:flat strings, it is the color of the solid background if 1 to 255, or causes no background if 0. If you omit background color, the background will be transparent. Omit foreground color as well to reset the color to default ('Text' User-interface color).

positionstring (ID, x, y)

Positions the top left corner of string #ID at the given x,y coordinates. Unlike show string at, this command will not affect the visibility of a string.

string X (ID)

Returns the horizontal X position of the top left corner of string #ID

string Y (ID)

Returns the vertical Y position of the top left corner of string #ID

add menu item(menu handle)

Given a menu handle (for example, the one returned by create menu), adds a new blank menu item to the end of the menu. Returns a menu item handle, which you can store in a variable for use with commands like set menu item caption or set menu item type.

delete menu item(menu item handle)

Given a menu item handle (for example, the one returned by add menu item or selected menu item), delete the menu item from the menu. (The change does not affect other copies/instances of the same menu if this menu was created in the menu editor.)

swap menu items(handle1, handle2)

Given two menu item handles (for example, the ones returned by selected menu item and next menu item) switch the positions of the two menu items. Note that this works both to rearrange menu items within one menu, or to move menu items between different menus.

select menu item(menu item handle)

Given a menu item handle (for example, the one returned by add menu item), move the menu selection cursor to point to that menu item.

selected menu item(menu handle)

Returns the handle for the selected menu item in the topmost menu, false if no menus are open, or, when given an optional menu handle (for example, the one returned by open menu) returns the selected item in that menu.

use menu item(menu item handle)

Given a menu item handle (for example, the one returned by selected menu item), activate the menu item. This will cause whatever actions (text box, menu, script, tag changes, etc.) that have been configured for this menu item to be triggered.

first menu item(menu handle)

Given a menu handle (for example, the one returned by open menu), return a menu item handle for the menu item at the top of the menu.

next menu item(menu item handle, visible only)

Given a menu item handle (for example, the one returned by selected menu item), return a menu item handle for the menu item below the specified one, or false there is no next menu item. You can optionally include invisible items by using the optional argument visible only, which defaults to true. Note that invisible menu items are always at the end of the menu, after the last visible menu item. See menu item by true slot if that's undesirable.

variable(mi)
mi := first menu item
while(mi) do, begin
  # do things to each menu item
  mi := next menu item(mi)
end

previous menu item(menu item handle, visible only)

Given a menu item handle (for example, the one returned by selected menu item), return a menu item handle for the menu item above the specified one, or false there is no previous menu item. You can optionally include invisible items by using the optional argument visible only, which defaults to true. Note that invisible menu items are always at the end of the menu, after the last visible menu item. See menu item by true slot if that's undesirable.

variable(m)
m := previous menu item(selected menu item)

menu item by true slot(menu handle, slot)

Given a menu handle (for example, the one returned by open menu), return a menu item handle for the menu item at the position specified by slot. The first slot in the menu is 0. This command uses the ordering of menu items as they appear in the Menu Editor in Custom. The "true order" doesn't change as menu items are hidden or unhidden, unlike the slot returned by menu item slot.

menu item true slot(menu item handle)

Given a menu item handle (for example, the one returned by add menu item), return the slot number of the menu item, as it appears in the Menu Editor. The first slot in the menu is 0. The "true order" doesn't change as menu items are hidden or unhidden, unlike the slot returned by menu item slot.

menu item by slot(menu handle, slot, visible only)

Given a menu handle (for example, the one returned by open menu), return a menu item handle for the menu item at the position specified by slot. The first slot in the menu is 0. You can optionally include invisible items by using the optional argument visible only, which defaults to true. Note that invisible menu items are always at the end of the menu, after the last visible menu item -- menu items are NOT in the same order as they appear in the Menu Editor! This means menu item slot numbers change as menu items are hidden or unhidden. Use menu item by true slot if you want to use the order shown in the Menu Editor.

menu item slot(menu item handle)

Given a menu item handle (for example, the one returned by add menu item), return a the slot number of the menu item. The first slot in the menu is 0. Menu item slot numbers change as menu items are hidden or unhidden. Use menu item true slot if you want to know the slot number as it appears in the Menu Editor.

find menu item caption(menu handle, string ID, search after handle, visible only)

Given a menu handle (for example, the one returned by open menu), and a string identified by string ID, Search the menu for a menu item with a label that is the same as the string, and return a handle to the matching menu item. The optional third argument search after handle is a menu item handle to start searching after instead of searching from the top of the menu. The optional fourth argument visible only is a true or false value that determines whether or not to include hidden items. It defaults to true.

variable(menu, mi)
menu := open menu(menu:test menu)
$0="Puppies"
mi := find menu item caption(menu, 0)
while(mi) do, begin
 # do something to each menu item labelled "Puppies"
 mi := find menu item(menu, 0, mi)
end

get menu item caption(menu item handle, string ID)

Given a menu item handle (for example, the one returned by selected menu item), take the caption and copy it into the string identified by string ID.

set menu item caption(menu item handle, string ID)

Given a menu item handle (for example, the one returned by selected menu item), replace the caption with the string identified by string ID.

get menu item type(menu item handle)

Given a menu item handle (for example, the one returned by selected menu item), return the type of the menu item.

set menu item type(menu item handle, new type)

Given a menu item handle (for example, the one returned by selected menu item), change the type of the menu item to new type. Available constants are: menutype:label,menutype:special, menutype:menu, menutype:textbox, and menutype:script

get menu item subtype(menu item handle)

Given a menu item handle (for example, the one returned by selected menu item), return the subtype of the menu item. The meaning of the subtype varies depending on the type.

set menu item subtype(menu item handle, new subtype)

Given a menu item handle (for example, the one returned by selected menu item), change the subtype of the menu item to new subtype. The meaning of the subtype varies depending on the type of the menu item. For menutype:special you can use constants like: menuspecial:items, menuspecial:spells, menuspecial:status, menuspecial:equip, menuspecial:order, menuspecial:team, menuspecial:orderteam, menuspecial:map, menuspecial:save, menuspecial:load, menuspecial:quit, and menuspecial:volume. For menutype:textbox you can use the textbox's ID number. For menutype:menu you can use the menu's ID number or a menu:name constant from your HSI file. For menutype:script you can use script references in the form @scriptname

get menu item tag(menu item handle, whichtag)

Given a menu item handle (for example, the one returned by selected menu item), and a tag number whichtag which can be 1 or 2, Return the a tag required for the menu item to be available. The tag number will be positive if the tag needs to be ON, or negative if the tag needs to be OFF.

set menu item tag(menu item handle, new tag, whichtag)

Given a menu item handle (for example, the one returned by selected menu item), and a tag number whichtag which can be 1 or 2, Set the tag required for the menu item to new tag. Use a positive number if the tag needs to be turned ON, and a negative number if the tag needs to be turned OFF.

get menu item settag(menu item handle)

Given a menu item handle (for example, the one returned by selected menu item), Return the number of the tag that will be set when the menu item is selected. The tag number will be positive if the tag will be set ON, or negative if the tag will be set OFF.

set menu item settag(menu item handle, new settag)

Given a menu item handle (for example, the one returned by selected menu item), Change the tag that will be set when the menu item is selected. Use a positive number if the tag should be turned ON, and a negative number if the tag should be turned OFF.

get menu item togtag(menu item handle)

Given a menu item handle (for example, the one returned by selected menu item), Return the number of the tag that will be toggled when the menu item is selected. (The tag number will always be a positive number).

set menu item togtag(menu item handle, new settag)

Given a menu item handle (for example, the one returned by selected menu item), Change the tag that will be toggled when the menu item is selected. (the tag number will always be positive).

get menu item bit(menu item handle, bit)

Given a menu item handle (for example, the one returned by selected menu item), and bit number bit, Return true if the bitset is ON, and false if the bitset is OFF. You can use constants for the bit bit number in the form of menu item bit:Hide when disabled and menu item bit:Close menu if selected.

set menu item bit(menu item handle, bit, value)

Given a menu item handle (for example, the one returned by selected menu item), and bit number bit, Set the bitset is ON or OFF depending on value. You can use constants for the bit bit number in the form of menu item bit:Hide when disabled and menu item bit:close menu when selected.

get menu item extra(menu item handle, extra)

Given a menu item handle (for example, the one returned by selected menu item), and an extra data number which can be 0, 1, or 2, return the the number stored in the extra data space. This extra data has no meaning of its own, and is just useful for advanced menu scripting.

set menu item extra(menu item handle, extra, num)

Given a menu item handle (for example, the one returned by selected menu item), and an extra data number which can be 0, 1, or 2, change the number stored in the extra data space to num. This extra data has no meaning of its own, and is just useful for advanced menu scripting.

get menu bit(menu handle, bit)

Given a menu handle (for example, the one returned by top menu), and bit number bit, returns true if the bitset is ON, and false if the bitset is OFF. For the bit bit number you should use one of the constants:

• menubit:translucent box
• menubit:never show scrollbar
• menubit:allow gameplay
• menubit:suspend player even if gameplay allowed
• menubit:no box
• menubit:no close
• menubit:no controls
• menubit:prevent main menu

set menu bit(menu handle, bit, value)

Given a menu handle (for example, the one returned by top menu), and bit number bit, sets the bitset is ON or OFF depending on value. For the bit bit number you should use one of the constants:

• menubit:translucent box
• menubit:never show scrollbar
• menubit:allow gameplay
• menubit:suspend player even if gameplay allowed
• menubit:no box
• menubit:no close
• menubit:no controls
• menubit:prevent main menu

get menu boxstyle(menu handle)

Given a menu handle (for example, the one returned by open menu), return a the boxstyle of the menu. This will be a number from 0 to 15.

set menu boxstyle(menu handle, new box style)

Given a menu handle (for example, the one returned by open menu), change the boxstyle of the menu. new box style will be a number from 0 to 15.

get menu textcolor(menu handle)

Given a menu handle (for example, the one returned by open menu), return a the text color of the menu. This will be a number from 0 to 255.

set menu textcolor(menu handle, new textcolor)

Given a menu handle (for example, the one returned by open menu), change the text color of the menu. new textcolor will be a number from 0 to 255. 0 is the default color.

get menu max rows(menu handle)

Given a menu handle (for example, the one returned by open menu), return a max rows to display of the menu, or 0 if the menu is auto-sizing. If the actual number of menu items is larger than the max rows, the menu will be scrollable.

set menu max rows(menu handle, new max rows)

Given a menu handle (for example, the one returned by open menu), change the max rows to display of the menu to new max rows. Use 0 if you want the menu to be auto-sizing. If the actual number of menu items is larger than the max rows, the menu will be scrollable.

get menu offset x(menu handle)

Given a menu handle (for example, the one returned by open menu), return the x offset position of the menu's anchor point in pixels relative to the center of the screen.

get menu offset y(menu handle)

Given a menu handle (for example, the one returned by open menu), return the y offset position of the menu's anchor point in pixels relative to the center of the screen.

set menu offset x(menu handle, new x)

Given a menu handle (for example, the one returned by open menu), change the x offset position of the menu's anchor point in pixels relative to the center of the screen.

set menu offset y(menu handle, new y)

Given a menu handle (for example, the one returned by open menu), change the y offset position of the menu's anchor point in pixels relative to the center of the screen.

get menu anchor x(menu handle)

Given a menu handle (for example, the one returned by open menu), return the x anchor position of the menu. The return value will be align:center, align:left or align:right.

get menu anchor y(menu handle)

Given a menu handle (for example, the one returned by open menu), return the y anchor position of the menu. The return value will be align:center, align:top or align:bottom.

set menu anchor x(menu handle, new anchor)

Given a menu handle (for example, the one returned by open menu), change the horizontal x anchor position of the menu. The new anchor can be align:center, align:left or align:right.

set menu anchor y(menu handle, new anchor)

Given a menu handle (for example, the one returned by open menu), change the vertical y anchor position of the menu. The new anchor can be align:center, align:top or align:bottom.

get menu text align(menu handle)

Given a menu handle (for example, the one returned by open menu), return the text alignment of the menu. The return value will be align:center, align:left or align:right.

set menu text align(menu handle, new align)

Given a menu handle (for example, the one returned by open menu), change the text alignment of the menu. The new align can be align:center, align:left or align:right.

get menu min chars(menu handle)

Given a menu handle (for example, the one returned by open menu), return the minimum width of the menu in chars, or 0 for menus that have their width autodetected.

set menu min chars(menu handle, new min)

Given a menu handle (for example, the one returned by open menu), change the minimum width of the menu in chars, or use 0 to make the menu width autodetected.

get menu max chars(menu handle)

Given a menu handle (for example, the one returned by open menu), return the maximum width of the menu in chars, or 0 for menus that do not have a maximum.

set menu max chars(menu handle, new max)

Given a menu handle (for example, the one returned by open menu), change the maximum width of the menu in chars, or use 0 for no maximum.

get menu border(menu handle)

Given a menu handle (for example, the one returned by open menu), return the border thickness of the menu in pixels. Positive numbers indicate a thicker border. Negative numbers indicate a thinner border.

set menu border(menu handle, new border)

Given a menu handle (for example, the one returned by open menu), change the border thickness of the menu in pixels. Positive numbers will result in a thicker border. Negative numbers will result in a thinner border.

get menu on close script(menu handle)

Given a menu handle (for example, the one returned by open menu), return a script id for the script that will be run when the menu is closed, or false if there is none. This command is only useful with scripts that have the allow gameplay and scripts bitset turned on.

variable(m, s)
m := open menu(5)
s := get menu on close script(m)
run script by id(s)
			

set menu on close script(menu handle, script id)

Given a menu handle (for example, the one returned by open menu), assign script id that will be run when the menu is closed, or false to disable any on-close script that has already been set. The script trigger only takes effect the next time you close the menu. If you re-open the menu again, you will need to re-set the on-close script again. This command is only useful with scripts that have the allow gameplay and scripts bitset turned on.

variable(m, s)
m := open menu(5)
set menu on close script(m, @my menu exit handler)
			

load slice collection (id)

Loads a collection of slices that you have defined in the slice collection editor. The argument is the id number of the collection. The return value is a handle to the container that holds the loaded collection.

lookup slice (lookup code, start slice)

Search for an important slice using a lookup code, and return a handle to it, or 0 if it is not found. User defined slice lookup codes are defined in the slice collection editor. You will find them as constants in your .hsi file with sli: prefixes. There are also some special slice lookup codes with names that start with sl: prefixes. You can optionally specify a slice for the lookup slice command to start searching from, but if you do not, the whole slice tree will be searched.

Although the user-defined slice lookup codes are always safe to use for any purpose, There is a lot of potential mischief that you can do with a handle to a special slice. If you do anything dubious, like reordering, reparenting, or god forbid freeing the special slice, don't expect your scripts to work in later versions of the engine, which are likely to impose stricter restrictions! You may parent your own slices to these special slices, but moving special slices around is definitely a bad idea.

Be aware that when there is more than one slice with the same lookup code, the lookup slice command will only return the first one it finds in a depth-first search. If you need to find multiple slices with the same lookup code, you must search manually using get slice lookup.

# this example loads a saved slice collection,
# and gets a handle to a slice in it that you
# have marked with a slice lookup code name.
variable(collection, sl)
collection := load slice collection(5)
sl := lookup slice(sli:my special slice, collection)

# this example gets a handle to the portrait of the currently displaying
# text box (if any) and allows you to manipulate it.
variable(portrait)
portrait := lookup slice(sl:textbox portrait)
if(portrait) then(
  replace portrait sprite(portrait, 5)
)

# This is a list of special slice lookup codes
lookup slice(sl:root)
lookup slice(sl:textbox text)
lookup slice(sl:textbox portrait)
lookup slice(sl:textbox choice0)
lookup slice(sl:textbox choice1)
lookup slice(sl:textbox box)
lookup slice(sl:textbox portrait box)
lookup slice(sl:textbox choice box)
lookup slice(sl:textbox root)
lookup slice(sl:script layer)
lookup slice(sl:textbox layer)
lookup slice(sl:string layer)
lookup slice(sl:maproot)
lookup slice(sl:obsolete overhead)
lookup slice(sl:walkabout layer)
lookup slice(sl:hero layer)
lookup slice(sl:npc layer)
lookup slice(sl:walkabout sprite component)
lookup slice(sl:walkabout shadow component)
lookup slice(sl:backdrop)
lookup slice(sl:map layer0)
lookup slice(sl:map layer1)
lookup slice(sl:map layer2)
lookup slice(sl:map layer3)
lookup slice(sl:map layer4)
lookup slice(sl:map layer5)
lookup slice(sl:map layer6)
lookup slice(sl:map layer7)
lookup slice(sl:status portrait)
lookup slice(sl:status walkabout)
lookup slice(sl:status battlesprite)
lookup slice(sl:status page select)
lookup slice(sl:status statlist)
lookup slice(sl:status hide if no mp)
lookup slice(sl:status hide if no lmp)
lookup slice(sl:status hide if max lev)
lookup slice(sl:plank holder)
lookup slice(sl:status hide if no portrait)
lookup slice(sl:item itemlist)
lookup slice(sl:item exitbutton)
lookup slice(sl:item sortbutton)
lookup slice(sl:item trashbutton)
lookup slice(sl:plank menu selectable)
lookup slice(sl:spell listlist)
lookup slice(sl:spell spelllist)
lookup slice(sl:spell hide if no list)
lookup slice(sl:spell cancelbutton)
lookup slice(sl:virtual keyboard button)
lookup slice(sl:virtual keyboard buttontext)
lookup slice(sl:virtual keyboard shift)
lookup slice(sl:virtual keyboard symbols)
lookup slice(sl:virtual keyboard select)
lookup slice(sl:virtual keyboard entrytext)
lookup slice(sl:virtual keyboard del)
lookup slice(sl:virtual keyboard enter)

sprite layer

Returns a slice handle for the slice (also called the 'script layer') which is the default parent of all new script-created slices, such as created by load hero sprite and create rect. You can move slices elsewhere in the slice tree with set parent. You can use spritelayer together with first child if you want to loop through all your slices without knowing their handles. Another way to get this slice is to use lookup slice: lookup slice(sl:script layer).

variable(sl)
sl := first child(sprite layer)
while (sl) do, begin
 if (slice is sprite(sl)) then, begin
   # do an operation on each sprite
 end
 sl := next sibling(sl)
end

get slice lookup (handle)

Returns the lookup code of a slice, or false if it has none. You can compare the result with the sli: slice lookup values in your hsi file, or with the sl: special lookup values in plotscr.hsd

set slice lookup (handle, code)

Changes the lookup code of a slice. The first argument is the slice handle, the second is the new lookup code. You can pass false as the second argument to remove a slice's lookup code. This command works with the sli: slice lookup values in your hsi file. It does not work with the sl: special lookup values in plotscr.hsd, nor can it modify the lookup code of slices that already have special lookup codes. Only user-defined lookup codes can be changed. Built-in special lookup codes cannot.

get hero slice (who)

Get the slice for a hero walkabout. The argument is the hero's position in the walkabout caterpillar. You will not be able to manually reposition this slice. The main purpose of getting this slice is so you can access the sprite slice attached to it, or if you want to attach other slices to a hero walkabout.

get npc slice (npc)

Get the slice for an NPC walkabout. The argument is the NPC id or an NPCreference. You will not be able to manually reposition this slice. The main purpose of getting this slice is so you can access the sprite slice attached to it, or if you want to attach other slices to an NPC.

slice width (handle)

Returns the width of any slice, for example a sprite.

slice height (handle)

Returns the height of any slice, for example a sprite.

set slice width (handle, width)

Changes the width of a container slice or a rect slice. This command does not work on sprite slices because they have a fixed width.

set slice height (handle, height)

Changes the height of a container slice or a rect slice. This command does not work on sprite slices because they have a fixed height.

clamp slice (handle1, handle2)

Try to move the slice handle1 so that its screen position will be inside the screen position of slice handle2. The size of the slices will not be changed. It does not matter if the slices are related.

fill parent (handle, true_or_false)

Make a slice handle automatically fill its parent. This will change the position and size of the slice so that it completely fills the parent (minus the parent's padding). You can also disable filling with this command by passing false as the second argument, such as fill parent(handle, false). If a slice is filling its parent, then any commands which modify the width or height of the slice will fail. You should resize the parent instead. This command only works on rects and containers. It will not work on sprites because they cannot change size.

is filling parent (handle)

Returns true if a slice handle is set to automatically fill its parent, or false if it is not. This command always returns false for sprite slice handles because sprites cannot be set to fill parent.

slice x (handle)

Returns the x position of any slice, for example a sprite. This position is relative to the slice's parent, and may depend upon the slice's Align settings.

slice y (handle)

Returns the y position of any slice, for example a sprite. This position is relative to the slice's parent, and may depend upon the slice's Align settings.

put slice (handle, X, Y)

Changes the position of any slice, for example a sprite. This position is relative to the slice's parent, and may depend upon the slice's Align settings.

set slice x (handle, X)

Changes the y position of any slice, for example a sprite. This position is relative to the slice's parent. More exactly, it's the relative displacement between this slice's anchor point, and the selected align point on the parent. The position of the parent's align point also depends on the amount of padding the parent has.

set slice y (handle, Y)

Changes the y position of any slice, for example a sprite. This position is relative to the slice's parent. More exactly, it's the relative displacement between this slice's anchor point, and the selected align point on the parent. The position of the parent's align point also depends on the amount of padding the parent has.

slice screen x (handle)

Returns the X position on the screen of the anchor point of a slice. This position is relative to the screen, so it is calculated based on not only the slice's X position, but also its alignment, and the position and size of its parents. However, the slice's anchor point setting doesn't affect this, because that specifies which point on the slice is attached to the anchor point.

slice screen y (handle)

Returns the Y position on the screen of the anchor point of a slice. This position is relative to the screen, so it is calculated based on not only the slice's Y position, but also its alignment, and the position and size of its parents. However, the slice's anchor point setting doesn't affect this, because that specifies which point on the slice is attached to the anchor point.

put slice screen (handle, x, y)

Change the screen position of any slice. The position of the slice relative to its parent will automatically be corrected. Alignment and anchor will not be changed. Note that this does not work when a slice is filling its parent.

set slice screen x (handle, x)

Change the screen X position of any slice. The position of the slice relative to its parent will automatically be corrected. Alignment and anchor will not be changed. Note that this does not work when a slice is filling its parent.

set slice screen y (handle, y)

Change the screen Y position of any slice. The position of the slice relative to its parent will automatically be corrected. Alignment and anchor will not be changed. Note that this does not work when a slice is filling its parent.

set slice visible (handle, vis)

Makes slice handle invisible or visible, according to vis. Slices are automatically visible when you load them, but you can make them invisible with set slice visible(handle, off). If the slice has children, they will become invisible too.

set sprite visible

get slice visible (handle)

Returns the visibility setting for slice handle. This is true for visible, or false for invisible. Note that this only tells you if the slice is set to be invisible, it will not tell you if the slice is invisible for some other reason, such as if it is offscreen, or if it is the child of an invisible parent or grandparent.

set slice clipping (handle, clip)

Changes whether or not a slice will clip its children if they overflow its edges. The first argument is a slice handle. The second argument is true to make the slice clip, or false to allow its children to overflow. (newly created slices do not clip by default)

get slice clipping (handle)

Returns true if the slice handle is set to clip drawing its children, or false if child slices are allowed to be drawn overflowing its edges.

slice edge x (handle, edge)

Returns the x position of a particular edge of a slice. use the constants edge:left, edge:center, edge:right

slice edge y (handle, edge)

Returns the y position of a particular edge of a slice. use the constants edge:top, edge:middle, edge:bottom

set slice edge x (handle, edge, value)

Changes the x position of a specific edge of a slice. This is like set slice x, except that you can set by any edge regardless of the slice's anchor. Use the constants edge:left, edge:center, edge:right

set slice edge y (handle, edge, value)

Changes the x position of a specific edge of a slice. This is like set slice y, except that you can set by any edge regardless of the slice's anchor. use the constants edge:top, edge:middle, edge:bottom

set horiz align (handle, edge)

Changes the horizontal alignment of any slice relative to its parent. The available edges are edge:left, edge:center, edge:right. The default value is edge:left.

set vert align (handle, edge)

Changes the vertical alignment of any slice relative to its parent. The available edges are edge:top, edge:middle, edge:bottom. The default value is edge:top.

set horiz anchor (handle, edge)

Changes the horizontal anchor of any slice. The available anchor values are edge:left, edge:center, edge:right. The default value is edge:left.

set vert anchor (handle, edge)

Changes the vertical anchor of any slice. The available anchor values are edge:top, edge:middle, edge:bottom. The default value is edge:top.

get horiz align (handle)

Returns the horizontal alignment of any slice relative to its parent. The return value will be one of edge:left, edge:center, edge:right.

get vert align (handle)

Returns the vertical alignment of any slice relative to its parent. The return value will be one of edge:top, edge:middle, edge:bottom.

get horiz anchor (handle)

Returns the horizontal anchor that a slice uses to position itself relative to its parent. The return value will be one of edge:left, edge:center, edge:right.

get vert anchor (handle)

Returns the vertical anchor that a slice uses to position itself relative to its parent. The return value will be one of edge:top, edge:middle, edge:bottom.

realign slice (handle, horiz align, vert align, horiz anchor, vert anchor)

A quick way to set the alignment and optionally the anchor of a slice with a single command. If you leave out the arguments for the anchor then only the alignment will be changed.

center slice (handle)

A quick way to center the alignment and the anchor of a slice with a single command. Equivalent to realign slice(handle, edge:center, edge:center, edge:middle, edge:middle).

set padding (handle, pixels)

Sets the padding value in pixels for all the edges of a slice handle. This is a positive number to move children attached to the edges towards the center of the slice, or a negative number to move attached children further from the center.