Overview

This assignment is primarily about getting your environment set up, getting used to working in the Unreal Engine, and working out how to submit for this class. In addition, in this assignment, you will be working with HLSL shader code, a C-like language for GPU programming.

Part of the goal of the course is to develop skills for working in large projects. 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.

Assignment Goals

The primary goals of this assignment are:

  1. Become familiar with the Git version control system.
  2. Gain experience with UE5 and the Unreal Editor.
  3. Gain experience with shader code.
  4. 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 plan to work in the lab, you MUST get an external SSD drive.

It is also possible to do the work in this class on an Amazon EC2 instance. If you go this route, I recommend a 4-core g4ad.xlarge Windows instance using the NICE DCV template, with EBS root volume drive size increased to 350 GB. At current rates, this instance costs $0.56/hour that it is actively running, plus $42/month in storage costs. The g5's and g6's are newer GPUs, but we will be fine with the cheaper g4's. The g4ad instances have AMD GPUs, while the g4dn instances have NVIDIA (and are a little more expensive to run). You can temporarily switch to a 64-core g4ad.16xlarge at $6.41/hour for faster compiles (e.g. about 20 minutes!). At these rates, I'd expect work in this class would cost you about $150-$200. 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. I usually set up an Amazon CloudWatch event to stop the instance if the CPU load is low for more than about 20 minutes, though this won't help if you accidentally leave something running on the instance.

Most UE5 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 UE5 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 UE5 on Linux plan 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 an SSD with about 250 GB of free disk space. If you don't have that much, or if you have a spinning hard drive, you can use a USB SSD drive. You'll definitely want an SSD (with ~500 MB/s read and write speeds), instead of a hard drive with 200 MB/s transfer speeds, or regular flash drives with transfer speeds closer to 150 MB/s. Compiling UE5 is very disk-intensive, and can be extremely painful on a slow disk!

Submission

Since even just the build process will take a while in UE5, and require significant disk space, we will mostly not be directly running your projects, though we may occasionally build and run one or two student's projects or ask you to demo it. Instead, grades will mostly be based on visual inspection of your git commits and code, as well as video or images 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 use the GitHub interface to upload any file changes. It mangles the line endings in text files, which makes our access and grading significantly more difficult. Making your grader's life difficult is never a good idea!

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 a 4 core, 2.3 GHz, 16 GiB Amazon instance with SSD, and an approximately 5 Gb internet connection.

Get set up (see the Setup lecture slides)

  1. Download a copy of the Unreal Engine, version 5.6.x
    • Create an Epic account if you do not already have one
    • Download the "Epic Games Launcher"
    • Download the Unreal Engine, version 5.6.x
  2. 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.
  3. →→ 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 manually invite you to the class github team. Allow up to 24 hours for me to see your response and send the invitation.
    • Look for an invitation email in the mail account you used to sign up for github
    • You must accept that invitation to get access to the class repository
    • You will not be able complete step 6 of the setup, or anything after it, until you have that access.
  4. Link your Github account to your Unreal Engine profile and 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/g4g2025 class repository to get your own copy on GitHub.
    • You will not have access to complete this step until you have completed the form in step 2 and I have manually granted you permission.
    • Do not rename the fork from g4g2025. We have grading scripts that rely on that naming convention.
  7. Clone to your local drive. ⏱ (5m)
    • UE5 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 if you have spaces in that path, you should put the clone somewhere other than your home directory
    • UE5 also does not like it if the total path length is too long. The path to where you clone g4g2025 should be about 50 characters or less
    • 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, instead of the entire history of UE5, saving about 29 GB and maybe half an hour of download time.
      • 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/11 repositoryURL, where repositoryURL is the URL you get from the "Clone or Download" button for your g4g2025 fork on GitHub.
  8. Run the Setup script in your g4g2025 directory. ⏱ (25m)
    • Setup.bat for windows, Setup.command for Mac, Setup.sh for Linux
    • 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.

Create an Unreal Project

  1. Launch your copy of the Unreal Editor from the Epic Games Launcher
  2. Inside the UE5 Editor, create a new blank blueprint project. Call the project "assn1" (lower-case please!) and save it at the top level of your g4g2024 directory.
    • Do not choose a different name or location. We rely on the name and location to be the same for everyone to ease grading.
  3. Now would be a good time to commit a checkpoint of your progress.
    • Be sure to save in the UE5 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 files from the assn1/Config directory. If you've waited until later to commit, you may also see files from the assn1/Content directory. 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 demo lecture to create a cloud sphere.
    • When you get to the step to create a ush file, be sure to put it into the project Shaders directory
  4. Commit along the way.

Grad Students

Do any one of the extensions listed in the last four slides of the Shader Walkthrough lecture. 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.

Submitting

Git Submission

  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 a copy of your project does not count. Commit and push early so you won't be scrambling with any unexpected problems at the end.
  2. Add an "assn1/assn1.txt" file with notes on your assignment.
    1. Include your name and campus ID at the top of this file.
    2. Describe what is and is not working in your project.
    3. Include the image and video links mentioned below and make sure we can access them.
  3. Be sure to commit all of the necessary files: a git status should not report any files.
  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. Once you are done, 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.
    • You should push your changes before midnight, but can tag an existing commit after the deadline. The tag will inherit the date of its commit. 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.
    • The command-line commands for this are:
      • git tag assn1 (tag locally)
      • git push origin assn1 (explicitly push the tag to GitHub)
    • Since tags are git's way to handle software releases, they are not designed to move once made. If you realize you forgot something and need to re-tag to a different commit, you will need to remove the local tag and the tag on GitHub, then retag:
      • git tag -d assn1 (delete the local tag)
      • git push --delete origin assn1 (delete the tag on GitHub)
      • git tag assn1 (retag locally)
      • git push origin assn1 (push the new tag back to GitHub)

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. Share this image in google drive, box, one drive, or similar and include the link in an assn1/assn1.txt file

Video

  1. Record a 15 second video with the camera moving around the cloud. You can use the UE5 Sequencer, windows game bar recording, or even a recorded single-participant WebEx or Zoom "meeting". The last of those options is probably easiest! Please do record directly from the screen, not from a phone or device pointed at the screen.
  2. Upload your video to youtube, vimeo, box, google, or other site where we'll be able to watch it and include the link in your assn1/assn1.txt.
    • 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.