AC Script

API Reference

Version 1.57

Special thanks go to Pax for permission to include this excerpt from the
ACScript User's Guide in the SkunkWorks documentation package.

Thanks also to the ACScript development team for showing the way:
Lax, Pax, Polecat, Husk, Redfist, Heysun, and Dr. Doom


Table of Contents


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.

The ac object

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:


The properties, events, and methods supported by the ac object are detailed below.

ac object methods

Methods are basically internal functions to the object. They do things, like print a message, move the mouse, etc.


This function generates a beep noise, number times.


This function sends the specified string to the output locations specified by the method SetDebug().


Returns an automation object which supports several properties for querying data:



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:


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 .


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.


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:

F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12,

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:



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.


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.


The same as KeyPress(), except that the specified keys are simulated to have been released by the user.


Works the same as MouseClick(), except that the button is pressed down, and simulated to be held


Same as MouseButtonRelease(), except that the mouse button is simulated to have been released.


Simulates a click of the mouse button specified by "button". 0 for the left button, 1 for the right, 2 for the middle.


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.js


Positions the mouse at the absolute screen position specified.


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);


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, 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.


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.


This method causes ACScript to halt execution for roughly the number of specified milliseconds (1000 milliseconds to a second).


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.

ac object properties

Just as objects have methods, they have properties. Properties are read to determine information about the game.


Returns the amount of weight your character is carrying, in pyreals.


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


Returns the object of the currently selected item.


Returns the amount of health your character has.


Returns true if you're in combat mode, false if you aren't.


Returns an array, like the location messages.. see t.js.


Returns the amount of mana your character has.


Returns your gender.


Returns your level


Returns your character's name.


Returns your profession.


Returns your race. (Your heritage, actually)


Takes the name of an object and returns it's ObjectID.


Returns the number of loose pyreals your character is carrying.


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.


Returns the amount of stamina your character has.


Returns a string with the version of the engine as "", ie: "1.0.20".


Returns the name of the world you're logged on to.

ac object events

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.


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.

0BasicTrue means that there's basic info in the basic array
1AttributeTrue means that there's attribute info in the attribute array
2HumanInfoTrue means that there's human info in the human info array

basic[3]: Contains the following 3 attributes in this order:

0LevelTarget's level
1Current HealthTarget's current health
2Max HealthTarget's maximum health

attribute[10]: Contains the following 10 attributes in this order:

0StrStrength attribute
1EndEndurance attribute
2QuickQuickness attribute
3CoordCoordination attribute
4FocusFocus attribute
5SelfSelf attribute
6Current StaminaTarget's current stamina
7Current ManaTarget's current mana
8Max StaminaTarget's maximum stamina
9Max ManaTarget's maximum mana

humaninfo[11]: Contains the following 11 elements in this order:

0Allegiance rankRank Name
1Followers# of characters in the allegiance (or -1 if not known)
2LoyaltyMay be 0, it's the loyalty skill level
3LeadershipMay be 0, it's the leadership skill level
4Player killer flag
5GenderMale or Female
7ClassAdventurer, Life Mage, Vagabond, ha ha
8Fellowship nameName of the fellowship the target is in
9Monarch nameName of the target's monarch
10Patron nameName 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.

0Flags[6]Bitmask decribing which fields in the remaining arrays are valid.
1BasicTrue means there's data in the Basic array
2ArmorTrue means there's data in the Armor array
3WeaponTrue means there's data in the Weapon array
4EnchantmentTrue means there's data in the Enchantment array
5PortalTrue means there's data in the Portal array

basic[14]: Basic data about the item - weight, value, type, descriptions, etc.

0Object Type
1ValueValue of the object in pyreals
2MassBurden units in pyreals
3Total PagesThe number of pages, for books or tomes
4Used PagesFor books etc. - how many pages have been used.
5Open StateFor packs, corpses, chests, etc.
6InscriptionInscription on the item, if any.
7AuthorPerson writing the inscription.
8UnknownThe meaning of this value is unknown at this time.
9Detailed DescriptionA longer descrption - gained when assess has succeeded.
10Simple DescriptionA short description of the item.
12EfficiencyUsed for mana stones, denotes the efficiency of the stone.
13StorageUsed 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.

0SlashingProtection level from slashing damage
1PiercingProtection level from piercing damage
2BludgeonProtection level from bludgeoning damage
3FireProtection level from fire damage
4AcidProtection level from acid damage
5ColdProtection level from cold damage
6ElectricalProtection level from electrical damage
7Armor LevelBase armor level of the item

weapon[10]: Sent for any weapons.

0Damage TypeDamage type dealt by this weapon.
1SpeedSpeed of the weapon.
2SkillWhich skill is appropriate for the weapon.
3DamageMaximum damage.
4Damage RangeModifier that determines the minimum damage the weapon will do. Example, a 5-10 damage sword would have [3] as 10 and [4] as .5
5Damage BonusExpressed as a percentage, such as a 113% Yumi or a 110% Composite bow (or a -33% Nayin).
6UnknownWe don't know what this is, yet. It may be related to the weapon's range for ranged weapons.
7Defense BonusExpressed as a percentage, this is the bonus the weapon bestows on your melee defense skill.
8Attack BonusExpressed as a percentage, this is the bonus to your attack skill using this weapon gives you.
9HighlightsThis 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.

0DiffThe Arcane Lore requirement for the item.
1SpellcraftThe casting level of the item, used to determine resists.
2RankReqThe allegiance rank you must possess to be able to make the item's magic function
3ManaThe amount of mana currently stored in the item.
4MaxManaThe maximum amount of mana that can be stored in the item.
5ManaBurned per rateThis is how many points of mana the item burns every [6] seconds. It's a negative number, possibly denoting that it repeats.
6ManaRateThe rate at which mana is used by the item, not counting the effects of your mana conversion skill.
7RaceReqWhich Heritage you must belong to in order to use the item's magic. You don't qualify 66% of the time.
8AltSkillReqWhat alternate skill level must you have in order to use this.
9AltSkillWhat alternate skill must you have trained (or spec'd?) in order to use this
10SpellNamesNames of the enchantments
11SpellDescDescriptions of the enchantments
12ManaTransferAmount 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.

0LowLevelMinimum level requirement to use the portal
1HighLevelMaximum level to use the portal
2DestinationPortal 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)



This gets sent when either you kill a monster, or when a monster kills you.

ACMsg_OnDeathOther(deadid, killerid, msg)

ACMsg_OnDeathSelf(id, msg)


This event occurs when you've logged out normally from AC.



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:

3=upper arm
4=lower arm
6=upper leg
7 = lower leg



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.


severity is a value between 0 and 2:
0 = Storm ended
1 = Mild storm
2 = Severe storm


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.


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.


Fires when a spell failed to cast on you.


This event occurs when you've begun logging into the world.




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.




Updates when the amount of pyreals in your possestion changes.


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)


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.


Reason the trade ended. 0 success.


ID of the person who cleared the window.

ACMsg_OnTradeStart(initid, receiveid)

Two args, the initiater, and the receiver.

ACMsg_OnVitals(health, stam, mana)


This important method of the ac object is key to writing macros that know about the world around them. It's only by calling WaitEvent that your macros will have events dispatched to them.

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.

WaitEvent syntax:


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:


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.

The Inventory object

ACScript includes an object just for your inventory, to make it easier to write macros that use your inventory items. Inscribe everything on your mule or automatically top off your spell comps, it's all up to you.

The properties supported by the Inventory object are detailed below.

Inventory object properties

GetItem(pack, item)

'pack' and 'item' are zero based. This property returns the item ID of the item in 'pack', at slot 'item'.


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).


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.


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.


'pack' is zero based and should be less than Inventory.NumberOfPacks. It returns the number of items in that pack.


Returns the number of packs in your inventory.