Korsun Pocket AI Scripting Exe Tutorial

SSG have provided Run5 permission to make their Korsun Pocket AI Scripting exe available to the Korsun Pocket Community. This is a special file that is used to program the AI scripts which are generally used by the computerised AI in the opening moves of a battle. The file can be downloaded from the Run5 Files Section.

This file is provided as is and is not supported officially by SSG or Matrix - although should you have any difficulties using it, then just post a message on the Run5 Discussion Forums and Im sure we will be able to sort those difficulties out.

Prior to reading this tutorial it is recommended that you have first read and understand the Editor Tutorial #8 - Programming AI.

At this point in time it is probably worthwhile for us to briefly look at the two forms of AI Programming, Operational AI and Scripted AI. Operational AI is the AI that is programmed from within the Scenario Editor itself. Operational AI is where the Pc makes decisions based upon the Objectives/Regions and Operation cards that have been assigned to it. We covered this in Editor Tutorial #8 - Programming AI.

Scripted AI is where the AI mimics the actual turn of a human player that has been written as a 'script'. This tutorial show you how to create scripted AI.

It is important to understand that Scripted AI is actioned by the Computer before Operational AI is. In fact when you create the operational AI, you must provide instructions to the AI on how it should 'process' and action units that may have been subject to an AI script, after the script has run. More details about this can be found in Editor Tutorial #8 - Programming AI, although understand now that the Operational AI may use units to move or attack at the end of each turn even though they may have been subject to a script. Also note that not all units need to be subject to a script. Units not subject to a script will be processed normally by the Operational AI.

This tutorial has been put together to guide through the use of this special executable scripting tool.

Step 1 is to download the file and unzip it into your ..Korsun Pocket directory.

The sole purpose of this file is to record and program scripted AI moves - it can not be used to play a normal game of Korsun Pocket and presents no other purpose other then that stated previously.

Before we load the file up, let me briefly explain the theory behind the use of this file. This file will allow you to play and replay a PBEM game against yourself. The exe will create the AI script files based your turns in these PBEM games. In other words, the AI scripted moves will be exactly the same as what your moves are in the PBEM game that you start with this exe. When we get around to loading the exe you will notice that some options and buttons are grayed out and not available, for example, you can only move one unit at a time and some actions are unable to be reversed with the undo button.

It is also important to understand that the actual AI scripts are not created until you actually replay your turn from the viewpoint of the opposing forces. For example, lets say I am going to create a new AI script for TAO. Using the AI Scripting exe, I start a PBEM game of TAO against myself. As the germans I move my units and have my first turn. I then end my turn normally and return to the menu, I then select Load Email game and I load the Allied Turn 1, but before I move any units as the allies, I MUST replay the German turn from the Allies perspective. It is the viewing of the German turn replay that actually creates the script files for the previous German Turn.

Ok that's the theory.. lets have a look at this in action! Having downloaded the script exe and saved it to your .. Korsun Pocket folder, double click on the Korsun_Scipting.exe file to run it.

You should then be presented with the familiar looking Korsun Pocket Main Menu screen, as shown below:


Although if you look closely, it is slightly different. All options are grayed out except for Email Game. This is because, as previously mentioned, the script exe is used to play PBEM games against yourself, and it is these turns that you play that form the basis for your AI scripts.

Click on the Email Game option to commence an Email Game and progress to the next screen. The next screen is the standard PBEM config or start up screen:

Because you are simply playing a PBEM game against yourself for scripting purposes, there is no need to enter names and email addresses for each of the Allied and Axis players, so just leave them as they are. Go ahead and click on Accept Email Game to proceed to the Battleset/Scenario selection screen. Select your battle and scenario as you normally would.

When you get to the Game Options screen you will notice that all of the options are grayed out, this is because they have been 'fixed' in place for the purpose of creating these scripts.

Don't worry these settings will not be recorded in the script files. Go ahead and click on Start Game.

Now go ahead and play your turn 1 for the Axis. Everything you do from here on in, until you click on End Turn, will become part of the AI script. Where ever you move a unit, entrench, use extended movement, blow or repair a bridge, take a replacement or place an interdiction marker will form part of the AI script. In other words, everything you do will form part of the AI and will be replicated by in games against the computerised AI.

There are some things which you need to know though, you have to move each unit one at a time, for scripting purposes you can not move a stack of units all at once. Nor can you successfully undo actions, so if you make a mistake, start again! Having said that, you probably want your scripts to be exact and well thought out, so should have no need to undo careless moves!

After you have moved your units then click on the End Turn Button. Note: That you do not have to move or 'script' all units or actions (interdictions or replacements). As we have learnt from previous Tutorials, in particular the one on Programming AI, the Computer is able to use and apply the "operational" AI to units after the turns script has run. If as part of your script you do not move, or give instructions to a unit or an action, then the Operational AI will simply move or process the action at the end as part of its normal operational AI processing.

So for example, it is possible to only create a script for some of your units, and then leave the rest of your units to be actioned by the Operational AI. If you do not want to script a unit, then simply don't move it or give it instructions as part of your PBEM turn.

After clicking on the End Turn Button, you will be taken to a screen to confirm that you want to end your scripted PBEM turn. Click on the Exit and Restart Button.

You should now be taken back to the Korsun Pocket Main Menu screen:

Now you you need to go through the whole process again and load the game from the other sides, the Allied perspective, so go ahead and click on Email Game and proceed to the PBEM Startup Config screen.

This time though the Load Email Game option is active - it is NOT grayed out. That's because your previous turn has now been saved and we are able to load it to commence our PBEM game - but from the opposing sides view. So now click on Load Email Game....

.. and then select your Scripted Save Game and finally click on Load Game.

What you have now done is loaded your Scripted Save Game and you should now be able to commence your first turn as the Allies. But before going ahead and doing that, what we need to do is replay your Axis Turn 1 from the Allied sides perspective. This is a critical step to the creation of your scripted AI, as the actual script AI file is created when you view you the replay.

So go ahead and click on the View Replay Button:

Click on the Play button within the Replay Panel,

And your previous turn should now play out on the screen. As mentioned above, this results in the Axis Turn 1 script file being created. In fact if what happens is as the replay plays out, the Computer should create a file called 'ScriptXAx1' in your ..korsun pocket\ReplayGame. I will explain some more about this file in a moment.

After watching the replay though, go ahead and now have your First Turn as the Allies in the same manner that you did the Axis. When finished click on the End Turn Button and then the Exit and Restart Button, and then go ahead and Start an Email Game again and Load up the next Turn Scripted PBEM Game Turn.

This should now commence the Axis Turn 2. Remember that you MUST watch the Replay of the last Allied Turn so that the Script for the Allies is created. Then go ahead and have your second turn as the Axis, Exit and then load up the next Allied Turn, watch the previous Axis turn in the reply and so on.. continue doing this until you are satisfied that you have scripted enough turns.

Be mindful though that a script will only effectively work for so many turns. In fact depending upon the scenario you may only want to script the first few turns. The reason for this is that as the game progresses and develops the variables relating to the placement of enemy troops increases. For example its no good creating a script for 10 turns that seeks to defend area X, if after the first 5 turns it is clear that the enemy isn't going to attack that area.

Remember that AI scripts mimic your exact movements within a turn. So whilst this can be a very powerful tool and be very effective in some situations - like the opening moves to a scenario (ie: Clearing the Strong points in TAO), it does have some limitations. Those limitations are that scripted AI can not react to unexpected or unplanned for circumstances. As mentioned, 5 turns into a battle its hard to predict or know if an enemy unit is going to be in hex X, Y - and therefore its risky to script an attack in that hex if you can not be confident a unit will be there.

So as a rule of thumb, you probably only want to script the first few turns of your scenario and then let the Operational AI work out what needs to be done.

So lets assume that you have now scripted 3 turns each for the Allies and the Axis, by following the steps outlined above. We aren't finished yet though! So long as you have followed these steps correctly, script files should have been created for each turn for each of the Axis and Allied sides, so all up you should have 6 files (1 for each turn for each side - 3 turns x 2 sides = 6 scripts!) in your ..korsun pocket\ReplayGame folder.

The files should be called this:


Lets have a brief look at the naming convention of these files, so that we can better understand which each of them is for.

'ScriptXAx1' - relates to the Axis Turn 1 script file. We know this because the 'Ax' represents Axis and the 1 following it represents the first turn. So therefore 'ScriptXAx2' represents Axis Turn 2 script and 'ScriptXAx3' is for the Axis Turn 3.

'ScriptXAl1' - relates to the - yep you guess it - Allied Turn 1 script. That's because the 'Al' represents Allied, and as from above we can see that the numbering convention at the end of the file tells us what turn it is. So 'ScriptXAl3' relates to Allied Turn 3 script.

But it doesn't end there! There is something else which we need to understand. As we covered and explained in Editor Tutorial #8 - Programming AI, you can actually program more then 1 AI for each side in each scenario. In fact you could have lets say, 3 AI's for each side in a scenario. When the scenario starts the computer then randomly select one of the AI's to base the game upon. It will use this AI routine for the length of the game.

We therefore need to tell the computer which AI routine these scripts relate to. The way we tell it is by renaming the 'X' in the script file name 'ScriptXAx1' to correspond to the AI routine that it relates to. For example 'Script1Ax1'.

So go ahead and rename each of the files by changing the X in the script file names to a '1' to indicate Operation Routine 1.

The name of your files should now be as follows:


This means that these AI Scripts will now be used when the computer selects AI operation 1 when it begins a game. If you have only programmed 1 operation for each side, then these scripts will always be used.

If you have programmed more then 1 operation, then you can create - using the same methods as described above, to create script files for each of your operations - just make sure to number them to correspond to their appropriate AI Operation numbers.

For example:

'Script2Ax1' would be the script for Axis Turn 1 for AI operation 2.

'Script3Al2' would be the script for Allied Turn 2 for AI operation 3.

The final thing we need to do now, is to copy all of the renamed script files over to the folder of the scenario that the scripts relate to. For example if the scripts relate to a scenario you have created called Moscow, then they must now be placed in your ..korsun pocket\scenarios\moscow folder.

Some Tips:

Generally if you have more then 1 Operational AI programmed, this means that you have programmed variant AI strategies. For example Operation 1 may have the Axis forces attacking area Z and Operation 2 may have Axis forces attacking area Y instead. Make sure that each of your scripts reflect these different strategies! In other words, make sure your Scripts for Operation 2 reflect operation 2's general strategy and vice a versa.

There may be some instances where even though you have programmed more then 1 operational AI for each side, it may be appropriate to use the same scripts for each operation. In these instances, you can simply copy the 'Script1Ax1' files and rename the copies 'Script2Ax1' etc.

It is quite ok to only Program 1 Operational AI and therefore only 1 set of scripts.

As mentioned previously, Don't seek to create scripts for too many turns too far into the game - and remember if you do create a script for a specific turn - you Don't have to have that script apply to all units. If you Don't want the script to apply to a specific unit then do not select or move the unit during your PBEM script set up turn.

Remember, if you can not predict where a unit will be at a given turn (either one of the enemies, or one of your own - because you didn't script that unit the previous turn), then you probably want to think twice about creating a script for that turn at all, and leaving the Operational AI to do what it does best!

Finally, you probably only need to and want to script for the first few turns of your scenario!

Good luck - and if you have any questions or problems then post a message in the Scenario Design Forum of the Run5 Discussion Board.