5. Version Control

Version Control

Version Control is coming soon to SuperbulletAI! This powerful feature will automatically save snapshots of your project at key moments, allowing you to instantly revert to any previous state if something goes wrong. Imagine being able to experiment freely with new features, knowing you can always return to a working version with a single click. Whether you accidentally delete important code, want to test different approaches, or need to show clients various iterations of your game, version control acts as your project's time machine and safety net.

1. Why Version Control is Critical

Version control is one of the most important practices in software development and game creation. Here's why it's essential:

  • Safety Net: Never lose your work again - every change is tracked and recoverable
  • Experimentation Freedom: Try new features or changes without fear of breaking your existing code
  • Collaboration: Work with others seamlessly, merging changes without conflicts
  • History Tracking: See exactly what changed, when, and why
  • Backup: Your code is stored in multiple places, protecting against hardware failures
  • Release Management: Easily manage different versions of your game for testing and production

Without version control, you're essentially working without a safety net. One accidental deletion or bad change could destroy hours or days of work.

2. Setting Up GitHub and GitHub Desktop

While we're developing SuperbulletAI's built-in version control system, we strongly recommend using GitHub and GitHub Desktop to protect your projects.

a. Creating a GitHub Account

  1. Visit GitHub: Go to github.com (opens in a new tab)
  2. Sign Up: Click "Sign up" in the top right corner
  3. Choose Username: Pick a username that represents you or your projects
  4. Email & Password: Use a valid email address you can access
  5. Verify Account: Check your email and verify your account
  6. Choose Plan: The free plan is perfect for getting started

b. Installing Git and GitHub Desktop

Don't worry if you've never heard of "git" before - GitHub Desktop will install everything you need automatically!

What is Git?

Git is the underlying technology that tracks changes to your files. Think of it as the engine that powers version control. GitHub Desktop is the easy-to-use visual interface that makes git simple for everyone.

Installing GitHub Desktop (includes Git)

GitHub Desktop makes version control visual and easy to understand, and it automatically installs git for you:

  1. Download: Visit desktop.github.com (opens in a new tab)
  2. Choose Your System: Click the download button for Windows or Mac
  3. Install:
    • Windows: Run the downloaded .exe file and follow the installer
    • Mac: Open the downloaded .dmg file and drag GitHub Desktop to Applications
  4. First Launch: Open GitHub Desktop - it will automatically install git if needed
  5. Sign In: Sign in with your GitHub account (the one you just created)
  6. Configure: Enter your name and email - this will appear on your saved versions

Verifying Git Installation

After GitHub Desktop finishes installing, git will be ready to use. You don't need to do anything else - GitHub Desktop handles all the technical details for you!

c. Setting Up Your Repository

  1. Add Existing Repository: In GitHub Desktop, click "Add an Existing Repository from your hard drive"
  2. Select Your Project: Navigate to Documents/SuperbulletAI and select your project folder created by SuperbulletAI
  3. Initialize Git: If prompted, click "create a repository" to initialize version control for your existing project
  4. Review Files: GitHub Desktop will show all your SuperbulletAI project files ready to be tracked
  5. First Commit: Add a commit message like "Initial SuperbulletAI project" and click "Commit to main"

3. Going Back to Previous Versions (Reset)

Sometimes you'll want to go back to an earlier version of your project - maybe you tried something that didn't work, or you want to test how your game looked yesterday. This is called "resetting" and it's like having a time machine for your project!

a. View Your Project History in GitHub Desktop

  1. Open GitHub Desktop and select your SuperbulletAI project
  2. Click "History" tab to see all your saved versions (called "commits")
  3. Browse Timeline: Each entry shows when you saved changes and what you changed
  4. Find the Commit ID: Each version has a unique ID (like abc1234) - you'll need this for the reset command

b. Opening the Terminal/Command Prompt

Don't worry - the terminal is just a text-based way to give your computer instructions!

On Windows:

  1. Press Windows Key + R
  2. Type cmd and press Enter
  3. A black window opens - this is Command Prompt

On Mac:

  1. Press Cmd + Space (opens Spotlight)
  2. Type terminal and press Enter
  3. A window opens - this is Terminal

c. Navigating to Your Project

Before you can reset, you need to tell the terminal where your SuperbulletAI project is located:

cd Documents/SuperbulletAI/YourProjectName

Replace YourProjectName with your actual project folder name.

Example:

cd Documents/SuperbulletAI/MyAwesomeGame

d. Going Back to Previous Versions

Now you can use git reset commands. ⚠️ Important: Always save your current work first!

1. Save Your Current Work First

git add .
git commit -m "Saving current progress before testing"

2. Reset to a Previous Version

git reset --hard HEAD~1

What this means:

  • git reset --hard = Go back and remove all changes after that point
  • HEAD~1 = Go back 1 version from the latest

3. Reset to a Specific Version

If you know the commit ID from GitHub Desktop (like abc1234):

git reset --hard abc1234

4. Go Back Multiple Versions

git reset --hard HEAD~3

This goes back 3 versions from the latest.

e. Getting Your Recent Work Back

If you want to return to your latest work after testing:

  1. Look at your history in GitHub Desktop to find your "Saving current progress" commit
  2. Copy the commit ID (the letters and numbers)
  3. Reset to that commit:
git reset --hard [paste-commit-id-here]

f. Safety Tips

  1. Always commit before experimenting: Save your work first with git add . and git commit -m "message"
  2. Copy commit IDs: Write down or copy the commit ID of your current work before going back
  3. Test on copies: If you're nervous, make a copy of your project folder first
  4. Don't panic: If something goes wrong, you can usually recover using GitHub Desktop's history

g. Common Reset Commands Summary

# Navigate to your project
cd Documents/SuperbulletAI/YourProjectName
 
# Save current work
git add .
git commit -m "Saving before reset"
 
# Go back 1 version
git reset --hard HEAD~1
 
# Go back 3 versions  
git reset --hard HEAD~3
 
# Go to specific version (replace abc1234 with real commit ID)
git reset --hard abc1234

Remember: git reset --hard will delete changes, so always save your work first!

4. Best Practices

  • Commit Often: Make small, frequent commits with clear messages
  • Use Branches: Create branches for new features or experiments
  • Push Regularly: Keep your GitHub repository updated with your latest work
  • Write Clear Commit Messages: Describe what you changed and why
  • Test Before Committing: Make sure your code works before saving it

Coming Soon: SuperbulletAI Version Control

We're working on integrating version control directly into SuperbulletAI, which will make this process even more seamless. Features will include:

  • One-click versioning: Save versions with a single button
  • Visual timeline: See your project's evolution graphically
  • Automatic backups: Never lose work with automatic version creation
  • Collaborative features: Share and merge changes with team members

Until then, GitHub and GitHub Desktop provide an excellent foundation for protecting your work and learning version control principles.

a. With Cube3D6. Publishing your Roblox Game