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.

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 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. 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 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 one or two student's projects 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 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. 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 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.
  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/g4g2024 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 g4g2024. 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 g4g2024 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 20 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/15 repositoryURL, where repositoryURL is the URL you get from the "Clone or Download" button for your g4g2024 fork on GitHub.
  8. Run the Setup script in your g4g2024 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.

Build UE5

  1. Run the GenerateProjectFiles script (bat for Windows, command for Mac, or sh for Linux).
    • You will only need to re-run this when you add or remove source files.
  2. Open the generated project file (The newly created UE5.sln Visual Studio solution or UE5.xcodeproj 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 many hours. Fortunately, you will not need to do a full build often.
  4. Run the UE5 Editor 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 g4g2024 directory (so it'll be g4g2024/assn0).
    • 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.

Commit your work

  1. You do not need to quit the UE5 Editor, but be sure to save your work there before you commit.
  2. Look at what it wants you to commit before you do it
    • Command-line: git status
  3. You will need to stage the things you want to commit
    • Command-line: git add files or git add directory
  4. Do a git status again to confirm everything is staged correctly.
    • 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.
    • The "git status" message tells you how to un-stage anything you did not intend to commit
  5. Commit the change with a descriptive message that might help the grader to know what is in this commit
    • Command line: git commit -m "short message describing this commmit"
    • A commit message like "Initial assn0 project commit" is perfectly acceptable, something like "blarg" or "commit" is not.
  6. Test pushing 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
  7. Create an assn0 level and set it as the startup level, then make that one of your incremental commits.
  8. Add at least one sphere to the level and commit again.

Submitting

Text file

Add an assn0.txt file to your assn0 directory (i.e. g4g2024/assn0/assn0.txt)

  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.
  5. Make sure assn0.txt is committed to git before you submit

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.
    • Enter console commands in the Cmd blank at the bottom of the main editor window, in the line at the bottom of the UE5 "Output Log" window, or by hitting the back-quote key (`) then entering the command.
    • Screen shots will appear in a assn0/Saved/Screenshots directory.
  2. Upload the resulting image file to google drive, box, onedrive, etc.
  3. Make sure the file is set so at least the TA and I have view access
  4. Add a line to your assn0.txt with the URL for this image file

Git Submission

Make sure everything is submitted and tagged. Log into GitHub to check once you are done.

  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 (at least in future assignments), 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. Be sure to commit all of the necessary files: your assn0.txt, assn0.uproject, and all Content and Config directory files.
  3. Push your changes back to your personal GitHub repository.
    • You can and should do this multiple times during development. There are no points for pushing often, but if something goes wrong, it can be a life saver to have your partial work already pushed to GitHub.
  4. Add an assn0 tag for your final commit.
    • Git tags are typically used to mark releases (we're starting this semester with the 5.4.1-release tag from Epic's UnrealEngine GitHub repo. For our purposes, your completed assignment is a release.
    • The command-line commands for this are:
      • git tag assn0 (tag locally)
      • git push origin assn0 (explicitly push the tag to GitHub)
    • You should push your changes before midnight on the due date, 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.
    • 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 before the deadline, you will need to remove the local tag and the tag on GitHub, then retag:
      • git tag -d assn0 (delete the local tag)
      • git push --delete origin assn0 (delete the tag on GitHub)
      • git tag assn0 (retag locally)
      • git push origin assn0 (push the new tag back to GitHub)