1. Introduction

1.1 What is GBare Engine?

GBare Engine is a lightweight, modular 2D game engine written in C# using the Raylib-cs library. Its goal is to provide developers with a flexible, minimalistic framework for creating 2D games with full control over components and behavior. GBare does not enforce a specific architecture – instead, it allows you to build GameObjects by attaching individual Components (e.g., Transform, Rigidbody, Collider, Animator) and defining behavior in code.

1.2 System Requirements

1.3 Installation and First Run

  1. Download GBare.dll

  2. Reference the DLL in Your Game Project
    In Visual Studio:
    Right-click project → Add → Reference → Browse → Select GBareEngine.dll

  3. Install Raylib-cs via NuGet
    Your game project still needs to include Raylib:

  4. Create your first GameObject
    for example

    public class Player : GameObject {  //Declaration of GameObject
    public void Update(){
    Console.WriteLine("Frame update");
    }
}

    This GameObject outputs “Frame update” every frame to the Console.

  5. Register your GameObject and run it
    In void Main()

{
Engine.RegisterNew(new Player()); //Registers Player GameObject

Engine.LoadAndRun(new Player()); // Starts your game without scene file
                               
}

If you want to use Scene file (.GBS)

Engine.RegisterNew(new Player()); //Registers Player GameObject

Engine.LoadAndRun(Scene scene);

Core Concepts

2.1 GameObject

A GameObject is the base unit in the engine. It represents anything in the game: a player, an enemy, a UI element, etc. A GameObject by itself holds no logic – it’s simply a container for Components.

Key Features:

Example:

public  class  Player : GameObject {
	public  override  void  Start()
    {
        AddComponent(new Transform()); // Adds Transform component, stores position
        AddComponent(new Collider()); // Adds Collider
        AddComponent(new Rigidbody()); // Adds Rigidbody. Always add Rigidbody after Transform and Collider
        
        
    } 
    public  override  void  Update()
    { 
     // Movement logic 
    }

	public  override  void  Draw()
    { 
     // Render logic 
    }
}

2.2 Component

A Component adds data or behavior to a GameObject. All components inherit from the abstract Component class and have:

Common Built-in Components:

2.3 Scene

A Scene stores all active GameObjects and manages their lifecycles.

Key responsibilities:

There is not need to do Update()or Draw() manually , because Engine already manages that.

A Scene can be saved to .GBS file. File structure is written in Json.
Example of .GBS file:

{
 "Objects": [
   {
     "Name": "Player",
     "Components": [
       { "Type": "Transform", "X": 400, "Y": 20 },
       { "Type": "Collider", "Width": 32, "Height": 32 },
       { "Type": "Rigidbody", "Mass": 1.0 }
       
     ]
   }
 ]
}

2.4 Engine

The static Engine class runs the game loop and handles scene loading.

Key methods:

3. Project Structure

A basic game project using the GBare Engine should follow a clean and modular directory layout. Here’s a recommended structure:

/MyGameProject  
│  
├──  /Scenes  
│    │  
│     └──  Default.GBS  // Serialized scene data  
├──  /GameObjects 
│    │  
│    ├──  Player.cs // Your custom GameObject subclass  
│    │  
│    └──  Enemy.cs   
├──  Program.cs // Main entry point 
├──  MyGameProject.csproj // Your game project file
│  
├──  /bin /  /obj                   //  Compiled output (auto-generated)

3.1 Program.cs

This file contains your game’s main entry point. Typically it:

  1. Registers all custom GameObjects

  2. Loads a .GBS scene

  3. Starts the engine runtime

Example:

Engine.RegisterNew(new Player()); //Registering GameObjects
var data = Engine.SceneIO.GetSceneData("./Scenes/Default.GBS"); //Loading scene
var scene = Engine.SceneIO.GetSceneFromData(data);
Engine.LoadAndRun(scene);

4. Error Handling

The GBare Engine includes a basic but expandable error-handling system through custom exception classes. These exceptions help you identify issues at different stages of engine usage, such as scene loading, component instantiation, and more.

Below are the custom exceptions included in the engine:

4.1 EngineException

Namespace: GBare_Engine

Thrown when a generic engine-level failure occurs. Most commonly used as a fallback when deserialization or internal state validation fails.

4.2 RigidBodyException

Namespace: GBare_Engine

Thrown when Rigidbody tries to perform a calculation with invalid data
(e.g. Mass = 0 ).

Typical cause: Invalid RigidbodyData settings or invalid Rigidbody properties.

4.3 Vector2Exception

Namespace: GBare_Engine

Thrown when Vector2 data does not meet expectations.

Typical cause: Vector2 argument is null

4.4 RequiredComponentException

Namespace: GBare_Engine

Thrown when Component or GameObject require Component that does not exists or had not been registered.

Typical cause: Component has not been registered.

4.5 FieldAccessException

Namespace: System

Thrown when Gamestore is required to save data when Gamestore hadn’t been Initialized.

Typical cause: Gamestore not initialized.

4.6 ComponentKeyNotFoundException

Namespace: GBare_Engine

Thrown when the engine attempts to instantiate a component with a type string that doesn’t match any known type in ComponentFactory.

Typical cause: A typo in the .GBS file’s Type field, or an unregistered custom component.

4.7 GameObjectInstantiationException

Namespace: GBare_Engine

Thrown when the engine tries to instantiate a GameObject that has not been registered using Engine.RegisterNew(...).

Typical cause: Forgetting to register a GameObject before loading a .GBS scene that refers to it.

5. Conclusion

Congratulations! You’ve now been introduced to the core structure and functionality of the GBare Engine. In this Getting Started guide, you’ve learned how to:

This foundation is designed to help you quickly get up and running with 2D game development using GBare, while leaving room for advanced customization and expansion.