Croquet SDK
From Croquet Consortium
Croquet System Overview
NOTE: Since late 2006, the Croquet system has no longer been under active development while its derivative, Open Cobalt, is now the focus of a very active international community-based software development effort. See opencobalt.org for details.
Introduction
The Croquet SDK is a powerful open source software development environment for creating and deploying deeply collaborative multi-user online applications on multiple operating systems and devices. It is not an end-user application. Cobalt is an emerging open source application designed for those who are interested in creating sharable virtual worlds and is being built through a community-based effort using the current Croquet SDK. Derived from Squeak, Croquet features a peer-based network architecture that supports communication, collaboration, resource sharing, and synchronous computation between multiple users on multiple devices. Using Croquet, software developers can create and link powerful and highly collaborative cross-platform multi-user 2D and 3D applications and simulations - making possible the distributed deployment of very large scale, richly featured and interlinked virtual environments.
Every part of the system is designed around enabling real-time, identical interactions between groups of users. The architecture of Croquet actually makes it quite easy to develop collaborative applications without having to spend a lot of effort and expertise in understanding how replicated applications work. There are a number of simple patterns and rules to remember, but otherwise, it is quite simple to quickly develop very powerful systems. The following sections are intended to provide a general overview of how the Croquet system actually works.
TeaTime and Islands are the basis for Croquet's replicated computation and synchronization. They are designed to support multi-user applications that can be scaled to massive numbers of concurrently interacting users in a shared virtual space. The TeaTime approach is designed to support multi-user applications that can be scaled to massive numbers of concurrently interacting users in a shared virtual space. The most directly visible part of this architecture is the TObject class which is used to define and construct subclassed Tea objects. A Tea object acts with the property that messages sent to it are redirected to replicated copies of itself on other users participating machines in the peer-to-peer network. All of the interesting objects inside of Croquet are constructed out of subclasses of TObject. This messaging protocol supports a coordinated distributed two-phase commit that is used to control the progression of computations at participating user sites. In this way, messages may be dynamically redirected to large numbers of users while maintaining the appropriate deadline based scheduling. Thus, TeaTime is designed to allow for a great deal of adaptability and resilience, and works on a heterogeneous set of resources. It is a framework of abstraction that works over a range of implementations that can be evolved and tuned over time, both within an application, and across applications.
Therefore, Croquet is based upon the concept of replicated computation – rather than replicated data. Croquet is based upon a synchronized message passing model, where the messages themselves ensure that the replicated systems remain consistent between machines. Though it is necessary to synchronize the world state of a new user by transferring the current contents of the world, after that, the worlds stay consistent only through the creation and processing of time based messages.
Implementation of TeaTime in the Croquet SDK
The current Croquet SDK does not implement "full TeaTime" replication semantics. That decision was made pragmatically because the expressive value of closures was not thought to be worth the complexity. Instead, two low-level and well crafted modifications have been implemented: "islands" and "routers". These are pragmatic solutions that are like the "stack-only" choice made by Lisp 1.5 (in LISP, a choice was made not to implement lambda-calculus closures - but instead to limit the LISP semantics to those that can be implemented on a stack machine based on so-called applicative-order evaluation - a pragmatic decision based on a belief that the expressive value of closures was not thought to be worth the complexity). We hope that eventually these will be modified to support the TeaTime full semantics. In the meanwhile, islands and routers meet the needs of our present efforts to deliver scalable multiuser virtual worlds without the need for reliance on centralized server infrastructures. Our design approach sets the stage for the full TeaTime semantics to be slipped back underneath Croquet with little impact at some time in the future.
Islands and Replicated Computation
The basic unit of replication and collaboration in Croquet is called an Island. A Croquet Island is first a secure container of arbitrary objects and access to the contents of an Island is governed by strict rules that ensure proper bottlenecking. Internally, objects see no difference between the rights they have in accessing other objects than in any other traditional system – except for a significant restriction that explicit infinite loops are simply not allowed. This is replaced instead by a mechanism we refer to as “temporal tail recursion” (discussed later). A single Island is actually made up of a collection of containers all in identical states on different machines connected by a network. One of these containers on a particular machine could be thought of as a replica or projection of the Island - albeit a complete projection. Croquet guarantees that the evolution of the state of a particular Island replica is identical to any other replica of the same Island. This is the basis of the Croquet collaboration architecture. Readers should take note that the term “Island” is used in several ways in this document. As just described, an Island consists of the set of all of its replicas. For clarity, we may refer to a copy as an “Island replica” (or simply “replica”), while the whole set is called the “Island”. Furthermore, Island is a Squeak class that implements the base “Island” model; a replica is an instance of the Island class.
Croquet Islands
Croquet Islands are secure containers of other objects and are the basic unit of replication. They act as a kind of meta-object in that they have perhaps an even better model of encapsulation - certainly more secure, than traditional object models and they enforce a rigorous content-hiding and message passing model. This is a necessary precursor to guarantee identical behavior and identical response to external events (a similar concept to Islands is the Vats in the E programming language). Croquet Islands are generic object containers that are simple to checkpoint and exchange. They can easily be saved to disk for use later or archiving, or they can be transported between users to initiate collaborative interaction with the contents of the Islands. Objects internal to an Island have the same access privileges to each other that ordinary objects have. They can send messages directly to each other or themselves, can maintain direct access links to each other, and in general exhibit the same kinds of relationships that ordinary objects enjoy. They cannot, however, send messages outside the scope of the Island – nor can objects outside the Island send messages directly to the objects inside. That is not to say that there is no way for external messages to be sent to an object inside of an Island.
A TFarRef is an object that exists outside of the Island, but can act as a proxy for an object that is actually inside the Island. A message sent to the TFarRef is forwarded on to the actual object that is inside. This is actually a somewhat simplistic view of what actually happens – the actual process is a bit more interesting. The TFarRefs are actually generated by having the Island register a particular object as being externally accessible. An external name is generated, and a TFarRef is made available by the Island. The Island maintains a Dictionary that maps the TFarRef back to the original object. In Croquet, messages are sent to the original object inside of the Island indirectly via the TFarRef. This ensures that we have a nice way of bottlenecking the message, as we will usually have to redirect it in such a way that ensures it is properly replicated. Though there are ways to bypass this bottlenecking, it is extremely dangerous do so, as it can easily lead to a violation of the replicated state of the system. This invalidates the guarantee the Croquet has of ensuring perfectly replicated state inside of an Island. However, certain actions simply cannot be performed in a replicated way. An example of this is rendering of the content of an Island. Rendering only makes sense to a local observer, and is a relatively expensive action. Replicating the action of rendering a scene in Croquet is not only inefficient; it also does not make much sense.
Replicated Islands
Islands in Croquet are the units of replication in the system. For Islands to work properly, they must be deterministically equivalent. This means that given an identical initial state between two Island replicas, and given exactly the same inputs at the same time – the end states of these Island replicas must be identical. If for some reason there is even a slight divergence in state, this can easily be multiplied such that the end results are completely out of sync. Since the entire point of Croquet is to provide the users a perfectly replicated simulation environment that can be used as the basis of communication of information and ideas, this kind of breakdown renders the system totally useless. Of course, the entire point of the Island architecture is to have any number of Island replicas exhibiting identical state anywhere on the network – hence, anywhere in the world or even beyond.
A number of new concepts and objects need to be introduced to describe how the replicated Island architecture works. The first is the Croquet Message, which includes not just the token message name, but the target of the message, the message arguments and when the message will be executed. The second is the Croquet Router, which is the object that manages messages that are generated externally to an Island but are sent to it. It both determines when this external message will be executed and replicates it to all of the Island replicas. The third is the Croquet Controller, which is the interface between the Island and the Router and manages external events by redirecting them to the Router. Together with Islands, these are the main elements of a robust time-based replicated architecture.
Croquet Messages
A Croquet message is made up of four components, the target – which is the object that will actually execute the message, the actual message, the arguments to the message, if any, and the time at which the message will be executed. The time value is also used to sort the unexecuted message in the Island’s message queue. Croquet messages can be generated either internally, as the result of the execution of a previous message inside of an Island, or externally, as the result of an external event usually generated by one of the users of the system. There is virtually no difference between internally and externally generated messages as far as the internal execution of the Island is concerned. A major difference between the two is that the timestamps on externally generated messages are used by an Island to indicate an upper bound to which the Island can compute its current message queue to without danger of computing beyond any possible pending messages.
Timing
The definition and manipulation of time plays the central role in how we are able to create and maintain a replicated Island state. We must be able to guarantee that every internally generated message will be executed in exactly the proper order at exactly the proper time. Externally generated messages must be properly interleaved with the internally generated messages at exactly the right time and order. When a new message is generated, it is inserted in the sorted queue based upon its execution time.
Island Time
An Island’s view of time is defined only by the order of the messages it has in an internal queue. Islands can only respond to external, atomic, time-stamped messages. These messages are literally the Island clock. Though Islands have internal time based messages that can be queued up, these cannot be released for computation until an external time based message has been received which indicates the outer temporal bound to which the Island can compute to. This is a key point of the architecture. Though we may have a huge number of internal messages ready to be executed, they remain pending until an external time stamped message is received indicating that these internal messages are free to be computed up to and including the newly received message. Each Island’s message queue is processed by a single thread, so issues with improperly interleaved messages do not arise.
When a message is executed, the time remains atomic in that it does not advance during the execution of this message. The “now” of the message stays the same. When we generate a future message during the current message, we always define its execution time in terms of the current “now” plus an offset value. This offset must always be greater than zero (though in fact zero is an acceptable value in certain circumstances, it should almost always be avoided because if it is infinitely iterated, Croquet can’t advance and the system will appear to freeze.) If we generate multiple future messages, they will have an identical “now”, though they may have different offsets. If we generate two messages at the same “now” and with an identical temporal offset value, an additional message number is used to ensure deterministic ordering of the messages.
All of the messages in the Island queue are “future” messages. That is, they are messages generated as the result of the execution of a previous internal message with a side effect of sending messages to another object at some predefined time in the future, or they are messages that are generated as the result of an external event – usually from a user, that is posted to the Island to execute at some point in the future, usually as soon as possible. All of these messages have time stamps associated with them. The internal messages have time stamps that are determined by the original time of the execution of the message that initially posted the message plus the programmer defined offset. The external messages have a time that is determined by an external object called a router and is set to a value that is usually closely aligned with an actual time, though it doesn’t need to be.
Internal future messages are implicitly replicated; they involve messages generated and processed within each Island replica, so they involve no network traffic. This means that an Island’s computations are, and must be, deterministically equivalent on all replicas. As an example, any given external message received and executed inside of a group of replicated Islands must in turn generate exactly the same internal future messages that are in turn placed into the Islands’ message queues. The resulting states of the replicated Islands after receipt of the external message must be identical, including the contents of the message queues.
External future messages are explicitly replicated. Of course external messages are generated outside of the scope of an Island, typically by one of the users of the system. The replication of external messages is handled by an object called a Router, which in addition specifies when the message will be executed. The Router is more fully described below.
External non-replicated messages are extremely dangerous and must be avoided. They do play a role, but it is extremely rare that anyone will ever have a need to make use of this mechanism. The problem is obviously that if a non-replicated message is executed and happens to modify the state of an Island it breaks the determinism the Island shares with the other replicated copies. We do use such non-replicated message when rendering the contents of an Island, but this is extremely well controlled.
Each Island has an independent view of time that has no relationship to any other Island (Island used here as the complete collection of Island replicas). This includes (for example) that a given Island could have a speed of time (relative to real time) that was a fraction of another. This is useful for collaborative debugging, where an Island can actually have a replicated single step followed by observation by the peers.
Since time is atomic and the external messages act as the actual clock, latency has no impact on ensuring that messages are properly replicated and global Island state is maintained. It does mean that higher latency users have a degraded feedback experience.
Islands enforce an internal “temporal tail-recursion" with the use of the #future: message. Basically, a message is arranged to execute some unit of time from the atomic "now" in the future. Hence, a message like:
#turn: angle
cube rotateAroundY:angle.
(self future:100)turn: angle+1.
causes the angle to be increased by one degree every 100 milliseconds.
The Croquet Router/Sequencer
The Croquet Router plays two major roles. First, it acts as the clock for the replicated Islands in that it determines when an external event will be executed. These external events are the only information an Island has about the actual passage of time, so the Island simply cannot execute any pending messages in its message queue until it receives one of these time-stamped external messages. The second critical role played by the Router is to forward any messages it receives from a particular Croquet Controller to all of the currently registered Islands. Given that Islands cannot execute beyond these external messages, it is usually necessary to manufacture new messages simply for the sake of moving time forward. These messages are created by the Router and are called heartbeat messages. They are basically message-free and contain only a time-stamp that allows the island to execute to. Routers can be located almost anywhere on the network and need not be collocated with a particular Island. Typically, the creator of the Island will own the Router by default.
The Croquet Controller
The Croquet Controller is the non-replicated part of the Island/Controller pair. The role of the Croquet Controller is to act as the interface between the Island and the Router and between the user and the Island. Its main job is to ship messages around between the other parts of the system. The Controller also manages the Islands message queue, by determining when messages will get executed. Interestingly, a Croquet Controller can exist without an Island, acting as a proto-Island until the real island is either created or duplicated. In this case it is used to maintain the message queue until either a new Island is created or until an existing Island is replicated.
Croquet Message Execution
The basic idea behind Croquet’s replicated message model is that the Croquet Router acts as the clock for all of the Island replicas. This is a guarantee that they all share exactly the same model of time. The Croquet Controller acts as the interface between the Router and the user and the Router and the Island. Every replica of an Island has its own Controller, but there is only one Router for the set of replicas of an Island.
To track a message from an initial event to execution inside of an Island, we first consider a user interacting with a specific object. The user never has direct access to the objects inside of an Island, so he can only interact with a far reference to that object, a TFarRef. A message is constructed using the following line of code:
farRef future aMessage:arguments
What we are doing here is sending aMessage: to the farRef to be executed as soon as possible in the future. In fact, another way to read #future is “ASAP”. The farRef forwards this message to the Croquet Controller of the Island that contains the actual object that the farRef refers to. The Controller simply forwards the message again to the Croquet Router associated with the Island. The Router immediately places the current time stamp on the message – note that no two time stamps are equivalent – and forwards the message, now containing the execution time, back to the original controller. The controller then inserts the message into the Islands message queue and begins to execute all of the messages that are already in the queue that have a time stamp less than the new message.
This may seem a bit round about just to get a message to the local Island, but this process makes much more sense when seen in the context of replicated messages as described in the next section.
An interesting thing to point out is that a given internal message can generate a new message at a delta from the time of the original internal message that is actually less than the time of the new external message that is driving the clock. This newly minted message is simply added to the queue and executed in its own proper order before we actually execute the external message. If in turn its delta is small enough, it may even generate a number of additional messages that get executed before the external time stamped message is.
Replicated Message Execution
The main reason for the existence of the Islands, Routers, and Controllers is to enable the perfect replication of even complex interactions and simulations. The model for this is basically identical to the description in the previous section up to the point where the no time-stamped messages are sent out of the Croquet Router. A replicated Island has multiple identical copies of itself in various locations around the world (or the office or school). There is still only one Router, but now, for every Island replica there is a Croquet Controller.
After the Router receives a message from one of the Controllers, it now forwards the time stamped message to all of the Controllers connected to it – including the original one. The Controllers all insert the new message into the sorted message queues and executes the messages in each queue up to and including the new message. This means that every Island is now completely up to date with every other one.
Starting, Joining, and Participating
The process of creating a new Croquet session from scratch and then having new users join into the process is relatively simple. There are three parts to it – creating the Router, Controller, and Island – Joining the Router – and Participating in the Croquet session.
Starting Up
The first action required in creating a new Croquet world is for us to create a new Croquet Router. This Router can be on any accessible machine on the network – either remotely on a WAN, locally on the LAN, or on the same machine that will act as host to the original Island. Routers are extremely lightweight objects, so they really don’t take up many resources, either in space or computation. The Router has a network address and port number that is how we will find it later.
Once the Router exists, we need to create a new Croquet Controller. This needs to be located on the same machine that the new Island will be located on, and is usually the original users own computer. Again, this is not essential. It is quite easy to create a Croquet Controller/Island pair on a remote server. Of course, this may take a few more resources than a simple Router requires. We give the Controller the address and port number for the original Router and it begins to connect.
Joining
The first thing the Controller does is send a message to the Router asking to subscribe to its message stream. Given that we made both the Router and the Controller, we are guaranteed of getting access – but it is important to note that this may not be true for other users as they attempt to join. You will have to grant them explicit permission – or leave the Router open to anyone, if they are to join the session. Once the Router authorizes the Controller it will begin publishing its message stream to it.
The only messages coming from the Router at this point are the heart beat messages – assuming we set the Router to generate these. In any case, the Controller is designed to simply begin adding these messages to its message queue. This is actually important when we are joining an already existent replicated Island, because in that case many of the messages that get sent and stored on the queue will be necessary to bring the Island replica up to date after it is replicated locally. Joining is view only access. At this point, even if there were an Island, the user is not allowed to send messages that might modify it in any way.
At this point, we can create a new Island from scratch using the Controller. We can also populate the Island and have the objects inside of it begin the process of sending their own internal messages into the message queue. Once the Island exists, we still need to be allowed to participate in it, which allows us to send it external messages generated by user events. Like joining, this is simply making a request to the Island to be allowed to participate. If granted, our Controller receives a list of facets, which is a kind of encrypted dictionary of messages that we are allowed to send from the user through the Router to the Island.
Adding Users
The new users need to be able to join a Croquet session while it is running, with minimal cost to the other users. If done properly, the other users might not even notice that another user has joined the session apart from seeing a new avatar appear in the scene. Since a Croquet Router already exists, we only need to create a new Controller on our local machine. This is identical to creating the original Controller on the original users machine. Just as before, the new Controller requests that it be allowed to join the ongoing Croquet session. Once permission to join is granted by the Router, the new Controller will begin receiving messages from the Router. In this case, these messages will likely include events generated by the current users of the Croquet Island, so these messages are extremely important. Now, instead of creating a new local Island, the Controller needs to request a copy of the current Island from the other user. The Router forwards this request to the original Controller and the Island is “checkpointed”, in that a copy is made at a particular instant in time and streamed out to the new user via the Router. Once the Island has been copied over to the new users machine – the message queue is truncated to the time of the most recent message executed by the Island, and execution seamlessly picks up from that point. The two users are now perfectly synchronized with identical Islands.
Participating
At this point, the new user has basically read-only access to the Island and must also ask to be allowed to participate. Again, it requests this from the Router and if granted the new user can begin to interact with his peers inside of the Island. The current system allows for both joining and participating with one message via the Croquet Harness.
Nice Side Effects
Because no messages are ever lost, and because the original message senders cannot specify when a message is to be executed, latency does not create timing or synchronization problems, just feedback problems. Systems will act sluggish if you have a higher latency, but the contents of the Island will remain identical between all users regardless. This also means that users are not punished for having a high-latency participant sharing an Island, though the high-latency participant may have a less than satisfactory experience. Since Routers are independent of Island/Controller pairs, they can be positioned anywhere on the network. This means that they can be moved to a position of minimal group latency, or onto centralized balanced latency servers. Routers can even be moved around if necessary to improve latency for specific users or groups for a certain time period.
The Future of Croquet Objects
The real work of Croquet is actually performed by the objects that are inside of the Islands. These are the objects that know how to display themselves, respond to external user events, and perform time-based simulations. They can be 3D objects that get rendered using OpenGL, or 2D objects that lie flat on the screen, or even zero-D objects that have no visual representation at all, but can perform complex computations. In fact, there are really no special “Croquet” objects. The real distinction is that objects inside of Islands can send and receive future messages. These are virtually any message that an object understands, but sent into the future to be executed at an explicit later time. The syntax is basically the same as sending a normal message to an object, except we need to specify how far into the future the message will be executed. As an example, if we want to rotate a cube in the 3D world by ten degrees around its y-axis we would normally write:
cube addRotationAroundY:10.
This would be executed immediately, and the cube would be rotated 10 degrees. If instead, we wanted to perform this operation sometime in the future, perhaps one second, we would write something like this:
(cube future:1000) addRotationAroundY:10.
The only real difference is the #future:1000, that specifies we want the next message - #addRotationAroundY: - to be executed 1000 milliseconds, or one second from now.
Virtually any object can be sent messages this way. Outside of an Island, we only have indirect references to the objects inside of it. We can still send messages to these inside objects via the reference, but we cannot specify when these messages are actually executed. To send a message to the cube inside of the Island, we first need to have a TFarRef to the cube – call it farCube, and to send the translation message we would do something like the following:
farCube future addRotationAroundY:10.
We cannot specify how far into the future this message will be executed. The only guarantee is that the Router will attempt to have it execute as soon as possible. If it is necessary to have a delayed future send, then you will need to write another method that in turn performs a future send of the required time. As an example, if you want to have the rotation triggered in five seconds after the external future send, you could write the following method:
MyCube>>#addRotationAroundY: angle when: time
(self future: time) addRotationAroundY: angle.
Then, you would execute the following from outside of the Island:
farCube future addRotationAroundY:10 when: 5000
Note that this is still relatively undefined. All you know is that the actual add rotation message will be executed exactly five seconds after this message is executed, and all you know about that is it will be dependent on the best efforts of the Router and network.
Getting Started with the Croquet SDK
First Things First
It is important to point out that Croquet is presently in the form of a software developer's kit (SDK) and not yet an application that can easily be used by end-users. The NSF-sponsored Cobalt effort is centered around developing an application supporting the needs of end-users. The Croquet SDK, on the other hand, comes complete with a few examples that illustrate different features and capabilities of the system which the uninitiated often and mistakenly think are finished end-user applications.
Learn Squeak
In order to efficively use the full capabilities of Croquet SDK 1.0, you will need to learn how to start and stop Squeak, manipulate objects, and examine and change code. To help more people get familiar with Squeak's very powerful programming environment, the new book Squeak by Example is now being made available under the Creative Commons Attribution-ShareAlike 3.0 license. It's intended for both students and developers and guides readers through the Squeak language and development environment by means of a series of examples and exercises. This is very useful to those who wish to become more familiar with the Croquet programming environment. You can either download the PDF for free, or you can buy a softcover copy from lulu.com. Another very good resource is the book Squeak: Object-Oriented Design with Multimedia Applications by Mark Guzdial, Prentice-Hall, 2000. There are also number of useful resources available for learning OpenGL, including the OpenGL Programming Guide by Mason Woo, Jackie Neider, Tom Davis, and Dave Shreiner, Third Edition. Addison-Wesley. 1999 and OpenGL Game Programming by Kevin Hawkins and Dave Astle, Prima Publishing, 2001. See the Squeak website for more information on this powerful language.
Requirements
The Croquet SDK currently runs on Windows XP, Macintosh OSX, and Linux on a single computer. A three-button mouse is highly recommended. To collaborate with other users, you will need a LAN or Internet connection.
Depending on what you want to do, it is possible to run the Croquet SDK on computers with fairly limited capabilities. But in general, your experience will be better with a computer that runs faster, has more memory, and has a faster Internet connection. A 1 GHz processor and 750 MB of RAM are a reasonable threshold for most purposes.
Croquet's graphical performance is quite sensitive to the performance of the computer's graphics coprocessor. The MINIMUM technical requirements are 32 MB of video memory (VRAM), with hardware/driver support for stencil buffers and at least 16 bit depth buffer (32 bits better) while under OpenGL 1.3 and higher. It is not always easy for most users to be able to determine if these conditions are present on their computers. As a rough guide, most video cards that come with at least 64 MB VRAM are likely to have the right hardware on board. However, Microsoft Corporation has established a practice of distributing graphics drivers that disable graphics hardware acceleration when used with OpenGL rather than their proprietary DirectX. Windows users should check with their hardware manufacturer (in the case of laptops, the correct drivers are often provided by the laptop manufacturer, rather than the video card manufacturer). Reinstalling the manufacturer's driver will often fix problems with your system that are caused by a Microsoft DirectX upgrade.
Croquet also requires that you install OpenAL on your system. This makes it possible to run applications that use spatialized sound. Recent versions of Macintosh OSX include the OpenAL libraries as a standard part of the system. Windows users may also find that their sound card came with an OpenAL driver. If you need to install OpenAL, download the installer here.
Installing the Croquet SDK
Simply unpack the downloaded archive to any convenient location. Everything is included within the new directory.
Starting Squeak
Croquet is provided with an .image file that contains all the original Croquet object definitions. In this release, it is named Croquet1.0.n.image, where n is an integer. However, you may be using a newer file with additional or changed definitions, created by you or someone else. You will need to know the name of this .image file. Squeak can be started by dragging and dropping the .image file onto the virtual machine executable for your platform. There are platform-specific variations:
Windows: The virtual machine executable is named Croquet exe. If you just double-click on the .exe without dragging anything on to it, the .exe will automatically find an .image file to use. If there is only one .image file in the directory, it will use that one without asking. If there are multiple .image files, you will be prompted to select one. You can also arrange for Windows to use the .exe whenever you double-click on the .image file. The way to do this is to double-click on the .image file, browse for the .exe, and click "Always use the selected program to open this kind of file."
Macintosh: The virtual machine executable is named Croquet.app. If you double-click on the .app without dragging anything on to it, the .app will prompt you for an .image file to open. You can also arrange for MacOS to use the .app whenever you double-click on the .image file. The way to do this is to cctrl-click on the .image and choose Open With -> Other. Then select the .app and click the "Always Open With" box. Since the default settings on Mac OS do not display the “.app” extension you will may see an application called something like Croquet with an icon like below.
Linux: The virtual machine executable is named croquet. Several methods of installing Croquet on Linux exist and vary by distribution. On many recent distributions, all one need to do to get started is expand the compressed download and execute the Croquet.sh shell script file within the expanded folder, named CroquetSDK-1.0.n, often by simply double-left clicking its icon in popular desktop user environments.
Before starting, make sure that OpenGL and OpenAL libraries are installed and available on your computer. Croquet should look for the libraries in by searching the LD_LIBRARY_PATH, but depending on how you have arranged you system, you may need to make symlinks or move the libraries. The libraries are:
libGL.so libopenal.so
If you are missing these libraries, you can get them at:
http://www.opengl.org/ or http://berkelium.com/OpenGL/sgi-download.html
We know that Croquet works under Fedora Core 4.0 linux distro with OpenGL 2.0 and OpenAL 0.0.8. Your mileage may vary.
Once you have the audio and graphics support libraries in place, unzip the croquet distribution. Suppose you name the directory holding this software "croquet-beta". In this example, to run Croquet:
cd CroquetSDK-1.0.* ./croquet.sh
The croquet.sh shell script makes sure that a couple important links are in place, then launches the croquet virtual machine with the croquet.image file found in your croquet directory. You might want to modify this. Here is the shell script source:
#!/bin/sh
IMAGE="Croquet.1.0.18.image"
DIR=`dirname $0`
EXE="$DIR/bin/i686-pc-linux-gnu"
# make source link if necessary
if [ ! -r $DIR/CroquetV1.sources ] ; then
ln -s $DIR/bin/CroquetV1.sources $DIR/CroquetV1.sources
fi
# make libGL.so link if necessary
if [ ! -x /usr/lib/libGL.so -a -x /usr/lib/libGL.so.1 ] ; then
if [ ! -x "$EXE/libGL.so" ] ; then
echo Creating libGL.so symlink in $EXE
ln -sf /usr/lib/libGL.so.1 "$EXE/libGL.so"
fi
fi
# make libopenal.so link if necessary - OpenAL is a good thing
if [ ! -x /usr/local/lib/libopenal.so ] ; then
ln -s /usr/lib/libopenal.so.0 /usr/local/lib/libopenal.so
fi
exec "$EXE/squeak" -plugins "$EXE" \
-vm-display-X11 -swapbtn \
"$DIR/$IMAGE"
Regardless of your underlying operating system environment, you will be presented with the following screen:
Click on the "First Steps" panel to expose the Squeak desktop. You are now ready to run Croquet.
Stopping Squeak
Click on the Squeak desktop -- anywhere where there isn't something else. From the "World" menu that pops up, select "quit" (the last item on the menu).
Starting the Croquet SDK
Getting Oriented
There are a total of nine Croquet objects within the Croquet 1.0 SDK. These objects may be thought of as demonstration "applets", and are available within the green Squeak object browser window towards the left side of your screen. You may click on one of these objects and drag it out of the Squeak object browser. Doing so will serve to launch the object and thereby initiate an instance of Croquet. The instance will, by default, run in a small window in order to allow you to use other Squeak tools while Croquet is running.
Running a Single Instance of the Croquet Demo
To run the Croquet demo world, you will need to click on the "Demo (Master)" object within the green colored object browser and drag it onto the light grey Squeak desktop (the background). A red rectangular window will appear as you drag the mouse and be set at the location that you release the mouse on.
Within the red window, the system will create a live instance of a master Croquet world within 15-30 seconds after releasing the mouse button (depending on the capability of machine you are using). The world is loaded when the clouds in the sky begin moving.
Running the MPEG Demo World
Click on the "MPEG Demo (Master)" object within the green colored object browser and drag it onto the light grey Squeak desktop (the background). A red rectangular window will appear as you drag the mouse and be set at the location that you release the mouse on. Within that window, the system will create a live instance of a master Croquet world within 15-30 seconds after releasing the mouse button depending on the capability of machine you are using. The world is loaded when the clouds in the sky begin moving. You have now successfully launched a single machine demo space containing an MPEG movie that will play when clicked from a distance. To play the brief movie, move the avatar back from the window and click the image.
Running the KAT Demo
Connecting to Others
Establishing a Shared Croquet Demo Space (Method 1)
On one of two computers that are connected via a LAN, click on the "Demo (Master) object within the green colored object browser and drag it onto the light grey Squeak desktop (the background). A red rectangular window will appear as you drag the mouse and be set at the location that you release the mouse on. Within that window, the system will create a live instance of a master Croquet world within 15-30 seconds after releasing the mouse button depending on the capability of machine you are using. The master world is ready to be joined once the clouds in the sky begin moving.
On the other computer, drag the Demo (Participant) object out of the green colored object browser as described above. Once loaded, the participant object will look for a master on the LAN, and when it finds one it will synchronize itself by copying the state of the master world and then start it running. You will be able to tell you have synchronized with the other user(s) when you see the world and the clouds begin moving.
Now that you and the other user(s) have joined a common Croquet world, you will be able to see each other's avatars, and changes made in one world (such as moving/creating objects) are reflected in the other world (or even all other connected worlds). If one of the participants leaves the common world, their avatar will disappear, but they or other users can always rejoin the running world.
Establishing a Shared Croquet Space (Method 2)
On one of two computers that are connected via a LAN, click on the "Croquet(Master) object within the green colored object browser and drag it onto the light grey Squeak desktop (the background). A red rectangular window will appear as you drag the mouse and be set at the location that you release the mouse on. Within that window, the system will create a live instance of a master Croquet world within 15-30 seconds after releasing the mouse button depending on the capability of machine you are using. The master world is ready to be joined once the clouds in the sky begin moving.
On the other computer, drag the Croquet(Participant) object out of the green colored object browser as described above. Once loaded, the participant object will look for a master on the LAN, and when it finds one it will synchronize itself by copying the state of the master world and then start it running. You will be able to tell you have synchronized with the other user(s) when you see the world and the clouds begin moving.
Now that you and the other user(s) have joined a common Croquet world, you will be able to see each other's avatars, and changes made in one world (such as moving/creating objects) are reflected in the other world (or even all other connected worlds). If one of the participants leaves the common world, their avatar will disappear, but they or other users can always rejoin the running world.
Establishing a Shared Croquet Space (Method 3)
Here we will establish a connection between two different master spaces using Sailing (Master) and SimpleDemo (Master) located within the green colored object browser.
On one computer, drag the Sailing (Master) object out of the objects bin. Croquet will start an instance of the boating world which will then be available for participants to join. On another computer, drag the SImpleDemo (Master) object out of the objects bin. Again, Croquet will start an instance of this world which will be available for participants to join.
From either of the worlds, go to the Tools menu and select the "Connect to Another World" option. In the Postcard Settings window, select from the popup list of nearby worlds, then click the OK button. This will create a one-way portal to the other world. If you then click in the content area of the portal window to open it, you will synchronize with the other world and will be able to drive your avatar through the portal to enter your friend's world. Once you are in the shared world, you and the other avatar(s) can collaboratively update the world. To coordinate your actions, you can use the text or audio chat tools found in the Talk menu.
See also, A Beginners Guide#Connecting Two Computers and WAN/LAN, Connecting and Discovery.
Stopping the Croquet SDK
To quit Croquet, you delete the Squeak Morph that forms the top-level window for Croquet. This is done by bringing up the Morphic menu, which is platformspecific:
Windows: Alt-click on the Croquet window. (Hold down the Alt key and then press the left mouse button)
Macintosh: Apple-click on the Croquet window. (Hold down the apple or "flower" key and then press the mouse button)
Linux: Alt-click on the Croquet window. (Hold down the Alt key and then press the left mouse button.) Morphic will then bring up a "halo" of buttons around the Croquet window. To quit Croquet, click the pink 'X' button in the upper left corner.
Morphic will then bring up a "halo" of buttons around the Croquet window. To quit Croquet, click the pink 'X' button in the upper left corner.
Getting Started FAQs
Question: Are there additional Tutorials to help me get started?
Answer: Yes. Go here.
Need Help?
The Mailing lists are a great way to get help and opinions.
A Croquet SDK Beginner's Guide
Introduction
So, you are new to Squeak and Croquet, are excited about what you have learned about this system, and now want to get started creating powerful applications...
The first thing to keep in mind is that it is imprortant not to think of the Croquet SDK as an application in itself - despite the fact that one can use the SDK to enter collaborative environment and do the types of things that you would expect to be provided by applications such as Second Life or ActiveWorlds (Croquet is intended to be used as a way of building simulations and real-time collaborative environments that are far more powerful, capable, and customizable than Second Life and ActiveWorlds).
In its current state of development, Croquet should be thought of as an enabling technology intended for use by software developers to create their own applications or customized OpenGL-based game engines - complete with user interfaces and application-specific features and functionalities. In this way it is more similar to a combination of a virtual machine-programming language-3D game engine "hybrid" than it is to a "level editor" that would be used to create environments that run on an existing game engine. Croquet-based "level editors" are currently being developed by a number of people, however, none has yet been made available as part of the distribution. It is anticipated that these tools will be available within the next year.
Connecting Two Computers
The Croquet SDK (Software Developer Kit) is a software toolkit for building realtime collaborative systems. To really experience Croquet you should create a shared, collaborative space inhabitied by more than one user. You will probably want two computers on a local area network to try this. Here is how:
Drag a Croquet world object out of the green objects bin onto the grey background. A window will appear where you release the mouse button and the system will create a live instance of the Croquet world. Two different ways of establishing shared spaces are described below.
1. Join a common space using Demo (Master) and Demo (Participant)
- On one computer, drag the Demo (Master) object out of the objects bin. Croquet will build an instance of the demo world, and make it available for participants to join. The master is ready to be joined once the clouds in the sky start moving.
- On another computer, drag the Demo (Participant) object out of the objects bin. The participant object will look for a master on the LAN, and when it finds one it will synchronize itself by copying the state of the shared world and then start it running. You will be able to tell you have synchronized with the other user(s) when you see the world and the clouds begin moving.
- Now that you and the other user(s) have joined the common world, you will be able to see each other's avatars, and changes made in the world (such as moving/creating objects) are reflected in everyone's copies of the world. If one of the participants leaves the world, their avatar will disappear, but they or other users can rejoin the world.
2. Establish a connection between two different master spaces using Sailing (Master) and SimpleDemo (Master)
- On one computer, drag the Sailing (Master) object out of the objects bin. Croquet will start an instance of the boating world which will then be available for participants to join.
- On another computer, drag the SImpleDemo (Master) object out of the objects bin. Again, Croquet will start an instance of this world which will be available for participants to join.
- From either of the worlds, go to the Tools menu and select the "Connect to Another World" option. In the Postcard Settings window, select from the popup list of nearby worlds, then click the OK button. This will create a one-way portal to the other world. If you then click in the content area of the portal window to open it, you will synchronize with the other world and will be able to drive your avatar through the portal to enter your friend's world.
- Once you are in the shared world, you and the other avatar(s) can collaboratively update the world. To coordinate your actions, you can use the text or audio chat tools found in the Talk menu.
See also, Getting Started#Connecting to Others.
Programing in Croquet
For basic information on how to approach programming in Croquet, please refer to the Developer's Guide (Please note that these documents do not attempt to teach you how to use the Squeak programming environment, or how to program in OpenGL. There are a number of useful resources available for both of these, including Squeak: Object-Oriented Design with Multimedia Applications by Mark Guzdial, Prentice-Hall, 2000, and the OpenGL Programming Guide by Mason Woo, Jackie Neider, Tom Davis, and Dave Shreiner, Third Edition. Addison-Wesley. 1999).
Croquet SDK Default User Interface
Introduction
The Croquet platform is designed to support any number of different user interfaces. With the majority of development effort going into core Croquet functionality, this release provides a single top-level user interface (although individual objects in the space can define their own interfaces). The following sections describe how to interact with the Croquet SDK via this interface; the reader should bear in mind that this interface is not a fundamental part of Croquet and is there only for temporary convenience in getting around.
Only a keyboard and mouse are required to interact with Croquet and this default user interface. As is traditional in Smalltalk environments, the Croquet SDK supports three-button mice. The default interface makes uses of two, which we name the “manipulation” and “navigation” buttons. Keyboard modifiers enable the use of mice with only a single button.
Movement
The “navigation” button depends on the underlying operating system as follows:
Windows: right-click (Press the right mouse button.)
Macintosh: option-click. (Hold down the option key and then press the mouse button.) If you have a three-button mouse, you can also press the right mouse button.
Linux: Same as Windows.
To drive your avatar around, press and hold the navigation mouse button within the Croquet window, at some distance from the center of the window. The closer your mouse is towards the top, the faster you move forward. The closer your mouse is towards the bottom, the faster you move backwards. Similarly for turning left or right. If you also hold down the shift key, you will look up and down rather than moving forwards or backwards, respectively.
You can move vertically in the space using the arrow keys. Note, however, that in most Croquet worlds, any object below you will apply "gravity," such that when you stop pressing, e.g., the up arrow button, you will gradually fall back down to the object. You will not fall through an object. You can also use the mouse’s scroll-wheel to move up and down.
Picking and Manipulation
Picking and manipulating 3D objects in Croquet is a central feature of the system. It is what gives the users the ability to create and manipulate their environment and allows them to interact with it in a way that simply wasn’t possible before. We describe three examples of picking and manipulating objects here.
3D Windows
There are several flat rectangular window objects in Croquet that all define the same default behavior for manipulation: Moving the mouse over the window causes buttons to appear above the top of the window. These will fade away in time if not used. The buttons are activated by clicking them.
Moving the mouse over the window causes buttons to appear above the top of the window. These will fade away in time if not used. The buttons are activated by clicking them.
The window to the left has an active set of buttons along the top. The other windows displayed, (the mirror in the background for example) don’t. If you move the cursor over these windows, the halo will instantly appear.
From left to right the buttons are:
The kill button removes the window and its contents if there is no other reference to them.
The camera button takes a picture of the contents of the window's contents, and (if the window contains a portal) records the current viewpoint as "landmark" that can be returned to later. There will be more on landmarks and portals later. Currently, this is undefined for a window that does not have portal contents.
This down arrow button aligns the viewpoint of the camera (the user’s viewpoint) directly on the window such that it is flat and takes up the entire view screen. This is very useful for viewing and editing documents.
The hand button allows the user to grab the window. The window will now “follow” the user around no matter where he goes, until he selects the hand button again to release it. The window is then left where the camera and user left it.
The plus button opens the contents of the window – which are currently closed. Once the window is opened, the contents are visible. This button icon then turns into a minus button, which allows the window to be closed again.
Several parts of the window frame are also active individually:
Click on the top window frame and drag it in order to move the window in a plane perpendicular to line of sight of the user. Click on the bottom window frame to drag it in the plane of the ground.
Click on either side frame of the window and drag horizontally in order to rotate the window about the vertical.
The result of rotating the window.
Click on any corner of the window and drag to resize it.
The result of resizing the window.
3D Edit Box
The 3D edit box is used to manipulate and position objects in the 3D environment. It is used to translate the object parallel to any of the faces of the box, rotate around any of the three axes, and scale it in and out from the center of the box. The side of the box is made up of eight squares, four in the corners, and four on the edges. Three sides meet at each corner of a box, so in each corner we see three rectangles. Two sides meet at each edge of a box, so we see two rectangles meeting at each side of the box.
In this image, we see the edit cube. If the user selects one of the corner rectangles in the edit cube, the object will be translated in a direction parallel to the surface of that corner rectangle. The arrows above indicate the directions that the object can be dragged when the underlying rectangle is selected. This allows the object to easily be positioned virtually anywhere in the 3D space. This utilizes the planar translation primitive interface control.
When the user selects one of the edge rectangles, as shown, the object is rotated around the axis parallel to the selected edge.
This rotation is performed in the frame of reference of the object itself. This makes it trivial to use. This rotation uses the cylindrical spinner primitive interface control.
Complex, hierarchical objects can be easily edited as well. Once the object is selected, the children of the object can be selected by pressing a down arrow. Sibling objects can be selected by pressing the left or right arrows, and the parent can be selected by pressing an up arrow. Once selected, each of the individual children can be edited in exactly the same way as the above picture illustrates.
The corner rectangles can also be used to scale the object. If the corners are selected while the shift key is down, then the object is scaled proportionately by the distance of the cursor from the center of the edit cube.
One of the key problems with the earlier effort was that if the enclosed object had any functional elements, they were unavailable while editing. The Croquet edit box has all of the editing capabilities of the earlier effort, but allows complete access to the enclosed object’s function.
Portals, Postcards, and Projections
Simply put, a Space is a place. In Croquet, a space is a container of objects, including often, the user’s avatar. A good example of a space might be a child’s play room. All of his toys are objects that happen to be lying on the floor, or perhaps put away. A child can always come into the room to play, or even to pick up a toy and carry it outside. In Croquet, Spaces can act like rooms, but they can also act as landscapes, or virtual conference rooms, or any kind of 3D container of any size.
2D Portals
Portals are simply a 3D spatial connection between spaces. If you place one portal in one space, and a second portal in a second space and link them using the other’s TPostcards, then you can view from one space into the other. In the example of the child’s room, a portal is simply the door to the hallway. The hallway is just another space. One key difference between Croquet portals and spaces and the real world is the concept of actual versus virtual location. In the real world, the hallway must be physically next to the child’s play room, or the door simply won’t go anywhere – at least it won’t lead into the hall. In the virtual world, a portal can connect ANY two spaces, even if one is located on a computer half a world away. Physical location doesn’t mean anything. Connections are all virtual. Consider as an example, the mirror. In Croquet, a mirror is actually a portal that happens to be linked back to itself. In other words, it is actually a door that happens to open into the room from which it is leaving.
A closed Portal into another space – ready to be opened…
The Portal is now open and we can see into the linked Space, in this case the entrance to a multiplayer game.
Here the portal has been rotated toward the user. Just like the mirror, we have a slightly different view into the game world.
One of the key aspects for Croquet is the ability to have a portal dynamically move around in a space, while allowing the proper view through the portal. This is a bit strange, but it works like this: when you look through a window, what you see is determined partially by your position relative to the window. If you move to your left, you can see more of the space to your right (and vice versa). But, if you could pick up the window and move it relative to your position - instead of you moving relative to its position, the exact same thing should happen. It should be much like picking up a box and looking through a hole in it. You turn the box around to see different areas.
The big win for portals is that they allow the user to jump from one virtual space to another by simply walking through the portal, just as the child walked through the door from his play room. What is different in Croquet is that the portal can lead to anywhere in the virtual world. In turn, portals that are contained within these spaces can themselves lead to other worlds.
This sequence shows a remote avatar jumping through a portal into a virtual game world.
Portals have a number of important uses.
Portals allow a world designer to partition a space into connected areas; this is now a standard part of any reasonable game engine. If a portal is not visible from a particular position and orientation, none of the objects inside the portal are rendered. This is essential for complex spaces.
We can use portals for project management. They allow a hierarchical structure (or any other kind of graph) for managing worlds. They act the same way that a project window in Squeak or live folders on a desktop might work.
Portals act as virtual links between users spaces. The user will be able to use it as a bookmark into another user’s workspace and access it at any later time.
Islands and their contents can only be accessed using a view portal and a TPostcard.
TPostcard
The idea of a TPostcard is very similar to that of a URL link in a web browser. It specifies a location somewhere on the net where the linked content may be found. In our case, a TPostcard links to a Croquet router, which in turn references a replicated Island. It goes further than that, we also need to know which particular object inside of the Island we are referencing, and sometimes may even need to know if there is a transformation associated with this link.
The TPostcard is used to find the Router in the following way:
Look up the routerAddress. If this is a valid address, it will initiate a connection. If it is nil, it will look for the TContact matching the routerName/ routerID, and then connect to the router specified by that TContact. The set of known TContacts is automatically propogated over the local area network, can also be populated by the programmer.
Once the router has been discovered, the Island is synced.
These instance variables MUST be left as references. Every element in them must exist inside of an Island that may be replicated. There can be no controllers or FarRefs placed into this object. The standin must be constructed by the containing Island.
routerAddress – the address of the router on the net. routerID - the routerID is a unique ID associated with a single Island with which it should share the same ID and name. routerName - the routerName is a user created name that can describe the Island/Router group and help the user find the router again. viewpointName - the name of an entry point into the island. This will typically be a TFrame of some sort. viewpointID - the ObjectID of the entry point.
3D Portals
3D Portals (TPortal3D) are just a different kind of portal – one where we can view and manipulate the contents of another (or even the same) space. In the example below, there is a TScrollBox3D around the 3D Portal. The handles of this box allow the user to scroll around inside of the micro space, rotate the portal around any axis, and drag the scale the contents of the TPortal3D.
3D portals are complete miniature copies of existing spaces that are completely accessible and editable by the user. They are inside of a clipping box, which can in turn be inside of another 3D edit box. 3D portals are extremely useful for getting a complete overview of an environment, even when the user is inside that same environment.
This is an example of a 3D portal inside of an edit box. The edit box has the same properties as described above, except that instead of translating the entire contents of the box, the corner rectangles are used to scroll through the 3D space.
Here we see a miniature version of the same space that the user is in. Notice that the windows inside the smaller 3D portal are identical to the outside environment. The girl in the blue dress is actually a miniature version of the user’s avatar. The user is moving the window in the center of screen by manipulating it in the 3D portal, but the full-size version is moving in exactly the same way. This is simply because it is really the same object.
The above image demonstrates how the 3D portal allows the world can be scaled using the 3D edit box scaling rectangles.
A key advantage of 3D portals is that because they are always live working environments, they allow for a god’s eye view editing capability that is simply unavailable in traditional approaches to design. The user can edit a miniature version of an object in the space while experiencing the results of the edit in the full-size space.
The View Portal
Even the Croquet view screen is actually a TPortal. This is basically a TPortal that is used by the camera to render a scene, only instead of having it appear as a link between spaces, it is a link between the user and the space.
Overlay Portals
Any TPortal can also have other TPortals as “overlays”. These are TPortals that are linked to spaces that may contain user interface objects, or may be used to extend the functionality of an Island with a “ghost” overlay. A “ghost” overlay portal makes the content in that overlay look as if it is just another part of the world inside the main space, including giving the user access to modify and control these ghost objects.
System Overlay
The System Overlay is just a standard Croquet overlay that is designed to work with the View Portal. It contains standard Croquet user interface objects, and any additional objects the user may wish to add. The System Overlay is not replicated.
Projections
A Projection is something like a TPortal, but instead of rendering an entire space from a particular point of view, a Projection will render a remote Island TFrame and its children as if it is inside of the local Island being rendered. This allows objects to be moved between Islands extremely efficiently, and allows a single TFrame object in its own Island be useful to a number of users in a number of different contexts at a time.
Typing and Key Entry
Some objects react to the keyboard when they are highlighted by having the mouse pointer over them.
Connecting via LAN and WAN
Master/Participant Connections
The Croquet SDK is a toolkit for building real-time collaborative applications. To really experience what Croquet technology has to offer, you should create a shared, collaborative space inhabited by more than one user. You will probably want two computers on a local area network to try this. Here is how:
First, launch the Croquet SDK, then click on the “First Steps” button on the splash screen. You can then drag a Croquet world object out of the green objects bin to create a live instance of Croquet. We describe two different ways of establishing a shared space below.
Master/Participant Connections
Join a common space using Demo (Master) and Demo (Participant).
1. On one computer, drag the Demo (Master) object out of the objects bin. Croquet will build an instance of the demo world, and make it available for participants to join. The master is ready to be joined once the clouds in the sky start moving.
2. On another computer, drag the Demo (Participant) object out of the objects bin. The participant object will look for a master on the LAN, and after it finds one, it will synchronize itself by copying the state of the shared world, and then begin running it. You will be able to tell you have synchronized with the other user(s) when you see the world and the clouds begin moving.
3. Now that you and the other user(s) have joined the common world, you will be able to see each other’s avatars, and changes made in the world such as moving or creating objects, are reflected in everyone’s copies of the world. If one of the participants leaves the world, their avatar will disappear, but they or other users can rejoin the world.
Master/Master Connections
Establish a connection between two different master spaces using Sailing (Master) and SimpleDemo (Master).
1. On one computer, drag the Sailing (Master) object out of the objects bin. Croquet will build an instance of the boating world, which will then be available for participants to join.
2. On another computer, drag the SimpleDemo (Master) object out of the objects bin. Again Croquet will build an instance of this world and make it available for others to join.
3. From either of the worlds, go to the Talk>Chat menu, and select the “Connect to Another World” option. In the Postcard settings window, select from the popup list of nearby worlds, then click the OK button. This will create a one-way portal to the other world. If you then click in the content area of the portal window to open it, you will synchronize with the other world, and will be able to drive your avatar through the portal to enter your friend’s world.
4. Once you are in the shared world, you and the other avatar can collaboratively update the world. To coordinate your actions, you can use the text or voice chat tools found in the talk menu.
Currently, the connection mechanism is somewhat hard-coded. The system works extremely well once the connection is made. We create a Master Island, there should be only one on a network, and any number of participants. There is a simple broadcast discovery mechanism for local area networks, where all of the routers associated with a master broadcast their existence and location to the other participants. If the participant’s setup has specified an interest in that particular Island, then a join is automatically requested and the Islands are synchronized. Typically, we have labeled the morphs that generate a new master Island/Router pair as Master, and the participant as Participant. For wide area network connections we currently need to set this up by hand. Code illustrating how this is done is in the section below called Connecting. We are developing discovery services that will dramatically simplify this process. Ultimately, this will be as easy as specifying a page location in a browser.
Croquet SDK Bug Reporting
When you report a bug, please make sure to provide information about how to reproduce the bug. Also, if you have any additional information (such as screenshots, a SqueakDebug.log etc.) please attach it to the bug report. All of these items are extremely useful when trying to fix any problems.
