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.

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, 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.

AddEntityDebugSceneRenderer(Game, EntityDebugSceneRendererOptions?)

Adds an EntityDebugSceneRenderer to the game's GraphicsCompositor for rendering entity debug information.

public static void AddEntityDebugSceneRenderer(this Game game, EntityDebugSceneRendererOptions? options = null)

Parameters

game Game

The Game instance to which the entity debug renderer will be added.

options EntityDebugSceneRendererOptions

Optional settings to customize the appearance of the debug renderer. If not provided, default options will be used.

Examples

The following example demonstrates how to add an entity debug renderer with default settings:

game.EntityDebugSceneRenderer();

You can also specify custom options:

var options = new EntityDebugRendererOptions { FontSize = 16, FontColor = Color.Red };
game.EntityDebugSceneRenderer(options);

Remarks

This method adds a custom EntityDebugSceneRenderer to the game's graphics compositor, allowing the display of debug information such as entity names and positions in a 3D scene. The renderer can be customized using the options parameter, which allows the user to define font size, color, and other settings.

Exceptions

InvalidOperationException

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

AddGraphicsCompositor(Game)

Adds a default GraphicsCompositor with enabled post-effects to the specified Game instance and sets it as the game's SceneSystem GraphicsCompositor.

public static GraphicsCompositor AddGraphicsCompositor(this Game game)

Parameters

game Game

The Game instance to which the GraphicsCompositor will be added.

Returns

GraphicsCompositor

The newly configured GraphicsCompositor instance with enabled post-effects.

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) 

public static void AddParticleRenderer(this Game game)

Parameters

game Game

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) 

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

Parameters

game Game
renderFeature RootRenderFeature

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.

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.

SetupBase(Game)

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

public static void SetupBase(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.

ShowColliders(Game)

Enables the visualization of collider shapes in the game scene. This feature is useful for debugging physics-related issues.

public static void ShowColliders(this Game game)

Parameters

game Game

The current game instance.

Remarks

This method activates the rendering of collider shapes within the physics simulation. It helps to visually inspect and debug the positioning and behaviour of colliders at runtime.

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