games

A repository for storing games that the El Segundo High School Robotics Club programs together.

• How to set up your computer
  • Installation
    • Windows installation
    • Windows installation (via Chocolatey)
    • MacOS installation
    • Installing the Visual Studio Code plugins
  • Cloning the repository
• libGDX Cheatsheet
• Common problems

How to set up your computer

Installation

What you need to install

1. Visual Studio Code — Integrated Development Environment (IDE)
   • It's not the best text editor in the world (not even close), but it does have a useful realtime collaboration plugin that allows all of us to work on the same code at the same time and see each other's edits.
2. OpenJDK 17 — Java Development Kit (compiler and runtime)
   • We decided on 2023-06-01 that the first game would be written in Java, since that's what the students are learning in AP Computer Science.
3. Git — Version control tool
   • Git allows us to easily document, share, search through, and merge changes even when our edits diverge. Our club only uses the terminal version of Git.

Windows installation

1. If you have installed the Chocolatey package manager, you can skip to the next section. Otherwise:

2. Download VSCode and install it. Please pin it to your taskbar so it is easy to find.

   • FRC students who set up their computers as driver stations will already have a copy of VSCode with a name like FRC VS Code 2023 or the like. If you have that, it will work just fine -- you don't need to install a separate copy of VSCode.

3. Install OpenJDK 17.

   Our preferred JDK is Adoptium (formerly AdoptOpenJDK)'s Temurin JDK. You can install it by hand or you can use VSCode to do it:

   • Open VSCode.
   • Type Ctrl + Shift + P to activate the Command Palette.
   • Within the Palette, type "install jdk" and you should see a Java: Install New JDK entry or the like; activate it.
   • Click the giant Download button.

   Either way, make sure the java command is in your PATH, and that the JDK version is 17 or greater. Both can be accomplished with a single shell command: shell java --version

4. Install Git.

   The most common Windows build of Git is Git for Windows. In addition to the git.exe terminal application itself, it includes:

   • A Git-specific shell called "Git Bash" (which we don't use),
   • A graphical interface called "Git GUI" (which we don't use), and
   • A credential manager that allows you to log into GitHub using your web browser whenever you execute git push (we do use this.)

   You can install this program separately, but it's easier to install it by installing Cmder, a multi-tabbed terminal for Windows that has Git for Windows built into it. You'll want the full version; once it is installed, pin it to your taskbar and use it as your preferred terminal.

Windows installation (via Chocolatey)

Chocolatey is not required for this project. But for those students who don't the Chocolatey package manager and have the permission to install it, we highly recommend that they do. Chocolatey makes installing and upgrading software much, much easier.

If you have Chocolatey, open a terminal as an administrator and run the following commands:

1. To install Visual Studio Code: choco install vscode
   • Please pin it to your taskbar to make it easy to open in the future.
2. To install OpenJDK 17: choco install temurin17
3. To install Git for Windows: choco install git

MacOS installation

These instructions rely on the Homebrew package manager.

1. Install Visual Studio Code: brew install visual-studio-code
   • Please pin it to your Dock to make it easy to open in the future.
2. Install OpenJDK 17: brew install openjdk@17
   • You'll probably need to set $JAVA_HOME as well. See Common Problem #1 for more details.
3. Install Git: brew install git

Installing the Visual Studio Code plugins

1. Open VSCode.
2. Click on the Extensions button on the left sidebar.
3. Search for and install the following extensions:
   1. Extension Pack for Java - allows you to build and debug Java code
   2. GitLens - shows commit history per-line
   3. Live Share - allows collaborators to simultaneously edit the same buffers
   4. Rewrap - Allows you to word-wrap long lines using Alt + Q (⌥Option + Q on MacOS)
   5. Base16 Rebecca - Uche likes purple color themes

Cloning the repository

1. Create an account on GitHub if you haven't yet.

   We need the GitHub account for two things: allowing you to commit into this repository and for getting that collaboration plugin working.

   • Just to emphasize: Git and GitHub are not the same thing. Git is the version control software you will use with this project; GitHub is just a website where we happen to store our source code (and which integrates well with Visual Studio Code.)
   • Once you have the account, let Uche know about it so he can add it to the eshsrobotics programming group.

2. Choose a folder to store your source code (if you haven't yet)

   Most students store their code in a folder which is easy to find, like Desktop, Documents, or Downloads. Create a subfolder underneath it to store your source code projects. Make a note of where it is, since you will need to be able to navigate to it from a terminal.

   There's plenty of help online for learning basic terminal commands. The most important ones that we use are:

   • cd path/to/your/folder - Changes to a different folder
     • cd .. - Goes up to the parent folder
   • pushd path/to/your/folder - Changes to a different folder while remembering where you were before
     • popd - Goes back to where you were before you executed pushd
   • dir - Lists the contents of a folder
     • If you are using the Bash shell, try ls -Flarth

3. cd into that folder from the terminal.

4. Execute the clone command:

   git clone https://github.com/eshsrobotics/games

5. Finally, open the games folder from within Visual Studio Code. You're done!

libGDX Cheatsheet

The java games in this repository use libGDX, a Java game library that combines several popular game-related frameworks. It uses Gradle for building and running, so there are a number of important Gradle targets:

1. Compiling and testing:
   • ./gradlew build: Builds the application for all output environments.
   • ./gradlew lwjgl3:build: Builds just the desktop version of the application.
   • ./gradlew html:build: Builds just the web version of the application.
2. Running:

   • ./gradlew lwjgl3:run: Runs the desktop version of the application

   • ./gradlew html:superDev: Runs the web application in Super Dev mode, which allows browser debugging and on-the-fly recompilation.

     Visit http://localhost:8080/index.html to play your game.

   • ./gradlew ios:launchIPhoneSimulator: Runs the iPhone version of the app. This requires XCode, and so it will only succeed on Macs.

   • ./gradlew android:installDebug android:run: Runs the Android version of the app. This requires an installed Android SDK on your system; once you install it, you will need to set the ANDROID_HOME environment variable to point to that folder.

You can add --debug at the end of any of these Gradle targets to get more information if something does wrong.

Common problems

1. Q: I'm on MacOS Ventura 13.3.1. When I ran ./gradlew build, I encountered the following error:

   Downloading https://services.gradle.org/distributions/gradle-7.6.1-bin.zip
   
   Exception in thread "main" javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
       at java.base/sun.security.ssl.Alert.createSSLException(Alert.java:131)
       [...snip...]
       at java.base/sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:434)
       ... 31 more
   

   What's going on?
   ——Frustrated in Fresno

   • A: You probably haven't set your $JAVA_HOME environment variable, so Java is looking for the gradle.org certificates in the wrong place.

     MacOS Homebrew installs OpenJDK 17 in /usr/local/opt/openjdk@17, so you should add:

     # Point Java tools at OpenJDK 17 (necessary for libGDX game
     # development)
     export JAVA_HOME=/usr/local/opt/openjdk@17

     to a Bash initialization script such as $HOME/.profile. (If that file does not exist, you will need to create it.) After saving this change, any future shells you run will have $JAVA_HOME set, and you should be able to build.

2. Q: Why is my project build failing with this error?

   Error: Could not find or load main class org.gradle.wrapper.GradleWrapperMain
   Caused by: java.lang.ClassNotFoundException: org.gradle.wrapper.GradleWrapperMain
   

   ——Flabbergasted Floridian

   • A: You are the victim of bad defaults and a bad error message. A more sensible error message would have said:

     Error: could not find gradle-wrapper.jar
     Did you accidentally add it to your .gitignore?
     

     • As it turns out, the gdx-setup.jar project generation wizard creates broken projects out of the box, since its .gitignore file excludes the directory that it puts gradle-wrapper.jar in. Without this JAR file, ./gradlew cannot operate.

       The person who runs the wizard will have a local copy of gradle-wrapper.jar, but since it is automatically gitignored, it will not be pushed upstream when they push the rest of their code. Everyone who pulls it will see the error message shown above!

     • To fix the problem, do the following:

       1. Change .gitignore to add an exception for gradle-wrapper.jar.

          @@ -93,6 +93,7 @@ nb-configuration.xml
          
           /local.properties
           .gradle/
          +!gradle/wrapper/gradle-wrapper.jar
           gradle-app.setting
           /build/
           /android/build/
          

       2. git add ./gradle/wrapper/gradle-wrapper.jar so that other people can see it.

     • This problem is one of several reasons that we migrated the project from using gdx-setup.jar to using gdx-liftoff.