Overview

For this assignment, will be primarily getting your environment set up, getting used to working in the Unreal Engine, and working out how to submit for this class.

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 5 (UE5) from source.
  3. Gain experience with UE5 and the Unreal Editor.
  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. I recommend a 4-core g4ad.xlarge Windows instance using the NICE DCV template, with EBS root volume drive size increased to 300 GB. At current rates, this instance costs $0.56/hour that it is actively running, plus $30/month in storage costs. You can switch to a 64-core g4ad.16xlarge at $6.41/hour for faster compiles. At these rates, I'd expect work in this class to 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.

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 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 an SSD with about 150 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, which can make file-heavy operations including compiling extremely painful!

Submission

Since it takes a significant amount of time to build UE5, 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 or images of your running project that you will record and up!oad.

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 a 4 core, 2.3 GHz, 16 GiB Amazon instance with SSD, and an approximately 5 Gb 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/g4g2022 class repository to get your own copy on github (you will not have access until you have completed the form in step 2 and I have manually granted you permission).
    • Under "Settings > Collaborators & teams" for your g4g2022 fork, 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)
    • 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 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 UE5 (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=7/11/2022 repositoryURL, where repositoryURL is the URL you get from the "Clone or Download" button on github.
  8. Run the Setup script in your g4g2022 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 UE5

  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 UE5 Visual Studio solution or XCode project).
  3. Do a build. ⏱⏱⏱ (17.5h)
    • In Visual Studio:
      • Right click on UE5 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 UE5.
      • Build just UE5, 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 UE5 in the Solutuion Explorer, from the Build menu, or using Ctrl+B when UE5 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 UE5 in the toolbar box next to the play and stop buttons
      • Build just UE5, 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 UE5Editor to make sure it worked. ⏱⏱ (50m)

Create an Unreal Project

  1. Inside the UE5 Editor, create a new blank C++ project without(!!!) starter content. Call the project "assn0" (lower-case please!) and save it at the top level of your g4g2022 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 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 assn0.uproject file, and everything in the assn0/Content and assn0/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.
  3. Create an assn0 level, set it as the startup level, and add a sphere to the level.

Submitting

Image

Make a screen shot of your assn0 level with the sphere visible.

  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 assn0 directory.
  3. Image files are set to be ignored by git in the UE5 .gitignore file.
    • You can tell git to accept image files in the project directories by editing the .gitignore. For example, to allow png image files, add /*/*.png someplace down around the Content folder changes
    • Alternately, you can have git continue to ignore image files in general, but force it to add a specific file with something like git add -f screenshot.png

Git Submission

Make sure everything is submitted and tagged. Log into github to check for what is currently committe and tagged.

  1. 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 "assn0.txt" to your assn0 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 approximately how long your build took on this system.
    4. Describe what is and is not working in your project, and any notable problems.
  3. Be sure to commit all of the necessary files: your assn0.txt, screen shot image, assn0.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 assn0 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 assn0, then git push origin assn0.
    • 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 realize you forgot something and need to re-tag to a different commit before the deadline, you will need to git tag -d assn0 to remove the local tag, git push --delete origin assn0 to remove the tag from github, then follow the tagging directions again to re-tag