back to unity client documentation  back to  
unify the web

UClient for Macromedia Flash: Application Developer's Guide
This document gives a high-level overview of Unity application development for Flash, and introduces the basic architecture of UClient for Macromedia Flash. For more detailed information, see the uClientCore API documentation and the uSimpleChat tutorial.

UClient Package Contents
Here's a brief look at the directory structure of UClient.

Name Description
/docs/ Contains UClient for Macromedia Flash documentation. Always be sure to check the website for the latest docs as these files may well be out of date.
/flash mx versions/ Contains application templates for Macromedia Flash MX (version 6 of the Flash authoring tool). While the majority of UClient's templates are in Flash MX 2004 format, and use ActionScript 2.0, this directory contains older-style Flash MX and ActionScript 1.0 templates for creating Unity applications.
/lib/ Contains the uClientCore class library both in Flash MX 2004 component format and .swf format. The component format is added to each application at author-time, while the optional .swf format is loaded at runtime. By convention, all application templates for Flash MX 2004 use the component format, while application templates for Flash MX (version 6 of the Flash authoring tool) use the .swf format. When working with multiple applications, the .swf format offers an overall reduction in filesize (once the .swf is loaded, it is cached for reuse by other applications).
/uAdmin/ Contains the server administration tool, which offers statistics, remote tools for starting and stoppping the server, and a visual representation of rooms, namespaces, attributes, and connected clients. To run the admin, open /uAdmin/deploy/uAdmin.swf in Flash Player 6 or later.
/u[ApplicationName]/ The remaining diretories in the UClient package are the individual application templates and learning samples included with the product (e.g., /uTicTacToe/). Each application directory contains source .fla files, source class files (.as), deployed versions of the applications. For details, see Application Template File Structure, below.

Application Template File Structure
Each application template in UClient for Macromedia Flash contains two folders:

The /deploy/ folder contains the exported .swf file for the application, ready to post to a website. The /deploy/ folder also may also contain a configuration file in XML format, which is loaded by the application .swf file. The configuration file contains the location of the Unity server, the port on which Unity server is running, and the application log level (one of: DEBUG, INFO, WARN, ERROR, or FATAL).

The /source/ folder contains the application's .fla file and class files (.as files). The class files, themselves, are stored in a directory structure that matches their ActionScript 2.0 package name, as in "/org/moock/unity/appname/ClassFile.as".

Here's the content of the /uGuestBook/ application sample:

Application Template Class Structure
Every UClient application must create a subclass of the core UClient class. This subclass is typically named after the application itself. For example, the uGuestBook application's UClient subclass is named UGuestBook. The UClient subclass connects to the server and, once a connection is established, starts the application in motion, usually by creating rooms and/or displaying the application interface. For details, see the UClient class documentation.

UClient applications also typically respond to room and namespace events with classes that observe the core URoom and NameSpace classes. These observing classes are known as the "room view" and "namespace view" (following the popular Model-View-Controller design pattern). A UClient application often has at least one room view class and one namespace view class. These view classes are named after the room and namespace that is broadcasting the events. For example, the uGuestBook application creates a single room, "guestbook" in a single namespace, "uguestbook". Hence, its room view class is named GuestBookRoomView, and its namespace view class is named GuestBookNamespaceView.

All application classes are stored externally, with each class in a separate .as file. The classes in the uClientCore API are loaded via either the uClientCore component or the uClientCore.swf class library.

Application Template .fla Structure
Each application template has a main .fla file found in the /source/ directory. That .fla file must adhere to the following requirements:

All application templates fulfil those requirements. Applications for Flash MX 2004 include the uClientCore component. They also preload the application using a very basic main timeline preloader. After the movie has loaded, the preloader sends the playhead to the frame labeled "main", where the application's UClient subclass instance is created and connected to the Unity server. An example timeline for a UClient application (uGuestBook.fla) is shown below.

uGuestBook.fla Timeline

To prevent a load delay before frame 1, each UClient application template sets the export frame for ActionScript classes to a frame after the main timeline preloader. For example, in uGuestBook.fla, the export frame for ActionScript 2.0 classes is set to frame 6, after the frame labeled "mainLoadLoop". To set the export frame for ActionScript 2.0 classes, follow these steps:

  1. Select File > Publish Settings.
  2. Click the Flash tab.
  3. Click the Settings button next to ActionScript version.
  4. Under Export frame for classes, enter the desired frame.

The ActionScript Settings dialog for uGuestBook.fla is shown below.

uGuestBook.fla ActionScript Settings

All UClient application templates store the source .fla file and the exported .swf file in separate directories (/source/ and /deploy/). To ease this separation, the .swf export location for each .fla file is set under the .fla file's Publish Settings. For example, the .swf export location for uGuestBook.fla is set to ../deploy/uGuestBook.swf, as shown below.

uGuestBook.fla .swf Export Location

Using the Debug Version of the uClientCore Component
Most UClient applications ship with the standard version of the uClientCore component. The debug version of the uClientCore component logs every single message that is sent to or received from the Unity server. In a production environment the standard version of uClientCore should be used because displaying copious log messages reduces application performance. However, during development, it's often handy to read what's actually being sent to the server. To use the debug version of uClientCore in a .fla file, follow these steps:

  1. Delete the uClientCore component from the .fla's library.
  2. Drag an instance of the uClientCore (debug) component from the Components panel to the .fla's stage.
  3. Delete the instance you just dragged to the stage.

If the uClientCore components are not already in your Components panel, follow the instructions under Adding the uClientCore Component to a New Unity Application.

Adding the uClientCore Component to a New Unity Application
To add the uClientCore or uClientCore (debug) component to a new application, you can do one of the following:

To add the uClientCore components to your Flash Components panel, follow these steps:

  1. Open the following folder, substituting your operating system user account name for [USER] and your Flash language code for [LANGUAGE CODE] (in English, [LANGUAGE CODE] is "en"):
    • On Windows:
      c:/Documents and Settings/[USER]/Local Settings/Application Data/Macromedia/Flash MX 2004/[LANGUAGE CODE]/Configuration/Components/
    • On Mac:
      HD:/Users/[USER]/Application Support/Macromedia/Flash MX 2004/[LANGUAGE CODE]/Configuration/Components/
  2. In the /Components/ folder, create a new folder named /Unity/.
  3. Copy uClientCore.swc and uClientCore-debug.swc from /UClient/lib/ to /Components/Unity/.
  4. If you are currently running the Flash authoring tool, click the Components panel's popup options menu (top right of the panel) and select "Reload".
The uClientCore components should now appear in the Components panel.

Documentation Version
1.0.0