Decal Script

 User’s Guide

Version

Client – 0.3.0

Plugin – 0.3.0

Server – 1.0.0


 

Table of Contents

 

·        Introduction to DScript

·        Features

·        Using the DScript Server Interface

·        Using the DScript Client Interface

·        Receiving Game Events with DScript

·        Programming with DScript

o       The AC Object

§         Variables

§         Methods

§         Properties

§         Events

o       The Inventory Object

§         Methods

§         Properties

o       The Spell Object

§         Methods

§         Properties

·        End User License Agreement

 


 

Introduction

Decal Script is a scripting tool designed to allow an end user to write scripts for Asheron’s Call.  This utility includes both a client and a server.  The client and server communicate via TCP/IP and therefore do not need to be run on the same machine.  Furthermore, the server comes with the capability to support as many as 50 clients at a time.  Each client must have a unique username/password on the server to which they connect.  All scripts are contained on the machine running the server software and can only be viewed or modified by the administrator.  The server uses the Microsoft Active Scripting engine to execute scripts.  This offers the ability to use scripts written in both Visual Basic Script and Java Script.

 

Why Client/Server?

 

One of the biggest questions I’ve heard about this project is, “Why have a client/server?”.  The answer is both simple and complex.  Originally, the client/server configuration was put into place because of a problem arising between Decal and Decal plug-ins written in Visual Basic.  Since then the client/server configuration has developed more into a feature than a handicap. 

·        Eventually, the server will allow clients to interact with each other directly.  One client will be able to check the status of another, trigger an event for it, or give it instructions.  This would provide for better coordinated macros than using chat messages or tells.

·        The server allows for a central storage location of scripts.  For those running multiple accounts on multiple computers, scripts will no longer need to be copied to each machine every time they are updated.

·        Clan members, friends, and acquaintances can be given access to your scripts without actually getting a copy of them.  This is good for those ones you don’t really want to give away.

 


 

Features

 


 

Using the DScript Server Interface

The DecalScript Server provides end-users with a simple and effective graphical interface.  Through this interface script projects and user accounts can be managed and server settings can be configured.

 

 

This is the main DecalScript Server window.  The names of users currently connected to the server will appear in the “Connected Users” list.  The server administrator may at any time disconnect a user from the server by clicking on their name and hitting the “Boot User” button.  The User List dialog can be accessed via the “User List” button or the “User List” selection in the “Options” menu.  The projects available to connecting clients are listed in the “Available Projects” list.  Projects can be managed via the Project Editor when either the “New” or “Edit” buttons are pressed, or by selecting “Project Editor” from the “File” menu.  Selecting a project and pressing the “Delete” button will remove the “.prj” file associated with the project, however it will not delete the source files of which the project is comprised.  If a project is added or removed while the server is running the “Rescan” button can be pressed to update the Project List.

 

 

The User List dialog offers the ability to manage all user accounts on the server.  Users can be added by pressing the “Add” button, entering a Username and Password, and pressing the “Save” button.  Current users can be edited by selecting their name from the User List, pressing “Edit”, making the desired changes, and then pressing the “Save” button.  Accounts can be deleted via the “Delete” button.  Clients who are connected to the server at the time their account is deleted are not disconnected from the server.

 

 

The Project Editor is used to create or modify projects.  When creating a new project, the user must provide a project name, specify whether the project is to be comprised of JScript or VBScript files, and add at least one source file before hitting the “Save” button.  When editing projects, the user is given the ability to switch between JScript and VBScript, as well as the ability to add and remove project files.  Projects of type Java Script may only contain “.js” files, and projects of type VB Script may only contain “.vbs” files.  Mixed projects are not allowed.  All project files(“.prj”) and all script files(“.js” and “.vbs”) must be stored in the server’s “Projects” folder.  Subdirectories are not supported at this time.

 

 

The Preferences dialog offers the administrator the ability to change the TCP/IP port the server utilizes, and also gives the ability to change several options.  Currently the only implemented option is that of “Start Minimized”, which will cause the server dialogs to be hidden upon starting the server.  The server can still be accessed while minimized by double-clicking or right clicking the spinning globe icon in the Tool Tray.

 


 

Using the DScript Client Interface

 

The DScript Client includes a simple to use graphical user interface.  The client is made up of a Windows based client as well as a Decal plugin.  For both to function properly Decal must be running, and the DScript Windows client must be running before a character is logged in.

 

The DecalScript plugin is very simple to operate.  When the Start button is pressed, the windows client will begin processing the currently loaded script, and the caption on the Start button will change to “Stop”.  When stop is pressed, the windows client will cause the script to timeout, and halt the script.

 

 


 

Receiving Game Events with DScript

 

All events triggered due to in-game events are listed in the AC Object documentation under section “Events”.  There is a wide variety of events available for use.  Effective use of events can give a macro insight into in-game happenings, and make the difference between scripts that mindlessly send mouse clicks and keypresses, and those that can imitate a player and make choices based on current status.

 


 

Programming with DScript

 

The AC Object

 

Variables

 

Width

Returns screen width in number of pixels.

Height

Returns screen height in number of pixels.

 

Methods

 

ac.DebugMsg(Msg)

 

Sends Msg to all locations specified by ac.SetDebug

 

ac.KeyEvent(String)

 

Simulates the sequential keypress of each character in the string argument.  A listing of special features and key code strings can be found here.

 

ac.KeyPaste(String)

 

Copies the string to the clipboard and pastes it.

 

ac.KeyPress(KeyCode)

 

Simulates a key pressed and held.  A complete listing of KeyCodes can be found here.

 

ac.KeyRelease(KeyCode)

 

Simulates a key release.  A complete listing of KeyCodes can be found here.

 

ac.MouseButtonPress(Button)

 

Simulates a mouse button pressed and held.  Left = 0, Right = 1, Middle = 2

 

ac.MouseButtonRelease(Button)

 

Simulates a mouse button release.  Left = 0, Right = 1, Middle = 2

 

ac.MouseClick(Button)

 

Simulates a mouse button click.  Left = 0, Right = 1, Middle = 2

 

ac.MouseDoubleClick(Button)

 

Simulates a mouse button double click.  Left = 0, Right = 1, Middle = 2

 

ac.MouseMove(x,y)

 

Sets the mouse cursor at the specified position.

 

ac.SelectObject(ObjID)

 

Will select object with GUID ObjID.

 

ac.SetDebug(Flags)

 

Indicates where DebugMsg output should go.  1 = Chat Window.  2 = Debug Window.  4 = File Specified by ac.SetDebugFile.  8 = OutputDebugString Win API.  Add numbers together for combination output.

 

ac.SetDebugFile(FileName)

 

Sets the file where debug output should be sent if ac.DebugMsg is called and Debug Flag is set for file output.  If full path is not specified file will be placed in same dir as project file.

 

ac.SetPreviousSelectedObject(ObjID)

 

Sets ObjID as the previous selected object.

 

ac.Sleep(milliseconds)

 

Delays the execution of the script for the specified amount of time.

 

ac.SpellCast(SpellID)

 

Casts spell with ID SpellID.  A complete list of spells and their IDs can be found here.  Spell must be learned and valid target must be selected before calling SpellCast.

 

ac.StopScript()

 

Will cause the script currently be executed to timeout and stop.

 

ac.UseItem(Item1ID, Item2ID)

 

Can be called to use one item on another, or to use a single item by specifying item1id and 0 for item2id.

 

ac.WaitEvent()

 

Essentially a DoEvents statement in VB.  This must be included in long loops if they don’t already contain a Sleep statement.

 

ac.WriteToChatWindow(text, color)

 

Writes the specified text to the chat window.  Some colors include:

 

0 = Green

4 = Yellow

13 = Light Blue

22 = Pink

2 = White

7 = Dark Blue

21 = Red

 

ac.RawWriteToChatWindow(text,color)

 

Works just like ac.WriteToChatWindow but will not place a carriage return at the end.

 

Properties

 

ac.Burden

 

Returns the amount of weight(in burden units) currently held by the character.

 

ac.Connected

 

Whether the plugin is running or not.  1 for yes, 0 for no.

 

ac.GetSelectedObjectID

 

Returns the GUID of the selected object.

 

ac.Health

 

Returns the amount of health the character has.

 

ac.ItemProperty(ObjectID, Name)

 

Returns the property of ObjectID specified by Name.  Available properties include:  name, name2, value, location, totalvalue, stackcount, stackmax, container, owner, icon, usesleft, usesmax, exists.

 

ac.InCombatMode

 

Returns true if in combat mode, false if not.

 

ac.Location

 

Returns a 5 element array containing your characters location.

 

0

Landblock

1

X

2

Y

3

Z

4

Heading

 

Elements 1-4 are trimmed to a maximum of 2 decimal places.

 

ac.Mana

 

Returns the amount of mana the character has.

 

ac.MyGender

 

Returns a string containing character’s gender.

 

ac.MyID

 

Returns the character’s unique GUID.

 

ac.MyLevel

 

Returns character’s level.  (not being updated – value does not change from login)

 

ac.MyName

 

Returns a string containing character’s name.

 

ac.MyProfession

 

Returns a string containing character’s class title.

 

ac.MyRace

 

Returns a string containing either “Sho”, “Aluvian”, or “Gharu’ndim”.

 

ac.Pyreals

 

Returns the number of pyreals character has.

 

ac.SpellCastResult

 

Returns a value indicating result of last attempted spellcast.  Value is 0 for failure, 1 for success, and –1 if no attempt has been made at casting a spell since ac.SpellCastResult was last called.

 

ac.Stamina

 

Returns the amount of stamina the character has.

 

ac.World

 

Returns the name of the server currently connected to.

 

Events

 

ACMsg_OnChatSpell(msg, from, srcid)

 

Triggers when you or someone within broadcast range utters spell words.

 

ACMsg_OnChatLocal(msg, from, srcid)

 

Triggers when you or someone within broadcast range says anything.

 

ACMsg_OnChatBroadcast(msg, sender, senderid, ctype)

 

Triggers when you or someone within broadcast range says something or utters spellwords. Ctype = 0x02 for chat, and 0x11 for spell messages.

 

ACMsg_OnChatEmoteCustom(EmoterID, EmoterName, Msg)

 

Triggers when you or someone within broadcast range uses /e to emote something.

 

ACMsg_OnChatEmoteStandard(EmoterID, EmoterName, Msg)

 

Triggers when you or someone within broadcast range uses a standard emote.

 

ACMsg_OnChatServer(text, color)

 

Triggers when the server sends text.  Happens for trade skill events, spellcasts, and many others.

 

ACMsg_OnCombatMode(value)

 

Triggers when you enter or exit combat mode.  Value = true for enter and false for exit.

 

ACMsg_OnDeathMessage(msg)

 

Triggers when you kill something or get killed.

 

ACMsg_OnDeathOther(deadid, killerid, msg)

 

Triggers when someone nearby is killed or commits suicide.

 

ACMsg_OnDeathSelf(msg)

 

Triggers when you are killed.

 

ACMsg_OnLocChangeSelf(landblock, x, y, z, heading)

 

Triggers when the server updates the client with current location information.

 

ACMsg_OnLogon(id, name, health, stamina, mana)

 

Triggers when you log a character in.

 

ACMsg_OnObjectCreate(ObjectName, ObjectID)

 

Triggers when an object is created.

 

ACMsg_OnSpellCastSelf(SpellID)

 

Triggers when you successfully cast a spell.  SpellID list can be retrieved from spell.mdb database.

 

ACMsg_OnSpellExpire(SpellID, Layer)

 

Triggers when a spell expires.  Either when a casted spell expires, or when an activated arcane item is removed.

 

ACMsg_OnSpellFailSelf(Reason)

 

Triggers when you fail at casting a spell.

 

ACMsg_OnTargetHealth(ID, Health)

 

Triggers when the server sends the targets current health.  ID is that of the target.  Health is a percentage between 0 and 1.

 

ACMsg_OnTell(from, msg, srcid, destid)

 

Triggers when someone sends you a tell.

 

ACMsg_OnTellFellowship(from, msg)

 

Triggers when you or someone in your fellowship uses fellowship chat.  From is blank when you use fellowship chat.

 

ACMsg_OnTellFollower(from, msg)

 

Triggers when a follower uses @m.

 

ACMsg_OnTellPatron(from, msg)

 

Triggers when your patron uses @v.

 

ACMsg_OnTellVassal(from, msg)

 

Triggers when your vassal uses @p.

 

ACMsg_OnTradeAccept(id)

 

Triggers when a trade is accepted.  Id is that of the person accepting the trade.

 

ACMsg_OnTradeAdd(id, side)

 

Triggers when an item is added to a trade window.  Id is the guid of the item and side = 1 or 2 indicating the side the item was added to.

 

ACMsg_OnTradeEnd(reason)

 

Triggers when a trade is ended.  Reason is 0x00 for successful trade, 0x02 if either party entered combat mode, or 0x51 if either party moved out of range or canceled trade manually.

 

ACMsg_OnTradeReset(id)

 

Triggers when either party clears the trade window.  Id is that of the clearee.

 

ACMsg_OnTradeStart(initid, receiveid)

 

Triggers when a trade window is opened.  Initid is the id of the person starting the trade, receiveid is the id of the person receiving the trade.

 

ACMsg_OnVitals(health, stamina, mana)

 

            Triggers whenever the client receives an update pertaining to the characters health/stamina/mana.

 

The Inventory Object

 

Methods

 

inventory.MoveItem(ItemID, Pack, Slot, StackCount)

 

Moves item specified by ItemID to the location specified by Pack and Slot.  Both Pack and Slot are 0 based.  If only a portion of the stack of items is to be moved, that portion can be specified by StackCount.

 

inventory.UseItem(Item1ID, Item2ID)

 

Uses item specified by Item1ID on Item2ID, or simply uses Item1ID if Item2ID is specified as 0.

 

Properties

 

inventory.GetItem(Pack, Slot)

 

Returns the ID of the item in Pack at Slot.  Pack and Slot are 0 based.  If no item is found a –1 is returned.

 

inventory.HaveAny(ItemName)

 

Locates and returns the number of items in a stack of ItemName found in the inventory collection.  This may not necessarily locate the items in the order in which they appear in your inventory.

 

inventory.HowMany(ItemName)

 

Returns the number items(including stacked items) of ItemName located in entire inventory.

 

inventory.ItemsInPack(Pack)

 

Returns the number of items in a pack specified by Pack.  Pack is 0 based.

 

inventory.NumberOfPacks

 

Returns the number of packs including the main pack.

 

The Spell Object

 

Methods

 

spell.Cast(SpellID)

 

Casts spell with ID SpellID.  A complete list of spells and their IDs can be found here.  Spell must be learned and valid target must be selected before calling Cast.

 

Properties

 

spell.CastResult

 

Returns a value indicating result of last attempted spellcast.  Value is 0 for failure, 1 for success, and –1 if no attempt has been made at casting a spell since ac.SpellCastResult was last called.

 

spell.EnchantedWith(SpellID)

 

Returns a Boolean value which indicates whether or not the spell with ID SpellID is currently in affect on the player.

 

spell.Enchantments

 

Returns a visual basic array containing the id of every spell currently in affect upon the character.  Duplicates can exist due to spell layering.

 

spell.IDFromName(SpellName)

 

Returns the ID of spell named SpellName.

 

spell.NameFromID(SpellID)

 

Returns name of spell with ID SpellID.

 

spell.TimeRemaining(SpellID)

 

Returns an integer representing the time(in seconds) remaining before the spell specified by SpellID will expire.  Returns 0 if the spell is not in affect.  Returns –1 if the spell is being maintained by an arcane based item.  Currently not 100% accurate, but will be improved in the future.  Still quite usable as discrepancies I’ve noted seem to be within the 10-20 second range.

 

 

 


 

End User License Agreement

 

1.      The owner of this software grants all users use of this software free of charge.

2.      This software package may not be redistributed except in its original installation package without written permission from the software’s owner.

3.      No user may accept gifts or payment(monetary or otherwise) for services rendered by or through this software without written permission from the software’s owner.

4.      This software is distributed without warrantee of any kind. Neither the authors nor distributors of this software are responsible in any way for any failures of this software to perform as expected, or for any damage incurred by running this software.

5.      This End User License Agreement may be modified at any time without direct notification of the end user.  An up-to-date copy will be maintained on a site of the owner’s choosing.