Create "PupperQuest" - Grid-Based Roguelike Puppy Adventure Game

RACEngine.sln

@@ -53,6 +53,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Rac.Audio.Tests", "tests\Ra
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DocumentationTests", "tests\DocumentationTests\DocumentationTests.csproj", "{62D7BF87-6818-4C59-ACDA-C8AE0EB679DE}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PupperQuest", "samples\PupperQuest\PupperQuest.csproj", "{F081AE06-41A0-402F-BC49-3B289A54CA27}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -150,6 +152,10 @@ Global
 		{62D7BF87-6818-4C59-ACDA-C8AE0EB679DE}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{62D7BF87-6818-4C59-ACDA-C8AE0EB679DE}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{62D7BF87-6818-4C59-ACDA-C8AE0EB679DE}.Release|Any CPU.Build.0 = Release|Any CPU
+		{F081AE06-41A0-402F-BC49-3B289A54CA27}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{F081AE06-41A0-402F-BC49-3B289A54CA27}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{F081AE06-41A0-402F-BC49-3B289A54CA27}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{F081AE06-41A0-402F-BC49-3B289A54CA27}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{3DC13F69-59D3-4179-AF6A-BAA759D7D445} = {16D68806-95C0-4EF6-9029-30FB1B41CDBE}
@@ -174,5 +180,6 @@ Global
 		{F3A01F2C-443E-448D-B620-420CF5A096E5} = {5899090E-41B7-4A76-A371-342D74B571AE}
 		{4C0FA9D3-3245-49B7-A03A-CBE8E4A43578} = {5899090E-41B7-4A76-A371-342D74B571AE}
 		{62D7BF87-6818-4C59-ACDA-C8AE0EB679DE} = {5899090E-41B7-4A76-A371-342D74B571AE}
+		{F081AE06-41A0-402F-BC49-3B289A54CA27} = {4BA05353-0713-4E7A-9486-ECCF6B2BB2D4}
 	EndGlobalSection
 EndGlobal

samples/PupperQuest/Components/GameComponents.cs

@@ -0,0 +1,91 @@
+using Rac.ECS.Components;
+using Silk.NET.Maths;
+
+namespace PupperQuest.Components;
+
+/// <summary>
+/// Represents an entity's position on the game grid.
+/// Grid coordinates are discrete integer positions for turn-based movement.
+/// </summary>
+/// <param name="X">The X coordinate on the grid</param>
+/// <param name="Y">The Y coordinate on the grid</param>
+/// <remarks>
+/// Educational Note: Grid-based positioning simplifies collision detection and turn-based logic.
+/// Each tile represents a discrete space that can contain at most one entity.
+/// This is common in roguelike games for strategic movement and clear spatial relationships.
+/// </remarks>
+public readonly record struct GridPositionComponent(int X, int Y) : IComponent
+{
+    /// <summary>
+    /// Convert grid position to world coordinates for rendering.
+    /// Flips Y coordinate to match OpenGL convention (Y increases upward).
+    /// </summary>
+    /// <param name="tileSize">Size of each grid tile in world units</param>
+    /// <returns>World position as Vector2D for rendering systems</returns>
+    public Vector2D<float> ToWorldPosition(float tileSize)
+    {
+        // Flip Y coordinate: Grid Y=0 (top) becomes World Y=high (top in world space)
+        // This ensures that moving "up" in the game (decreasing grid Y) appears as moving up on screen
+        return new Vector2D<float>(X * tileSize, -Y * tileSize);
+    }
+}
+
+/// <summary>
+/// Stores movement direction and timing for grid-based movement animation.
+/// </summary>
+/// <param name="Direction">Direction vector for next movement</param>
+/// <param name="MoveTimer">Timer for smooth animation between grid positions</param>
+public readonly record struct MovementComponent(Vector2D<int> Direction, float MoveTimer) : IComponent;
+
+/// <summary>
+/// Marks an entity as the player-controlled puppy with game stats.
+/// </summary>
+/// <param name="Health">Current health points</param>
+/// <param name="Energy">Current energy/stamina for actions</param>
+/// <param name="SmellRadius">Range for detecting items and enemies</param>
+public readonly record struct PuppyComponent(int Health, int Energy, int SmellRadius) : IComponent;
+
+/// <summary>
+/// Represents a tile in the game world with type and passability.
+/// </summary>
+/// <param name="Type">The type of tile (Floor, Wall, Door, etc.)</param>
+/// <param name="IsPassable">Whether entities can move through this tile</param>
+public readonly record struct TileComponent(TileType Type, bool IsPassable) : IComponent;
+
+/// <summary>
+/// Visual representation data for entities and tiles.
+/// </summary>
+/// <param name="Size">Size of the sprite in world coordinates</param>
+/// <param name="Color">RGBA color for rendering</param>
+public readonly record struct SpriteComponent(Vector2D<float> Size, Vector4D<float> Color) : IComponent;
+
+/// <summary>
+/// AI behavior component for enemy entities.
+/// </summary>
+/// <param name="Behavior">The type of AI behavior to execute</param>
+/// <param name="Target">Entity ID of the current target (0 if no target)</param>
+/// <param name="PatrolRoute">List of positions for patrol behavior</param>
+public readonly record struct AIComponent(AIBehavior Behavior, uint Target, Vector2D<int>[] PatrolRoute) : IComponent;
+
+/// <summary>
+/// Marks an entity as an enemy with combat properties.
+/// </summary>
+/// <param name="Type">The type of enemy</param>
+/// <param name="AttackDamage">Damage dealt to player on contact</param>
+/// <param name="DetectionRange">Range for detecting the player</param>
+public readonly record struct EnemyComponent(EnemyType Type, int AttackDamage, int DetectionRange) : IComponent;
+
+/// <summary>
+/// Game level information and progression state.
+/// </summary>
+/// <param name="CurrentLevel">Current level number</param>
+/// <param name="HasExit">Whether this level has an exit to next level</param>
+/// <param name="IsComplete">Whether level objectives are completed</param>
+public readonly record struct LevelComponent(int CurrentLevel, bool HasExit, bool IsComplete) : IComponent;
+
+/// <summary>
+/// Collectible items with gameplay effects.
+/// </summary>
+/// <param name="Type">Type of item</param>
+/// <param name="Value">Numeric value for the item effect</param>
+public readonly record struct ItemComponent(ItemType Type, int Value) : IComponent;

samples/PupperQuest/Components/GameEnums.cs

@@ -0,0 +1,98 @@
+namespace PupperQuest.Components;
+
+/// <summary>
+/// Types of tiles in the game world.
+/// </summary>
+/// <remarks>
+/// Educational Note: Tile-based level design is fundamental to grid-based games.
+/// Each tile type has different properties affecting movement, rendering, and gameplay.
+/// </remarks>
+public enum TileType
+{
+    /// <summary>Empty walkable floor space</summary>
+    Floor,
+
+    /// <summary>Solid impassable wall</summary>
+    Wall,
+
+    /// <summary>Door that can be opened/closed</summary>
+    Door,
+
+    /// <summary>Stairs leading to next level</summary>
+    Stairs,
+
+    /// <summary>Starting position for the player</summary>
+    Start,
+
+    /// <summary>Exit/goal position</summary>
+    Exit
+}
+
+/// <summary>
+/// AI behavior patterns for enemy entities.
+/// </summary>
+/// <remarks>
+/// Educational Note: Simple state-based AI is effective for roguelike games.
+/// Each behavior represents a different challenge type for the player.
+/// Academic Reference: "Artificial Intelligence for Games" (Millington & Funge, 2009)
+/// </remarks>
+public enum AIBehavior
+{
+    /// <summary>Moves toward player when detected</summary>
+    Hostile,
+
+    /// <summary>Runs away from player when nearby</summary>
+    Flee,
+
+    /// <summary>Follows predefined patrol route</summary>
+    Patrol,
+
+    /// <summary>Stands still until player gets close</summary>
+    Guard,
+
+    /// <summary>Wanders randomly around the level</summary>
+    Wander
+}
+
+/// <summary>
+/// Types of enemy entities with different behaviors and appearances.
+/// </summary>
+/// <remarks>
+/// Educational Note: Enemy variety creates different tactical challenges.
+/// Each type demonstrates different AI patterns and player interaction strategies.
+/// </remarks>
+public enum EnemyType
+{
+    /// <summary>Small fast enemies that chase the player</summary>
+    Rat,
+
+    /// <summary>Medium enemies that flee from the player</summary>
+    Cat,
+
+    /// <summary>Large enemies that patrol and chase when close</summary>
+    Mailman,
+
+    /// <summary>Stationary guards that block passages</summary>
+    FenceGuard
+}
+
+/// <summary>
+/// Types of collectible items with different effects.
+/// </summary>
+public enum ItemType
+{
+    /// <summary>Restores health points</summary>
+    Treat,
+
+    /// <summary>Restores energy/stamina</summary>
+    Water,
+
+    /// <summary>Increases smell detection radius</summary>
+    Bone,
+
+    /// <summary>Key to unlock doors</summary>
+    Key,
+
+    /// <summary>Special item needed to complete level</summary>
+    Toy
+}