GraphicsTown UI Basics
You have been using the Graphics Town framework for the prior workbooks. The changes made for this workbook are small, and are specific to Graphics Town.
The documentation for the framework is framework code documentation, but as always, the code is the main documentation.
The main difference for GraphicsTown is that we are going to use some features that make it possible for a user to appreciate a town built in it. You should make sure that these features work in your program. They should work if you use the framework correctly. We provide a control panel (
WorldUI). Please do not remove the
WorldUI - you can add things to it, but please do not remove any of the functions.
The key features:
- The UI provides the ability to stop the animation (the
runcheckbox), and to control the animation speed (the
speedslider). In order for this to work, you need to implement your behaviors correctly (see below).
- The user needs to be able to move around the world in order to explore the town. The framework provides two different types of camera controls (orbit and flying). It also provides other ways to position cameras relative to the objects.
- The user needs to be able to find the interesting objects quickly. The UI provides a “lookat” dropdown that lists all objects, as well as a “highlighted” objects list that allows these to be found quickly. This requires defining the objects correctly (see below).
- The user should be able to “follow” a moving object (so see how it moves around in the world). At least some objects should be followable. In the framework, this requires the
rideableproperty to be set (see below).
- The user should be able to “ride” a moving object (and see the world from that object’s point of view). At least some objects should be rideable. In the framework, this requires the
rideableproperty to be set (see below).
To get all this functionality, you simply need to create your objects correctly! You do not need to implement the UI. We’ve done it for you. You should check that we can look at your objects by picking them with the UI, and ride (and follow) your moving objects.
If you change the UI, please be careful not to break the functionality. We do need to be able to click on objects in the list to look at them.
There is a “grader” button - please leave this in place. If you’re curious, what it does is fetch a script from our server and runs it on your object list. The script hasn’t been implemented yet. We might put something there to help you test your code.
The UI code allows objects to be “looked at” (you select an object and the camera is teleported to look at that object by changing the lookfrom and lookat points). Each object has a
lookFromLookAt method. It makes a guess of where to put the camera based on the object’s bounding box, but this is a guess. Object’s can override this method to do a better job.
If you point the camera at a moving object, you point the camera at where the object is at the moment you move the camera. After that, the regular camera controls apply. Look at works best with non-moving objects. Use “Follow” to watch where an object goes.
Because the list of objects to lookat can get long, the UI has a second selector for “highlighted objects”. It behaves just like the “lookat” list.
To put an object on the “highlighted” list, you set its
highlight member field to true. You should only highlight objects that are described in the rubric and text boxes. There is an example of how to highlight objects in
grtown.js - this looks the objects up by name.
If an object is rideable, you can also follow it. To do this, first ride it, then select “follow object” from the camera type drop down. If you ride another object, it gets switched. See making objects ridable below.
Right now, follow tries to estimate a position for the camera based on the object’s bounding box. It places itself behind (in the Z direction) and slightly above the object. Guessing how to position the camera based on the bounding box is problematic.
The Initial Camera
The initial camera configuration is based on the groundplane. If you don’t have a groundplane, you must specify the initial camera configuration when you create the GrWorld.
The Framework uses THREE’s flying controls. They aren’t great, and they aren’t documented. Drag the mouse to turn (be careful: if you drag outside the canvas it will miss the mouse up event). WASD to move, Q and E to roll.
stepWorld method of
GrObject to animate things. The basics were introduced in workbook 8. You can put the behavior into a class (like the example does with
SpinCube in 08-07-02.js). Over the later workbooks, you saw the use of tricks like adding methods to the objects after the object is created.
SimpleBehaviors.js in the Framework folder has an example. Hidden in workbook 11, page 2 are more examples (the
spinY function adds a method to an object, but the code to blink an object also adds a
stepWorld method, and takes advantage of the non-lexical
11-02-02.js in workbook 11.
You should use the time delta passed to
stepWorld not the “clock” time (as we have in prior workbooks). If you use the time delta parameter, your objects will correctly stop when the world is stopped, and have their speeds controlled by the speed slider. The delta parameter is the number of milliseconds the world should advance.
For more complicated behaviors, you will need to keep track of time. The
stepWorld method is given an amount of time (delta) that things advance, but isn’t given the actual resulting time. You may need to keep a variable inside of the object that gets incremented each time.
We do not recommend you use THREE.JS’s animation system - it is complicated to figure out, and will not work well with the Graphics Town framework (it is unclear how to integrate the “play” loops of each action with the animation loop of
GrWorld). The course staff will not help you use THREE.js’s animation system.
Making Objects Rideable
The user interface allows the camera to be placed so that the user “rides” and object. In order for this to work, the object needs to be defined so that its center is at the origin, and the direction of travel is along the positive Z axis.
In riding mode, the object is not drawn (otherwise, you’d see the inside of the object). This is done by hiding it.
GrObject you set the
rideable variable to be an
Object3D that has the correct motion (the camera will be placed at the origin of this object’s coordinate system, and will face towards its positive z axis).
To make a particle effect, you can either make each one be a separate shape (triangle or cube), or use a
Points object (where each particle is a tiny dot - and then you use a
You are required to use at least one model file. You can find free models all over the web. OBJ is the simplest file format, but it can be problematic. More modern file formats are often more robust.
THREE has loaders for many file formats, however they are not part of the main system. We have included the loader for OBJ files and FBX files with the Graphics Town Repository. We have also provided interfaces to make using these loaders easier within the framework.
If things don’t work as expected, be sure to check the console log for errors. Because the loaders are not part of the “core” of THREE, they often have dependencies that must be loaded separately.
Also, be aware that using a model can be challenging. For one, there are issues that the author may have created the model as a scale or position that isn’t convenient for you. Also, there are lots of broken model files around the web. These include incorrect normals, missing parts, or even files that are not valid data.
Time of Day
The Framework has support for “time of day” as an extra parameter to the
stepWorld method of
GrObject. This is for future expansion. Right now, the parameter is not used, and your objects can ignore it.
Using Other Parts of THREE
We did not include all of THREE.js in the workbook. In particular, the complete examples set includes useful tools such as loaders for more file formats and subdivision surfaces. If you want to use on of these components, you need to add it to the workbook. The course staff can give you some guidance, but we cannot help you use parts of THREE beyond the core pieces we give you.