Project 0, CPSC 314 Jan 2016

This preliminary project will get you started with the course, and has four parts. First, you'll make sure that your machine is set up with the infrastructure you need, including using either a text editor or an IDE to edit JavaScript, configuring your web browser to access local JavaScript files, version control (for example with git). You'll also want to check out the basics of JavaScript if you haven't used it before. Second, you'll get started with running an example WebGL/JavaScript program and making a few simple changes to it, and learning how to use your browser's JavaScript debugger to inspect and change the running program. Third, you will also read the academic conduct guidelines for the course and certify that you understand them. Fourth, you'll set up and test the handin command.

This preliminary "Project 0" is mandatory but not marked; we will not mark your Project 1 until we see that p0 has been handed in as required below.

1. Development Environment
   • Editing Code

     You will need to edit Javascript and HTML files on your machine. You have two choices: a standard text editor, or an IDE (Integrated Development Environment) like Eclipse.

     • Standard text editor: You can simply edit Javascript and HTML files with your favorite text editor, reload the file in the browser to run the new code, and use the built-in debugging support in the browser. One popular multiplatform code editor is sublime. The default simple editors TextEdit for Macs and Notepad for Windows are also popular. Just remember that you should never try to use Microsoft Word for coding!
     • IDE: You can also can edit Javascript files through the Eclipse IDE, which should be familiar to you from working with Java files in previous courses. If you have not used Eclipse for Javascript before, see the Getting Started in Eclipse with JavaScript resource page.
   • Web Browser

     We recommend using either Chrome or Firefox. You may run into compatability problems with Safari or Internet Explorer.

   • Running Local Code

     Since JavaScript is typically sent from a server, by default most web browsers do not allow accessing JavaScript files stored on your local computer, for security reasons. However, while you are developing WebGL/JS in this course, you will find it very useful to be able to access local files, for example JavaScript libraries! There are two solutions.

     Quickly grab the code for this project.

     The easiest option, which we recommend, is to simply enable your browser to run local JavaScript. On Chrome in Linux, you will need to start the program with the command-line flag google-chrome --allow-file-access-from-files. On Mac OS quit Chrome and use the command

     open -a "Google Chrome" --args --allow-file-access-from-files

     . Here are several pages with instructions on how to enable local file access:
     • Three.js guide to running things locally (multiple browsers)
     • Chrome instructions from www.chrome-allow-file-access-from-file.com
     • Another Chrome guide from voxelent
     • Firefox instructions for running locally.

     The alternative solution is to install and run a web server on your computer, such as WAMP or LAMP.

   • Version Control

     We strongly recommend that you use version control. It's particularly crucial for teams, but it's highly desireable even if you're working individually. We recommend git, but you are welcome to use another package if you prefer.

     • Download git and install it if you do not already have git loaded on your machine. If you will be using Eclipse, then download EGit as well.
     • We recommend using BitBucket because it allows you to make a private repo for free. Note that github only allows public repos if you're using it for free. (You do need to keep your code for this course private!)
   • JavaScript Basics

     You will need to familiarize yourself with the basic syntax of JavaScript.

     • JavaScript tutorial, reasonable place to start if you haven't used JavaScript at all before
     • Compact description of JavaScript, particularly good for people who have a solid understanding of Java already
     • Important concepts of JavaScript, further reading on JavaScript
     • JavaScript API

2. Example WebGL/JavaScript Code

   The example code PO Webgl-Sandbox uses Physijs, which is a wrapper for the ammo.js project, which is a port of the Bullet physics library.

• Download Files
  • You can either clone the git repository, or just download the source (as a tar or zip file):
    • to clone the repository on the command line, using the command

      git clone https://Glen_B@bitbucket.org/Glen_B/webgl-learning.git

    • or you can clone the repo using eclipse
    • or you can download the repository and unpack it with the command tar -xvzf filename.tar.gz.
• Run Code

  • Load the file example/vehicle.html in your browser. You should see a red car that you can drive forward by pressing the up arrow key; turn using the left and right arrow keys. The physics simulation includes collision and friction computations: try crashing the car into the blocks to see what happens!

    This HTML file loads the JavaScript file examples/vehicle.js file that is loaded by examples/vehicle.html.

• Edit and Debug JavaScript

  If you're using Eclipse, start it up and import the project. If you're using a text editor, load the file into it. Just reload the page in the browser to see the results of your edits.

  The debuggers in both Chrome and Firefox have very similar capabilities:

  • Debugging in Chrome
  • Debugging in Firefox

  Try using the debugger built into your browser to do each of these operations:

  • Setting breakpoints
  • Stepping in and over
  • Printing/showing values
  • Changing variables
• Make Changes

There are three primary code changes that you should make in example/vehicle.js. Search for the string "CHANGE", which marks the locations in the code where you should make your edits.

1. CHANGE: the force applied from the engine. Something like 3000 has an interesting effect.
2. CHANGE: the number of boxes in the simulation. Try decreasing to a small number, like 5. Try increasing to a large number, like 500, and notice how the simulation slows down.
3. CHANGE: Try adding some new geometry in the scene. For example, try using cones instead of boxes. Hint: you might want to reduce the number of cones!
• Take Screenshot

  Take a screenshot of the browser window after you have changed the number of boxes in the simulation. Use the built-in capabilities of your operating system (Linux, Mac, or Windows). Your screenshot should be in PNG format. Instructions:

  • Windows screenshots
  • Mac screenshots
  • Linux screenshots
3. Academic Conduct Guidelines
   • Carefully read through the three pages that deal with plagiarism, cheating, and academic misconduct:
     • Course-specific guidelines at http://www.ugrad.cs.ubc.ca/~cs314/Vjan2016/cheat.html
     • Tamara's general discussion at http://www.cs.ubc.ca/~tmm/courses/cheat.html
     • Department guidelines at http://www.cs.ubc.ca/about/policies/collaboration.shtml
   • As part of this lab, you will to confirm that you have read and understood these guidelines. Ask Tamara right away if you have any questions, either on Piazza, by email, or in person.

4. Handin

   You will now set up and test the process of handing in your project using the handin command.

   • Make a new directory called cs314 in your home directory, and then a subdirectory within that called p0. It's best to have keep your working directories separate from your handin directories, and just copy files over when you're ready to hand things in.
   • For this assignment, you will only need to hand in four files.
     • A screenshot in png format of the simulation after it has been modified with a different number of boxes
     • the JavaScript file vehicle.js (which should have minor alterations)
     • the HTML file vehicle.html
     • a README.txt file that includes
       • name, account id (four or five characters), and student number for every member of the team (or just you, if you're working individually)
       • A very brief description of what changes you made to the P0 source.
       • The statement statement "I/we have read and understood the cheating policies at http://www.ugrad.cs.ubc.ca/~cs314/Vjan2016/cheat.html".
   • Hand in this project with the command

     handin cs314 p0

     You do not need to be in any particular directory to run this command; handin will automatically use the contents of ~/cs314/p0 no matter what directory you are in when you run it.
   • You can check what you have handed in at any time by simply looking at the contents of the directory. You should also check using handin -c to doublecheck that the handin was successful.