Overview

For this assignment, will be primarily getting your environment set up and getting used to working in the Unreal Engine

To ease you into working with Unreal, this assignment is pretty specific about what to do. Expect that subsequent assignments will rely more and more on your ability to figure out how to do what is required. This may require searching for help online or experimenting on your own. On this and future assignments, graduate students (those taking the class as CMSC 691) will have additional component(s) that are less clearly defined and may require more research or experimentation to complete.

Assignment Goals

The primary goals of this assignment are:

  1. Become familiar with the GIT version control system.
  2. Make a successful build of the Unreal Engine 4 (UE4) from source.
  3. Gain experience with UE4 and the Unreal Editor.
  4. Gain experience with shader code.
  5. Work through the submission process we will use this semester.

Development Environment

If you have a reasonably powerful PC or Mac, you should be able to use it. In general, if you would not want to play a modern 3D game at a reasonably high quality setting on your computer, you probably do not want to use it for this class.

We have a limited number of systems in the GAIM lab on campus (ENG 005a) that can be used for this class. If you think you might need to use one of these for work in this class, let me know as soon as possible.

It is also possible to do the work in this class on an Amazon EC2 instance. I recommend a g4dn.xlarge Windows instance using the NICE DCV template, with EBS root volume drive size increased to 150 GB. At current rates, this instance costs $0.71/hour, plus $15/month in storage costs. At these rates, I'd expect work in this class to cost you about $70-150. If you do use Amazon, be sure to stop the instance when you are done to avoid racking up continuous charges while it is sitting idle.

Most UE4 engine development takes place on Windows, so that tends to be the most stable and tested platform. I also test everything I ask you to do in this class on Mac. It is possible to build UE4 for Linux, but that is the least well supported platform, and I am not able to test or trouble-shoot there. Consequently, if you do elect to try to build UE4 on Linux plan significant extra time to figure out issues on your own (or time to abandon Linux if you get stuck).

If you are working on your home PC, you will need about 150 GB of free disk space. If you don't have that much, you can use a USB SSD drive. Note that, though they are more expensive, you'll definitely want an SSD (with ~500 MB/s read and write speeds). Regular flash drives tend to have transfer speeds closer to 150 MB/s, which can make file-heavy operations including compiling quite painful.

Submission

Since it takes a significant amount of time to build UE4, we will mostly not be directly running your projects. We may occasionally build and run a specific project or ask you to demo it, but just building every submitted project would take 30-40 hours and about 4 TB of disk space. Instead, we will mostly grade based on visual inspection of your git commits and code, as well as video of your running project that you will record and upload.

We will be looking for multiple git commits with meaningful commit messages during your development. These should be made using a local git client to the clone of your repository on your local drive, then pushed to your fork of the repository on github and submitted by tagging the revision you want to submit when you are done. Do not, under any circumstances, use the github interface to upload any file changes.

Details

Here's a detailed description of what you need to do for this assignment. Numbered items are things you need to do, bullets below them are possibly helpful comments. The steps that have some waiting time (from a few minutes to a few hours) are marked with ⏱, with notes on how long it took on my 2.6 GHz quad-core i7 Mac with SSD, and an approximately 45 Mbps internet connection.

Get set up (see the Overview lecture slides)

  1. Create a Github account if you do not already have one. If you already have a fork of the Unreal Engine in your github account, you will need to create a new github account for this class, as you are allowed only one fork of any upstream repository.
  2. Fill in this form to provide me with your github username and information about what computer you might use for this class. Once you have done that, I'll be able to give you access to the class material. You will not be able complete step 6 of the setup, or anything after it, until you have that access.
  3. Create an Epic account if you do not already have one, and link your Github account to your Unreal Engine profile.
  4. Join the Epic Games github group.
  5. Get a GIT client. You should never commit through the github web interface for this class.
    • Command line tools come pre-installed for Mac, or can be downloaded for any of Mac, Windows or Linux.
    • SourceTree is a free visual interface for Windows or Mac.
    • There are a bunch of others as well. If you have a favorite, use it.
  6. Fork the UMBCGAIM/g4g2021 class repository to get your own copy on github.
    • Under "Settings > Collaborators & teams" for your g4g2021 fork, and add me (olano) and the TA (iboutsikas) as collaborators with Write permission. We'll need that for grading.
    • In the same spot, remove any team access. The original had access for the entire class (so you could fork it), but yours should not.
  7. Clone your copy to your local drive. ⏱ (<5m)
    • UE4 does not like non-standard characters in the path. If you have anything other than standard ASCII characters in the path to your home directory, or spaces in that path, you should put the clone somewhere other than your home directory
    • I recommend using the command-line tools for this step, even if you are using a visual interface for everything else. This will allow make a shallow clone with only the most recent release revisions (about 2 GB), instead of the entire history of UE4 (about 21 GB).
    • On PC, right click in a directory window and choose "Git Bash". On Mac, you can access them in a Terminal window.
    • Use git clone --shallow-since=8/18/2021 repositoryURL, where repositoryURL is the URL you get from the "Clone or Download" button on github.
  8. Run the Setup script in your g4g2021 directory. ⏱ (25m)
    • This downloads a number of additional large files that are not in the git repository. If your internet connection is slow, it can take a while.

Do a test commit (see the Overview lecture slides)

  1. Edit the .gitignore file to continue to ignore the Engine Content directory, but not ignore project Content directories
  2. Add it to the files to be committed
    • If using command-line git commands:
    • Do a git status to see that it is marked as edited
    • Do a git add .gitignore to add it to the commit staging list
    • Do a git status again to confirm that it will be committed and no other files are modified
  3. Commit the change
    • If using command-line git commands, use git commit -m "short message describing this commmit"
  4. Push your commit back to github
    • Do a git pull to make sure you are up to date
    • Do a git push to upload your changes to github
    • Log into github to confirm that the commit is there

Build UE4

  1. Run the GenerateProjectFiles script.
    • You will need to re-run this only when you add or remove source files.
  2. Open the generated project file (The newly created UE4 Visual Studio solution or XCode project).
  3. Do a build. ⏱⏱⏱ (3.5h)
    • In Visual Studio:
      • Right click on UE4 in the Solution Explorer window, and choose "Set As Startup Project".
      • Make sure the configuration boxes in the toolbar just below the menus are set to Development Editor, Win64, and UE4.
      • Build just UE4, not the entire solution, either by pressing the play button in the top menu bar (this will start the next step as well when the build is done), from the menu that pops up when you right click on UE4 in the Solutuion Explorer, from the Build menu, or using Ctrl+B when UE4 is selected in the solution explorer menu. Building the entire solution includes dozens of additional auxilliary tools that we do not need that will make the already long build time even longer.
      • Watch the Output window for progress.
      • If build errors happen, it will switch to an error list window, but usually the full message in the build Output window is more useful for figuring out what went wrong. At this stage, this is most likely running out of disk space or path problems, though it is possible you could have a message indicating something else should be installed to complete the build on your computer.
    • In Xcode:
      • Select UE4 in the toolbar box next to the play and stop buttons
      • Build just UE4, either by pressing the play button in the top menu bar (which will also start running when the build is done), from the product menu, or using ⌘B
      • Follow the build progress by opening the Build window in the Report Navigator (last tab icon just below the play button)
    • This will likely take at least an hour, and quite possibly several. Fortunately, you will not need to do a full build often.
  4. Run UE4Editor to make sure it worked. ⏱⏱ (50m)

Create an Unreal Project

  1. Inside the UE4 Editor, create a new blank Blueprint project without(!!!) starter content. Call the project "assn1" (lower-case please!) and save it at the top level of your g4g2021 directory.
    • We won't be using the starter content for this (or any) projects, and it adds a ton to your git repository size.
    • We do want the name and location to be the same for everyone to ease grading.
  2. Now would be a good time to commit a checkpoint of your progress.
    • Be sure to save in the UE4 Editor before you commit.
    • Look at what it wants you to commit before you do it (command-line: git status).
    • You will need to stage the things you want to commit (command-line: git add files).
    • This should be the assn1.uproject file, and everything in the assn1/Content and assn1/Config directories. The gitignore file should keep them from being included, but be sure not to commit anything from the Binaries, DerivedDataCache, Intermediate, or Saved directories.

"Do" the cloud project

  1. Save the default level with the name assn1
  2. In Settings > Project Settings, set assn1 as the Editor Startup Map, so it'll automatically go into that map/level
  3. Follow the directions from the shader walkthrough lecture to create a cloud sphere.
  4. Commit along the way.

Grad Students

This part is only 10 points of the project grade, so don't turn the project in more than a day late to get it done if the rest is working

Use 3D texture advection to add motion to the cloud shader from the shader walkthrough lecture.

Texture advection first appeared in a visualization paper by Max and Becker in 1995. It was popularized in games by a 2010 SIGGRAPH presentation by Alex Vlachos detailing its use in the Left 4 Dead 2 and Portal 2. However, the best resource for this project is the 2012 GDC presentation by Carlos Gonzalez Ochoa about the fluid rendering in Uncharted. This presentation includes a slide with the handful of lines of shader code necessary to implement the effect in 2D. I also have a shadertoy demo that does something similar in the GLSL shading language instead of the HLSL language used by UE4.

  1. Figure out how to generate Curl Noise in shader code to use as your 3D flow field. It is one of the options in the Vector Noise material node.
  2. Figure out how to access time in seconds (not frames) in your shader code.
  3. At each ray march step, use curl noise to find a flow direction, then blend together two offset 3D noise evaluations to compute the cloud density.
  4. Tune curl noise scale, flow magnitude, and flow speed to reasonable values.

Submitting

Material Graph

Take a screen shot of your material graph, sufficient to read any material node names & values.

  1. You can either use the standard Windows/Mac screen shot tools, or the EditorScreenShot console command.
  2. Move/save this screen shot image to your assn1 directory.
  3. Image files are set to be ignored by git in the .gitignore file. You can force it to add these anyway with git add -f screenshot.png

Video

Use Sequencer to render a 15 second movie at 1280x720 resolution at 30 frames per second (450 frames), with the camera moving around the cloud.

  1. Add a Level Sequencer Cinematic to the level.
  2. Add a Cine Camera actor to the sequencer.
  3. Make sure the camera is pointed at your cloud object (you can use the rotation controls, or the camera’s “Look At” property.
  4. Make sure the cut length is 450 frames.
  5. Render the movie to a video file.
  6. Upload your video to youtube, vimeo, box, google, or other site where we'll be able to watch it.
    • Recording and sharing videos this way is a great way to show off your work, especially when looking for a job. You are unlikely to convince anyone with an ounce of security sense to download and run a random executable, but you may be able to get them to watch a short interesting video clip.

Git Submission

Make sure everything is submitted and tagged

  1. For full credit, you must commit multiple times during development. This will be part of your grade on every assignment in this class.
    • We'll be looking for your development process, so make sure the commit messages are somewhat meaningful, and at meaningful points along the way.
    • One commit per file once you are done does not count. Committing a zip of your directory does not count. Emailing me or the TA a copy of your project does not count.
  2. Add an "assn1.txt" to your assn1 directory.
    1. Include your name and campus ID at the top of this file.
    2. Describe your test computer (at least OS, CPU, and GPU).
    3. Describe what is and is not working in your project.
    4. Include the link to the video of your running scene, and make sure we can access it.
  3. Be sure to commit all of the necessary files: your assn1.txt, material graph image, assn1.uproject, and all uassets and umaps.
  4. Push your changes back to your personal github repository.
    • You can and should do this multiple times during development.
    • There won't be any external changes unless you're using git to work in more than one place (which you can totally do), but the usual sequence is git pull to first get anything that's changed on github, followed by git push to upload your changes.
  5. Add an assn1 tag for your final commit.
    • Git tags are typically used to mark releases. For our purposes, your completed assignment is a release.
    • The command-line commands for this are git tag assn1, then git push origin assn1.
    • You should push your changes before midnight, but can tag an existing commit after the deadline. Since it is tricky to move tags once they are made, it is probably a good idea to tag the day after your final submission.
    • If you do need to re-tag you will need to git tag -d assn1" to remove the local tag, git push --delete origin assn1 to remove the tag from github, then follow the tagging directions again to re-tag