The Quick Start tutorial is broken up into the following sections:

1. Before you begin
2. Finding the Bot object
3. Creating your first bot
4. A simple example - chat client application
5. A complex example - using the database object

Each section of the Quick Start tutorial builds on the previous section, and is recommended that you complete them in sequential order. If you are not able to complete all of the sections in one sitting, then you should save your project when exiting Magik, and re-open it when you continue the tutorial.

If you are not yet familiar with the Tekadence Magik authoring environment, it is strongly recommended that you stop here and review the Tekadence Magik Documentation first.

1. Before you begin

Before you begin this tutorial, you should do two things:

1) Start Tekadence Magik. This should be easy since you are already familiar with how to use Magik and would have done this before.

2) Create a new Basic Application project. It is possible that there is already a new document open when you start Magik, however you can create a new document by choosing New... from the file menu, and then Basic Application in the template dialog.

It is also strongly recommended that while you are working through the tutorial, that you only have one document open (the one you just created). This will minimize confusion when talking about switching between different document views.

The tutorial assumes you are familiar with the Magik user interface and will refer to components such as the Object Browser and Window Editor as if you know what they are, and how to use them.

Last chance! If you are not yet familiar with the Tekadence Magik authoring environment, it is strongly recommended that you stop here and review the Tekadence Magik Documentation first.

2. Finding the Bot object

Once you have successfully installed the latest version of the IRC module for Magik, you should start by locating the Bot object in the Default Classes scrapbook. In Magik, objects can also be referred to by using their complete name, which helps specify an entire namespace in the case of more than one object having the same name (from different vendors for example).

The Default Classes scrapbook is organized into folders that specify the root namespace of an object. Since the Bot object's complete name (including namespace) is: com.axlogic.magik.irc.Bot, you will find the Bot object in a folder titled "com.axlogic.magik.irc".

Under the Scrapbooks menu you will also find a menu item titled "IRC", which is discussed later in this tutorial in more detail. The IRC scrapbook includes the Bot object found in the Default Classes, as well as a collection of compound objects designed to simplify some of the more complex tasks of creating an IRC application. For future reference, when the tutorial calls for creating a Bot object from the scrapbook, you can use either the Default Classes or the IRC scrapbook.

3. Creating your first bot

This section will give you a basic understanding of the Bot object, and introduce you to some of the core concepts required to build sophisticated IRC applications with Tekadence Magik.

In the following step-by-step instructions, you will learn how to:

• Add a Bot object to your application
• Configure the Bot server and port address
• Change your Bot's name
• Connect to the server
• Join a channel
• Send a message to the channel
• Disconnect from the server

3.1 Add a Bot object to your application

Step 1. Open the Scrapbook window by choosing either Default Classes or IRC from the Scrapbooks menu. Note: If the window is minimized, you may have to click on the Scrapbook icon in your taskbar.

Step 2. Drag the Bot object from the Scrapbook on to the Window object icon in the Object Browser view. After you drop the Bot object in the Object Browser, you will notice that the Window object will expand and you will see that the Bot is now a child of the Window.

3.2 Configure the Bot server and port address

With the Bot object selected in the Object Browser, you will notice that there are three interesting properties that we will be concerned with while configuring the Bot to log in to the IRC server.

The most important property to configure is the server property. This property is empty by default, and is required to specify the actual IRC server that your bot will execute on. There are many IRC servers that allow bots, and you probably want to use the server that you normally connect to when using your favorite IRC client application. Some popular IRC servers are:

Homelan (irc.homelan.com)
FunNet (irc.funnet.org)
Chatster (irc.chatster.org)
GamesNET (west.gamesnet.net)

In order to connect to one of the servers above, you would have to set the Bot's server property to its corresponding internet address. For example, to log into the Homelan server set the property value to: irc.homelan.com.

Not all IRC servers have the same port address. In the case that you wish to connect to an IRC server that has a port other than the default port (6667), you must also change the port property value, in addition to setting the server property.

3.3 Change your Bot's name

You may want to change the name that appears when your bot joins a channel on the IRC server. By default, the name given to the bot is MagikBot, however this can be changed by modifying the nick property value.

3.4 Connect to the server

The Bot object will automatically connect to the server when the application enters runtime mode, either by choosing Run from the File menu, or by entering preview mode in the Window editor (as long as the Bot is a child of the Window object).

For the purpose of this tutorial, we want to connect to the server by opening the Window editor and entering preview mode.

Step 1. Right-Click on the Window object in the Object Browser and choose Edit... from the popup menu.

Step 2. Click on the projector icon in the Window editor's toolbar.

3.5 Join a channel

To join a channel once the bot has been connected to the server you must send it a join message, specifying the channel you wish to join. Since there are several ways you can do this in Magik, such as patching or scripting custom message handlers, we will stick to invoking messages through the Console - a useful tool for testing during the authoring process.

Step 1. Bring up the Console window by choosing Console from the View menu.

Step 2. Select the Command tab in the Console window, and click in the console area to get a blinking cursor next to the ">" symbol.

Step 3. Type the following command in the console to invoke the join message of the Bot object:

> System.subtree.Bot.join( "#magik_bot" );

Don't type the '>' character! That is there to show you what the line will look like in the console when you enter the command. Note: This command will join a channel called #magik_bot, however you should substitute the actual channel you want the bot to join in its place.

Don't worry if the console returns the message **Not Found**. That just probably means you forgot the semicolon at the end of the command, but it won't affect the message being sent to the Bot object.

3.6 Send a message to the channel

To send a message to a user logged into the IRC server, or to a specific channel, follow the same instructions for joining a channel. When you get to the console however, you will want to enter the following command:

> System.subtree.Bot.sendMessage( "Hello world!", "#magik_bot" );

This command will send the message "Hello world!" to the channel #magik_bot. If you want to send a message to a specific user that connected to the server, you would replace #magik_bot with the users name:

> System.subtree.Bot.sendMessage( "Hello world!", "FrizzleFried" );

If you want to send a message to the current channel - which is the same as the most recent channel that the bot has joined, you can omit the target parameter:

> System.subtree.Bot.sendMessage( "Hello world!" );

Note: For further reference, the sendMessage message and other Bot object messages are described completely in the Bot object documentation.

3.7 Disconnect from the server

The Bot object will disconnect from the server automatically when you exit runtime mode, either by exiting the application or be leaving preview mode in the Window editor. You can also send the disconnect message to the Bot to disconnect from the server.