Tick5 AI Programming Interface

What's new
About
Download
License
Screenshots
Manual
Tutorial
sf.net page
Contact

The AI Programming Interface

This section introduces you Tick5's AI Programming Interface. The example Lua scripts included in this section will not help you to build a sophisticated AI, but illustrate the AI Programming Interface and the basics of an AI engine written in Lua script. To build your own superior AI for Tick5, you need to get yourself familiar with AI and the game by either reading some books or googling the Internet.

Tick5 is built using Lua 5.0. You can find the Lua 5.0 Reference Manual here. The book Programming In Lua by Lua's chief architect Roberto Ierusalimschy can be find here. Its first edition is available for online reading.

The example Lua script files included in this manual are named as filename.wz, rather than the conventional filename.lua, to avoid to mix these written specially for Tick5 with those that can run with the official Lua interpreter. Furthermore, the game is called wuziqi in my native language. However, you are free to choose the extension name. ;-)

Happy AI programming! And don't forget to share your superior AI with me and others. ;-)

The `tick5think()` function

To build an AI engine for Tick5, you need to create a Lua script that has a function named tick5think.

tick5think(
board )

Tick5 calls this function when it is the turn of the AI engine implemented by the Lua script. When Tick5 calls tick5think(board),it passes in a game board. The function tick5think(board) needs to return two integers which are the x- and y-coordinate of a move. Tick5 retrieves the x- and y-coordinate returned by tick5think(board

), verifies them, and places a
stone on the spot if they are valid

x- and y-coordinate.

The simplest example of a Tick5 AI built using Lua script goofy.wz is here. In this example, the function tick5think(board) doesn't do any "thinking". It ignores the passed in board and simply returns the x- and y-coordinate of the spot (3, 3).

This script runs one turn at most, and it won't go any further once the spot (3, 3) has been occupied no matter whether by itself or by its opponent player.

See Playing Tick5 on how to run a Lua script.

The `mycolor()` function

The AI Programming Interface provides a function mycolor()which allows you to query the color of the stone the script is playing.

mycolor() returns 1 for black stone; return -1 for white stone.

This function helps you to determine the stone color your AI plays at runtime, such that you don't need to hard-code the stone color in your script, which makes it possible for you to program a script that is generic to play both black and white stone.

The game board

To enforce the game rules, Lua scripts cannot directly operate the game board. ;-) The board passed into tick5think(board)is a copy of the game board at the time the function is called. The AI Programming Interface provides functions for you to query and manipulate the copy of the game board. You can use these functions to get information you need to make the best possible move.

Hereafter in this manual, board always means the copy of the game board, not the game board itself.

A spot on the board is identified with its x- and y-coordinate. Both x- and y-coordinate start with zero and end with the dimension of the board minus one. Tick5 has a 15x15 board. (0,0) are the coordinates of the intersection on the top-left corner of the board, while (14,14) on the bottom-right corner.

Query the board

The AI Programming Interface provides the following functions to query the board. Calling these functions is harmless, because they won't make any change to the board. To call these functions, the board and a colon must be placed before the functions.

`board:dimension()`	returns a integer which is the width and height of the game board.
`board:isfull()`	returns true if the board is full; false, if not.
`board:isempty()`	returns true if the board is empty; false, if not.
`board:isempty(x,y)`	returns true if the spot (x, y) is empty; false, if not.
`board:getstone(x,y)`	returns 1 if the stone on spot (x, y) is black; 0 if empty; -1 if white.
`board:plies()`	returns the number of moves both parties have made so far.
board:inboard(x,y)	returns if the spot (x,y) is within board; otherwise, false.
board:lastmove()	returns x-, y-coordinate and stone color of the last move, if any; otherwise, nils.

Another example Lua script goofy2.wz can be found here. In this example, the function tick5think(board) does a little bit "thinking." It randomly picks a pair of x- and y-coordinate using Lua's math function math.random(). It queries the board object to see whether the spot (x, y) is empty or not. It returns the coordinates if the spot is empty; it continues to repeat the procedure, if not empty, and until an empty spot is found.

The script runs fast. However, anyone who knows the game rules will defeat it without any effort. ;-)

See Playing Tick5 on how to run a Lua script.

Manipulate the board

The AI Programming Interface provides the following functions to manipulate the board. Calls to these function will change the board. To call these functions, the board and a colon must be placed before the functions.

`board:putstone(x,y,c)`	put a stone of color c on spot (x, y), returns true if it is successful; false, otherwise. c = 1, represents a black stone; c = -1, a white stone.
`board:remove(x,y)`	removes the stone on spot (x, y), returns false if no stone on the spot; true, otherwise.
`board:clean()`	removes all the stones from the board, making it empty.
board:set(x,y,c)	same as putstone(x,y,c), deprecated.
board:reset(x,y)	same as reset(x,y), deprecated.

Clone the board

The AI Programming Interface provides the clone() function which allows you to make a copy of the board. To call the function, the board and a colon must placed before the function.

board:clone() returns a copy of the board object.

As you can see, the board can be massed up by calling set(x,y,c), reset(x,y)or clean(). You may need to make a copy of the board with the help of function clone(), before your Lua script does whatever necessary to the board when it is "thinking".

In this example, goofy3.wz, the function clone() is called to make a copy of the board then the script masses up with the copy . The function clone() is also utilized to find the last move the opponent made. This example does the same as the previous one, except that it wanders around to explore the board before it randomly picks up an empty spot.

See Playing Tick5 on how to run a Lua script.

A good practice

The AI Programming Interface provides the function keeprunning() which allows you to check the status of the game.

keeprunning() returns false if the game is going to stop or an undo quest is sent to the game; returns true, otherwise.

It is a good practice to periodically call keeprunning()within loops. Exit the loop or even tick5think(board)function, if it returns false. Otherwise, you will not be able to stop the game properly or undo a move immediately.

In this example, goofy4.wz, there is an infinite loop in the tick5think(board) function. Within the inifinite loop, a black and a white stone is respectively placed on each empty spot and removed, and no move is made. However, the

keeprunning()

function is called within the infinite loop to determine whether it should jump out of the loop or not.

Let this script player white stone and you play blank. Start the game. After you make a move, you will see the Lua Output window is being filled up. After clicking either Stop Button of Tick5

on the toolbar, you will see the output stopped.

See Playing Tick5 on how to run a Lua script.

Last update on May 12, 2007