Table of Contents

Class Game

Namespace
BSGameLib.Game
Assembly
BSGameLib.Game.dll

The base class for a game. Subclass it, override the methods a game needs, such as Initialize and Update, and call Run() to start the game loop.

public abstract class Game : IGame, IDisposable
Inheritance
Game
Implements
Inherited Members

Constructors

Game()

Creates a game with a default window.

protected Game()

Game(IWindowOptions)

Creates a game whose window is made from options.

protected Game(IWindowOptions options)

Parameters

options IWindowOptions

Properties

BaseServiceDescriptors

The service registrations the game starts from. Pass them to RebuildServiceProvider(IEnumerable<ServiceDescriptor>, Action<IServiceCollection>) with overrides added.

protected IReadOnlyList<ServiceDescriptor> BaseServiceDescriptors { get; }

Property Value

IReadOnlyList<ServiceDescriptor>

ContentManager

Loads and caches the game's content, such as textures and fonts.

public IContentManager ContentManager { get; }

Property Value

IContentManager

CurrentKeyboard

The keyboard state for this frame.

protected Keyboard.Snapshot CurrentKeyboard { get; }

Property Value

Keyboard.Snapshot

DisplayController

Controls the display, such as its VSync and fullscreen state.

public IDisplayController DisplayController { get; }

Property Value

IDisplayController

FrameDeltaSeconds

The length of one update step in seconds: always 1/60, since the loop runs updates at a fixed 60 a second however fast it draws. The same as DeltaSeconds.

protected float FrameDeltaSeconds { get; }

Property Value

float

GraphValidationMode

How much each frame graph is checked. Full in debug builds, Disabled in release builds.

protected FrameGraphValidationMode GraphValidationMode { get; set; }

Property Value

FrameGraphValidationMode

Graphics2D

The 2D drawing entry points, for sprites and other 2D draws.

public IGraphics2D Graphics2D { get; }

Property Value

IGraphics2D

Keyboard

The keyboard. The state for each frame is in CurrentKeyboard and PreviousKeyboard.

protected Keyboard Keyboard { get; }

Property Value

Keyboard

LastDrawTime

The last frame's draw duration in whole milliseconds, presenting included.

protected long LastDrawTime { get; }

Property Value

long

LastPollEventTime

When the platform last polled for events, in milliseconds since it started.

protected long LastPollEventTime { get; }

Property Value

long

LastUpdateTime

The last update step's duration in whole milliseconds.

protected long LastUpdateTime { get; }

Property Value

long

Logger

The game's logger. Null until the service container exists.

protected ILogger<Game> Logger { get; }

Property Value

ILogger<Game>

PreviousKeyboard

The keyboard state for the frame before this one.

protected Keyboard.Snapshot PreviousKeyboard { get; }

Property Value

Keyboard.Snapshot

RenderContextFactory

Begins render passes and runs frame graphs for the game's drawing.

protected IRenderContextFactory RenderContextFactory { get; }

Property Value

IRenderContextFactory

RenderSurface

The surface the game draws to.

public IRenderSurface RenderSurface { get; }

Property Value

IRenderSurface

ServiceProvider

The container the game resolves services from. Null until Run() has built the services.

protected IServiceProvider ServiceProvider { get; }

Property Value

IServiceProvider

ShaderManager

Holds the shaders and materials the game draws with.

public ShaderManager ShaderManager { get; }

Property Value

ShaderManager

ShapeRenderer

Draws shapes with the shape material.

public ShapeRenderer ShapeRenderer { get; }

Property Value

ShapeRenderer

TextRenderer

Turns text into sprite draws, so glyphs go through the same path as other sprites.

protected ITextRenderer TextRenderer { get; }

Property Value

ITextRenderer

UnscopedServiceProvider

The root service container. It owns the game's services, and is replaced by RebuildServiceProvider(IEnumerable<ServiceDescriptor>, Action<IServiceCollection>).

protected IServiceProvider UnscopedServiceProvider { get; }

Property Value

IServiceProvider

Window

The game's window. Set once Run() has created it.

protected IGameWindow Window { get; }

Property Value

IGameWindow

Methods

AddComponent(Component)

Adds a component, so that its update and draw run each frame when it has them.

public void AddComponent(Component component)

Parameters

component Component

Exceptions

InvalidOperationException

The services have not been built yet, which is before Run() builds them.

AddDefaultRenderGraphPass(FrameGraphBuilder, IGameTime, FrameGraphPassHandle?, Color?)

Adds the framework's default render pass: clears (if clearColor is given), calls Draw(IGameTime), then draws every registered IDrawable in BSGameLib.Game.Game.Drawables order. Every sample game calls this from ConfigureRenderGraph(FrameGraphBuilder, IGameTime), either as the only pass (the base implementation's behavior) or last, depending on an earlier custom pass via dependsOn (e.g. a scene pass that needs to run first).

protected FrameGraphPassHandle AddDefaultRenderGraphPass(FrameGraphBuilder builder, IGameTime gameTime, FrameGraphPassHandle? dependsOn = null, Color? clearColor = null)

Parameters

builder FrameGraphBuilder
gameTime IGameTime
dependsOn FrameGraphPassHandle?

An earlier pass's handle this one should run after — pass the value returned by that pass's own Execute(Action<FrameGraphPassContext>) call. Omit for a single-pass game.

clearColor Color?

When given, the pass clears the color buffer to this color before drawing. Omit to leave whatever was already in the target (rarely what you want for the back buffer).

Returns

FrameGraphPassHandle

BeginFrame(IGameTime)

Runs once per frame, after the update steps and before the render graph is built. Rarely overridden — most per-frame setup belongs in Update(IGameTime).

protected virtual void BeginFrame(IGameTime gameTime)

Parameters

gameTime IGameTime

Configure(IServiceCollection)

Register your own services into the DI container before anything else spins up. Called once, before Initialize(). This is the place for collection.AddUI(), logging, and anything your GetService<TService>() calls elsewhere will need resolved.

protected virtual void Configure(IServiceCollection collection)

Parameters

collection IServiceCollection

ConfigureRenderGraph(FrameGraphBuilder, IGameTime)

Builds this frame's render graph. The base implementation just calls AddDefaultRenderGraphPass(FrameGraphBuilder, IGameTime, FrameGraphPassHandle?, Color?) with no clear color and no dependency — fine for a game that only needs Draw(IGameTime) plus registered IDrawables and doesn't care what was in the back buffer beforehand. Override this once you need any of: a clear color (pass one to AddDefaultRenderGraphPass(FrameGraphBuilder, IGameTime, FrameGraphPassHandle?, Color?) instead of a full override, if that's the only thing you need), multiple passes (e.g. a scene pass feeding a post-process pass), or resources that need explicit read/write/dependency declarations. See FrameGraphBuilder's remarks for the usual shape of a custom pass, and FrameGraphTemplates for ready-made multi-pass shapes (scene+post-process+UI, shadow maps) before hand-rolling your own.

protected virtual void ConfigureRenderGraph(FrameGraphBuilder builder, IGameTime gameTime)

Parameters

builder FrameGraphBuilder
gameTime IGameTime

CreateServiceProvider(IServiceCollection)

Builds the service container from services. Override it to use another container.

protected virtual IServiceProvider CreateServiceProvider(IServiceCollection services)

Parameters

services IServiceCollection

Returns

IServiceProvider

Dispose()

Releases the game's services, render context, window and platform. Safe to call more than once.

public void Dispose()

Dispose(bool)

Releases the game's resources. Override it to release your own, and call the base.

protected virtual void Dispose(bool isDisposing)

Parameters

isDisposing bool

Draw(IGameTime)

Simple, single-pass immediate-mode drawing hook for games that don't need a custom ConfigureRenderGraph(FrameGraphBuilder, IGameTime) override. Called automatically from within the framework's default render-graph pass (AddDefaultRenderGraphPass(FrameGraphBuilder, IGameTime, FrameGraphPassHandle?, Color?)), before registered IDrawable components draw — only if your ConfigureRenderGraph(FrameGraphBuilder, IGameTime) override (or the base one, if you don't override it) actually calls AddDefaultRenderGraphPass(FrameGraphBuilder, IGameTime, FrameGraphPassHandle?, Color?). The default pass has no render-pass descriptor of its own, so relying on Draw(IGameTime) alone gives you no explicit clear — use AddDefaultRenderGraphPass(FrameGraphBuilder, IGameTime, FrameGraphPassHandle?, Color?)'s clearColor parameter (or override ConfigureRenderGraph(FrameGraphBuilder, IGameTime) yourself) once you need one. Prefer overriding ConfigureRenderGraph(FrameGraphBuilder, IGameTime) instead of this once you need more than one pass, a specific render target, or resource dependencies between passes.

protected virtual void Draw(IGameTime gameTime)

Parameters

gameTime IGameTime

EndFrame(IGameTime)

Runs once per frame, after the render graph has executed.

protected virtual void EndFrame(IGameTime gameTime)

Parameters

gameTime IGameTime

ExecuteDefaultRenderGraphPass(IGameTime)

The execute delegate AddDefaultRenderGraphPass(FrameGraphBuilder, IGameTime, FrameGraphPassHandle?, Color?) wires up: calls Draw(IGameTime), then draws every visible IDrawable in BSGameLib.Game.Game.Drawables, ordered by DrawOrder. You generally don't call this directly — it exists as its own method so a custom ConfigureRenderGraph(FrameGraphBuilder, IGameTime) override could reuse it as an Execute delegate for a differently-configured pass if needed.

protected void ExecuteDefaultRenderGraphPass(IGameTime gameTime)

Parameters

gameTime IGameTime

Exit()

Ends the game loop after the current frame. Run() returns once the loop has exited.

public virtual void Exit()

~Game()

Releases unmanaged resources if Dispose() was not called.

protected ~Game()

GetComponent<TComponent>()

Returns the first drawable or updatable component of type TComponent, or null when there is none.

public TComponent GetComponent<TComponent>() where TComponent : Component

Returns

TComponent

Type Parameters

TComponent

GetService<TService>()

Returns the service of type TService, or null when it is not registered.

public TService GetService<TService>()

Returns

TService

Type Parameters

TService

Exceptions

InvalidOperationException

The services have not been built yet, which is before Run() builds them.

Initialize()

Runs once after the window/render backend/DI container are ready but before the game loop starts. Load content, set the window size, call ViewManager.SetView<T>() — anything that needs services to exist but only needs to happen once.

protected virtual void Initialize()

RebuildServiceProvider(IEnumerable<ServiceDescriptor>, Action<IServiceCollection>)

Replaces the service container with one built from descriptors and the overrides that configureOverrides adds, then disposes the old one.

protected void RebuildServiceProvider(IEnumerable<ServiceDescriptor> descriptors, Action<IServiceCollection> configureOverrides)

Parameters

descriptors IEnumerable<ServiceDescriptor>
configureOverrides Action<IServiceCollection>

RefreshCoreServices()

Re-reads the core services, such as the window and renderers, from the container. Called after the container is rebuilt.

protected virtual void RefreshCoreServices()

RemoveComponent(Component)

Removes a component added with AddComponent(Component). A component that is not added does nothing.

public void RemoveComponent(Component component)

Parameters

component Component

Run()

Starts the game: opens the window, runs Initialize, then loops until Exit() is called. Returns when the loop has exited.

public void Run()

Update(IGameTime)

Runs once per frame, before the render graph is built. Input handling, game logic, camera movement — anything that changes state the render graph will read this frame.

protected virtual void Update(IGameTime gameTime)

Parameters

gameTime IGameTime

Remarks

Input is already current when it runs: the frame loop updates the keyboard and mouse managers and every player slot's IInputBindingService (see PlayerInputManager) once per update step, straight after the platform's events, whether or not the game uses BSGameLib.UI. Don't update them again here; a second update in the same step loses every just-pressed edge.