Chat Integration API

This client API allows your game to interact with the Kongregate chat client by opening up a custom tab which you have control over.

Overview

The chat API allows you to display a tab in Kongregate chat. This tab is split into two components. The top half, or the "canvas" can be drawn on with various techniques including text, images, and support for the AS2 drawing API. The bottom half, called the "dialogue", is used for displaying chat style messages, whispers, etc.

The Canvas

The canvas is made up of different kinds of display objects. These are basically named movie clips which can be created with the contents of an image, text, or custom art using the AS3 drawing API. The canvas supports a wide range of positioning and layout options which allow you to customize the canvas as you see fit. You also have control over how large the canvas is, and can query the API for the size of the canvas.

The Dialogue

The dialogue should look familiar to anyone who has used Kongregate. It allows users to type in chat input, as well as receive messages from other users, along with general information such as challenge announcements. The chat API allows you to display custom messages from users in this dialogue. This is used to implement the "match chat" in Kongai, Zening, Battalion, Skystone, etc. When the game SWF receives a match chat message from your opponent, it uses the chat API to display that message in chat. You may also add an event listener to receive copies of any messages the user puts into the chat box.

Accessing The API

Once you have the Kongregate API loaded in your game, you can access the chat functionality by referencing the chat member of your Kongregate API object.

API Functions

Displaying a Custom Tab

This function displays a custom tab in the chat area, which will replace any other custom tabs that might be showing. It takes a name, description, and options. The name parameter is the name that will be shown on the tab itself. The description will be displayed below the tab in a wider space. The options object may contain a size field, which is a decimal between 0 and 1 indicating the size you wish the canvas to be, with the default being 0.5, for example:

kongregate.chat.showTab("MyTab","My Custom Tab",{size:0.75});

Closing the tab

When you would like to close the tab, you may use the closeTab function.

kongregate.chat.closeTab();

Displaying chat text

Displaying chat text can be done with the displayMessage function, which takes a message and a username. The message is the message you wish to display, while the username is the user you want the message to be displayed from.

kongregate.chat.displayMessage("Hi there!","BenV");

Clearing the chat dialogue

You may clear all the messages in the chat dialogue by using the clearMessages function:

kongregate.chat.clearMessages();

Positioning canvas objects

Before you can display a canvas object, you must know how to position it properly. Position objects are just instances of Object that can have various properties describing where the element should be displayed. The object can have many different properties, not all of which are supported by every element type:

  x - X offset
  y - Y offset
  w - Width of the object
  h - Height of the object
  parent - Name of the parent object, if any
  align - Alignment of the object relative to its parent (if any)
          Legal values are "tl","t","tr","r","br","b","bl","l", "c" 
          (top left, top, top right, right, bottom right, bottom, 
          bottom left, left, and center, respectively)

Canvas size

The size of the canvas can be retrieved using the getCanvasSize function. It returns an object which has width and height elements. This function is only valid after the tab_visible event has been fired for your tab.

var size:Object = kongregate.chat.getCanvasSize();
trace("Width: " + size.width + ", Height:" + size.height);

Displaying canvas images

You can load an image from an external source into the canvas by using the displayCanvasImage function. It takes a name, url, and position object:

var url:String = "http://www.fake.com/picture.jpg";
var position:Object = {x:100,y:100};
kongregate.chat.displayCanvasImage("Image", url, position);

Displaying canvas text

You can display text on the canvas with the displayCanvasText function. It takes name, text, position, and an options object, which may contain any of the fields in an AS3 TextFormat object.

var position:Object = {x:0,y:0};
var options:Object = {font:"Verdana",size:12,color:0x7FB7FF};
kongregate.chat.displayCanvastext("Text", "Testing123", position, options);

Drawing custom shapes

You may use the drawCanvasObject function to use any of the methods in the AS2 Drawing API in order to create a custom graphic shape. This function takes a name, and a list of drawing operations, which must come from this list:

 beginFill()
 beginGradientFill()
 clear()
 curveTo()
 endFill()
 lineTo()
 lineStyle()
 moveTo()
 drawRect()
 drawRoundRect()
 drawCircle()
 drawEllipse()

 var commands:Array = [
            ["beginFill",0x333333,100],
            ["moveTo",25,25],
            ["lineTo",75,25],
            ["lineTo",75,75],
            ["lineTo",25,75],
            ["lineTo",25,25],
            ["endFill"] ];
 kongregate.chat.drawCanvasObject("box",commands);

Note that unlike other display operations, drawing onto an object which already exists will not replace it, but instead will draw onto the existing object.

Removing a canvas object

You can remove any canvas object with the removeCanvasObject function, which accepts the name of the object to remove:

kongregate.chat.removeCanvasObject("MyObject");

Events

You may use the standard addEventListener function to listen for various events broadcast by the chat API.

The tab_visible event is broadcast when a showTab request is completed and the custom tab is created:

kongregate.chat.addEventListener("tab_visible",onTabShown);
function onTabShown(event:Event){
  trace("Tab shown!");
}

The message event is broadcast when the player inputs something into the chat window and presses return. The event contains a data field which you can use to get at the text that was entered:

kongregate.chat.addEventListener("message",onPlayerMessage);
function onPlayerMessage(event:*){
  trace("Message: " + event.data.text);
}