Although you may never need to use them directly, there are some variables that tell your scripts about how AC is running:
The below screen resolution properties are correct in full screen mode and windowed mode both, and are the foundation upon which the library was written.
Width: This is the width of the Asheron's Call screen in pixels.Height: This is the height of the Asheron's Call screen in pixels.
ACScript has a built in object for handling keyboard, mouse, and Asheron's Call network I/O. These functions are accessed by specifying the object name ("ac"), followed by a period, and then the name of the method you wish to invoke or property you wish to read.
The ac object, for instance, has a method called "KeyEvent", which simulates the user pressing a key, or entering a string of keys. In order to call this function from you script, you would write JScript code that looks like this:
ac.KeyEvent("Hi!");
Methods are basically internal functions to the object. They do things, like print a message, move the mouse, etc.
ac.Beep(number);
This function generates a beep noise, number times.
ac.Debug(string);
This function sends the specified string to the output locations specified by the method SetDebug().
ac.GetObject();
Returns an automation object which supports several properties for querying data:
toString;
Name;
LongName;
Location;
Type;
Holder;
HolderSlot;
Value;
TotalValue;
StackCount;
StackMax;
UsesLeft;
UsesMax;
Container;
ObjectID;
Owner;
Model;
Icon;
ac.GetObjectCollection(flags);
Gets a collection of items from ACScript's object table. Flags can either be omitted, or set to INC_OBJECT_ALL, to get the complete object table. Or flags can be a bitmask of the following values from the library:
ciCollectionAll
ciCollectionPlayers
ciCollectionMonster
ciCollectionPlayerCorpse
ciCollectionMonsterCorpse
ciCollectionLifestone
cCollectionPortal
ciCollectionMerchant
ciCollectionEquipment
ac.ItemProperty(object ID, name);
This property takes two input parameters, the objectID That you want to query a property for, and the property name. "name", and "location". , and .
Options:
Name - returns the objects name
name2 - The secondary name as, as in "sacks of hawthorn"
holder - the id of the person holding this object
holderslot - where the holder is holding the object
value - value of the item
location -returns it's location - if known - as a VBArray (which needs to be converted to a JScript array before being used
totalvalue - value of the stack
stackcount - how many in the stack
stackmax - maximum that could be stacked
container - the ID of the the container for this object
owner - sometimes the user ID of the person holding it
model - the graphics model for this object
icon - the graphics icon for this object
type - This value stores data about the type of object. Still collecting data, but some examples: 0x1c - Character, 0x3c - PK Character.
UsesLeft - remaining uses on things like healing kits
UsesMax - Maximum uses on things like healing kits
exists - tests to see if the item is in ACScript's object table. 0 if it's not, non-zero if it is.
ac.KeyEvent(string);
Key Event takes a string argument. The string can either be a literal, quoted string, such as "Hi", or a string variable.
A character proceeded by the symbol "^" will be sent as if the control key was being held down when the key was pressed. Similarly, a key can be set with shift or ALT simulated by proceeding the character with "~" or "@", respectively. If you wish to send one of these keys, you can either send it in a string by itself ("~", for example), or include two consecutive instances in the string ("~~A", would simulate the user pressing "~" and "A", for example).
Special keys can be enclosed in brackets, such as "{ESC}" for the ESCAPE key. Here is a list of supported special keys:
ALT, BACK, CONTROL, DEL, DOWN, END, ESC,
F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12,
HOME, INS, KEYPAD *, KEYPAD +, KEYPAD -, KEYPAD, LEFT,
NUM 1, NUM 2, NUM 3, NUM 4, NUM 5, NUM 6, NUM 7, NUM 8, NUM 9, NUM 0, PGDN, PGUP, PRTSC, RETURN,
RIGHT, SHIFT, SPACE, TAB, UP,
Features can be combined. If you wanted to send the quick key combination to log out (SHIFT+ESC), for example, you would write the following code:ac.KeyEvent("~{ESC}");
ac.KeyPaste(msg);
This function will paste the text in 'msg' to the clipboard, and then simulates a CONTROL-V to paste it to AC. This does not place control in the chat window, the caller must do that if desired. This function also ignores any of the special key processing done by the other keyboard simulation functions. The raw text is simply copied, and pasted.
ac.KeyPress(string);
KeyPress() works exactly the same as KeyEvent(), except that the keys specified are simulated to be held down until the KeyRelease() is sent for the string.
ac.KeyRelease(string);
The same as KeyPress(), except that the specified keys are simulated to have been released by the user.
ac.MouseButtonPress(button);
Works the same as MouseClick(), except that the button is pressed down, and simulated to be held
ac.MouseButtonRelease(button);
Same as MouseButtonRelease(), except that the mouse button is simulated to have been released.
ac.MouseClick(button);
Simulates a click of the mouse button specified by "button". 0 for the left button, 1 for the right, 2 for the middle.
ac.MouseMove(x,y);
Moves the mouse pointer to the coordinates that you specify.
Note: ACScriptLib allows your macro to support multiple resolutions by using one of several functions to move the mouse pointer to a specific spot on the AC screen, such as a pack, armor location, weapon slot, etc. via a formula instead of just coordinates. See ACScriptLib.jsac.MouseMoveAbs(x,y);
Positions the mouse at the absolute screen position specified.
ac.Print(string);
Sends a string to the ACScript console window. This is useful for debugging, or logging information about your scripts operation.
Note: You should use ac.Print when you as a Macro author want to display something to the user of the macro, and ac.Debug when you want to add debug output.ac.RegisterHandler(event, function_name);
Registers a user defined event handler. Example:
var cookie = ac.RegisterHandler(ciOnVitals, "MyOnVitalsFunction");ac.UnRegisterHandler(event, cookie);
Unregisters a user defined event handler. Example:
ac.UnRegisterHandler(ciOnVitals, cookie);ac.SetDebug(flags);
This function determines the behavior of the Debug() method. In particular, it determines where the debug output will be set. "flags" is a bit mask, 0x01 specifies that output should be sent to the debug terminal (Using the Win32 API OutputDebugString()), and 0x02 specifies that it should be sent to the console.
Having debug output sent to the debug terminal can be useful. By using tools such as DebugView, available on the SysInternals web page at http://www.sysinternals.com/ntw2k/freeware/debugview.shtml, you can view the debug output of one machine on the monitor of a second machine on the network. This is a convenient way of debugging your executing scripts while Asheron's Call takes up the entire screen. DebugView can also be set to log to a file, so that you can save the output for later review.
By default, ACScript sends the debug output to both the console and the debug terminal. If you don't have a debug terminal attached, ACScript still sends the output correctly to the console.
ac.SetPreviousSelectedObject(ObjectID);
This function uses knowledge of the client memory space to set which object the client considers to be the previous selected object. Note: It's prone to break on patch day, because any time the client is recompiled the memory addresses will change.
ac.Sleep(milliseconds);
This method causes ACScript to halt execution for roughly the number of specified milliseconds (1000 milliseconds to a second).
ac.WaitEvent(timeout);
This method is useful only for scripts that don't use the –E command line option and so receive network messages from ACCom. When it's called, ACScript will dispatch event callbacks to your script. It will dispatch any pending events, and then return or wait for a maximum period of time (timeout – in milliseconds) before returning. WaitEvent() will return after dispatching all waiting events, regardless of whether the timeout has been reached or not. Please see the special section on WaitEvent for more information.
Just as objects have methods, they have properties. Properties are read to determine information about the game.
ac.Burden
Returns the amount of weight your character is carrying, in pyreals.
ac.ConnectedToAC
Returns a bitmask indicating whether or not you're connected to AC, and how complete your game state is.
The following bits are set:0x01 - Connected to AC
0x02 - Received the cached login message
0x04 - Received the real login message
0x08 - Received full inventory information
0x10 - Inventory data is from ACCom cache
0x20 - Object table is from ACCom cache
ac.GetSelectedObjectID
Returns the object of the currently selected item.
ac.Health
Returns the amount of health your character has.
ac.InCombatMode
Returns true if you're in combat mode, false if you aren't.
ac.Location
Returns an array, like the location messages.. see t.js.
ac.Mana
Returns the amount of mana your character has.
ac.MyGender
Returns your gender.
ac.MyLevel
Returns your level
ac.MyName
Returns your character's name.
ac.MyProfession
Returns your profession.
ac.MyRace
Returns your race. (Your heritage, actually)
ac.ObjectFromName(name)
Takes the name of an object and returns it's ObjectID.
ac.Pyreals
Returns the number of loose pyreals your character is carrying.
ac.SpellCastResult
Returns the result of the last spell. 0 for success. The result is cleared when this function is called.
ac.SpellNumOnTab(tab, index)
Returns a number which uniquely identifies the spell that's located on the specified tab, at the specified index.
ac.Stamina
Returns the amount of stamina your character has.
ac.Version
Returns a string with the version of the engine as "major.minor.build", ie: "1.0.20".
ac.World
Returns the name of the world you're logged on to.
There are a large number of potential Event functions which may be called in your script. The script t.js will be updated for each ACScript release to include callbacks for all supported events.
ACMsg_OnAddToPack(id, name of object, destid, index)
ACMsg_OnAdjustStack(objectid, name of object, new stack size)
ACMsg_OnAnimationSelf(a, b, c, d, e)
ACMsg_OnApproachVendor(id,buy_ratio, sell_ratio,item_collection)
Start talking to a vendor, id is the ID of the vendor, buy_ration is the ratio that the vendor will purchase items at (price/value). Sell ratio is the same thing only for what the vendor sells, and item_collection is a collection (array of objects) that the vendor has in stock.
ACMsg_OnAssessCreature(id,success,name,flags[3],basic[3],attribute[10],humaninfo[11])
In addition to id, success, and name, the event now receives four arrays: flags[3], basic[3], attribute[10], and humaninfo[11].
flags[3]: 3 booleans, each indicating what other arrays contain valid data.
Index Name Description 0 Basic True means that there's basic info in the basic array 1 Attribute True means that there's attribute info in the attribute array 2 HumanInfo True means that there's human info in the human info array basic[3]: Contains the following 3 attributes in this order:
Index Name Description 0 Level Target's level 1 Current Health Target's current health 2 Max Health Target's maximum health attribute[10]: Contains the following 10 attributes in this order:
Index Name Description 0 Str Strength attribute 1 End Endurance attribute 2 Quick Quickness attribute 3 Coord Coordination attribute 4 Focus Focus attribute 5 Self Self attribute 6 Current Stamina Target's current stamina 7 Current Mana Target's current mana 8 Max Stamina Target's maximum stamina 9 Max Mana Target's maximum mana humaninfo[11]: Contains the following 11 elements in this order:
Index Name Description 0 Allegiance rank Rank Name 1 Followers # of characters in the allegiance (or -1 if not known) 2 Loyalty May be 0, it's the loyalty skill level 3 Leadership May be 0, it's the leadership skill level 4 Player killer flag 5 Gender Male or Female 6 Race Heritage 7 Class Adventurer, Life Mage, Vagabond, ha ha 8 Fellowship name Name of the fellowship the target is in 9 Monarch name Name of the target's monarch 10 Patron name Name of the target's patron ACMsg_OnAssessItem(id, success, name, flags[6], basic[14], armor[8], weapon, enchant, portal)
The format of these arguments is similar to OnAssessCreature. That is, the first is an array which indicates which, if any, of the following arrays contain valid data.
flags[6]: The first element, flags[0], contains a bit mask which describes in greater detail what fields in the remaining arrays are valid. The other 5 elements are bools, one for each of the following 5 arrays.
Index Name Description 0 Flags[6] Bitmask decribing which fields in the remaining arrays are valid. 1 Basic True means there's data in the Basic array 2 Armor True means there's data in the Armor array 3 Weapon True means there's data in the Weapon array 4 Enchantment True means there's data in the Enchantment array 5 Portal True means there's data in the Portal array basic[14]: Basic data about the item - weight, value, type, descriptions, etc.
Index Name Description 0 Object Type 1 Value Value of the object in pyreals 2 Mass Burden units in pyreals 3 Total Pages The number of pages, for books or tomes 4 Used Pages For books etc. - how many pages have been used. 5 Open State For packs, corpses, chests, etc. 6 Inscription Inscription on the item, if any. 7 Author Person writing the inscription. 8 Unknown The meaning of this value is unknown at this time. 9 Detailed Description A longer descrption - gained when assess has succeeded. 10 Simple Description A short description of the item. 11 Comment 12 Efficiency Used for mana stones, denotes the efficiency of the stone. 13 Storage Used for mana stones, denotes the amount of mana that can be stored. armor[8]: Sent for anything that has an armor value, or damage type protections - armor, shields, clothing.
Index Name Description 0 Slashing Protection level from slashing damage 1 Piercing Protection level from piercing damage 2 Bludgeon Protection level from bludgeoning damage 3 Fire Protection level from fire damage 4 Acid Protection level from acid damage 5 Cold Protection level from cold damage 6 Electrical Protection level from electrical damage 7 Armor Level Base armor level of the item weapon[10]: Sent for any weapons.
Index Name Description 0 Damage Type Damage type dealt by this weapon. 1 Speed Speed of the weapon. 2 Skill Which skill is appropriate for the weapon. 3 Damage Maximum damage. 4 Damage Range Modifier that determines the minimum damage the weapon will do. Example, a 5-10 damage sword would have [3] as 10 and [4] as .5 5 Damage Bonus Expressed as a percentage, such as a 113% Yumi or a 110% Composite bow (or a -33% Nayin). 6 Unknown We don't know what this is, yet. It may be related to the weapon's range for ranged weapons. 7 Defense Bonus Expressed as a percentage, this is the bonus the weapon bestows on your melee defense skill. 8 Attack Bonus Expressed as a percentage, this is the bonus to your attack skill using this weapon gives you. 9 Highlights This information pertains to whether or not the various other pieces of information about the weapon are highlighted in red, green, or not at all. enchant[14]: Sent for any items which have enchantments. Indicates what spells the item has and what is required to activate them.
Index Name Description 0 Diff The Arcane Lore requirement for the item. 1 Spellcraft The casting level of the item, used to determine resists. 2 RankReq The allegiance rank you must possess to be able to make the item's magic function 3 Mana The amount of mana currently stored in the item. 4 MaxMana The maximum amount of mana that can be stored in the item. 5 ManaBurned per rate This is how many points of mana the item burns every [6] seconds. It's a negative number, possibly denoting that it repeats. 6 ManaRate The rate at which mana is used by the item, not counting the effects of your mana conversion skill. 7 RaceReq Which Heritage you must belong to in order to use the item's magic. You don't qualify 66% of the time. 8 AltSkillReq What alternate skill level must you have in order to use this. 9 AltSkill What alternate skill must you have trained (or spec'd?) in order to use this 10 SpellNames Names of the enchantments 11 SpellDesc Descriptions of the enchantments 12 ManaTransfer Amount of mana to transfer (For mana stones) portal[3]: sent for portals. Contains upper and lower level restrictions as well as the text description of the portal.
Index Name Description 0 LowLevel Minimum level requirement to use the portal 1 HighLevel Maximum level to use the portal 2 Destination Portal destination ACMsg_OnChatBroadcast(msg, sender, senderid, type)
4 args, msg being sent, name of the sender, id of the sender, and a type flag (color displayed in game).
ACMsg_OnChatEmoteCustom(ObjectID, EmoterName, msg)
3 args, id of the emoter, name of the sender, msg being emoted.
ACMsg_OnChatEmoteStandard(ObjectID, EmoterName, msg)
3 args, id of the emoter, name of the sender, msg being emoted.
ACMsg_OnChatLocal(msg, from, srcid)
ACMsg_OnChatServer(text, type)
Text is the text being sent, and type. Most magic related messages go through here.
ACMsg_OnChatSpell(msg, from, srcid)
ACMsg_OnCombatMode(on_off)
ACMsg_OnDeathMessage(s)
This gets sent when either you kill a monster, or when a monster kills you.
ACMsg_OnDeathOther(deadid, killerid, msg)
ACMsg_OnDeathSelf(id, msg)
ACMsg_OnEnd3D()
This event occurs when you've logged out normally from AC.
ACMsg_OnEndPortalOther(id)
ACMsg_OnEndPortalSelf()
ACMsg_OnLocChangeOther(id, landblock, x, y, z, heading)
ACMsg_OnLocChangeSelf(landblock, x, y, z, heading)
ACMsg_OnLogon(id, name, health, stamina, mana)
ACMsg_OnMeleeDamageOther(name, damage)
ACMsg_OnMeleeDamageSelf(name, damage,location)
This event now receives 3 parameters: name, damage, and location. 'location' is a number from 0 to 8 indicating where on your body you were hit:
0=head
1=chest
2=abdomen
3=upper arm
4=lower arm
5=hand
6=upper leg
7 = lower leg
8=foot
ACMsg_OnMeleeEvadeOther(name)
ACMsg_OnMeleeEvadeSelf(name)
ACMsg_OnMyPlayerKill(id, msg)
ACMsg_OnObjectCreate(name, id, type)
ACMsg_OnObjectCreatePlayer(name, id)
ACMsg_OnOpenContainer(id, count)
Sent when you open a chest or corpse. ID is the objectID of the container, and count is the number of items in the container.
ACMsg_OnPortalStormWarning(severity)
severity is a value between 0 and 2:
0 = Storm ended
1 = Mild storm
2 = Severe storm
ACMsg_OnPortalStormed()
You've been portal stormed.
ACMsg_OnRemoveFromInventory(id, name)
ACMsg_OnSetFlagOther(id, flag, on)
Sets a flag for another character. Only known value is 0x4 for pk.
ACMsg_OnSetFlagSelf(flag, on)
Set's a character flag. Only known value is 0x4 for pk.
ACMsg_OnSpellCastSelf(spellid)
When you succeed in casting a spell, you receive this message. ID is the spell ID you cast successfully. This actually gets sent before the spell animation, so be aware of the timing issues.
ACMsg_OnSpellExpire(spell, layer)
For creature and life spells. Spell is the spell id, and layer is the spell layer number.
ACMsg_OnSpellExpireSilent(spell, layer)
Just like OnSpellExpire, only for spells that expire without a text notification, such as for magic items.
ACMsg_OnSpellFailSelf(reason)
Fires when a spell failed to cast on you.
- -1: You don't know that spell.
- -2: Your skill is not high enough to have much hope of casting the spell.
- -3: The spell timed out - without casting. Sometimes seen in place of 1024 for being out of components.
- 29: You were too busy to cast the spell.
- 1024: Out of components.
- 1025: Insufficient mana.
- 1026: Fizzle.
- 1028: A player cast a spell but one or both of you weren't PK.
ACMsg_OnStart3D()
This event occurs when you've begun logging into the world.
ACMsg_OnStartPortal()
ACMsg_OnStartPortalSelf()
ACMsg_OnStatLevel(level)
ACMsg_OnStatSkillExp(skillid, skill, exp, offset, nextpt)
Five arguments, skill, skill name, difficulty of task performed, total number of points added past the base for this skill, and number of points needed for the next skill point.
ACMsg_OnStatTotalBurden(burden)
ACMsg_OnStatTotalExp(exp)
ACMsg_OnStatTotalPyreals(pyreals)
Updates when the amount of pyreals in your possestion changes.
ACMsg_OnStatUnspentExp(exp)
ACMsg_OnTargetHealth(id, health, name)
Sends the health for the targeted creature. Only sent if the creature you have targeted is a valid combat target. I.e., not sent for other players if you're not PK.
ACMsg_OnTell(from, msg, srcid, destid)
ACMsg_OnTellFellowship(from, msg)
ACMsg_OnTellFollower(from, msg)
ACMsg_OnTellMelee(from, msg, srcid, destid)
ACMsg_OnTellMisc(from, msg, srcid, destid, type)
ACMsg_OnTellPatron(from, msg)
ACMsg_OnTellServer(from, msg, srcid, destid)
ACMsg_OnTellVassal(from, msg)
ACMsg_OnTradeAccept(id)
One argument, the id of the person who accepted the trade.
ACMsg_OnTradeAdd(id, side)
ID of the item being added, and which side it's added to.
ACMsg_OnTradeEnd(reason)
Reason the trade ended. 0 success.
ACMsg_OnTradeReset(id)
ID of the person who cleared the window.
ACMsg_OnTradeStart(initid, receiveid)
Two args, the initiater, and the receiver.
ACMsg_OnVitals(health, stam, mana)
ACScript uses a single threaded event model for communicating with applications. This means that incoming game event notifications can only be dispatched to scripts when execution control is returned to the engine. This happens when a script calls the ac object's method WaitEvent().
When WaitEvent() is called, it in turn calls event functions in your script. These functions all start with the prefix "ACMsg_". There are approximately 50 possible events that can be trigged by various game events. Everything from your vitals (health, stamina, and mana) being updated to incoming chat messages is handled. As these game events arrive, they are saved in a queue maintained by the ACScript engine. When you call WaitEvent(), these queued events are converted into event callbacks made to your script.
WaitEvent() has 4 different modes of operation. The mode used is determined by the second parameter (see below) when you call WaitEvent. Together, the mode and timeout parameters determine the behavior of the WaitEvent call.
By default, WaitEvent() will process all queued events, stopping if the processing takes longer than the timeout value. If there are no events currently in the queue, WaitEvent will wait up to 'timeout' milliseconds for an event to be queued, and then dispatch it. In this mode, WaitEvent() will return the total number of events processed.
If the mode parameter, which is optional, is 1 WaitEvent() will dispatch only one event. If no events are queued, it will wait for up to 'timeout' milliseconds for an event to arrive. In this mode, WaitEvent() will return the ID of the event dispatched.
If the mode parameter is 2, WaitEvent() will dispatch events until either the timeout is reached, or the event specified in the optional 3rd parameter is dispatched. In this mode, the WaitEvent returns 0 in the event of a timeout, or the number of the event you requested as success.
If the mode parameter is 3, WaitEvent() will not return until it has waited for the entire 'timeout' number of milliseconds. It will dispatch events continuously during that time. In this mode, WaitEvent() will return the total number of events processed. It is usually appropriate to use WaitEvent in this mode, rather than using the ac.Sleep().
Important note: When connected to Asheron's Call, ACScript will receive incoming events continuously. As noted above, these events are stored in a queue while waiting to be processed. This queue can not be allowed to grow arbitrarily large without having an adverse affect on system performance. Therefore, it's important that your script, if connected to AC, call WaitEvent() regularly to empty the queue. Currently, the queue size is limited to approximately 1000 messages. If you application doesn't call WaitEvent() frequently enough to keep the number of queued messages below this number, you'll receive a warning message and queued messages will be discarded.
timeout, // timeout value in milliseconds
mode, // mode flag (0-3). Optional. Default 0.
message_id // ID of message to wait for in mode 2.
);
ACScriptLib sets several constant values which can be used to simplify calling WaitEvent(). There is a constant for each mode:
ciWaitModeOne
ciWaitModeSpecific
ciWaitModeUntilTimeout
In addition, each of the events supported by the system have an associated constant in ACScriptLib. For example:
ciOnVitals is defined as 1, and corresponds to the event function ACMsg_OnVitals().
See ACScriptLib.js for the complete list of constants. See also the script waittest.js in the test directory.
GetItem(pack, item)
'pack' and 'item' are zero based. This property returns the item ID of the item in 'pack', at slot 'item'.
HaveAny(name)
This returns the amount of the named item in the first stack the system finds looking through your inventory (or 1 if it's a non-stackable item).
HowMany(name)
This property searches through all your inventory counting all the items named 'name'. This is somewhat slower than HaveAny(), so it's best to use that function if it provides the information you need. Script writers should check the inventory bit returned by ConnectedToAC() before depending on the return values of Inventory properties. ACScript must be running when the user logs on to ensure that you have a complete inventory state.
Initialized
This is the same as calling (ConnectedToAC & 8). It returns TRUE if ACScript has received enough information to fully initialize the inventory state. If this is not true, then some of the inventory functions may return values that don't agree with what Asheron's Call itself sees.
ItemsInPack(pack)
'pack' is zero based and should be less than Inventory.NumberOfPacks. It returns the number of items in that pack.
NumberOfPacks
Returns the number of packs in your inventory.