Building a Chat Application with Unity, Part 1

overview

part 1 of a four-part workshop

pre-requisite: Introduction to Unity

create a very basic chat application called uSimpleChat

download workshop files here

uSimpleChat, Version 1

uSimpleChat v1 will show how to do the following:

create a room using the server uconfig.xml file

use the client-side Unity class library, uClientCore

make a UClient subclass

connect to Unity

invoke a method on other clients

respond to a method invocation from a remote client

the chat application room

recall that:

each application defines one or more rooms to contain its users

each room resides in a namespace

for now, we'll create the chat application room in the namespace "udefault"

udefault is provided automatically by Unity as a convenience

our chat application room will be called "chat"

create the chat room

we'll create the chat room by modifying the server's uconfig.xml file

follow these steps:

if Unity is currently running, stop it (rooms specified in uconfig.xml are loaded at startup only)

edit uconfig.xml

add the following XML code to the <INSTANCES> tag of uconfig.xml:

<ROOM> <NAMESPACE>udefault</NAMESPACE> <ID>chat</ID> <AUTOJOIN>true</AUTOJOIN> </ROOM>

Save uconfig.xml.

Start Unity. (On Windows, double-click startserver.bat. On Unix, run startserver.sh.)

use uAdmin.swf to verify that the room was created.

notice the <AUTOJOIN> tag: it forces every client to automatically join the room 'chat'

install the uClientCore class library

uClientCore is a component

to install it in Flash MX 2004, follow these steps:

make folder C:/Program Files/Macromedia/Flash MX 2004/[LANGUAGE CODE]/First Run/Components/Unity

copy /UClient/lib/components/uClientCore-debug.swc to C:/Program Files/Macromedia/Flash MX 2004/[LANGUAGE CODE]/First Run/Components/Unity

shut down flash mx 2004 if it is running, then start it

open the components panel (Ctrl+F7) and verify that the uClientCore component appears

application file structure

the uSimpleChat application has the following directory and file structure (provided):

uSimpleChat.swf is the compiled client application

uSimpleChat.fla is the source Flash document

USimpleChat.as is the application's class file (UClient subclass)

export settings

open uSimpleChat.fla

use File > Publish Settings > Formats to set the export location of uSimpleChat.swf to: ../deploy/uSimpleChat.swf

use File > Publish Settings > Flash > ActionScript Version > Settings to set "Export frame for ActionScript 2.0 classes" to frame 6

setting class export frame lets us preload classes and component code

warning: components must be placed after export frame or they won't work!

add uClientCore to the Flash document

we need to add uClientCore to uSimpleChat.fla

once uClientCore is added, we can access all its classes

to add uClientCore follow these steps:

drag an instance of uClientCore from the components panel to the Stage

delete the instance

now the component is in the Library, ready for use

no on-Stage instance is required

add UI components to the Flash document

drag instances of TextArea, TextInput, and Button to frame 21 of the interface layer

name the TextArea instance incoming

name the TextInput instance outgoing

name the Button instance send

*** very important: for TextArea, TextInput, and Button symbols in the Library:

select Linkage

then uncheck "Export in first frame"

(our ActionScript 2.0 classes are exported at frame 6, so our components *must* be exported at frame 7 or later)

the USimpleChat class

all Unity Flash applications must extend the UClient class

recall that the UClient subclass

connects to the server

sends and receives data

provides access to the application's RoomManager and RemoteClientManager

optionally responds to remote method invocations

our UClient subclass is USimpleChat

USimpleChat's methods

USimpleChat defines three methods:

sendMessage(): sends chat messages to other clients

displayMessage(): receives chat messages from other clients

onClientReady(): displays the interface when the client has connected

USimpleChat class file

now let's build the basic USimpleChat class file:

create a text file in the following location: /uSimpleChat/source/org/moock/unity/simplechat/USimpleChat.as

edit the file with Flash MX 2004 Professional or your favourite text editor

add this code to the file:

import org.moock.unity.*; class org.moock.unity.simplechat.USimpleChat extends UClient { }

USimpleChat constructor

the USimpleChat class constructor initializes new USimpleChat objects

but USimpleChat has no initialization tasks of its own

hence, USimpleChat's constructor simply preserves the behaviour of its superclass's constructor function

put this code between the { } of the USimpleChat class declaration:

public function USimpleChat (target:MovieClip, host:String, port:Number, configURL:String, disableLog:Boolean) { // Invoke UClient constructor. super(target, host, port, configURL, disableLog); }

USimpleChat constructor parameters

USimpleChat's constructor parameters specify the following information:

target: the movie clip on which the interface should be displayed

host: the address of the server to which to connect

port: the port on which the server is running (9100 by default)

configURL: the location of an optional configuration file (not used in our chat)

disableLog: indicates whether to show or hide logging information (we hide it in this chat)

create the onClientReady() method

onClientReady() governs what happens when client is connected and ready for action

in this version of uSimpleChat, our client auto-joins the room udefault.chat

hence, onClientReady() just shows interface for that room

add this code after the constructor:

public function onClientReady ():Void { // Display the user interface for this app. getTargetMC().gotoAndStop("simpleChatInterface"); }

getTargetMC() returns the target movie clip passed to the USimpleChat constructor

create the sendMessage() method

sendMessage() sends a chat message to other users

how are messages sent? with a remote method invocation

sendMessage() invokes displayMessage() on clients in room udefault.chat

sendMessage() passes input from outgoing to displayMessage()

add this code after the onClientReady() method:

public function sendMessage ():Void { if (getTargetMC().outgoing.text.length > 0) { var msg:String = getTargetMC().outgoing.text; var safeMsg:String = '<![CDATA[' + msg + ']]>'; invokeOnRoom("displayMessage", "udefault.chat", true, safeMsg); getTargetMC().outgoing.text = ""; } }

create the displayMessage() method

displayMessage() displays a chat message on screen

displayMessage() is invoked remotely by other clients

displayMessage() displays text and client id in incoming TextArea component

clientID is supplied automatically by Unity server

add this code after the sendMessage() method:

public function displayMessage (clientID:String, msg:String):Void { getTargetMC().incoming.text += "User" + clientID + ": " + msg + "\n"; getTargetMC().incoming.vPosition = getTargetMC().incoming.maxVPosition; }

instantiate USimpleChat

USimpleChat is now done

we just need to use it in our Flash document (uSimpleChat.fla)

specifically, we need to:

create the USimpleChat instance

connect the USimpleChat instance to server

add this code to the scripts layer, at the frame labeled "main":

// Create USimpleChat instance and connect to Unity. import org.moock.unity.simplechat.USimpleChat; var sc:USimpleChat = new USimpleChat(this, "localhost", 9100, null, true); sc.connect(); // Wait here. When connection succeeds, the application // will proceed to the frame labeled "simpleChatInterface". stop();

send button event handler

lastly, we must make the Send button invoke sendMessage() when pressed

attach the following code to frame 21 of the scripts layer:

send.clickHandler = function (e:Object):Void { sc.sendMessage(); }