{"__v":10,"_id":"570eb6a6a38d470e0060c9b6","category":{"__v":3,"_id":"56af6d6ecc4cbd0d00ce2c88","pages":["56af6e8460a37a0d00ed87ac","56af71e58be2ea0d00b48887","56af73a08be2ea0d00b48890"],"project":"56abbf55f25f160d00e17f4e","version":"56abbf55f25f160d00e17f51","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-01T14:36:30.275Z","from_sync":false,"order":2,"slug":"concepts","title":"Kongregate APIs & Concepts"},"parentDoc":null,"project":"56abbf55f25f160d00e17f4e","user":"56abbec30b9e0b0d00616274","version":{"__v":12,"_id":"56abbf55f25f160d00e17f51","project":"56abbf55f25f160d00e17f4e","createdAt":"2016-01-29T19:36:53.665Z","releaseDate":"2016-01-29T19:36:53.665Z","categories":["56abbf56f25f160d00e17f52","56abca6bf9757e0d007c6650","56acddfa0ab3c00d00ce3332","56af65da9d32e30d0006d30f","56af66cab34d210d003d9ad0","56af6afcd21e9c0d00b628d1","56af6d6ecc4cbd0d00ce2c88","5705b12221cfed0e00e8c580","570a5676ade45d0e00c1ad33","570d7d25d1e4b82000d9e385","570eac3c3160d10e0041df0e","575709000fd6a3200010dded"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-04-13T21:14:14.464Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Note\",\n  \"body\": \"This feature will not function unless we have enabled it for your game. If you would like to have this feature enabled, please email us at [apps:::at:::kongregate.com](mailto:apps@kongregate.com)\"\n}\n[/block]\n## Custom chat API\n\nThis client API allows your game to interact with the Kongregate chat client by opening up a custom tab which you have control over. Please note that this API is optional and not necessary to have normal Kongregate chat for your game. It also does not provide chat services - it is only a way of displaying content in a chat box, though that can be used for your own chat if you hook it up to your own chat system.\n\n### Overview\n\nThe 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 AS3 drawing API. The bottom half, called the \"dialogue\", is used for displaying chat style messages, whispers, etc.\n\n### The canvas\n\nThe 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 its size.\n\n### The dialogue\n\nThe 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. \n\nThe chat API allows you to display custom messages from users in this dialogue. For example, it can be used to create a \"match chat\" between two players. When the game receives a match chat message from your opponent, it would use the chat API to [display that message](doc:client-api-chat-displaymessage) in the custom tab. It would also [add an event listener](doc:client-api-chat-addeventlistener) to receive copies of any messages the user puts into the chat box.\n\n### Accessing the API\n\nOnce 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. The following is a list of relevant API calls for managing the custom chat tab:\n\n* [Chat.AddEventListener](doc:client-api-chat-addeventlistener)\n* [Chat.ClearMessages](doc:client-api-chat-clearmessages) \n* [Chat.CloseTab](doc:chatclosetab) \n* [Chat.DisplayMessage](doc:client-api-chat-displaymessage) \n* [Chat.ShowTab](doc:chatshowtab) \n\n#### Positioning canvas objects\n\nBefore you can display a canvas object, you must know how to position it properly. Position objects 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:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`x`\",\n    \"0-1\": \"Integer\",\n    \"0-2\": \"X offset of the object\",\n    \"1-0\": \"`y`\",\n    \"1-1\": \"Integer\",\n    \"1-2\": \"Y offset of the object\",\n    \"2-0\": \"`w`\",\n    \"2-1\": \"Integer\",\n    \"2-2\": \"Width of the object\",\n    \"3-0\": \"`h`\",\n    \"3-1\": \"Integer\",\n    \"3-2\": \"Height of the object\",\n    \"4-0\": \"`parent`\",\n    \"4-1\": \"String\",\n    \"4-2\": \"Name of the parent object, if any\",\n    \"5-0\": \"`align`\",\n    \"5-1\": \"String\",\n    \"5-2\": \"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)\"\n  },\n  \"cols\": 3,\n  \"rows\": 6\n}\n[/block]\n### Displaying canvas images\n\nYou can load an image from an external source into the canvas by using the `displayCanvasImage` function. It takes a `name`, `url`, and `position` object:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`name`\",\n    \"0-1\": \"String\",\n    \"0-2\": \"Name of the canvas object\",\n    \"1-0\": \"`url`\",\n    \"1-1\": \"String\",\n    \"1-2\": \"Link to the image to display\",\n    \"2-0\": \"`position`\",\n    \"2-1\": \"Object\",\n    \"2-2\": \"Position of the object, as described above\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n**Example:** Load an image and display it at 100,100 on the canvas\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var url:String = \\\"http://www.fake.com/picture.jpg\\\";\\nvar position:Object = { x:100, y:100 };\\nkongregate.chat.displayCanvasImage(\\\"Image\\\", url, position);\",\n      \"language\": \"javascript\",\n      \"name\": \"ActionScript 3\"\n    },\n    {\n      \"code\": \"var url = \\\"http://www.fake.com/picture.jpg\\\";\\nvar position = { x:100, y:100 };\\nkongregate.chat.displayCanvasImage(\\\"Image\\\", url, position);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n### Displaying canvas text\n\nYou can display text on the canvas with the `displayCanvasText` function. It accepts the following arguments:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`name`\",\n    \"0-1\": \"String\",\n    \"0-2\": \"Name of the canvas object\",\n    \"1-0\": \"`text`\",\n    \"1-1\": \"String\",\n    \"1-2\": \"The text to display\",\n    \"2-0\": \"`position`\",\n    \"2-1\": \"Object\",\n    \"2-2\": \"The position object, as described above\",\n    \"3-0\": \"`options`\",\n    \"3-1\": \"Object\",\n    \"3-2\": \"Any fields from an [AS3 TextFormat](http://livedocs.adobe.com/flash/8/main/wwhelp/wwhimpl/common/html/wwhelp.htm?context=LiveDocs_Parts&file=00002801.html) object\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n**Example:** Display the text `Testing123` at `0,0` using the `Verdana` font at size 12.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var options:Object = { font:\\\"Verdana\\\", size:12, color:0x7FB7FF };\\nkongregate.chat.displayCanvasText(\\\"Text\\\", \\\"Testing123\\\", position, options);\",\n      \"language\": \"javascript\",\n      \"name\": \"ActionScript 3\"\n    },\n    {\n      \"code\": \"var options = { font:\\\"Verdana\\\", size:12, color:0x7FB7FF };\\nkongregate.chat.displayCanvastext(\\\"Text\\\", \\\"Testing123\\\", position, options);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n### Drawing custom shapes\n\nYou may use the `drawCanvasObject` function to use any of the methods in the AS3 Drawing API in order to create a custom graphic shape. This function takes a `name`, and a list of drawing operations and arguments:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`name`\",\n    \"0-1\": \"String\",\n    \"0-2\": \"The name of the canvas object\",\n    \"1-0\": \"`operations`\",\n    \"1-1\": \"Array\",\n    \"1-2\": \"A nested array of drawing operations to perform, along with their arguments.\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\nThe drawing operations must come from the following list:\n\n```\nbeginFill\nbeginGradientFill\nclear\ncurveTo\nendFill\nlineTo\nlineStyle\nmoveTo\ndrawRect\ndrawRoundRect\ndrawCircle\ndrawEllipse\n```\n\n**Example:** Drawing a box using the `drawCanvasObject` function\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var commands:Array = [\\n   [\\\"beginFill\\\", 0x333333, 100],\\n   [\\\"moveTo\\\", 25, 25],\\n   [\\\"lineTo\\\", 75, 25],\\n   [\\\"lineTo\\\", 75, 75],\\n   [\\\"lineTo\\\", 25, 75],\\n   [\\\"lineTo\\\", 25, 25],\\n   [\\\"endFill\\\"]\\n];\\n\\nkongregate.chat.drawCanvasObject(\\\"box\\\", commands);\",\n      \"language\": \"javascript\",\n      \"name\": \"ActionScript 3\"\n    },\n    {\n      \"code\": \"var commands = [\\n   [\\\"beginFill\\\", 0x333333, 100],\\n   [\\\"moveTo\\\", 25, 25],\\n   [\\\"lineTo\\\", 75, 25],\\n   [\\\"lineTo\\\", 75, 75],\\n   [\\\"lineTo\\\", 25, 75],\\n   [\\\"lineTo\\\", 25, 25],\\n   [\\\"endFill\\\"]\\n];\\n\\nkongregate.chat.drawCanvasObject(\\\"box\\\", commands);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note\",\n  \"body\": \"Unlike other display operations, calling `drawCanvasObject` using a name which already exists will not replace it, but instead will draw onto the existing object.\"\n}\n[/block]\n### Removing a canvas object\n\nYou can remove any canvas object with the `removeCanvasObject` function, which accepts the `name` of the object to remove:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`name`\",\n    \"0-1\": \"String\",\n    \"0-2\": \"The name of the canvas object to remove\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n**Example:** Remove the object named \"MyObject\"\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"kongregate.chat.removeCanvasObject(\\\"MyObject\\\");\",\n      \"language\": \"javascript\",\n      \"name\": \"ActionScript 3\"\n    },\n    {\n      \"code\": \"kongregate.chat.removeCanvasObject(\\\"MyObject\\\");\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n### Canvas size\n\nThe 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var size:Object = kongregate.chat.getCanvasSize();\\ntrace(\\\"Width: \\\" + size.width + \\\", Height:\\\" + size.height);\",\n      \"language\": \"javascript\",\n      \"name\": \"ActionScript 3\"\n    },\n    {\n      \"code\": \"var size = kongregate.chat.getCanvasSize();\\nconsole.log(\\\"Width: \\\" + size.width + \\\", Height:\\\" + size.height);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"api-custom-chat","type":"basic","title":"Custom Chat"}
[block:callout] { "type": "warning", "title": "Note", "body": "This feature will not function unless we have enabled it for your game. If you would like to have this feature enabled, please email us at [apps@kongregate.com](mailto:apps@kongregate.com)" } [/block] ## Custom chat 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. Please note that this API is optional and not necessary to have normal Kongregate chat for your game. It also does not provide chat services - it is only a way of displaying content in a chat box, though that can be used for your own chat if you hook it up to your own chat system. ### 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 AS3 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 its size. ### 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. For example, it can be used to create a "match chat" between two players. When the game receives a match chat message from your opponent, it would use the chat API to [display that message](doc:client-api-chat-displaymessage) in the custom tab. It would also [add an event listener](doc:client-api-chat-addeventlistener) 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. The following is a list of relevant API calls for managing the custom chat tab: * [Chat.AddEventListener](doc:client-api-chat-addeventlistener) * [Chat.ClearMessages](doc:client-api-chat-clearmessages) * [Chat.CloseTab](doc:chatclosetab) * [Chat.DisplayMessage](doc:client-api-chat-displaymessage) * [Chat.ShowTab](doc:chatshowtab) #### Positioning canvas objects Before you can display a canvas object, you must know how to position it properly. Position objects 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: [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "`x`", "0-1": "Integer", "0-2": "X offset of the object", "1-0": "`y`", "1-1": "Integer", "1-2": "Y offset of the object", "2-0": "`w`", "2-1": "Integer", "2-2": "Width of the object", "3-0": "`h`", "3-1": "Integer", "3-2": "Height of the object", "4-0": "`parent`", "4-1": "String", "4-2": "Name of the parent object, if any", "5-0": "`align`", "5-1": "String", "5-2": "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)" }, "cols": 3, "rows": 6 } [/block] ### 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: [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "`name`", "0-1": "String", "0-2": "Name of the canvas object", "1-0": "`url`", "1-1": "String", "1-2": "Link to the image to display", "2-0": "`position`", "2-1": "Object", "2-2": "Position of the object, as described above" }, "cols": 3, "rows": 3 } [/block] **Example:** Load an image and display it at 100,100 on the canvas [block:code] { "codes": [ { "code": "var url:String = \"http://www.fake.com/picture.jpg\";\nvar position:Object = { x:100, y:100 };\nkongregate.chat.displayCanvasImage(\"Image\", url, position);", "language": "javascript", "name": "ActionScript 3" }, { "code": "var url = \"http://www.fake.com/picture.jpg\";\nvar position = { x:100, y:100 };\nkongregate.chat.displayCanvasImage(\"Image\", url, position);", "language": "javascript" } ] } [/block] ### Displaying canvas text You can display text on the canvas with the `displayCanvasText` function. It accepts the following arguments: [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "`name`", "0-1": "String", "0-2": "Name of the canvas object", "1-0": "`text`", "1-1": "String", "1-2": "The text to display", "2-0": "`position`", "2-1": "Object", "2-2": "The position object, as described above", "3-0": "`options`", "3-1": "Object", "3-2": "Any fields from an [AS3 TextFormat](http://livedocs.adobe.com/flash/8/main/wwhelp/wwhimpl/common/html/wwhelp.htm?context=LiveDocs_Parts&file=00002801.html) object" }, "cols": 3, "rows": 4 } [/block] **Example:** Display the text `Testing123` at `0,0` using the `Verdana` font at size 12. [block:code] { "codes": [ { "code": "var options:Object = { font:\"Verdana\", size:12, color:0x7FB7FF };\nkongregate.chat.displayCanvasText(\"Text\", \"Testing123\", position, options);", "language": "javascript", "name": "ActionScript 3" }, { "code": "var options = { font:\"Verdana\", size:12, color:0x7FB7FF };\nkongregate.chat.displayCanvastext(\"Text\", \"Testing123\", position, options);", "language": "javascript" } ] } [/block] ### Drawing custom shapes You may use the `drawCanvasObject` function to use any of the methods in the AS3 Drawing API in order to create a custom graphic shape. This function takes a `name`, and a list of drawing operations and arguments: [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "`name`", "0-1": "String", "0-2": "The name of the canvas object", "1-0": "`operations`", "1-1": "Array", "1-2": "A nested array of drawing operations to perform, along with their arguments." }, "cols": 3, "rows": 2 } [/block] The drawing operations must come from the following list: ``` beginFill beginGradientFill clear curveTo endFill lineTo lineStyle moveTo drawRect drawRoundRect drawCircle drawEllipse ``` **Example:** Drawing a box using the `drawCanvasObject` function [block:code] { "codes": [ { "code": "var commands:Array = [\n [\"beginFill\", 0x333333, 100],\n [\"moveTo\", 25, 25],\n [\"lineTo\", 75, 25],\n [\"lineTo\", 75, 75],\n [\"lineTo\", 25, 75],\n [\"lineTo\", 25, 25],\n [\"endFill\"]\n];\n\nkongregate.chat.drawCanvasObject(\"box\", commands);", "language": "javascript", "name": "ActionScript 3" }, { "code": "var commands = [\n [\"beginFill\", 0x333333, 100],\n [\"moveTo\", 25, 25],\n [\"lineTo\", 75, 25],\n [\"lineTo\", 75, 75],\n [\"lineTo\", 25, 75],\n [\"lineTo\", 25, 25],\n [\"endFill\"]\n];\n\nkongregate.chat.drawCanvasObject(\"box\", commands);", "language": "javascript" } ] } [/block] [block:callout] { "type": "info", "title": "Note", "body": "Unlike other display operations, calling `drawCanvasObject` using a name which already exists will not replace it, but instead will draw onto the existing object." } [/block] ### Removing a canvas object You can remove any canvas object with the `removeCanvasObject` function, which accepts the `name` of the object to remove: [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "`name`", "0-1": "String", "0-2": "The name of the canvas object to remove" }, "cols": 3, "rows": 1 } [/block] **Example:** Remove the object named "MyObject" [block:code] { "codes": [ { "code": "kongregate.chat.removeCanvasObject(\"MyObject\");", "language": "javascript", "name": "ActionScript 3" }, { "code": "kongregate.chat.removeCanvasObject(\"MyObject\");", "language": "javascript" } ] } [/block] ### 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. [block:code] { "codes": [ { "code": "var size:Object = kongregate.chat.getCanvasSize();\ntrace(\"Width: \" + size.width + \", Height:\" + size.height);", "language": "javascript", "name": "ActionScript 3" }, { "code": "var size = kongregate.chat.getCanvasSize();\nconsole.log(\"Width: \" + size.width + \", Height:\" + size.height);", "language": "javascript" } ] } [/block]