diff --git a/Introduction.md b/Introduction.md new file mode 100644 index 0000000..bc146ca --- /dev/null +++ b/Introduction.md @@ -0,0 +1,107 @@ +# Introduction + +> [!IMPORTANT] +> Voile is still work in progress and not production-ready. Expect stability and performance issues, lacking documentation, and experimental APIs. + +Welcome to the documentation for Voile, a cross-platform game framework written in C#. + +## Considerations + +Before using Voile or any other software, its important to know if a particular engine/framework is suitable for your workflow, goals and requirements. **Here's what Voile doesn't try to be**: + +- **A fully fledged game IDE with a scene editor**. Voile will have its own editors for some resources (particles, asset bundles, etc.) and a default module for a scene graph based on Entity Component architecture, but it will not provide a full blown scene editor in itself. Consider alternatives such as Godot or Unity if you require tight integration with a WYSIWYG editor. +- **A cutting edge 3D engine**. Voile will provide basic 3D functionality suitable for PSX or cartoon-styled games, but if you want to make AAA grade 3D graphics, consider Unreal or Unity. +- **A dedicated game engine**. Voile will never provide tools for a specific genre. Think of it as a collection of libraries that simplify work with rendering, input, physics, and creating your own tools for modifying your game-specific content. Entity management, order of execution, etc. is managed manually by the user. + +## What's missing + +Voile is still work in progress, but has a [roadmap](roadmap.md) with planned features. + +## Features + +- 2D rendering. +- **Minimal size and fast startups**. Voile is built with NativeAOT compatibility in mind, doesn't ship unnecessary things, and doesn't run anything without your knowledge. +- **Full control over resources and lifetime**. No default main loop behavior, implicit system initialization (more on that later), and resources instantiation. +- **Content hot-reloading**. All resources can be reloaded while the game is running, reducing iteration time. + +## Minimal project example + +### TestGame.cs + +```csharp +using Voile; +using Voile.Resources; +using Voile.Utils; + +public class TestGame : Game +{ + public override string ResourceRoot => "Resources/"; + + // Called when it's time to initialize the subsystems, or modify default game settings or system settings. + public override void Initialize() + { + // Initializes systems with defaults. + InitializeDefault(); + } + + // Called when it's time to load the game's resources, such as images or sounds. + protected override void LoadResources() + { + if (!ResourceManager.TryLoad("my_sound", "sounds/test_sound.ogg", out Sound? _testSound)) + { + // Handle resource load failure here. + // Display an on-screen alert, close the game, reload from a different path, etc. + } + + if (!ResourceManager.TryLoad("inter_regular", "fonts/Inter-Regular.ttf", out Font? _font)) + { + // Handle resource load failure here. + // Display an on-screen alert, close the game, reload from a different path, etc. + } + } + + // Called when it's safe to manipulate the resources or/and systems. + // You can safely create game objects, scenes, etc. in this method. + protected override void Ready() + { + Input.AddInputMapping("play", new InputAction[] { new KeyInputAction(KeyboardKey.Spacebar) }); + Input.AddInputMapping("sprint", new InputAction[] { new KeyInputAction(KeyboardKey.LeftShift) }); + Input.AddInputMapping("toggle_fullscreen", new InputAction[] { new KeyInputAction(KeyboardKey.F11) }); + } + + // Called when everything has been readied to start the main loop. + protected override void Run() + { + while (Renderer.ShouldRun) + { + if (Input.IsActionPressed("play")) + { + _logger.Echo("Spacebar pressed!"); + } + + Renderer.BeginFrame(); + // Sets transform for drawing at the center of the screen. We won't use transform pivot. + Renderer.SetTransform(position: Renderer.WindowSize / 2, pivot: Vector2.Zero); + Renderer.DrawCircle(radius: 16f, Color.White); + Renderer.EndFrame(); + } + } + + // Called when the application quits and it's safe to clean up. + public override void Shutdown() + { + // Default resource shutdown and cleanup. + ShutdownDefault(); + } + + private Logger _logger = new(nameof(TestGame)); +} +``` + +### Program.cs + +```csharp +// Use the default constructor for game. +var game = new TestGame(); +game.Start(); +```