DreamScape Documentation
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
- Load "!mktrack.sx" into ScriptX, to compile the ScriptX
Tracking Service.
It depends on the file:
- tracking.sx -- source code
It creates the file:
- tracking.sxl -- Tracking module LibraryContainer
- Load "!mkthrow.sx" into ScriptX, to compile the Throwing
module into a LibraryContainer.
It depends on the files:
- anim.sxl -- Animation module LibraryContainer
- tracking.sxl -- Tracking module LibraryContainer
- import.sx -- source code
- throwing.sx -- source code
- room.sx -- source code
- puppet.sx -- source code
- ground.sx -- source code
- painter.sx -- source code
- narnia.sx -- source code
- bounce.aif -- audio media
It creates the file:
- throw.sxl -- Throwing module LibraryContainer
- Load "!mkrooms.sx" into ScriptX, to compile the rooms
into AccessoryContainers.
It depends on the files and directories:
- anim.sxl -- Animation module LibraryContainer
- tracking.sxl -- Tracking module LibraryContainer
- throwing.sxl -- Throwing module LibraryContainer
- rooms/roomName -- directories
It creates the files:
- rooms/roomName.sxa -- room AccessoryContainers
- Load "!mkparts.sx" into ScriptX, to compile the parts
into AccessoryContainers.
It depends on the files and directories:
- anim.sxl -- Animation module LibraryContainer
- tracking.sxl -- Tracking module LibraryContainer
- throwing.sxl -- Throwing module LibraryContainer
- pupimp.sx -- source code
- parts/partName -- directories
It creates the files:
- parts/partName.sxa -- part AccessoryContainers
- Load "!mkdream.sx" into ScriptX, to compile the DreamScape
TitleContainer.
It depends on the files:
- anim.sxl -- Animation module LibraryContainer
- tracking.sxl -- Tracking module LibraryContainer
- throwing.sxl -- Throwing module LibraryContainer
- dream.sx -- source code
It creates the file:
- dream.sxt -- TitleContainer
After it finishes saving, it runs DreamScape so you can test it out.
Running DreamScape
To run DreamScape, load the TitleContainer "dream.sxt"
into the Kaleida Media Player or ScriptX. It depends on the files and directories:
- anim.sxl -- Animation module LibraryContainer
- tracking.sxl -- Tracking module LibraryContainer
- throwing.sxl -- Throwing module LibraryContainer
- dream.sxl -- DreamScape TitleContainer
- rooms/roomName.sxa -- room AccessoryContainers
- parts/partName.sxa -- part AccessoryContainers
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.
- Importing Parts and Rooms
Select "Open Accessory..." from the File menu, or type Command-Y
on a Mac, or Control-Y on Windows. Select an AccessoryContainer file ending
with ".sxa" from the "parts" or "rooms"
directories. Importing a part adds it to the current room. Importing a room
adds it to the map, but doesn't connect it to any other rooms.
- Navigating from Room to Room
To move to an adjacent room, press the mouse button down over the background,
move up, down, left, or right, and release the button, without pausing.
This "flicking" room navigation gesture will quickly move you
from room to room. You can undo any navigation gesture by flicking back
in the other direction, since all links between rooms are supposed to be
two-way.
- Blowing the Wind
You can blow the wind in any direction (actually warping gravity), to fly
the moving parts around the room and off the edges, by pressing the mouse
button down over the background, moving it in the direction and magnitude
you want the wind to blow, and holding the button down. If you release the
button quickly instead of holding it down, it will be interpreted as a navigation
gesture, and you will move to an adjacent room. Once a part stops moving,
it isn't effected by wind or gravity any more, so you'll have to pick it
up and throw it to get it moving again.
- Hitting the Brakes
You can hit the brakes (actually increasing friction), to slow down all
the moving parts in the room, by pressing the mouse button down and holding
it down without moving. If you move instead of holding still, it will be
interpreted as a wind blowing or room navigation gesture.
- Moving Parts from Room to Room
To move a part to an adjacent room, just pick it up and throw it off the
edge towards that room. Use the map editor to connect and disconnect rooms.
- Map Editor
The map editor floats in a window above the current room, so it is always
with you no matter where you are. You can drag it almost off the edge of
the screen so it is out of your way, or anywhere else on the screen you
want. It has an icon for each room, which shows what each room currently
looks like, at 10% scale. There are thick blue lines between rooms that
are linked. You can drag the rooms around, and the lines will follow. You
can make a link between two rooms, by dragging one over to the other, and
dropping it down so the edges you want to link bump together. The rooms
will snap apart neatly, and there will be a blue line connecting the two
edges that touched. To break the link, drag the two rooms together again
just like you did to link them, and the link will be broken. If you load
the "parts/map.sxa" map accessory more than once, you don't
get a new map, but it performs another automatic layout of the current map.
The automatic layout algorithm does OK with geographically consistent grid-like
maps, but gets hopelessly confused with maps of weird topologies, so it
tries to respect how you've moved things around. A subject for further research.
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 ! !