DreamScape Documentation

By Don Hopkins, Kaleida Labs

Index: Introduction, Building, Running, Playing, Authoring Rooms, Authoring Parts.

Introduction

This is the documentation for DreamScape, an open ended interactive multimedia simulation environment for ScriptX, also known an Actualized Fantasy Screen Waster (not to be confused with a Virtual Reality Screen Saver). The DreamScape Demo given at the Apple World Wide Developer Conference flies through its many features.

DreamScape consists of rooms that can connect together in a map, and parts that can move around inside and between rooms. You can load new rooms and parts dynamically, and they can interact with you and each other in interesting, unexpected ways.

The parts have simulated physical dynamic behavior. You can pick them up, move them around, and throw them, and they bounce around the room, effected by gravity and friction, colliding and interacting with each other.

Parts can be animated, and articulated with registration points, so you can plug them together like legos or Mr. Potato Head. Some can even paint on the room background, and do all kinds of other magic stuff.

There is an overall map showing every room, with icons of the current image of each room, and lines between linked rooms, that rubber-band when you drag the icons around. You can go to any room by clicking on its icon, and even edit the map topology, making and breaking connections between rooms, simply by bumping their icons together.

You can create new rooms and parts, by copying the directory of a similar one, and editing its image, director file, or startup action source code in the directory. The room images are imported from BMP files, and the Director Toolkit is used to import articulated animations from Director files. The room and part definitions are compiled into AccessoryContainers that you can dynamically load into ScriptX, as many times as you want to create any number of objects.

This first release of the DreamScape is a snapshot of a working prototype, developed as a demonstration of ScriptX by Kaleida Labs. The DreamScape Design Philosophy describes some of the concepts around which DreamScape was designed. This code is intended to serve as an example of ScriptX programming and object oriented design techniques, with the caveat that it is under development, subject to drastic change, and has its share of limitations and skanky kludges. This other documentation describes the DreamScape design example in more detail.

Building DreamScape

Running DreamScape

To run DreamScape, load the TitleContainer "dream.sxt" into the Kaleida Media Player or ScriptX. It depends on the files and directories:

Playing DreamScape

Here are some of the most important features of the DreamScape user interface, that you have to know to play with it. It's fun to figure it out without reading a manual, but you may want know the following techniques. A more in-depth description of the user interface will be written later, but for now, you can refer to the DreamScape Design Philosophy for more tips.

Authoring Rooms for DreamScape

DreamScape loads rooms from the AccessoryContainers in the "rooms" directory, from the "rooms/roomName.sxa" files. The rooms are defined by the files in the "rooms/roomName" subdirectories.

You can make a new room by copying one of the other room directories in "rooms", and giving the new directory the name of your room.

Each room directory has a subdirectory called "rooms/roomName/image", which contains a 640x480 BMP file, that's used as the background image of the room. Edit the image to your liking, and save it into the "image" directory as an 8 bit BMP file, compressed or not, preferably using the Mac system colormap. There should only be one file in the "image" directory, and it should end with the ".bmp" extension.

You can link a room to other rooms in four directions: up, down, left, and right. You should be sure to make a link back from the other room in the opposite direction, since navigation in DreamScape is supposed to be undoable: if you move one direction, you can always get back to the same place by moving the opposite direction.

Each room directory may have subdirectories called "left", "right", "up", and "down", that each contain a single subdirectory whose name is the room adjacent to that edge. For example, to make a link between a room on the left called "foo" and a room on the right called "bar", create a directory called "rooms/foo/right/bar", and "rooms/bar/left/foo". Similarly for up and down.

The map overview lets you edit links between rooms, and automatically keeps the two way links consistent. Soon it will update the room directory, so the changes are persistent (but doesn't yet, in this first version of the prototype).

You can put parts into a room by making a subdirectory of the room directory called "rooms/roomName/parts", and making subdirectories in there whose names are part names, defined in the "parts" directory. For example, to put a butterfly (defined in "parts/buttrfly") into the room called "field", make a directory named "rooms/field/parts/buttrfly".

You can build all the rooms at once by loading "!mkrooms.sx" into ScriptX, or build a single room at a time by loading the file "rooms/roomName/!mkroom.sx" from the room directory.

Authoring Parts for DreamScape

As you might expect, DreamScape loads parts from the AccessoryContainers in the "parts" directory, from the "parts/partName.sxa" files. The parts are defined by the files in the "parts/partName" subdirectories.

You can make a new part by copying one of the other part directories in "parts", and giving the new directory the name of your part.

Each part directory has a file named "parts/partName/startup.sx", which contains a ScriptX function of one argument, an AccessoryContainer, that's used as the AccessoryContainer's startupAction, which is called and passed the AccessoryContainer when it's loaded.

The look and feel of the part is defined by the startupAction, which may plug in various kinds of media, that are stored in the AccessoryContainer. There are several template "startup.sx" files that you can copy, and substitute your own media, without programming. If you want to program in ScriptX, you can certainly write your own "startup.sx" files to make parts that do anything you want! Try to write them to be reusable, so you can plug in new media without modifying the code.

If there is a subdirectory called "parts/partName/director", it should contain a single Director file, that ScriptX imports as a set of named puppet parts. The parts are stored in the AccessoryContainer, for use by the startupAction to create the part. The startupAction, whose single argument is "ac", can refer to "ac[@parts]" to get the array of imported puppet parts. Refer to the comments in "pupimp.sx" and "puppet.sx" for more information about puppet parts, and look at the director files in the examples to see how to format named animation sequences with named registration points for importing into ScriptX.

You can build all the parts at once by loading "!mkparts.sx" into ScriptX, or build a single part at a time by loading the file "parts/partName/!mkpart.sx" from the part directory.

! ! N O W ! ! G O ! ! H A V E ! ! F U N ! !