Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Getting Started — C# SDK

Alpha — GoudEngine is under active development. APIs change frequently. Report issues

Prerequisites

Installation

Create a new console project and add the NuGet package:

dotnet new console -n MyGame
cd MyGame
dotnet add package GoudEngine

Open MyGame.csproj and add <AllowUnsafeBlocks>true</AllowUnsafeBlocks>. The SDK uses unsafe interop internally.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="GoudEngine" Version="0.0.832" />
  </ItemGroup>
</Project>

First Project

Replace Program.cs with a minimal window that closes on Escape:

using GoudEngine;

using var game = new GoudGame(800, 600, "My Game");

while (!game.ShouldClose())
{
    game.BeginFrame(0.2f, 0.3f, 0.4f, 1.0f);

    float dt = game.DeltaTime;

    if (game.IsKeyPressed(Keys.Escape))
    {
        game.Close();
        continue;
    }

    game.EndFrame();
}

BeginFrame clears the screen to the given color and prepares the frame. EndFrame swaps buffers and polls events. DeltaTime gives seconds since the last frame — use it to keep movement frame-rate independent.

Run it:

dotnet run

For 3D rendering, the same game window supports both 2D and 3D rendering. Load a 3D model and render it within the same frame loop:

var model = game.LoadModel("assets/model.gltf");
game.Draw3D(model, transform);

Debugger Runtime

Enable debugger mode before creating the windowed game or headless context.

using GoudEngine;

using var ctx = new GoudContext(
    new ContextConfig(new DebuggerConfig(true, true, "getting-started-csharp"))
);

ctx.SetDebuggerProfilingEnabled(true);
string snapshotJson = ctx.GetDebuggerSnapshotJson();
string manifestJson = ctx.GetDebuggerManifestJson();

For a ready-made headless route, run ./dev.sh --game feature_lab. The example publishes feature-lab-csharp-headless, confirms manifest and snapshot access, and prints the manual attach steps:

  1. start cargo run -p goudengine-mcp
  2. call goudengine.list_contexts
  3. call goudengine.attach_context

Drawing a Sprite

Load textures once before the loop. Drawing happens inside the loop between BeginFrame and EndFrame.

using GoudEngine;

using var game = new GoudGame(800, 600, "My Game");

ulong textureId = game.LoadTexture("assets/sprite.png");

float x = 100f;
float y = 100f;
float width = 64f;
float height = 64f;

while (!game.ShouldClose())
{
    game.BeginFrame(0.1f, 0.1f, 0.1f, 1.0f);

    if (game.IsKeyPressed(Keys.Escape))
    {
        game.Close();
        continue;
    }

    game.DrawSprite(textureId, x, y, width, height);

    game.EndFrame();
}

To draw a colored quad without a texture:

game.DrawQuad(x, y, width, height, new Color(1.0f, 0.0f, 0.0f, 1.0f));

Put your image files in an assets/ folder next to the project. The path is relative to the working directory when you run dotnet run.

Handling Input

IsKeyPressed returns true every frame the key is held. Use it for movement. For one-shot actions, track state yourself.

float speed = 200f;

while (!game.ShouldClose())
{
    game.BeginFrame(0.1f, 0.1f, 0.1f, 1.0f);

    float dt = game.DeltaTime;

    if (game.IsKeyPressed(Keys.Escape))
    {
        game.Close();
        continue;
    }

    if (game.IsKeyPressed(Keys.Left))  x -= speed * dt;
    if (game.IsKeyPressed(Keys.Right)) x += speed * dt;
    if (game.IsKeyPressed(Keys.Up))    y -= speed * dt;
    if (game.IsKeyPressed(Keys.Down))  y += speed * dt;
    if (game.IsKeyPressed(Keys.Space)) { }

    game.DrawSprite(textureId, x, y, width, height);

    game.EndFrame();
}

Mouse input follows the same pattern:

if (game.IsMouseButtonPressed(MouseButton.Left)) { /* click action */ }

float mouseX = game.MouseX;
float mouseY = game.MouseY;

Running an Example Game

The repository includes several complete C# games. Clone and run them directly:

git clone https://github.com/aram-devdocs/GoudEngine.git
cd GoudEngine
./dev.sh --game flappy_goud     # Flappy Bird clone
./dev.sh --game sandbox         # Full feature sandbox
./dev.sh --game goud_jumper     # Platformer
./dev.sh --game 3d_cube         # 3D rendering demo
./dev.sh --game isometric_rpg   # Isometric RPG
./dev.sh --game hello_ecs       # ECS basics
./dev.sh --game feature_lab     # Supplemental smoke coverage

dev.sh builds the engine and runs the example in one step. Source for each example is in examples/csharp/.

To use a locally built version of the engine instead of the published NuGet package:

./build.sh
./package.sh --local
./dev.sh --game flappy_goud --local

Next Steps