Every function a script can call, grouped by what it is for. If scripts are new to you, start with An introduction to scripting; for when scripts run, see Events.
Reading this page#
Each function is shown the way C# writes it: what it answers with, its name, and what it takes.
int GetPlayerLevel(int player)
That one takes a whole number, the player, and answers with a whole number, their level. You use it like this:
var level = GetPlayerLevel(player);
| It says | It means |
|---|
int | A whole number. |
string | Text, written in double quotes. |
bool | true or false. |
Color | A colour: one of the sixteen names, such as Yellow, or RGB(255, 128, 0). |
void | The function does something and answers nothing. |
Art is named by its key: official: and a name for the game's own, server: and a name for your server's, and a cell's number after # for one tile of a sheet, such as "official:tiles#412" or "server:grass". Functions that take art take its key. See your world's own art.
A function asked about something that is not there, such as a player who has left or a map that does not exist, does nothing, or answers 0, -1 or empty text. It does not stop your script.
The editor on the Scripting page checks every call as you type, so a misspelt name or a missing value is pointed out before you save.
Players: who and where#
Every function that takes player takes the number an event hands you. Most answer -1, or do nothing, for a number nobody is playing as.
| Function | What it does |
|---|
int FindPlayer(string name) | The number of the online player with that name, whatever its capitals, or -1. |
string GetPlayerName(int player) | The character's name. |
string GetPlayerDesc(int player) | The description the player wrote for themselves. |
string GetPlayerIP(int index) | The address the player is connected from, or 0.0.0.0. |
int GetPlayerMap(int player) | The number of the map the player is on. |
int GetPlayerX(int player) | Where the player stands, across: 0 to 11. |
int GetPlayerY(int player) | Where the player stands, down: 0 to 11. |
int GetPlayerDirection(int player) | Which way the player faces: 0 up, 1 down, 2 left, 3 right. |
void SetPlayerDirection(int player, int direction) | Turns the player to face a direction, 0 to 3. Everyone on the map sees it. |
void PlayerWarp(int player, int mapNumber, int x, int y) | Moves the player to a square of a map. A place that does not exist is refused. Moving within the same map does not run PartMap or JoinMap. |
void ForceWalk(int player, int x, int y, int speed) | Moves the player to a square of the map they are on and turns them the way they went. Everyone on the map sees it. |
string GetPlayerGraphic(int player) | The key of the sprite the player is drawn with. |
void SetPlayerGraphic(int player, string graphic) | Gives the player a sprite, such as "server:knight". Empty text puts back their guild's sprite, or their class's. Everyone on the map sees it. |
int GetPlayerGender(int player) | The character's gender, as a number. |
int GetPlayerClass(int player) | The number of the character's class, counting from 1. |
void SetPlayerClass(int player, int classIndex) | Changes the character's class. Their sprite and stats stay as they are. |
void SetPlayerName(int index, string name) | Renames the character. Refused if the name is empty, taken, or held for somebody else. |
int GetPlayerStatus(int player) | The player's status number. |
void SetPlayerStatus(int player, int status) | Sets the player's status, 0 to 100. |
bool GetPlayerFrozen(int player) | Whether the player is frozen. |
void SetPlayerFrozen(int player, bool frozen) | Freezes the player, so they cannot move, or lets them go. |
bool GetPlayerDead(int player) | Whether the player is marked dead. |
void SetPlayerDead(int player, bool dead) | Marks the player dead or alive, with none of what dying does: nothing is dropped and they are not moved. |
int GetPlayerCount() | How many players are online. |
string GetPlayersOnline() | The names of everyone online, with spaces between. |
int[] GetOnlinePlayers() | The numbers of everyone online, lowest first. |
int[] FindPlayersWithFlag(int flagNumber, int value) | The numbers of everyone online whose flag holds a value. |
int GetMaxUsers() | How many players the server lets in at once. |
To do something to everyone online, go through GetOnlinePlayers:
foreach (var other in GetOnlinePlayers())
PlayerMessage(other, "The gates are open.", Yellow);
What a player may do comes from their roles and rights, which the server's owner sets up. A tag is a word a script puts on a character and asks about later, such as SpellCaster for whoever finished a quest. Tags give no rights, and belong to one character.
| Function | What it does |
|---|
bool HasRight(int player, string right) | Whether the player holds a right, such as "EditMaps", from their roles or given to them directly. |
bool HasRole(int player, string role) | Whether the player holds a role, by its name. |
bool IsGod(int player) | Whether the player holds any right beyond those that only restrict a player. |
bool GiveRole(int player, string role) | Gives the player a role. Answers false if they had it already, or for Server Owner, which a script cannot give. |
bool TakeRole(int player, string role) | Takes a role away. |
bool GiveTag(int player, string tag) | Puts a tag on the character. Answers false if it had it already. |
bool TakeTag(int player, string tag) | Takes a tag off. |
bool HasTag(int player, string tag) | Whether the character has a tag. |
string[] GetPlayerTags(int player) | The character's tags, in alphabetical order. |
int[] FindPlayersWithTag(string tag) | The numbers of everyone online with a tag, lowest first. |
if (HasTag(player, "SpellCaster"))
PlayerMessage(player, "The old mage nods at you.", Cyan);
Players: health, stats and levels#
| Function | What it does |
|---|
int GetPlayerHP(int player) | Health now. |
int GetPlayerEnergy(int player) | Energy now. |
int GetPlayerMana(int player) | Mana now. |
void SetPlayerHP(int player, int hp) | Sets health, between 0 and the player's maximum. The player sees it. |
void SetPlayerEnergy(int player, int energy) | Sets energy, between 0 and the maximum. |
void SetPlayerMana(int player, int mana) | Sets mana, between 0 and the maximum. |
int GetPlayerMaxHP(int player) | The most health the player can have, with what they wear. |
int GetPlayerMaxEnergy(int player) | The most energy, with what they wear. |
int GetPlayerMaxMana(int player) | The most mana, with what they wear. |
void SetPlayerMaxHP(int player, int maxHp) | Sets the most health the player can have before equipment, 1 to 255. |
void SetPlayerMaxEnergy(int player, int maxEnergy) | The same, for energy. |
void SetPlayerMaxMana(int player, int maxMana) | The same, for mana. |
int GetPlayerStrength(int player) | Strength. |
int GetPlayerAgility(int player) | Agility. |
int GetPlayerEndurance(int player) | Endurance. |
int GetPlayerIntelligence(int player) | Intelligence. |
void SetPlayerStrength(int player, int strength) | Sets strength, 0 to 255. The player sees it. |
void SetPlayerAgility(int player, int agility) | Sets agility, 0 to 255. |
void SetPlayerEndurance(int player, int endurance) | Sets endurance, 0 to 255. |
void SetPlayerIntelligence(int player, int intelligence) | Sets intelligence, 0 to 255. |
void SetPlayerStats(int player, int statPoints) | Sets how many training points the player has to spend, 0 to 255. |
int GetPlayerLevel(int player) | The character's level. |
void SetPlayerLevel(int player, int level) | Sets the level, 1 to 255. |
int GetPlayerExperience(int player) | Experience gained towards the next level. |
int GetPlayerMaxExp(int player) | Experience needed for the next level. |
void GivePlayerExp(int player, int experience) | Gives experience, as a kill would. It can raise their level. More than 50,000 at once is refused. |
void TakePlayerExp(int player, int experience) | Takes experience away, never below 0 and never a level. More than 50,000 at once is refused. |
int GetPlayerDamage(int player) | What the player's next hit would do, before the target's armour. |
int GetPlayerArmor(int player, int damage) | What is left of a hit of that size, 1 to 255, after the player's armour. |
void SetPlayerLight(int player, int intensity, int radius) | Sets the light the player carries: how bright and how far, 0 to 255 each. Only that player sees it. |
Players: as an object#
GetPlayer hands back the whole player at once, which reads better than a dozen separate calls. It is for reading: to change something, use the functions above.
| Function | What it does |
|---|
IScriptPlayer GetPlayer(int player) | The player, or null for a number nobody is playing as. It has Index, Name, Class, Level, Experience, HpRegenRate, EnergyRegenRate, ManaRegenRate and Inventory, and the stats Hp, Energy, Mana, Strength, Agility, Endurance and Intelligence. Each stat has Current, Max (before equipment) and ModMax (with it). |
IScriptClass GetClass(int player) | The player's class: Name, HpChance, EnergyChance and ManaChance. |
IScriptMonster GetMonsterBeside(int player, int monster) | The monster in a place, counted from 0, on the map the player is on, or null: Name, Level, Armor, and the stats Hp, Strength and Agility. |
Inventory and equipment#
Inventory slots are numbered 1 to 30. An item's value is how many there are, for money and ammunition, and how much wear it has left, for anything else.
| Function | What it does |
|---|
int HasObj(int player, int itemNumber) | How much of an item the player holds: the amount, for money and ammunition, or how many of them otherwise. 0 for none. |
void GiveObj(int player, int itemNumber, int value) | Gives the player an item with that value. Money joins the money they have; anything else takes the first free slot. If there is no room, nothing is given. Runs GetObj and GotObj. |
void GiveInv(int player, int slotID, int itemNumber, int amount) | Gives an item into a particular slot. With a slot that does not exist, it behaves as GiveObj. |
int TakeObj(int player, int itemIndex, int amount) | Takes an amount of an item from the player: that many, for money and ammunition, or one whole item otherwise. Answers how much was taken, or 0 if they did not have enough. |
int TakeInv(int player, int slotID, int amount) | Takes an amount from the value of whatever is in a slot, and empties the slot when it reaches 0. Answers how much was taken. |
int GetPlayerInvObject(int player, int slotID) | The number of the item in a slot, or 0 for an empty one. |
int GetPlayerInvValue(int player, int slotID) | The value of the item in a slot. |
void SetInvObjectVal(int player, int slotID, int value) | Sets the value of the item in a slot. The player sees it. |
int GetPlayerEquipped(int player, int equipIndex) | The inventory slot of what the player wears in an equipment place, or 0 for nothing. Here the places count from 1: 1 for the main hand to 9 for the second accessory. |
int GetEquippedObjNum(int player, int slotID) | The number of the item the player wears in an equipment place, or 0. Here the places count from 0, as in the table below. |
void DisplayObjDur(int player, int slotID) | Tells the player, in chat, how worn the item in a slot is. |
int GetPlayerObjFlag(int player, int slotID, int flagNumber) | One of four small numbers, 0 to 3, a script can keep on an item a player holds. |
void SetPlayerObjFlag(int player, int slotID, int flagNumber, int value) | Sets one of them, to 0 to 255. |
bool WearItem(int player, EquipmentSlot slot, double amount) | Wears down what the player has in an equipment place by an amount. It breaks at 0, unless it is unbreakable, and the player is told. Answers whether it broke. |
void UseUpItem(int player, EquipmentSlot slot) | Destroys what the player has in an equipment place, as a last arrow is used up. |
int GetPlayerBank(int player) | The money the player has in the bank. |
void SetPlayerBank(int index, int bank) | Sets it. Nothing tells the player. |
Items#
| Function | What it does |
|---|
string GetObjectName(int itemNumber) | An item's name. |
int GetObjectType(int itemNumber) | The number of an item's type. |
int GetObjectData(int itemNumber, int dataIndex) | One of an item's first four settings, 0 to 3. |
int GetObjData(int itemNumber, int dataSlotIndex) | One of an item's eight settings, 0 to 7. |
Items on the ground#
A map holds up to 50 items on the ground, in places numbered 0 to 49.
| Function | What it does |
|---|
int SpawnObject(int mapNumber, int itemNumber, int value, int x, int y) | Puts an item on a square. It stays until somebody takes it. Answers -1 if it was placed and 0 if it could not be. |
int GetObjNum(int mapNumber, int index) | The number of the item in a place on the ground, or 0. |
int GetObjVal(int mapNumber, int index) | Its value. |
int GetObjX(int mapNumber, int index) | Where it lies, across. |
int GetObjY(int mapNumber, int index) | Where it lies, down. |
void DestroyObj(int mapNumber, int index) | Removes it. Everyone on the map sees it go. |
void DestroyObject(int mapNumber, int index) | The same as DestroyObj. |
int GetMapObjFlag(int mapNumber, int objIndex, int flagNumber) | One of four small numbers, 0 to 3, a script can keep on an item on the ground. |
void SetMapObjFlag(int mapNumber, int objIndex, int flagNumber, int value) | Sets one of them, to 0 to 255. |
Messages#
| Function | What it does |
|---|
void PlayerMessage(int player, string message, Color color) | A line in one player's chat, in a colour. |
void PlayerMessageRGB(int player, string message, Color color) | The same. With RGB, the colour can be any colour. |
void MapMessage(int mapNumber, string message, Color color) | A line to everyone on a map. |
void MapMessageAllBut(int mapNumber, int player, string message, Color color) | A line to everyone on a map except one player. |
void GlobalMessage(string message, Color color) | A line to everyone online. |
void MessageGods(string message, Color color, int access) | A line to every member of staff who is online. |
void NPCSay(int mapIndex, string text) | A line to everyone on a map, as said by that map's NPC. Nothing, if the map has none. |
void NPCTell(int targetPlayer, string text) | A line to one player, as said by the NPC of the map they are on. |
void PopupMessage(int player, string message, Color color, int targetType, int target) | Text that pops up on one player's screen over something: themselves (0), another player (1) or a monster on their map (2). |
void ViewportMessage(int player, string message) | Shows a notice on one player's screen. |
void EditScriptLabel(int player, string message, int left, int top, int width, int height, Color color) and void EditScriptLabel(int player, string message, int left, int top, int width, int height, Color color, int id) | Puts text in a rectangle on one player's screen, where it stays until it is changed. Give an id to show more than one at a time. |
Color RGB(int r, int g, int b) | A colour made from red, green and blue, 0 to 255 each. |
Color QBColor(int number) | One of the sixteen named colours by its number, 0 to 15. |
void PrintToServer(string message) | Writes a line to the server's console. Players do not see it. |
void PrintToChannel(string message) | The same. |
void PrintToIRC(string room, string message) | The same, with the room's name in front. |
Sounds and effects#
| Function | What it does |
|---|
void PlaySound(int player, string sound) | Plays a sound for one player, such as "server:thunder". |
void CreateTileEffect(int mapNumber, int x, int y, int sprite, int speed, int totalFrames, int loopCount, int endSound) | Plays an animation on a square. Everyone on the map sees it. |
void CreateCharacterEffect(int mapNumber, int player, int sprite, int speed, int totalFrames, int loopCount, int endSound) | Plays an animation on a player. |
void CreatePlayerEffect(int mapNumber, int sourcePlayer, int destPlayer, int sprite, int speed, int totalFrame, int endSound) | Plays an animation from one player to another. |
void CreateMonsterEffect(int mapNumber, int player, int monsterNumber, int sprite, int speed, int totalFrames, int endSound) | Plays an animation from a player to a monster. |
void CreateMonsterProjectile(int mapNumber, int sourceMonster, int targetPlayer, int sprite, int speed, int totalFrame, int endSound) | Shows something flying from a monster to a player. |
Maps#
Squares are numbered 0 to 11 across and 0 to 11 down.
| Function | What it does |
|---|
string GetMapName(int mapNumber) | A map's name. |
void SetMapName(int mapNumber, string name) | Renames a map. Up to 14 characters. |
int GetMapPlayerCount(int mapNumber) | How many players are on a map. |
int GetMapExit(int mapNumber, int direction) | The map an edge leads to (0 up, 1 down, 2 left, 3 right), or 0 for none. |
void SetMapExit(int mapNumber, int direction, int targetMap) | Sets where an edge leads. 0 closes it. |
int GetMapType(int mapNumber) | 0 for a friendly map, 2 for one where anyone can fight, 1 otherwise. |
bool GetMapSetting(int mapNumber, int setting) | Whether one of a map's settings is on: 0 friendly, 1 indoors, 2 always dark, 3 monsters start on the map, 4 double monsters, 5 monsters cannot be attacked, 6 anyone can fight. |
bool GetMapIsFriendly(int mapNumber) | Whether the map is friendly. |
bool GetMapIsPK(int mapNumber) | Whether anyone can fight on the map. |
void SetMapFlags(int mapNumber, bool friendly, bool indoors, bool alwaysDark, bool startOnMap, bool doubleMonsters, bool cantAttackMonsters, bool pk) | Sets a map's settings, all at once. |
void SetMapBoot(int mapNumber, int bootMapNumber, int bootX, int bootY) | Sets where a map sends players who are put off it. Map 0 for nowhere. |
string GetMapMusic(int mapNumber) | The key of a map's music, or empty text for none. |
void SetMapMusic(int mapNumber, string music) | Sets a map's music, such as "server:town". Empty text is silence. |
void SetMapMonster(int mapNumber, int monsterIndex, int monsterNumber, int delay) | Sets one of a map's monster entries: which kind appears and how often. Kind 0 removes it. |
int GetMapDarkness(int mapNumber) | How dark a map is, 0 to 255. |
void SetMapDarkness(int mapNumber, int darkness) | Sets it. Everyone on the map sees it. |
void SetOutdoorLight(int light) | Sets the darkness of every outdoor map at once, until the server restarts. |
bool GetMapWeather(int mapNmber, int flag) | Whether it is raining (0), snowing (1) or grey (2) on a map. |
void SetMapWeather(int mapNumber, bool raining, bool snowing, bool gray) | Sets a map's weather. Everyone on the map sees it. |
void MapReset(int mapNumber) | Puts a map back as it starts: monsters, doors, walls and the items on the ground. |
void MapRefresh(int mapNum) | Sends a map to everyone on it as it is now. Changes a script made show at once, but are not kept. |
void UpdateMap(int mapNum) | Saves a map with the changes scripts have made to it, and sends it to everyone on it. |
Tiles#
A tile can carry two attributes, which decide what stepping on it does. Each is a type and four numbers.
| Function | What it does |
|---|
int GetTileAtt(int mapNumber, int x, int y) | The type of a tile's first attribute, or 0. |
int GetAttData(int mapNumber, int x, int y, int layer) | One of the first attribute's four numbers, 0 to 3. |
void SetTileAtt(int mapNum, int x, int y, int val1, int val2, int val3, int val4, int val5) | Sets a tile's first attribute: its type, then its four numbers. |
int GetTileAtt2(int mapNumber, int x, int y) | The type of the second attribute. |
int GetAtt2Data(int mapNumber, int x, int y, int layer) | One of the second attribute's four numbers. |
void SetTileAtt2(int mapNumber, int x, int y, int val1, int val2, int val3, int val4, int val5) | Sets the second attribute. |
string GetTileGraphic(int mapNum, int x, int y, int layer) | The key of the art on one of a square's six layers: 0 ground, 1 second ground, 2 background, 3 second background, 4 foreground, 5 second foreground. Empty text for none, or for an animation the map keeps for itself. |
void SetTileGraphic(int mapNum, int x, int y, int layer, string graphic) | Sets it, to a tile or an animation. Call MapRefresh or UpdateMap afterwards for players to see it. |
bool GetTileIsVacant(int mapNumber, int x, int y) | Whether a player could step onto a square: no wall, warp, locked door, monster or player is on it. |
bool GetTileNoDirectionalWalls(int mapNumber, int x, int y, int direction) | Whether nothing on a square blocks a step from it in a direction. |
bool OpenDoor(int mapNumber, int x, int y) | Opens the door on a square for ten seconds, as walking into it does. Answers whether it opened. |
Monsters#
A map has a place for each entry in its list of monsters, and never fewer than six, numbered from 0. monsterIndex, and monsterNumber on these functions, mean that place, except where a kind of monster is asked for.
| Function | What it does |
|---|
int SpawnMonster(int mapNumber, int monsterNumber, int x, int y, bool frozen) | Puts a monster of a kind on a square, in the first free place. Answers the place it took, or -1 if it could not. |
void DestroyMonster(int mapNumber, int monsterIndex) | Removes a monster, with nothing of a death: no drop, no experience and no MonsterDie. |
void MonsterWarp(int mapNumber, int monsterIndex, int x, int y) | Moves a monster to a square of its map. |
int GetMonsterType(int mapNumber, int monsterNumber) | The kind of monster in a place, or 0 for none. |
string GetMonsterName(int mapNumber, int monsterIndex) | Its name. |
string GetMonsterDesc(int mapNumber, int monsterIndex) | Its description. |
int GetMonsterX(int mapNumber, int monsterNumber) | Where it stands, across. |
int GetMonsterY(int mapNumber, int monsterNumber) | Where it stands, down. |
int GetMonsterDirection(int mapNumber, int monsterIndex) | Which way it faces. |
int GetMonsterHP(int mapNumber, int monsterIndex) | Its health now. |
void SetMonsterHP(int mapNumber, int monsterIndex, int hp) | Sets its health, 0 to 255. |
int GetMonsterMaxHP(int mapNumber) | The most health a kind of monster has. Despite its name, the value it takes is the kind of monster. |
int GetMonsterStrength(int mapNumber, int monsterIndex) | Its strength. |
int GetMonsterAgility(int mapNumber, int monsterIndex) | Its agility. |
int GetMonsterArmor(int mapNumber, int monsterIndex) | Its armour. |
int GetMonsterSight(int mapNumber, int monsterIndex) | How far it sees. |
int GetMonsterSpeed(int mapNumber, int monsterIndex) | How fast it is. |
int GetMonsterRegen(int mapNumber, int monsterIndex) | How fast it heals. |
int GetMonsterExp(int mapNumber, int monsterIndex) | The experience it is worth. |
int GetMonsterObj(int mapNumber, int monsterIndex, int itemIndex) | The item in one of its three drops, 0 to 2. |
int GetMonsterValue(int mapNumber, int monsterIndex, int itemIndex) | How many of that item. |
int GetMonsterTarget(int mapNumber, int monsterNumber) | The player it is after, or -1. |
int SetMonsterTarget(int mapNumber, int monsterNumber, int targetPlayer) | Sends it after a player. |
void SetMonsterTileTarget(int mapNum, int monsterIndex, int x, int y) | Sends it to walk to a square and stop there. |
Combat#
| Function | What it does |
|---|
bool CanAttackPlayer(int player1, int player2) | Whether the rules let one player attack another here: the map, their guilds and who they are. It does not ask whether they are in reach. |
bool CanAttackMonster(int player, int targetMonster) | Whether the player's map lets monsters be attacked and there is one in that place. |
bool AttackPlayer(int player, int targetPlayer, int damage) | Hits a player for an amount, 0 to 255, as though the first player had struck them, with no roll and no armour. Answers whether it killed them. |
bool AttackMonster(int player, int targetMonster, int damage) | Hits a monster on the player's map for an amount, as though the player had struck it. The monster turns on them. Answers whether it killed it. |
void MonsterAttack(int monsterNumber, int targetPlayer, int damage) | Has the monster in a place on the target's map hit them for an amount. |
void MonsterAttackPlayer(int mapNumber, int monsterIndex, int player, int damage) | The same, naming the map. Nothing, if the player is not on it. |
Guilds#
| Function | What it does |
|---|
int GetPlayerGuild(int player) | The number of the player's guild, or 0. |
void SetPlayerGuild(int player, int targetGuild) | Puts the player in a guild as an ordinary member, out of any other. 0 takes them out. None of the rules for joining apply. |
int GetGuildRank(int player) | The player's rank in their guild, or 0. |
void SetGuildRank(int player, int rank) | Sets it. |
string GetGuildName(int guildNumber) | A guild's name. |
int GetGuildMemberCount(int guildNumber) | How many members it has. |
int GetGuildBank(int guildNumber) | The money in its bank. |
void SetGuildBank(int guild, int bank) | Sets it. |
int GetGuildHall(int guildNumber) | The map of its hall, or 0. |
int GetGuildSprite(int guildNumber) | Its sprite, or 0. |
Classes#
classNum counts from 1, as GetPlayerClass does.
| Function | What it does |
|---|
string GetClassName(int classNum) | The class's name. |
int GetClassSprite(int classNum) | Its sprite. |
int GetClassStartHP(int classNum) | The health a new character of the class starts with. |
int GetClassStartEnergy(int classNum) | The energy. |
int GetClassStartMana(int classNum) | The mana. |
int GetClassStartStrength(int classNum) | The strength. |
int GetClassStartAgility(int classNum) | The agility. |
int GetClassStartEndurance(int classNum) | The endurance. |
int GetClassStartIntelligence(int classNum) | The intelligence. |
int GetClassHPChance(int classNum) | The chance, out of 100, that a level raises the class's health. |
int GetClassEnergyChance(int classNum) | The same, for energy. |
int GetClassManaChance(int classNum) | The same, for mana. |
Remembering things#
Flags are explained in the introduction.
| Function | What it does |
|---|
int GetFlag(int flagNumber) | A world flag, 0 to 255. |
void SetFlag(int flagNumber, int value) | Sets it. Flags 0 to 127 are saved; 128 to 255 last until the server stops. |
int GetPlayerFlag(int player, int flagNumber) | One of a character's flags, 0 to 255. |
void SetPlayerFlag(int player, int flagNumber, int value) | Sets it. |
void ResetPlayerFlag(int flagNumber) and void ResetPlayerFlag(int player, int flagNumber) | Sets a flag back to 0: for one player, or, given only the flag, for every character there is. |
int GetA(int number) | One of a hundred numbers, 0 to 99, shared by all scripts. They last until the server stops. |
void SetA(int number, int value) | Sets one. |
void ResetA() | Sets all hundred to 0. |
int ReadINIInt(string filename, string header, string name, int defaultValue) | Reads a number a script stored under a file name, a heading and a name, or the default you give if it is not there. |
string ReadINIStr(string filename, string header, string name, string defaultValue) | The same, for text. |
void WriteINIStr(string filename, string header, string name, string data) | Stores text under a file name, a heading and a name. File names are short and plain: no dots or slashes, and up to 15 characters. |
void PrintToFile(string fileName, string text) | Adds a line to a log of your own in the server's data folder. The name has no dots or slashes and is up to 15 characters, and .log is added. |
Timers and other scripts#
| Function | What it does |
|---|
void ScriptTimer(int player, int seconds, string scriptName) | Runs a script for a player after a number of seconds, up to a day, if they are still online. |
void MicroTimer(int player, int microSeconds, string scriptName) | The same, in thousandths of a second, from 100 to 10,000. Timers are looked at twice a second. |
bool RunScript(string scriptName, params object[] args) | Runs another script now, with the values you give. Answers what it answered, or true if there is no such script. |
T RunScript<T>(string scriptName, params object[] args) | Runs another script and answers with what its main returns: RunScript<int>, RunScript<bool> or RunScript<string>. A number and a yes-or-no stand for each other, 0 being carry on. Asking for text from a script that returns a number, or the reverse, stops the script that asked, and the log says why. |
Time and the server#
| Function | What it does |
|---|
int GetTime() | The hour on the world's clock. |
void SetHour(int hour) | Sets it. Everyone sees the light change. |
void MakeDay() | Sets the clock to the hour day begins. |
void MakeNight() | Sets it to the hour night begins. |
int GetRealYear() | The real year. |
int GetRealMonth() | The real month, 1 to 12. |
int GetRealDay() | The day of the month. |
int GetRealDayOfWeek() | The day of the week, 0 for Sunday to 6. |
int GetRealHour() | The real hour, 0 to 23. |
int GetRealMinute() | The minute. |
int GetRealSecond() | The second. |
string ServerVersion() | The server's version. |
void BootPlayer(int index, string reason) | Disconnects a player, telling them why. |
void BanPlayer(int index, int days, string reason) | Bans a player for 1 to 255 days and disconnects them. |
Chance and arithmetic#
C# does arithmetic itself, and Math has the rest. These are the ones worth knowing.
| Function | What it does |
|---|
int Random(int max) | A whole number from 0 up to, but not including, the one you give. Random(6) is 0 to 5. |
double Rnd() | A number from 0 up to, but not including, 1. |
int Divide(int numerator, int divisor) | One whole number divided by another, rounded to the nearest. 0 when dividing by 0, where C#'s own / would stop the script. |
Kept for converted scripts#
These exist so that scripts converted from the original Odyssey keep working. C# does all of them better, as the last column says. The editor warns about the ones that will be taken away.
| Function | Write it as |
|---|
int GetPlayerSprite(int player) | GetPlayerGraphic(player) |
void SetPlayerSprite(int player, int sprite) | SetPlayerGraphic(player, key). The number is the old sprite's. |
int GetTileSprite(int mapNum, int x, int y, int layer) | GetTileGraphic(map, x, y, layer) |
void SetTileSprite(int mapNum, int x, int y, int layer, int sprite) | SetTileGraphic(map, x, y, layer, key) |
void PlayCustomWav(int player, int soundNum) | PlaySound(player, key) |
void SetMapMidi(int mapNumber, int midiNumber) | SetMapMusic(map, key) |
int GetPlayerAccess(int player) | HasRight(player, right), HasRole(player, role) or IsGod(player). GetPlayerAccess sums a player's rights into the original game's god levels, 0 to 10 or 255. |
string StrCat(string st1, string st2) | a + b |
string StrCat3(string st1, string st2, string st3) | a + b + c |
string StrCat4(string st1, string st2, string st3, string st4) | a + b + c + d |
bool StrCmp(string st1, string st2) | a == b. StrCmp ignores capitals. |
string StrFormat(string st1, string st2) | st1.Replace("*", st2) |
string Str(bool value) and string Str(int number) | value.ToString() |
int Val(string number) | int.Parse(text). Val reads the number the text starts with, so "12 gold" is 12, and answers 0 when it starts with none. |
int InStr(string st1, string st2) | text.IndexOf(part). InStr counts from 1, answers 0 when it is not there, and ignores capitals; IndexOf counts from 0 and answers -1. |
int Len(string st) | text.Length |
int StrLen(string st1) | text.Length |
string Mid(string st, int start, int length) | text.Substring(start, length). Mid counts from 1 and gives what there is when asked for too much; Substring counts from 0. |
string Mid2(string st, int start) | text.Substring(start). Mid2 counts from 1; Substring counts from 0. |
string Chr(int val) | ((char)number).ToString(). Chr answers only for 1 to 255. |
string Replace(string st, string find, string replace) | text.Replace(find, replace). Replace ignores capitals when finding. |
string Replace2(string st, string find, string replace, int start, int count) | Gives the text from character start on (counting from 1), with the first count replaced, or all of them for -1. |
int Abs(int value) | Math.Abs(value) |
int Sqr(int value) | (int)Math.Round(Math.Sqrt(value)). Sqr rounds to the nearest whole number. |
int Pow(int number, int exponent) | (int)Math.Pow(number, exponent). Pow answers 1 when the result is too large to hold. |
int Percent(int val1, int val2) | val1 * 100 / val2. Percent rounds to the nearest whole number and answers 0 when val2 is 0. |
bool IsPlaying(int player) | GetPlayer(player) != null |
string GetPlayerUser(int player) | GetPlayerName(player) |
int RunScript0(string scriptName) | RunScript(name). The numbered ones answer 0 for carry on and 1 for stop, and pass along the values the calling script was given. |
int RunScript1(string scriptName, int parm1) | RunScript(name, a) |
int RunScript2(string scriptName, int parm1, int parm2) | RunScript(name, a, b) |
int RunScript3(string scriptName, int parm1, int parm2, int parm3) | RunScript(name, a, b, c) |
int RunScript4(string scriptName, int parm1, int parm2, int parm3, int parm4) | RunScript(name, a, b, c, d) |
Lists of numbers#
Equipment places#
WearItem, UseUpItem and Inventory[...] take a place by name, such as EquipmentSlot.Head. GetEquippedObjNum takes its number.
| Number | Name | Number | Name |
|---|
| 0 | PrimaryHand | 6 | Relic2 |
| 1 | OffHand | 7 | Accessory1 |
| 2 | Chest | 8 | Accessory2 |
| 3 | Head | 9 | Legs |
| 4 | Ring | 10 | Feet |
| 5 | Relic1 | | |
Item types#
What GetObjectType answers, and ItemType names.
| Number | Name | Number | Name |
|---|
| 0 | None | 9 | Guild |
| 1 | Weapon | 10 | ProjectileWeapon |
| 2 | Shield | 11 | Ammunition |
| 3 | Armor | 12 | Relic1 |
| 4 | Helmet | 13 | Relic2 |
| 5 | Potion | 14 | Accessory1 |
| 6 | Money | 15 | Accessory2 |
| 7 | Key | 16 | EnergySource |
| 8 | Ring | | |
Colours#
| Number | Name | Number | Name |
|---|
| 0 | Black | 8 | DarkGrey |
| 1 | Blue | 9 | BrightBlue |
| 2 | Green | 10 | BrightGreen |
| 3 | Cyan | 11 | BrightCyan |
| 4 | Red | 12 | BrightRed |
| 5 | Magenta | 13 | BrightMagenta |
| 6 | Brown | 14 | Yellow |
| 7 | Grey | 15 | White |
What a player holds, as an object#
GetPlayer(player).Inventory reads a player's items without a function call for each fact.
| You write | You get |
|---|
Inventory.Slots | How many slots the inventory has. |
Inventory[3] | What is in slot 3, counting from 1, or null if it is empty. |
Inventory[EquipmentSlot.PrimaryHand] | What is worn in that place, or null. |
What you get back has Slot, Quantity (for money and ammunition), Durability (for anything that wears) and Item. Item is the item as your world defines it: Name, Type, Strength (a weapon's damage, or what a shield, armour or helmet absorbs), IsUnbreakable, and for bows, arrows and rings, BowBaseDamage, AmmoClass, AmmoDamage, RingType and RingModifier.
void main(int player)
{
var weapon = GetPlayer(player).Inventory[EquipmentSlot.PrimaryHand];
if (weapon == null)
{
PlayerMessage(player, "You are not holding a weapon.", Grey);
}
else
{
PlayerMessage(player, $"Your {weapon.Item.Name} hits for {weapon.Item.Strength}.", White);
}
}