Assignment 4: Minecraft

Overview

In this project, you will implement a procedural walking simulator inspired by minecraft. You will implement both CPU-side procedural terrain generation, and GPU-side on-the-fly procedural texture synthesis using Perlin noise.

Reminder About Teams

Per the syllabus, you may work on this project in self-selected teams of up to two. If you work in a team, in addition to the code submission process described below, each team member must submit an individual Collaboration Report on Canvas (either as raw text in the submission system, or as an attached .txt or .pdf) with answers to the following questions:

  1. In your estimation, what percent of the work did each team member contribute?
  2. Did you pair-program, or did you split up the project into individual tasks? Which parts of the project did each team member work on? (3-4 sentences).

Getting Started

Installing TypeScript

If you already installed TypeScript during the previous projects, you can skip this section. But if you need a reminder of how to install TypeScript on a new machine:

This project is written in TypeScript and will run in your browser. Before you can download and run the starter code, you will need to install the TypeScript compiler, and a minimalist HTTP server that you can run on your machine and that will serve up the Javascript to your browser.

  1. First, install the NPM package manager. You can get it here.
  2. Install the TypeScript compiler tsc, and http-server. If NPM is properly installed, you should be able to do this installation using the commands (might require an Administrator Mode command line on Windows):
npm install -g typescript
npm install -g http-server
npm install @types/offscreencanvas

If the installation is successful, you should be able to run tsc and http-server on your command line (both programs should have been added to your PATH).

WebGL 2.0

This project makes use of several features such as instanced rendering that became available with the release of WebGL 2.0 in 2022. Recent versions of all major projects support WebGL 2.0, but if you are using a very old machine you may need to update your browser to run the reference solution and starter code.

Starter Code

We have provided you with starter code, written in TypeScript and using WebGL, as a starting point for implementing this project. This code already implements a 3D GUI with mouse and keyboard camera controls (updated to only allow walking horizontally, and with more responsive keyboard controls). I’ve also given you some starter code for drawing multiple randomly-placed cubes using instanced rendering (look down at program start to see the cubes).

Build

I have written a script for you (make-minecraft.py) which invokes the tsc compiler on the TypeScript source files in src/, and does some post-processing to combine the Javascript files with static files necessary for the web site to function. The complete web package is installed in dist/. Do not directly edit the files in dist/; all development should take place in the source files in src/.

To compile the code, run make-minecraft.py from the folder that contains it (the project root folder).

Running the Code

To run the starter code, first, you need to launch the HTTP server. From the project root directory (containing dist/), run:

http-server dist -c-1

If successful, you should get a confirmation message that the server is now running. You can then launch the app by pointing your browser to http://127.0.0.1:8080.

Submission Instructions

All submissions must be uploaded to Canvas by the project due date and time. If you are working in a team, only one team member needs to upload the assignment (but see above about the Collaboration Report). In exceptional cases where Canvas is not working, you may turn in the assignment by emailing the TA a Dropbox link, handing him a USB stick, etc, but there will be no exceptions to the project due date–late submissions will be penalize per the syllabus late policy.

Submit your project as a single .tgz or .zip file. In addition to your complete source code, the .tgz file should include a README file containing, at minimum:

  1. Your name and the name of your teammate (if any);
  2. An explanation of any required features that you know are not working completely correctly, but would like to have considered for partial credit;
  3. Anything the milestone-specific specs below ask you to include.

Tip: after uploading your files to Canvas, it is not a bad idea to download them onto a different computer and check that it still compiles and runs, in case you accidentally leave out some important files from the .tgz. It is also wise to try to upload to Canvas well ahead of the final deadline: again, there will be no exceptions to the lateness policy, not even for technical difficulties.

(Important) Technical Details of Grading

  1. The submitted package should include everything needed to build your project, including make-minecraft.py and everything in src/. We will dock points on submissions that do not build correctly “out of the box.”

  2. Do not include the contents of dist/, .git folders, or other extraneous files in your submission.

Required Features

Additional Technical Comments

Adding New Files to the Build

In most cases you do not need to modify the build system manually to add new files. The build system will automatically add source files under the following directories to your project:

src/minecraft

On the other hand, files outside of these directories will NOT be added to the project automatically. For example, if you created a directory called src/shaders/, and added your custom shaders under this directory, these source files would NOT be built until you modify the make-minecraft.py as well.