Prerequisites

Basically, what you need to have is patience, and your AoM installed. This guide will be for both AoM and AoT as the XS is 99.98% the same.

You don't need to have any programming skills whatsoever - we will start of with the very basics.

Learning XS can be frustrating, and you'll learn a lot of things that alone won't do anything. Only the combination of everything you know allows you to create\develop\invent new things.

However this shouldn't discourage potential XS Scripters as once you have learnt the basics and get used to the language, you'll find extremely easy to produce code.

Therefore, we want to invite everyone one to join in, and feel free to ask any questions. .

I hope you enjoy this initiative, and start learning XS as we go along.
-invent00r

[This message has been edited by invent00r (edited 07-30-2008 @ 06:57 PM).]

Configuring AoM

The first thing we will be discussing today is how to properly configure AoM in order to reach it's full scripting potential. I'll try to explain everything as clear as possible, although I expect you to have some basic computer knowledge (as in browsing to certain folders, creating new files etc.). To start I'd like to make some basic naming conventions so we can clearly understand each other. The path where AoM is installed on your computer (usually C:\Program Files\Microsoft Games\Age of Mythology) will be called the AoM (root) folder, and the other AoM:TT folder (My Documents\My Games\Age of Mythology) will be referred to as the my games folder. Furthermore I assume that you have a clean version of AoM (and/or TT) installed. If you have any mods installed, that's your own responsibility. Another thing: usually when we refer to certain files, we will only mention 1 name, and it is up to you to find out what we mean depending on the version of the game you wish to use (AoM vs. AoT). For example: if we refer to the "ai" folder, know that for AoT you will need to go to the "ai2" folder, if we say "aomx.exe", know that we're also talking about "aom.exe" if you play vanilla. Sometime we will be nice and put "trigger(2)" for example, again: "trigger" for AoM vs. "trigger2" for AoT. It's pretty straight-forward most of the time, but if it's very unclear we will mention it explicitly. Another useful tip: go to menu bar -> extra -> folder options -> view, and enable "Hide extensions for known file types". This will make windows show all file extensions (the part behind the last dot), so we don't get in trouble with incomplete file names. Finally, if I say "open file X", and you are not sure what program to use to open it, use notepad for now. In part 3 invent00r will give you some advice on better text editors.

The single most important thing you'll be needing if you ever want to do some AoM scripting or modding, is the console. It's a development utility in the game that allows you to execute some basic commands on the fly (i.e. without the need of a script). In order to enable this we will need to modify some game files. First, navigate to your AoM folder\startup folder, and there create a file called user.cfg (as an empty notepad document). It doesn't exist by default, but could possibly already be there if you did any kind of scripting and/or modding before. For those who are wondering what all those CFG files are: they are the ConFiGuration files of age of mythology, that contain the command line options (also called configs) for the game. You will learn more about them later on. The word command lines derives from the time DOS was still around, and people used to start programs from the command line. There, they added optional statements after the path of the program. Anyone who ever worked with the command prompt still included in recent windows versions will know what I'm talking about. Nowadays these options can still be added to the so called command line by adding them to the properties->target box of a shortcut to the aom(x).exe file. Obviously adding them to a separate file is far more convenient if you wish to work with multiple configs.

Once the user.cfg file is created, open it with notepad and add the following lines:

+noIntroCinematics // skip the start-up movie, to increase start-up speed - you will need it
+Enableconsole // enables the console
+developer // grants some more access to certain game options
+debugRandomMaps // this will be needed in our RMS chapter
+aiDebug // this will be needed for general coding purpose
+aiShowBPValueText // will be told about later
+showAIEchoes // this will be needed for general coding purpose
+showAIOutput // this will be needed for general coding purpose
+logAIErrors // this will be needed for general coding purpose

Save and close the file. Now we'll move on to the gamex.con file. Once again a CONfiguration file, but this time it contains a list of console commands that will be executed as soon as the game is loaded. By default it's only used to initiate the basic hotkey mappings, but it can potentially be used for other things. More on that later. For now just add these lines at the end of the file:

map ("alt-q", "root",       "AIDebugInfoToggle()")                  //open/close AI menu
map ("alt-w", "root",       "uiShowAIDebugInfoKBUnit()")            //open Unit Debug Dialog
map ("alt-e", "root",       "gadgetToggle(\"XSDebugger\")")         //open XS Debugger
map ("alt-e", "XSDebugger", "gadgetUnReal(\"XSDebugger\")")         //close with same key
map ("esc",   "XSDebugger", "gadgetUnReal(\"XSDebugger\")")         //close with esc
map ("alt-r", "root",       "configSet(\"showConsole\") console()") //open console with ctrl+alt+F5
map ("alt-r", "console",    "console()")                            //close again with same key
map ("esc",   "console",    "console()")                            //or close with esc
map ("alt-d", "game",       "leaveGame()")                          //quick key to leave game, saves some time while testing
map ("alt-d", "root",       "dropToMainMenu()")                     //return to main menu anywhere but in game
map ("alt-f", "game",       "restartCurrentGame()")                 //quick key to restart game

You can go try these at once. To activate them, simple (re)start AoM. We will explain every tool at the appropriate time.

At this point we made all necessary changes, but there are some things we can do to clean up our AoM installation. Navigate back to your AoM folder, and doubleclick on "ai(2)". There, create a new folder called "backup", invent00r will certainly mention this folder again the next article. In the backup folder you should create another folder called "cpn". In there we will store all campaign AI files that clutter up the main AI folder. So go on and move all files called "scnxx(px).xs" (where x represents any number) to the new cpn folder. This will disable the campaign, but you probably don't play it anymore. Back in the ai folder, create another new folder called "docs". This will contain some AI specific documents that you might need to consult if you forgot something. We'll cover that later. You might want to create backup folders in the "trigger", "rm" and "startup" folders too, for your own convenience.

That's all for now, a new article by invent00r will follow soon!

Last update: august 2, 2008

[This message has been edited by Mythic_Freak (edited 08-02-2008 @ 09:27 AM).]

Programs and Tools

Now that you have your AoM well prepared, it's time to add some extras in order to achieve excellent code with no effort. It is therefore important to have a good text editor - not a word processor. This means that your fancy MS Word\Open Office Writer will not serve the purpose, and it might very well be counter-productive. Using notepad works, but is completely unoptimized to what we are going to do - programming.


Text Editors

---

I suggest the following tools, sorted by preference:

1. EmEditor - Excellent editor with a lot of goodies and very customizable. Sadly it's shareware.
   
2. PSPad - Good editor. Freeware, however it's a bit old. (Latest version is over 250+ days old).
   
3. Notepad++ - Very popular choice. Also Freeware.
   

EmEditor

---

This is the program I use. It's simple, really fast, and it's very user-friendly. Well.. But that's just my opinion. I recommend you at least trying out. Even tho this is shareware, when the trial expires you can randomly type a serial number and maybe you got a valid one and find yourself with a valid registered EmEditor. If not, you can click Ok and continue using the program - you have to repeat this each time you turn on your PC tho. So instead of being exactly shareware, it becomes nagware - it will keep reminding you that you may need to buy it.

Anyways, let's explorer this editor.
First of all, download the latest EmEditor - you probably have a 32 bit OS so you can just click the 1st link.
When installing, be sure not to deselect Plug-ins as they are extremely needed.
Open it up. First of all, right click under the main toolbar, and deactivate Tools and Macros. (Tools are just a bunch of shortcuts; Macros are not really necessary so you can remove them from the toolbar). Once you finished rearranged, lock up the toolbar.
Now you need to download this file (EmEditor_AllConfig.zip). (Open it and extract to your desktop area - you will erase it after you're done with it). Don't open up the file - there is no need to do that directly. If you don't know how to download and extract the file, just select & copy the url:

http://invent00r.googlepages.com/emeditor_30_07.reg

Go back to EmEditor and press Alt, T, X. This should bring up the Import and Export Wizard. Choose the 3rd option and select the file you've just downloaded or just type in the url. Now you have a new language in EmEditor - XS. .

Now up in the Plug-ins bar open up the Projects Plug-in. This is a very handy explorer-like feature, except you select which folders exists, and which files are to be included on them. You should create 2 Projects right now. One called AI, and save it under your AI folder, the other called Triggers, and save it under your trigger folder. You can add typetest.xml to that trigger project right away.

All in all, EmEditor is a comfortable editor to work with. So try it out.


PSPad

---

PSPad is a one-guy developed text editor. As such, releases tend to be very slow and it has remained without any updates since its last stable version - which was 250+ days ago. However, the latest beta build was released just yesterday so it just goes to show that it's still active.
PSPad is completely free and full of options. It also has word-complete and projects bar.

I don't have any specific config file for you, so you need to just use the default C++ syntax highlighter.

To do this, navigate through Configurations > Configurations of Highlighters> C/C++. Now click on the Filter tab and add a new line with *.xs.


Notepad++

---

Now we have the one of the most popular choice - even so that someone has uploaded to AoMH Downloads section, but I'll not link you there as it can be a outdated version.

It's very cross-plataform so that's a good thing and it's 100% free like PSPad.

Same as PSPad here - just use C++ highlights. Navigate through Settings > Styler Configurator.. > C++. Now add xs and Save & Close.

---

After you chosen your program, you need to set up a back-up folder. Each editor is different, but I'll just explain EmEditor since it's a tricky one: F11, D. Select XS. Click Properties then Backup tab. Now just select the 1st and the last options, and select your backup folder.

Curiosity: Game_Designer is currently working on some sort of Editor specially for AoM. But he is still in the very beginning stages so the future is very unknown.

Tools

---

There are a few tools that you must have to manipulate AoM:

1. References
   
2. AoMEd
   
3. xTrigger.xs
   
4. Proactive Triggers

References

---

The most value asset when it comes to programming is the Reference file - this contains all pre-programmed functions that we can use.
Functions is a subject that will be discussed on the next chapter so for now, just donwload the reference files and store them inside your AI folder or create a new specific folder for them. .


AoMEd

---

This is probably the latest version of the best modding tool there is for AoM. Tho we aren't going to be using it, it's important for you to know that exists and to know how AoM parses files.
AoM has certain files that go by the extension of .xmb, these are compressed versions of the readable .xml. If there's an xml file available, AoM will parse it and output a new xmb file. If there isn't any xml files, then it will just read the xmb file directly - so xml files > xmb files > bar files. Now bar files are just a bunch of .xmb files in one, so there isn't much science into that.

If, for some odd reason, you have a syntax error in one of your xml files (for example the typetest.xml file after you quickly edited it) AoM will not read the old xmb file, instead it will simply fail and dismiss that file.


xTriggers.xs

---

This is a file I made for trigger debugging purposes only. It will be explained how it works later on. For now, just download it by right clicking on the link and using Save Linked Content As - place it under your AI folder.


Proactive Triggers

---

You may say I'm just shamelessly promoting my triggers - not that I'm not -, but it does have XS Code 6 which is something you'll very much need.
For this reason, install the Pro version of the pack and enjoy the goodies .

---

Now we are fully ready to move on to the next chapter - XS Basics. Mythic_Freak will suffice.
-invent00r

Last update: august 30, 2008

[This message has been edited by invent00r (edited 08-30-2008 @ 03:18 PM).]

This is awesome guys

Good luck

Good luck I'm hoping I can make cenamics through this :P

Thanks for supporting this Roxas and Survivor Fo.

-invent00r

Sounds very beneficial to for people who wish to learn XS like me.

Please, keep up the good work.

Thanks rjs23, I just added part 2.

This is all good stuff.

Quick question, i think it was capn_kidd who did the first (or second AI) guide, and in his was you pressed alt+shift+d to open something....what was that something?

Captn_Kidd uses that bind to pop up the XS Debugger.

Personally, I use it to. But we think it's better if people get used to use all alt-something bindings for all debugging needs. .
-invent00r

Sigh*.. That was a lot of text! .
But I've finished writing my part thus, concluding this chapter.

Mythic_Freak will be creating the next thread hosting the XS Basics - there we will start the actual programming. .
-invent00r

This is great .

OOI i guess programs like visual basic or visual studio can be used for XD editing too right?

Well yes. They are also text-editors aimed towards programming.

If you're already used to them it's ok. If they support C++ syntax, even that's even better. .
-invent00r

very good. thank you for providing a good xs tutorial as i am on the way to understand it. can't wait for the next chapter of your lecture.

Is their a way to make random numbers easily?

The only way I can think of to partically do it ingame would be using a milisecond timer plus a division where you get the remainder.

@:nottud
This isn't exactly the place to ask. -.-. You should probably even created a thread just to discuss this. .

Anyways, assuming you're refereing to AoM and not AoT, I have came up with 2 possible ways for to solve it offline:

1. Using the kbGetRandomEnabledPUID() function - which sadly only works if an AI is working on the background. Since the player 1 is the one that is running the AI, there is no easy way to share the random number generated.
   
2. Using %u. This is an unsigned integer, in decimal which is random. This serves the purpose however it isn't synced with the other players so it doesn't work online.

As for online, there is one method presented by someone else. It works but it will take about 4 seconds.
-invent00r

This is a great effort being put out. I wish I had more time for AOM so that I could possible contribute, but I can point one thing out:

In the AOMED section you said:

AoM has certain files that go by the extension of .xmb, these are compressed versions of the readable .xml. If there's an xml file available, AoM will parse it and output a new xmb file. If there isn't any xml files, then it will just read the xmb file directly

As I remember, it won't compress an XML into an XMB file if the matching XMB already exists. You have to delete the XMB file to force AOM to rebuild the XMB file. This is an important point to people editing their trigger XML file and wondering why the new changes aren't taking effect.

For me changes to the xml file take effect without deleting the xmb. Maybe AoM checks the "last modified data" of the file, and does the conversion of the xml file is newer.

I'm not sure though.

AoM will always parse .xml whenever they are available unless, as Mythic_Freak stated, the file remained untouched.

Anyways, not all xml files are parse right at the start of the game. Some are only used when you access certain parts of the game, such as the Editor. That will parse all editor related files once you've entered it. If you exit it and reenter, then it will also be reparsing.

This doesn't happen with the files that are loaded once the game starts - including all the trigger files.

If you ever get some more AoM time then we would be glad to let you write a article about any subject you feel good at. .
-invent00r

I've always had it where if I edit the nottud.xml trigger file and do not delete nottud.xmb, the changes I made won't take effect and all I have to do to fix it is delete the nottud.xmb file. I ended up writing a test.bat batch file that deletes nottud.xmb, then runs aomx.exe so I wouldn't forget..

I'm sure there's a config out there to make AoM load the xml files without generating xmbs...

loadBinaryXML: attempts to binarize and load XML files in that manner 

Hmm... maybe if we disable that..?

I dont mind that it will use and xmb if it is available and if not rebuild it from the xml file. Forcing it to load xmls everytime will probably slow loading down a bit.

This has already helped me a bit... no more beginning cinematic, YAY!

This has already helped me a bit... no more beginning cinematic, YAY!

http://aom.heavengames.com/faq

@:Elrich
I feel that performance wise, the difference is so small you won't really feel it.

@:firepox
That will hardly help him at this point.

-invent00r