Shape Engine Documentation

repository·main·Indexed 20 days ago

https://github.com/davegreen-games/shapeengine

A high-performance game engine built on the Raylib framework, focusing on draw-based rendering using shapes instead of textures. It provides advanced geometric systems including polygon fracturing, Delaunay triangulation, and a robust collision system for various shapes. The engine includes a dedicated UI system, pathfinding, and the DaveGreen.ShapeEngine.ResourcePacker tool for managing resource directories via a CLI.

Tokens
2.3K
Snippets
5
Records
9
Agent score
20%

What's inside Shape Engine

  1. Shape Engine Core Features

    main

    Shape Engine provides a variety of systems for game development, focusing on performance and draw-based rendering. Key features include:

    • Geometry & Math: Polygon Fracturing, Polygon Clipping & Boolean Operations, Delaunay Triangulation.
    • Rendering & Visuals: Text & Font System, Word Emphasis System, Gapped Drawing, Striped Drawing, Screen Texture System, Color Palettes.
    • Gameplay Systems: Pathfinding, Collision System (including Segment, Line, Ray, Circle, Triangle, Quad, Rect, Polygon, Polyline), Input System (Keyboard, Mouse, Gamepad), Camera System, Savegame System, Audio & Music.
    • UI: Dedicated UI System.
  2. Shape Engine Collision System Limitations

    main

    Shape Engine includes a complete collision system (supporting shapes like Segment, Line, Ray, Circle, Triangle, Quad, Rect, Polygon, and Polyline), but it does not include a physics engine.

    While the engine detects collisions, the collision response (how objects react to hitting each other) is the responsibility of the developer. You may use Raylib's built-in physics system if needed.

  3. Minimal Project Setup with MyGameClass

    main

    To start a project, extend the Game class and implement the DrawGame method. You initialize the engine by passing GameSettings, WindowSettings, FramerateSettings, and InputSettings to the constructor.

    In the DrawGame override, you receive a ScreenInfo object (often named game) which provides access to the drawing area and input states like MousePos.

    using System.Drawing;
    using ShapeEngine.Color;
    using ShapeEngine.Core;
    using ShapeEngine.Core.Structs;
    using ShapeEngine.Geometry;
    using ShapeEngine.Geometry.RectDef;
    
    namespace ShapeEngineProject;
    
    public static class Program
    {
        public static void Main(string[] args)
        {
            var game = new MyGameClass
            (
                GameSettings.StretchMode("Shape Engine Game"),
                WindowSettings.Default,
                FramerateSettings.Default,
                InputSettings.Default
            );
            game.Run();
        }
    }
    
    public class MyGameClass : Game
    {
        public new static MyGameClass Instance  => myInstance?? throw new NullReferenceException("Instance is not initialized!");
        private static MyGameClass? myInstance;
        
        public MyGameClass(
            GameSettings gameSettings, WindowSettings windowSettings,
            FramerateSettings framerateSettings, InputSettings inputSettings)
            : base(gameSettings, windowSettings, framerateSettings, inputSettings)
        {
            myInstance = GetInstanceAs<MyGameClass>();
        }
        
        protected override void DrawGame(ScreenInfo game)
        {
            game.Area.Draw(new ColorRgba(Color.DarkOliveGreen));
            game.Area.DrawLines(12f, new ColorRgba(Color.AntiqueWhite));
            game.MousePos.Draw(24f, new ColorRgba(Color.Lime), 36);
        }
    }
  4. Install the ShapeEngine ResourcePacker tool

    main

    You can install ResourcePacker either as a local tool within a specific repository (recommended for version consistency) or as a global tool.

    To install it as a local tool, create a tool manifest in your repository and then install the package:

    1. Create the manifest: dotnet new tool-manifest
    2. Install the tool: dotnet tool install --local DaveGreen.ShapeEngine.ResourcePacker
    3. To restore the tool on other machines, run: dotnet tool restore

    Global Installation

    To install the tool globally on your system, run: dotnet tool install --global DaveGreen.ShapeEngine.ResourcePacker

    dotnet new tool-manifest
    dotnet tool install --local DaveGreen.ShapeEngine.ResourcePacker
    
    # To restore later
    dotnet tool restore
  5. Install Shape Engine via NuGet

    main

    The recommended way to use Shape Engine is to create a new .NET solution and project, then add the DaveGreen.ShapeEngine package via the NuGet manager. This method automatically handles all necessary dependencies like Raylib-Cs and Clipper2Lib.

    dotnet add package DaveGreen.ShapeEngine
  6. Manual Installation and DLL Management

    main

    If you are not using NuGet, you must manually manage dependencies.

    Required DLLs:

    • Clipper2Lib
    • Raylib-Cs
    • Microsoft.Toolkit.HighPerformance
    • Shape Engine Core
    • Raylib

    Important Notes:

    • The Raylib DLL must be placed at the root level of your project.
    • All other DLLs can be placed anywhere in your project hierarchy.
    • macOS Users: Use the .dylib file instead of the Raylib DLL and set the property Copy if Newer to true on the file.
    • Ensure you select the correct Raylib DLL version for your specific operating system.
  7. Common ResourcePacker usage examples

    main

    Below are common patterns for using the tool via dotnet tool run.

    # Pack a folder into a binary resource pack
    dotnet tool run shapeengine-resourcepacker -- pack Resources ./build/resources.res
    
    # Pack a folder into a text-based resource pack
    dotnet tool run shapeengine-resourcepacker -- pack Resources ./build/resources.txt
    
    # Unpack a resource pack
    dotnet tool run shapeengine-resourcepacker -- unpack ./build/resources.res ./build/unpacked-resources
    
    # Exclude specific extensions (e.g., .psd and .aseprite)
    dotnet tool run shapeengine-resourcepacker -- pack Resources ./build/resources.res --exceptions .psd .aseprite
    
    # Enable debug logging and parallel processing
    dotnet tool run shapeengine-resourcepacker -- pack Resources ./build/resources.res --debug --parallel
  8. Use the shapeengine-resourcepacker CLI

    main

    The shapeengine-resourcepacker CLI is used to pack resource directories into single files or unpack them back into directories.

    Format Selection

    • Binary Format: Use any file extension other than .txt for the output/input file (e.g., .res).
    • Text Format: Use the .txt extension for the output/input file to use the text-based format.

    Commands

    • pack <sourceDirectoryPath> <outputFilePath>: Packs a directory into a resource pack.
    • unpack <sourceFilePath> <outputDirectoryPath>: Unpacks a resource pack into a directory.
    • help or --help: Displays help information.

    If you run the tool without any arguments, it will open an interactive prompt.

    shapeengine-resourcepacker pack <sourceDirectoryPath> <outputFilePath> [--exceptions <.ext1> <.ext2> ...] [--debug] [--parallel]
    shapeengine-resourcepacker unpack <sourceFilePath> <outputDirectoryPath> [--exceptions <.ext1> <.ext2> ...] [--debug] [--parallel]
    shapeengine-resourcepacker help
    shapeengine-resourcepacker --help