Installation Guide

This guide will help you set up your development environment for creating games with the Popcorning Guinea Pig game engine.

Prerequisites

Required Software

  • .NET 10.0 SDK or later

  • Git (for version control)

    • Download from git-scm.com
    • Verify installation: git --version

Visual Studio (Windows - Recommended)

  • Visual Studio 2022 or later
  • Include the ".NET desktop development" workload
  • C# extension is included by default

Visual Studio Code (Cross-platform)

JetBrains Rider (Cross-platform)

  • Full-featured IDE with excellent C# support
  • Commercial license required

Platform-Specific Setup

Windows

  1. Install Visual Studio 2022 with .NET desktop development workload
  2. Install .NET 10.0 SDK
  3. No additional dependencies required - Raylib binaries are included

Linux

  1. Install .NET 10.0 SDK:

    # Ubuntu/Debian
sudo apt update
sudo apt install dotnet-sdk-10.0

# Fedora/RHEL/CentOS
sudo dnf install dotnet-sdk-10.0

  2. Install system dependencies:

    # Ubuntu/Debian
sudo apt install libopenal-dev libgl1-mesa-dev libglu1-mesa-dev

# Fedora/RHEL/CentOS
sudo dnf install openal-soft-devel mesa-libGL-devel mesa-libGLU-devel

macOS

  1. Install .NET 10.0 SDK:

    # Using Homebrew
brew install --cask dotnet-sdk

  2. Install Xcode Command Line Tools:

    xcode-select --install

Getting the Engine

git clone https://github.com/jacoblangston/popcorning-guinea-pig.git
cd popcorning-guinea-pig

Option 2: Reference the NuGet package (games)

Games consume the engine as a pinned package, never as a cross-repo project reference. The package is published to GitHub Packages on every v* tag.

GitHub's NuGet registry requires authentication even for public packages, and this repository is private — so a clean machine needs a token before dotnet restore will work.

  1. Create a classic personal access token with the read:packages scope, and export it. (A token with repo scope also restores, since the package inherits this private repository's permissions — but read:packages is the least privilege that works and the one to hand out.)

    export GITHUB_TOKEN=ghp_xxxxxxxx        # Windows: setx GITHUB_TOKEN ghp_xxxxxxxx

  2. Add a nuget.config next to your solution. The %GITHUB_TOKEN% placeholder is expanded by NuGet at restore time, so no secret is committed:

    <?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="github" value="https://nuget.pkg.github.com/jacoblangston/index.json" />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <packageSourceCredentials>
    <github>
      <add key="Username" value="YOUR_GITHUB_USERNAME" />
      <add key="ClearTextPassword" value="%GITHUB_TOKEN%" />
    </github>
  </packageSourceCredentials>
</configuration>

  3. Pin the version in your .csproj:

    <PackageReference Include="PopcorningGuineaPig.Engine" Version="1.0.0" />

  4. dotnet restore

A 401 Unauthorized from nuget.pkg.github.com means GITHUB_TOKEN is unset or lacks read:packages.

Option 3: Download as ZIP

  1. Visit the GitHub repository
  2. Click "Code" → "Download ZIP"
  3. Extract to your desired location

Building the Engine

Build from Command Line

# Navigate to the engine directory
cd src/PopcorningGuineaPig.Engine

# Restore dependencies
dotnet restore

# Build the engine
dotnet build

# Run tests (optional)
dotnet test

Build from IDE

Visual Studio

  1. Open src/PopcorningGuineaPig.Engine/PopcorningGuineaPig.Engine.sln
  2. Build → Build Solution (Ctrl+Shift+B)

Visual Studio Code

  1. Open the repository root folder
  2. Open terminal in VS Code (Ctrl+`)
  3. Run build commands as shown above

Verify Installation

Run an Example Project

Test your installation by running one of the included examples:

# Navigate to an example project
cd examples/main-menu/MainMenu

# Run the example
dotnet run

If successful, you should see a window with a main menu interface.

Expected Output

  • A window opens showing the engine splash screen or main menu
  • No error messages in the console
  • Smooth rendering at 60 FPS

Troubleshooting

Common Issues

"System.DllNotFoundException: Unable to load shared library 'raylib'"

Windows: Ensure Visual C++ Redistributable is installed Linux: Install the required system dependencies listed above macOS: Ensure Xcode Command Line Tools are installed

"The framework 'Microsoft.NETCore.App', version 'X.X' was not found"

Install the correct .NET version:

dotnet --list-runtimes

If .NET 10.0 is missing, download and install it from the Microsoft website.

Audio Not Working

Linux: Install ALSA development libraries:

sudo apt install libasound2-dev

macOS: Grant microphone permissions if prompted.

Performance Issues

If you experience poor performance:

  1. Update Graphics Drivers: Ensure you have the latest GPU drivers
  2. Check System Requirements: Verify your system meets minimum requirements
  3. Close Resource-Heavy Applications: Free up system resources
  4. Monitor Resource Usage: Use Task Manager/Activity Monitor to check CPU/GPU usage

System Requirements

Minimum Requirements

  • OS: Windows 10, Linux (Ubuntu 20.04+), macOS 10.15+
  • CPU: Dual-core processor, 2.0 GHz
  • Memory: 4 GB RAM
  • Graphics: OpenGL 3.3 compatible GPU
  • Storage: 500 MB available space
  • OS: Windows 11, Linux (Ubuntu 22.04+), macOS 12+
  • CPU: Quad-core processor, 3.0 GHz
  • Memory: 8 GB RAM
  • Graphics: Dedicated GPU with OpenGL 4.0+ support
  • Storage: 1 GB available space (for development files)

Next Steps

Once you have successfully installed the engine:

  1. Create Your First Game - Build a simple game to learn the basics
  2. Explore Examples - Study the included example projects
  3. Read Core Concepts - Understand the engine architecture

Additional Resources

  • Build Instructions - See BUILD_INSTRUCTIONS.md in the repository root for detailed platform-specific build instructions
  • GitHub Issues - Report bugs or request features
  • API Reference - Complete API documentation

Need Help? If you encounter issues not covered in this guide, please check the troubleshooting section or file an issue on GitHub.