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

object

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.

Add2DGround(Game, string?, Vector2?)

public static Entity Add2DGround(this Game game, string? entityName = "Ground", Vector2? size = null)

Parameters

game Game

entityName string

size Vector2?

Returns

Entity

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.

Add3DGround(Game, string?, Vector2?, bool)

Adds a 3D ground entity to the game with a default size of 10x10 units. The ground is created as a plane, and a collider can be optionally added.

public static Entity Add3DGround(this Game game, string? entityName = "Ground", Vector2? size = null, bool includeCollider = true)

Parameters

game Game

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

entityName string

The optional name for the ground entity. If not provided, it defaults to "Ground".

size Vector2?

The size of the ground, specified as a 2D vector. If not provided, it defaults to (10, 10) units.

includeCollider bool

Specifies whether to add a collider to the ground. Defaults to true.

Returns

Entity

The created Entity object representing the 3D ground.

Add3DGroundWithBepu(Game, string?, Vector2?, bool)

public static Entity Add3DGroundWithBepu(this Game game, string? entityName = "Ground", Vector2? size = null, bool includeCollider = true)

Parameters

game Game

entityName string

size Vector2?

includeCollider bool

Returns

Entity

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.

AddDebugShapes(Game, RenderGroup)

Adds ImmediateDebugRenderFeature and ImmediateDebugRenderSystem to the game.

Registers the system to the service registry for easy access.

public static void AddDebugShapes(this Game game, RenderGroup debugShapeRenderFroup = RenderGroup.Group1)

Parameters

game Game

debugShapeRenderFroup RenderGroup

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

AddInfinite3DGround(Game, string?, Vector2?, bool)

Adds an infinite 3D ground entity to the game. The visible part of the ground is defined by the size parameter, while the collider is infinite and extends beyond the visible ground.

public static Entity AddInfinite3DGround(this Game game, string? entityName = "Ground", Vector2? size = null, bool includeCollider = true)

Parameters

game Game

The Game instance to which the infinite ground entity will be added.

entityName string

The optional name for the ground entity. If not provided, it defaults to "Ground".

size Vector2?

Defines the visible part of the ground, specified as a 2D vector. If not provided, it defaults to (10, 10) units.

includeCollider bool

Specifies whether to add a collider to the ground. The collider is infinite, extending beyond the visible part. Defaults to true.

Returns

Entity

The created Entity object representing the infinite 3D ground.

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.

Create2DPrimitive(IGame, Primitive2DModelType, Primitive2DCreationOptions?)

public static Entity Create2DPrimitive(this IGame game, Primitive2DModelType type, Primitive2DCreationOptions? options = null)

Parameters

game IGame

type Primitive2DModelType

options Primitive2DCreationOptions

Returns

Entity

Create2DPrimitiveWithBepu(IGame, Primitive2DModelType, Primitive2DCreationOptionsWithBepu?)

public static Entity Create2DPrimitiveWithBepu(this IGame game, Primitive2DModelType type, Primitive2DCreationOptionsWithBepu? options = null)

Parameters

game IGame

type Primitive2DModelType

options Primitive2DCreationOptionsWithBepu

Returns

Entity

Create3DPrimitive(IGame, PrimitiveModelType, Primitive3DCreationOptions?)

Creates a primitive 3D model entity of the specified type with optional customizations.

public static Entity Create3DPrimitive(this IGame game, PrimitiveModelType type, Primitive3DCreationOptions? options = null)

Parameters

game IGame

The game instance.

type PrimitiveModelType

The type of primitive model to create.

options Primitive3DCreationOptions

The options for creating the primitive model. If null, default options are used.

Returns

Entity

A new entity representing the specified primitive model.

Remarks

The options parameter allows specifying various settings such as entity name, material, collider inclusion, size, render group, and 2D flag. Dimensions in the Vector3 for size are used in the order X, Y, Z. If size is null, default dimensions are used for the model. If no collider is included, the entity is returned without it.

Create3DPrimitiveWithBepu(IGame, PrimitiveModelType, Primitive3DCreationOptionsWithBepu?)

public static Entity Create3DPrimitiveWithBepu(this IGame game, PrimitiveModelType type, Primitive3DCreationOptionsWithBepu? options = null)

Parameters

game IGame

type PrimitiveModelType

options Primitive3DCreationOptionsWithBepu

Returns

Entity

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.

SetupBase2DScene(Game)

public static void SetupBase2DScene(this Game game)

Parameters

game Game

SetupBase2DSceneWithBepu(Game)

public static void SetupBase2DSceneWithBepu(this Game game)

Parameters

game Game

SetupBase3DScene(Game)

Sets up a default 3D scene for the game, similar to creating an empty project through the editor.

public static void SetupBase3DScene(this Game game)

Parameters

game Game

The Game instance for which the base 3D scene will be set up.

Remarks

This method performs the following setup operations in sequence:

1. Adds a default GraphicsCompositor to the game's SceneSystem and applies a clean UI stage.
2. Adds a camera to the game and sets it up with a MouseLookCamera component.
3. Adds a directional light to the game scene.
4. Adds ground geometry to the game scene.

SetupBase3DSceneWithBepu(Game)

public static void SetupBase3DSceneWithBepu(this Game game)

Parameters

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