[RELEASE] Jawq (WQ bot for PWI)

[Shareen]

Jawq (Just Another World Quest) bot is, as the name suggest, another wq bot.

I first started on this way back when the patch for PW was released and 7 new wq NPCs were added, since Interest07's bot no longer supported those.
While working on it, AlainProvist released updated version to support that patch and I put mine on the back burner.
After a while though, as I had a different design in mind, I picked up where I left off and eventually managed to finish it. Sort of.

Download link: , v1.0

Known "eye candy" issues, in order to limit number of offsets needed (and to save you from having to hunt them down ... offsets, not issues ):
- npc dialogue does not close after interaction - It does not affect quest progression or interfere with operations in any way, so no code was put in place to manipulate dialogue windows.
- dashed line indicating travel path always points to upper right hand side of map - again, it does not affect the actual travel direction.

The general guidelines for Jawq were these:
1. build wq logic in a language that majority of people here understands and can follow (AutoHotkey), it'll be open source so people can modify it.
2. build game interface in a language that is fast and can be compiled into dll (thus hidding "complex scary" implementation details from plain users)
3. be able to run wq mission on multiple clients at the same time (who doesn't multi box these days )
4. low computer resource usage
5. try to take as little time as safely possible to finish the mission (fly at altitudes lower then maximum, run across short distances rather then fly and waste time, ie,. vol6->vol7, vol22->vol23)

Some more bla bla ...

 Spoiler

If I'm honest, even before starting, I didn't have high expectations from AHK, past experiences with it have taught me well.
I did some initial dll calls, made a process scanner (code for which I shamelessly stole from Interest07's bot) and then I came to NPC and quest list "problem".
I wanted arrays, but back then AHK didn't have them, so I figured might as well check some newer versions.
To my surprise, AHK authors not only added arrays, but classes as well as objects. I saw them right there in docs, but I wasn't going to be lured in that easy, no, not until I try it my self.
So I did.

By the time the initial excitement subsided, I had already converted majority of the code into something resembling object oriented approach. At least to the degree AHK offered.
I couldn't stop now, it just got fun! How far can I push this, what else can it do?

Fast forward to today. It took way more time I'm willing to admit, to get it to this point and I decided to publish it.
Not that anyone needs another WQ bot, but for the same reasons Interest07 posted his: It's done, it works, might as well be useful to someone else.

Introduction .. of sorts

 Spoiler

Bot should work with every version of PW, assuming proper offsets are provided. It comes with offsets set to PWI, at the time of this post.

Jawq uses a dll to interface with PW game and AHK code to provide logic for the bot.
AHK code is available as full source code and, appart from Struct.ahk and sizeof.ahk that weren't written by me (author and links are at the top of those files), is free to distribute and modify.
You don't need to ask me for permission and you are free to take whole or parts of the code and use it as your own. Hell, you can repack and sell it for all I care.

Dll hooks the game and provides information back to caller in two ways:
1. return value of a function call
2. windows messages

Later is used for implementing events like functionality and is really at the core of how Jawq works.

How dll is used (and can be used) is fairly straightforward from AHK code, but if there are any doubts feel free to ask. In the unlikely event of question flood regarding dll, I can provide a detailed documentation for it.
IMPORTANT: Dll is compiled as 32-bit library, so you CANNOT load dll into programmes compiled for 64-bit systems.

I should point out I do not intend to provide continuous support for this bot. It's logic is open source, change what you don't like.

Jawq requires administrative privileges and if it's not run with them, it will attempt to relaunch it self as administrator.
If UAC is enabled on your system, you will receive a confirmation dialogue, like you would if you'd run it with admin rights. Obviously, you need to click ok or it won't work.

If ran as raw script (not compiled):
- On 64-bit systems, it will attempt to relaunch it self with 32-bit Unicode interpreter.
- On 32-bit systems, it will attempt to relaunch it self with 32-bit Unicode interpreter, if it detects that 32-bit ANSI interpreter is running.

If ran as compiled exe:
- On 64-bit systems, if it was compiled using 64-bit .bin file, it will throw exception upon failing to load PwInterface.dll
- On 32-bit systems, if it was compiled using 32-bit ANSI .bin file, it will report error upon startup, notifying you that it requires to be compiled as Unicode.

Compilation instructions:
- Regardless of OS, select Unicode 32-bit .bin file!
- If compiled on 64-bit systems (windows 7 tested), exe will run normally on 64 and 32 bit systems.
- If compiled on 32-bit systems (windows XP tested), I've experienced random crashes when attempting to run it on 64-bit windows7. Setting compatibility mode to windowXp solved it. Problem arises from Ahk2Exe, so none compiled scripts are NOT affected.
- If in doubt, use 64-bit windows 7 to compile, but again: make sure you select 32-bit Unicode .bin file!


How to: Setting up and using [Dummies/Kids users]

 Spoiler

- Download Jawq.rar
- Unpack to whatever location you like
- Check (modify if required) offsets file (Jawq.ini) located in root folder
- Make sure you have AutoHotKey installed. Get it from . Note: AutoHotkey is NOT required if you use compiled version

Run Jawq.ahk to start bot. (Jawq.exe if using compiled version)
If you had PW already running (and character logged in), bot will populate with characters logged inside clients it finds.
If not, you can populate bot with characters by starting PW, logging in and then clicking "Rescan" button. This can also be used to add new characters, when you log them in game later. Note that characters below level 70 will not be displayed.

Clicking "Start" button at each of the character name will start wq mission for that character.
If you don't want to start mission for a specific character that has been added in bot, simply click "Remove" button to remove it. Clicking "Rescan" button will add it back, should you change your mind at a later time.

How to: Setting up and using [Generic users]

 Spoiler

Download Jawq.rar and unpack. Sort out offsets shit if you need. Run Jawq.ahk. Controls are self explanatory.

How to: Setting up and using [Leet users]

 Spoiler

... <crickets> ...

How to: Setting up and using [Typical users]

 Spoiler

See Generic users first.

If AHK version check error comes up, ignore and close it. Run bot again. Ignore error again. Run again .. ignore error .. again.
Come cry to forums. Claim there was no error. Promise to provide screen shots to prove there was no error.
Notice the error while making screen shoots. Decide to download newer AHK version. Let forum users know this is stupid. While waiting for AHK to download, entertain the idea of editing screen shoots to remove error.
Install AHK. Run bot. Find 20 things wrong with it in 2 seconds flat. Post findings on forums. Using all upper case letters. Ignoring spelling and grammar.
Return to forums 3 minutes later. Complain why it wasn't fixed yet. Add 10 more things you found wrong with it. Make sure everyone knows you can do a better job.
Notice 2 posts from people that like the bot. Tell them they are stupid.
Log into twitter and facebook and share your hard life with other would be listeners. Ban few for telling you to "grow up". Threaten others.
Log back into forums, ...

... or, just don't use it. Please.

How to: Offsets [and the rest of Jawq.ini]

 Spoiler

People are used to it, so I went with "established" approach from Interest07's wq bot.
Offsets are located in file called Jawq.ini and are more or less same ones you'd need for wq bot, with some differences in names.
Here is detailed description of Jawq.ini and how entries map to wq.ini from Interest07's wq bot:

Jawq.ini	wq.ini	Section	Description
GameProcessName	N/A	main	Process name under which PW client runs. value type string possible values N/A default elementclient.exe
LogMode	logActivities	main	Logging of characters actions, one file per character. value type numeric possible values 0 = disabled, 1 = enabled default 0
LogPath	N/A	main	Path for logs inside Jawq root folder. value type string possible values OS allowed directory path, must end with slash default logs/
DelayOnError	N/A	main	How long to wait on certain errors, before retrying action that caused the error. value type numeric, msec possible values 50+ default 5000
MaxErrorRetries	N/A	main	How many times to retry action that resulted in error last time it was called. value type numeric possible values 0+ default 5
AnimateRemove	N/A	gui	Animates window resizing when removing characters that aren't first on list (2-n). value type numeric possible values 0 = disabled, 1 = enabled default 1
CallSendPacket	SendPacketAddress	offsets	Function in game that is used to send packets as if it was done by game. value type numeric possible values all, prefix with 0x if using hex notation default 0x006B4220
CallIsQuestAvailable	questFunctionAddress	offsets	Function in game that is used to check for availability of quest. value type numeric possible values all, prefix with 0x if using hex notation default 0x007966B0
BaseAddress	realBaseAddress	offsets	Start of memory chain from which all other data is read. value type numeric possible values all, prefix with 0x if using hex notation default 0x00BBC26C
BaseOffset	baseOffset	offsets	Node 1 (from BaseAddress) of memory chain. value type numeric possible values all, prefix with 0x if using hex notation default 0x1C
PlayerStruct	playerOffSet	offsets	Node 2 (from BaseAddress+BaseOffset) of memory chain that brings us to player structure. value type numeric possible values all, prefix with 0x if using hex notation default 0x34
PlayerId	N/A	offsets	Node 3 (from BaseAddress+BaseOffset+PlayerStruct) of memory chain, field player id in player structure. value type numeric possible values all, prefix with 0x if using hex notation default 0x480
PlayerLevel	N/A	offsets	Node 3 (from BaseAddress+BaseOffset+PlayerStruct) of memory chain, field player level in player structure. value type numeric possible values all, prefix with 0x if using hex notation default 0x48C
PlayerName	playerNameOffset	offsets	Node 3 (from BaseAddress+BaseOffset+PlayerStruct) of memory chain, field player name in player structure. value type numeric possible values all, prefix with 0x if using hex notation default 0x674
PlayerTransportMode	playerTransportModeOffset	offsets	Node 3 (from BaseAddress+BaseOffset+PlayerStruct) of memory chain, field player transport mode in player structure. value type numeric possible values all, prefix with 0x if using hex notation default 0x688
PlayerFlyMountId	playerFlyMountOffset	offsets	Node 3 (from BaseAddress+BaseOffset+PlayerStruct) of memory chain, field player fly mount id in player structure. value type numeric possible values all, prefix with 0x if using hex notation default 0x598
PlayerPositionX	playerXposOffset	offsets	Node 3 (from BaseAddress+BaseOffset+PlayerStruct) of memory chain, field player position x in player structure. value type numeric possible values all, prefix with 0x if using hex notation default 0x3C
PlayerPositionZ	playerYposOffset	offsets	Node 3 (from BaseAddress+BaseOffset+PlayerStruct) of memory chain, field player position z (altitude) in player structure. value type numeric possible values all, prefix with 0x if using hex notation default 0x40
PlayerPositionY	playerZposOffset	offsets	Node 3 (from BaseAddress+BaseOffset+PlayerStruct) of memory chain, field player position y in player structure. value type numeric possible values all, prefix with 0x if using hex notation default 0x44
PlayerTargetId	playerTargetIdOffset	offsets	Node 3 (from BaseAddress+BaseOffset+PlayerStruct) of memory chain, field player target id in player structure. value type numeric possible values all, prefix with 0x if using hex notation default 0xC20
PlayerFreeze	N/A	offsets	Node 3 (from BaseAddress+BaseOffset+PlayerStruct) of memory chain. Can player move or is "frozen in place" due to dialogue window being open. value type numeric possible values all, prefix with 0x if using hex notation default 0xC3E
PlayerQuestInventory	N/A	offsets	Node 3 (from BaseAddress+BaseOffset+PlayerStruct) of memory chain, points to Node 4: player quest inventory. value type numeric possible values all, prefix with 0x if using hex notation default 0xDC8
PlayerAction	playerActionStructOffset	offsets	Node 3 (from BaseAddress+BaseOffset+PlayerStruct) of memory chain, points to Node 4: player actions. value type numeric possible values all, prefix with 0x if using hex notation default 0x1204
PlayerQuestList	questFunctionOffset	offsets	Node 3 (from BaseAddress+BaseOffset+PlayerStruct) of memory chain, points to Node 4: player quest list. value type numeric possible values all, prefix with 0x if using hex notation default 0x120C
ItemId	N/A	offsets	Id of quest item in quest list. value type numeric possible values all, prefix with 0x if using hex notation default 0x08
Lists	baseListsOffset	offsets	Node 1 (from BaseAddress), points to start of lists. value type numeric possible values all, prefix with 0x if using hex notation default 0x1C
NpcList	npcListOffset	offsets	Node 2 (from BaseAddress+Lists), points to start of npc lists. value type numeric possible values all, prefix with 0x if using hex notation default 0x24
NpcSortedList	sortedNpcListOffset	offsets	Node 3 (from BaseAddress+Lists+NpcList), points to start of sorted npc list. value type numeric possible values all, prefix with 0x if using hex notation default 0x50
NpcId	npcIdOffset	offsets	Node 4+5[ArrayIndex] (from BaseAddress+Lists+NpcList+NpcSortedList+[ArrayIndex]), points to start of npc structure. value type numeric possible values all, prefix with 0x if using hex notation default 0x124

How to: NPCs and way-points [or "what the hell is lib/npcs.ahk"]

 Spoiler

The way bot works is it reads quest inventory of a character to find quest item id. Using this information it looks up which NPC it needs to go to in order to continue the quest.
npcs.ahk contains this look up list, that provides information on:
- which NPC is next on the list
- where it is (location)
- how to get to it (actions, way-points)
- what to do once character gets there (actions)

To explain on an example:

; Volume 01
npcs[14031] := new TNpc(4436, "Tailor Fang Pei", "Volume 1", 8348)
npcs[14031].addAction("flyUp", 230)
npcs[14031].addAction("flyTo", 1228.501, 240, 984.691)
npcs[14031].addAction("land")
npcs[14031].addAction("interact")

Assuming quest item has an id of 14031, npc Tailor Fang Pei would be next to visit.
To get there, character needs to first fly up (vertically, to an altitude of 230 - in game 23), then fly to location x:1228.501, z:240(altitude), y:984.691.
Once there, it needs to land and begin interaction with that NPC. Interaction consists of:
- target NPC (in above example with id 4436)
- talk to NPC (open dialogue)
- exchange quest (in above example, this would be quest with id 8348)
- unlock target
- unfreeze character (so it can move again)
- check quest inventory for new quest item id

It then looks up a new NPC according to quest item id received and continues until WQ mission is completed.

Another somewhat different example would be this one:

; Volume 34
npcs[37016] := new TNpc(29056, "Valiant Avatar", "Volume 34", 27992)
npcs[37016].addAction("flyUp", 300)
npcs[37016].addAction("flyTo", -2856.685303, 360, -2936.108154, 1061.125244, 360, -3517.101074)
npcs[37016].addAction("land")
npcs[37016].addAction("interact")

You will note that flyTo action has not one, but two locations specified. These are allowed with any flyTo action and they act as a secondary way-point in case the path that first one forms (between your current location and first way-point) is blocked. If blocked, it uses secondary way-point and, after reaching it, uses first one to reach original destination. Think of secondary way-point as a "go around" way-point.
It is only used to bypass blocked land (impassable terrain at the bottom right of map), but more obstacles can be added into obstacles.ahk file if you wish.

Definitions in obstacles.ahk are used to define what is "blocked" and part of code executing flyTo action, checks if path currently in place is blocked by anything defined in obstacles.ahk.

For a full list of available actions see npcs.ahk in lib folder.

How to: Error fail-overs

 Spoiler

In theory, all errors are just that, errors indicating error conditions that normally shouldn't occur.

In practice however, not all can or should be treated that severely. A good example would be ER_STOPPEDBEFOREDESTINATION.
It's an error yes, but not necessary an error condition: Character can be stopped by a number of reasons, such as hitting an impassable object (collision), stopped by user or stunned by a monster.
If collision occurred or user interfered, it is indeed an error condition and thus not recoverable, but likelihood of this is low.
A monster's stun, however, is temporary and does not constitute unrecoverable condition. Indeed, once stun effect wears off, we can be back on our way.
This is implemented with the use of so called fail-over or error retries.
Upon start up, every character has a fixed number of error retries, defined in Jawq.ini as well as a time delay between retries.
If error, such as ER_STOPPEDBEFOREDESTINATION occurs, bot assumes it's a recoverable one and will retry last action after DelayOnError (Jawq.ini) time elapses. It will attempt to retry MaxErrorRetries (Jawq.ini) until finally giving up and conceding to the fact it might have been unrecoverable error after all.

For a full list of errors and other constants see lib/constants.ahk

How to: DLL results and errors

 Spoiler

I'm a strong believer in error handling, error notices, error codes, etc...

Unfortunately, my beliefs start to waver quickly when it's time to implement that. I'd like nothing more than to say I did my best to provide error support and notices, but that'd be a lie. Truth is I did my best that my inherent lazy personality allowed.
When it comes to errors (and return values), points of interest are these:

1. All dll call results are application related results. What that means is you either get True (0) or error (>0), but values are always application related (See lib/constants.ahk for more details on those). It does NOT return any windows errors, see point 2.

2. All dll functions, when called, CLEAR LastError, that is, they set it to 0. LastError is a windows variable that holds the error (or 0 on success) of last windows API call. For example, if you make a call to VirtualAllocEx and an error occurs, LastError is set. AHK automatically calls windows GetLastError function and stores the result in A_LastError AHK built-in variable after every dll call. So, if you want to know if some dll call failed, you want to check A_LastError after EVERY dll call or next dll call will clear it.

By checking A_LastError you can determine if the result is valid. Additionaly, AHK "signals" dll failures it can, by setting result of a dll call to "" (empty string). So proper way of checking would be to check result for "". If it's not "", check A_LastError. If 0, check ErrorLevel. If 0, dll call result is valid.
"But that's not what you did", you'll say. Indeed, since majority of errors mentioned above occur due to wrong dll calls, you can rule them out once you get it right. I had those checks there when debugging, but removed them for production code for readability and "some" speed.

The reason I mention this is in case you decide to use the dll in some other language and you want to avoided cases, where you would get a return value of, for example true, from a dll call, despite the fact it failed to make the call properly. Of course, you'll need to handle calls to GetLastError there your self, the above "automation" only applies to AHK.

Please note that classes (even support ones like TForm or TControl) were written with this bot in mind. What that means is they've only been implemented and tested to the point that they support what bot needs. No less, no more. If you want to use them in your own projects, you have been warned.

Bot is version checked (and protected) in that it should only run on AHK version 1.1.09.00 or higher. Version 1.1.09.00 is the version it was developed in, so I know it works on this one.
Does it work on older ones? I don't know. If you'd like to test, comment out lines 2-5 in file Jawq.ahk to remove version protection.
If you get include error at start up instead of version pop-up, your AHK version is WAY too old and you need to update to use Jawq.

What can I say about libraries? Software engineering at its finest they are not. Hopefully, not at its worst either.
Good or bad, they can be found nesting in lib/ folder.

Thanks go to:
- HotKeyIt from AutoHotkey forums for providing a great structure handling library (_Struct.ahk and sizeof.ahk). See those for details.
- Interest07's WQ bot for idea. Oh yeah, I also nicked process scanner from his code, thought I'd mention it
- Swoosh for a code snippet on how to achieve vertical flight. No doubt that saved long hours of trial and error.

Edit 21.06.2013:

[Sᴡoosh]

I want to be far even as decided to use even go want to do look more like!

Great work man.

[Interest07]

Ooph, using AutoHotKey, you *********!

I'll be sure to download when I have the time to look it over AHK went OOP then eh?

[Afro-Head]

That is the best described release i ever see
Great work and Time you spend on this !

[martmor]

Thank you very much. Nice work.

It work fine.

I compiled it with 32 bit Unicode. This way it work on 64 bit machine too.

Sometimes I got at NPCs the Error 6. But I must take a look first which Error this is. One time got the NPC 10 (merchant) removed But now it work since longer time without Errors

[Shareen]

Originally Posted by martmor

Sometimes I got at NPCs the Error 6. But I must take a look first which Error this is.

Error 6 would be "Trying to start dialogue (TalkToNpc) while a dialogue is already open". It checks "freeze" flag for that one and if set, assumes it's becasue dialogue has been openned by someone else rather than bot.

Shouldn't happen under normal operations, did you fiddle with it while it was running?

Originally Posted by Afro-Head

That is the best described release i ever see
Great work and Time you spend on this !

Thank you.

Originally Posted by Interest07

Ooph, using AutoHotKey, you masochist!

I'll be sure to download when I have the time to look it over AHK went OOP then eh?

Yeah, seems they are heading in that direction. I don't know if they just reached a point where they said "right, it's time to go OOP" or pehaps there was some new blood injected into the group, someone keen on raising ahk fame, but either way I rather like it.

Originally Posted by Sᴡoosh

I want to be far even as decided to use even go want to do look more like!

Great work man.

Thanks. I don't know what you are smoking, but I want some

[martmor]

Hi Shareen

I finished now the first Char with your bot. It work great. The bot have a different flight high. As needed between the NPCs. sometimes 55, 60 or 77. Realy nice.

About the Error. No I did not made anything manual. One time I must relogged as the NPC wasn't there. Maybe a bug from PW? Not sure. I will try it tomorrow again.

How do you come to the coordinates like these:

-1715.609, 600, 62.466

They are different from interest07 coordinat system

[Shareen]

Originally Posted by martmor

... One time I must relogged as the NPC wasn't there. Maybe a bug from PW? Not sure.

I had that happen, I think about 5 times (over a period of over 3 years), with various bots.

It never happened when not using bots however, so I assume it's not inherently PW bug.

Originally Posted by martmor

How do you come to the coordinates like these:

-1715.609, 600, 62.466

They are different from interest07 coordinat system

These coordinates are the format used by game client internally, in memory. It's the "real" coordinates, the ones you see in client are derived from these.

Reason I went with these is they allow for much greater precision in setting locations and that could come in handy sometimes.
Say you'd want to use some location as a base and calculate a random offset for landing, so that if running several characters, they wouldn't all land on exact same spot. With “in-game” coordinates +/-1 meter is the same, where as using these, every centimetre counts.

There are probably other scenarios I haven't thought of, but having precision and not needing it is still better, then needing and not having it.

One must keep in mind that .dll can be used to build a different wq bot all together, so things like that could surely be of use.

[Sᴡoosh]

In case you wish to convert the internal coordinate representation that Shareen uses to the ones you see ingame, or vice versa :



Edit : Logically, bot needs the internal X/height/Y memory format though, so anything you change needs to be in this notation also.

[Shareen]

Originally Posted by Sᴡoosh

In case you wish to convert the internal coordinate representation that Shareen uses to the ones you see ingame, or vice versa :



Edit : Logically, bot needs the internal X/height/Y memory format though, so anything you change needs to be in this notation also.

That would work, but note that when converting in-game to d_goto (as it's called there) result is limited in precision.

You could also use bot itself, by calling:

player.getPlayerData()

to get current position and then displaying it from:

player.position.x
player.position.z
player.position.y

Above assumes that player is a TPlayer object and instance is hooked to a client, you'd need to sort that out beforehand.

If this is something you need or want, I guess I can add a few code snippets on how to do it.

[Interest07]

My only gripe with the bot is the messed up x, y, z system it's not x, z, y!!!

But I know that's apparently a popular way of doing things here

[Sᴡoosh]

No, I don't like it either. But PW, amongst many other games, does it like this, so we must adapt.

[Shareen]

Originally Posted by Interest07

My only gripe with the bot is the messed up x, y, z system it's not x, z, y!!!

But I know that's apparently a popular way of doing things here

Really, again with that?

Hehehe, I knew that would get you going.

I had to change something, else people would say I just stole entire WQ bot

[Interest07]

Horrible people, wish there was a downvote for you!

[Stefanowski]

Thanks for really great work here...
One thing: World Quest is only exp/spirit, and not too much of it tbh... Is it even worth doing?