Table of Contents

Class GameExtensions

Namespace
Stride.CommunityToolkit.Engine
Assembly
Stride.CommunityToolkit.dll

Provides extension methods for the Game class to simplify common game setup tasks, such as adding cameras, lights, and ground entities, as well as configuring scenes and running the game with custom logic.

public static class GameExtensions
Inheritance
GameExtensions

Methods

Add2DCamera(Game, string?, Vector3?, Vector3?)

Adds a 2D camera entity to the game's root scene with customizable position and rotation, defaulting to orthographic projection.

public static Entity Add2DCamera(this Game game, string? cameraName = "Main", Vector3? initialPosition = null, Vector3? initialRotation = null)

Parameters

game Game

The Game instance to which the camera entity will be added.

cameraName string

Optional name for the camera entity and camera slot. Defaults to "MainCamera" if not provided. If null, the entity will not be named.

initialPosition Vector3?

Initial position for the camera entity. If not provided, the camera will be positioned at a default 2D position.

initialRotation Vector3?

Initial rotation for the camera entity specified in degrees. If not provided, the camera will be rotated to the default 2D orientation.

Returns

Entity

The created Entity object representing the 2D camera.

Remarks

The camera entity will be created with an orthographic projection mode and added to the game's root scene. It will also be assigned to the first available camera slot in the GraphicsCompositor.

Add2DGraphicsCompositor(Game, Color?)

Adds a 2D graphics compositor to the specified game, optionally setting a clear color.

public static GraphicsCompositor Add2DGraphicsCompositor(this Game game, Color? clearColor = null)

Parameters

game Game

The game to which the 2D graphics compositor will be added. Cannot be null.

clearColor Color?

The color used to clear the screen. Defaults to CornflowerBlue if not specified.

Returns

GraphicsCompositor

The newly created 2D graphics compositor.

Remarks

This method sets the graphics compositor of the game's scene system to a default 2D configuration without post-processing effects. The clear color can be specified to customize the background color of the rendered scene.

Add3DCamera(Game, string?, Vector3?, Vector3?, CameraProjectionMode)

Adds a 3D camera entity to the game's root scene with customizable position, rotation, projection mode and default camera name "Main".

public static Entity Add3DCamera(this Game game, string? cameraName = "Main", Vector3? initialPosition = null, Vector3? initialRotation = null, CameraProjectionMode projectionMode = CameraProjectionMode.Perspective)

Parameters

game Game

The Game instance to which the camera entity will be added.

cameraName string

Optional name for the camera entity and camera slot. Defaults to "MainCamera" if not provided. If null, the entity will not be named.

initialPosition Vector3?

Initial position for the camera entity. If not provided, the camera will be positioned at a default 3D position (6, 6, 6).

initialRotation Vector3?

Initial rotation for the camera entity specified in degrees. If not provided, the camera will be rotated to face towards the origin with default angles (Yaw: 45, Pitch: -30, Roll: 0).

projectionMode CameraProjectionMode

The projection mode for the camera (Perspective or Orthographic). Defaults to Perspective.

Returns

Entity

The created Entity object representing the 3D camera.

Remarks

The camera entity will be created with the specified projection mode and added to the game's root scene. It will also be assigned to the first available camera slot in the GraphicsCompositor.

Exceptions

InvalidOperationException

Thrown if the GraphicsCompositor does not have any camera slots defined.

AddAllDirectionLighting(Game, float, bool)

Adds directional lighting from multiple angles to the current scene, enhancing scene illumination.

public static void AddAllDirectionLighting(this Game game, float intensity = 5, bool showLightGizmo = true)

Parameters

game Game

The game instance to which the lighting will be added.

intensity float

The intensity of the light sources.

showLightGizmo bool

Specifies whether to display a gizmo for the light in the editor. Default is true.

Remarks

This method creates six directional lights positioned around a central point, each aiming from a unique angle to simulate uniform lighting from all directions. The lights are added at predefined positions and rotations to cover the scene evenly.

AddDirectionalLight(Game, string?)

Adds a directional light entity to the game's root scene with optional customization.

public static Entity AddDirectionalLight(this Game game, string? entityName = "Directional Light")

Parameters

game Game

The Game instance to which the directional light will be added.

entityName string

Optional name for the new directional light entity. If null, the entity will not be named.

Returns

Entity

The created Entity object representing the directional light.

Remarks

This method creates a directional light with the following default settings: - Intensity: 20.0f - Position: (0, 2.0f, 0) - Rotation: X-axis rotated by -30 degrees and Y-axis rotated by -180 degrees. - Shadow Enabled: True - Shadow Size: Large - Shadow Filter: PCF (Percentage Closer Filtering) with a filter size of 5x5

The entity will be added to the game's root scene. You can customize the light properties by accessing the returned Entity object.

AddGraphicsCompositor(Game)

Adds a default graphics compositor with post-processing effects enabled to the specified game.

public static GraphicsCompositor AddGraphicsCompositor(this Game game)

Parameters

game Game

The game to which the graphics compositor will be added. Cannot be null.

Returns

GraphicsCompositor

The newly created GraphicsCompositor with post-processing effects enabled.

AddGroundGizmo(Game, Vector3?, bool, bool)

Adds a ground gizmo to the game's root scene, attached to an existing ground entity.

public static void AddGroundGizmo(this Game game, Vector3? position = null, bool showAxisName = false, bool rotateAxisNames = true)

Parameters

game Game

The Game instance in which the ground gizmo will be added.

position Vector3?

The position of the gizmo in 3D space. If null, the gizmo will be placed at the origin (0, 0, 0).

showAxisName bool

A boolean indicating whether the axis names (X, Y, Z) should be displayed on the gizmo. Default is false.

rotateAxisNames bool

A boolean indicating whether the axis names should rotate to always face the camera. Default is true.

Remarks

The gizmo is added as a child to an existing ground entity. If the ground entity is not found, the method will return without adding the gizmo. The gizmo helps visualize the ground with axis indicators in 3D space.

AddParticleRenderer(Game)

Adds particle rendering capabilities to the specified game.

public static void AddParticleRenderer(this Game game)

Parameters

game Game

The game to which particle rendering stages and features will be added. Cannot be null.

Remarks

This method extends the game's graphics compositor by incorporating stages and features necessary for rendering particles. Ensure that the game has a valid scene system before invoking this method.

AddProfiler(Game, string?)

Adds a profiler to the game, which can be toggled on/off with Left Shift + Left Ctrl + P, and provides other keyboard shortcuts. Changing the filtering mode with F1, altering the sorting mode with F2, navigating result pages with F3 and F4, and adjusting the refresh interval with the plus and minus keys.

public static Entity AddProfiler(this Game game, string? entityName = "Game Profiler")

Parameters

game Game

The game to which the profiler will be added.

entityName string

Optional name for the entity to which the GameProfiler script will be attached.

Returns

Entity

The entity to which the GameProfiler script was attached.

Remarks

This extension method creates an entity and attaches a GameProfiler script to it, enabling in-game profiling. The profiler's behaviour can be interacted with using various keyboard shortcuts as described in the GameProfiler class.

AddRootRenderFeature(Game, RootRenderFeature)

Adds a root render feature to the game's graphics compositor.

public static void AddRootRenderFeature(this Game game, RootRenderFeature renderFeature)

Parameters

game Game

The game instance to which the render feature will be added. Cannot be null.

renderFeature RootRenderFeature

The root render feature to add. Cannot be null.

AddSceneRenderer(Game, SceneRendererBase)

Adds a scene renderer to the game's GraphicsCompositor.

public static void AddSceneRenderer(this Game game, SceneRendererBase renderer)

Parameters

game Game

The Game instance to add the renderer to.

renderer SceneRendererBase

The scene renderer to be added, inheriting from SceneRendererBase.

Exceptions

ArgumentNullException

Thrown when the renderer is null.

InvalidOperationException

Thrown if the GraphicsCompositor is not set in the game's SceneSystem.

CreateFlatMaterial(IGame, Color?)

Creates a material with flat colors that aren't affected by lighting, ideal for 2D rendering.

public static Material CreateFlatMaterial(this IGame game, Color? color = null)

Parameters

game IGame

The game instance used to access the graphics device.

color Color?

The color of the material. Uses white if not specified.

Returns

Material

A new material instance with flat coloring unaffected by lighting.

CreateMaterial(IGame, Color?, float, float)

Creates a basic material with optional color, specular reflection, and microsurface smoothness values.

public static Material CreateMaterial(this IGame game, Color? color = null, float specular = 1, float microSurface = 0.65)

Parameters

game IGame

The game instance used to access the graphics device.

color Color?

The color of the material. Defaults to null, which will use the _defaultMaterialColor.

specular float

The specular reflection factor of the material. Defaults to 1.0f.

microSurface float

The microsurface smoothness value of the material. Defaults to 0.65f.

Returns

Material

A new material instance with the specified or default attributes.

Run(Game, GameContext?, Action<Game>?, Action<Game>?)

Initializes the game, starts the game loop, and handles game events.

public static void Run(this Game game, GameContext? context = null, Action<Game>? start = null, Action<Game>? update = null)

Parameters

game Game

The Game instance to initialize and run.

context GameContext

Optional GameContext to be used. Defaults to null.

start Action<Game>

Optional action to execute at the start of the game. Takes the game as a parameter.

update Action<Game>

Optional action to execute during each game loop iteration. Takes the game as a parameter.

Remarks

This method performs the following actions:

  1. Schedules the root script for execution.
  2. Initiates the game loop by calling Run(GameContext).
  3. Invokes the provided start and update delegates.

Run(Game, GameContext?, Action<Scene>?, Action<Scene, GameTime>?)

Initializes the game, starts the game loop, and handles game events.

public static void Run(this Game game, GameContext? context = null, Action<Scene>? start = null, Action<Scene, GameTime>? update = null)

Parameters

game Game

The Game instance to initialize and run.

context GameContext

Optional GameContext to be used. Defaults to null.

start Action<Scene>

Optional action to execute at the start of the game. Takes the root scene as a parameter.

update Action<Scene, GameTime>

Optional action to execute during each game loop iteration. Takes the root scene and game time as parameters.

Remarks

This method performs the following actions:

  1. Schedules the root script for execution.
  2. Initiates the game loop by calling Run(GameContext).
  3. Invokes the provided start and update delegates.

SetupBase2D(Game, Color?)

Configures the game for 2D rendering by setting up the necessary graphics compositor and camera.

public static void SetupBase2D(this Game game, Color? clearColor = null)

Parameters

game Game

The game instance to configure for 2D rendering.

clearColor Color?

The color used to clear the screen. Defaults to CornflowerBlue if not specified.

SetupBase3D(Game)

Sets up essential components for the game, including a GraphicsCompositor, a camera, and a directional light.

public static void SetupBase3D(this Game game)

Parameters

game Game

The Game instance that will receive the base setup.

Remarks

This method performs the following operations:

  • Adds a default GraphicsCompositor to the game's SceneSystem and applies a clean UI stage.
  • Adds a camera to the game.
  • Adds a directional light to the game.

TakeScreenShot(IGame, string, ImageFileType)

Saves a screenshot of the current frame to the specified file path.

public static void TakeScreenShot(this IGame game, string fileName, ImageFileType fileType = ImageFileType.Png)

Parameters

game IGame
fileName string

creates a file with this name

fileType ImageFileType
Edit this page