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. Become familiar with UE4, the use of the Unreal Editor, and visual scripting.
  4. Bake expensive content to a texture.
  5. Introduce methods of performance measurement and comparison.
  6. Work through the submission process we will use this semester.

To ease you into working with Unreal, this assignment is pretty specific about what to do. I expect that by the end of the semester, I'd be able to say, "Bake a material using multiple noise nodes into a texture and compare the performance of the original material with one using the baked texture." In other words, you should 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.

Development Environment

The PCs in the GAIM lab (ENG 005) are available for use for this class. If you have a reasonably powerful PC or Mac, you may be able to use it instead. Pay attention to the listed minimum system recommendations for UE4. 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. It is also a bad idea to try to use UE4 on a VM, because the overhead is too great, especially for graphics-heavy work.

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).

No matter what platform you use, you will need to buy a USB stick or USB drive of at least 64 GB. If you are primarily working on the lab computers, this will give you sufficient space for development that you can take with you and easily move between computers. If you are working at home, this will keep your files on portable form to show the TA or me when you have problems.

Submission

Since it takes a significant amount of time to build UE4 (especially once we start making changes to the engine code later in the semester), multiplied by the number of students if we need to build to grade, we will mostly not be directly running your projects. We'll look at what you commit through git, and at 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 the repository on your USB 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.

Details

assignment 1 sample resultsNumbed items are things you need to do, bullets below them are possibly helpful comments.

Get set up

  1. Create a Github account if you do not already have one.
  2. Send me your github username, so I can give you access to the class material. You will not be able complete step 7 of this part, 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. Follow the directions to enable SSH github access.
    • I recommend against a separate SSH passphrase for this.
  7. Fork the UMBCGAIM/g4g2018 class repository to get your own copy on github.
  8. Under "Settings" for your g4g2018 fork, choose "Collaborators & teams", and add me (olano) and the TA (shashankbukka) as collaborators with Write permission.
    • We'll need that to grade, and will deliver grades back to you by checking a rubric text file back into your repository.
  9. Clone your copy to your USB drive.
    • 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 revision (about 5 GB), instead of the entire history of UE4 (about 15 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 --depth 1 --no-tags repositoryURL", where repositoryURL is the URL you get from the "Clone or Download" button on github.
  10. If you are not working in the lab, get OBS Studio for recording video, and the C++ compiler tools for your platform (Visual Studio for Windows, free from imagine.microsoft.com; Xcode for Mac).
  11. Run the Setup script in the g4g2018 directory on your USB drive.

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 Development build of UE4Editor.
    • This will likely take at least an hour. Fortunately, you will not need to do a full build often.
    • Later, you might want UnrealLightmass as well, but we won't need it yet.
  4. Run UE4Editor to make sure it worked.

Create an Unreal Project

  1. Create a new blank Blueprint project without starter content. Call the project "assn1" and save it at the top level of g4g2018 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.
    • Also, if you put it at the top level of your git repository, when you re-run GenerateProjectFiles, your assn1 project will appear when you open UE4 in Visual Studio or XCode.
  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 that's "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 Content and Config directories. Don't commit anything from the Binaries, DerivedDataCache, Intermediate, or Saved directories.

Create a test scene

  1. Create a level named "assn1".
  2. Add three planes.
  3. Use Text Render Actors to label them them "Baseline", "Computed", and "Baked".

Make the "Baseline" test case

  1. Create a new unlit Material for the "Baseline" plane.
  2. Connect a constant color of black (0,0,0) to Emissive Color.
    • This will allow us to measure how much time is spent on stuff other than the material.

Make the "Computed" test case

  1. Create a new unlit Material the "Computed" plane.
  2. Use at least a couple of Noise nodes to make a cloud-like texture, connected to Emissive Color. Use texture coordinates as the input to the Noise nodes.
    • Using the texture coordinates makes sure the Computed and Baked cases will be the same scale
    • You'll need to use the "AppendVector" node to add a third component to the 2D texture coordinates.
    • It doesn't need to look exactly like mine. I expect everyone's to look a little different.
    • In fact, I don't care that much what it looks like as long as you've hooked up a couple of noise nodes in the Material editor.

Create a Blueprint to bake the "Computed" material

  1. Create a Render Target texture.
  2. Make an Actor Blueprint, and use DrawMaterialToRenderTarget to draw the "Computed" material into the RenderTarget on BeginPlay.
    • Do not use the built-in "Bake Materials" button. The point is to create a simple Blueprint (plus baking yourself gives more control over the process).
  3. Place this Blueprint in your scene.
  4. When you hit "Play", the Render Target texture should be filled in

Make the "Baked" test case

  1. Create a third unlit material for the "Baked" plane that uses texture coordinates to look up in the render target texture.
    • The "Computed" and "Baked" planes should look identical.

Benchmark

  1. Run in a separate window (using Play in Editor, otherwise known as PIE).
  2. Collect at least five timings with a screen-filling view of each of the planes.
    • Use the ProfileGPU console command, or Ctrl-Shift-Comma (PC) or Command-Shift-Comma (Mac).
  3. Report the mean time for each, as well as the mean difference from Baseline.

Video

  1. Use OBS to record a short video of your running project.
  2. Show us your computed and baked materials, your blueprint, and the project playing in the editor.
  3. Upload that video to youtube or your google drive.

Submitting

  1. For full credit, you must commit multiple times during development.
    • We'll be looking for your development process, so make sure the commit messages are somewhat meaningful, and at meaningful points along the way.
  2. Add an "assn1.txt" to the top 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. Include the average reported time for each of your three materials, the difference between the Computed and Baked cases and the Baseline, and the screen size used for timing (as reported by the r.SetRes console command.
    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, asssn1.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.
    • Wait to tag until your final commit.
  5. Add an "assn1" Tag for your final commit.
    • The command-line command for this is "git tag assn1", then "git push origin assn1".
    • You should push your changes before midnight, but can still tag an existing commit after the deadline. Since it is tricky to move tags once they are made, this is probably a good idea.

Grad Students

Also add a blueprint to switch between the three materials on a single plane when the user hits "1", "2" or "3". Note that you'll need to enable keyboard events for that Blueprint.