Table of Contents

Game Extensions

Extension methods for Game and IGame. They cover starting the game loop, assembling a scene from nothing, and the small conveniences - frame rate, materials, screenshots - that you would otherwise write once per project.

They all live in Stride.CommunityToolkit.Engine, so one using covers everything on game.. Some take Game and some take IGame; at a call site the difference does not show, because a Game is an IGame.

Tip

If you are working code-only, Code-Only Extensions is the shorter, curated list - the subset you actually reach for when there is no editor to hand you a scene.

Starting the game

  • Run() - Starts the game loop. start runs once the root scene exists, update runs every frame after it.
  • Run() with async start - The same, with a start that can await between steps. update begins only once that task completes.
  • Exit() - Closes the game from an IGame reference.
  • SetWindowSize() - The size the window opens at, before Run; the engine's default is 1280 by 720.
  • UseGameSettings() - What a Game Studio project gets from its GameSettings asset, built in code and applied the same way: the configurations the audio, physics and navigation systems read (HRTF, physics defaults, navigation build settings, Bepu simulations), rendering settings (graphics profile, back buffer, colour space) and the shader compilation mode. Call it before Run(). Safe in a project that has the asset too: the asset wins, and the call only adds the configurations it lacks.
Note

On the compilation mode, measured rather than assumed: on Direct3D 11 Debug (the engine's default for a game without settings) and Release produce identical shader bytecode, because the compiler only applies the optimisation level when debug information is off. AppStore is the one that differs - optimisation level 2 with the symbols stripped, so RenderDoc no longer shows shader source. Vulkan and Direct3D 12 ignore the mode. Bytecode is cached per mode, so a change means one full recompile on the next run.

Scene setup

The compositor, camera, lighting, sky and ground of a code-only scene as one object that Run applies before start.

The physics packages choose the engine with UseBepu() and UseBullet() - see Physics Extensions; the pieces one by one are under Code-Only Extensions.

Graphics compositor

Nothing renders without a compositor. These add one, or hang extra renderers off the one you have.

  • AddGraphicsCompositor() - Adds the default compositor, with post-processing enabled and an optional clear colour.
  • Add2DGraphicsCompositor() - The 2D configuration, without post-processing.
  • AddSceneRenderer() - Appends your own SceneRendererBase to the compositor's render chain.
  • AddRootRenderFeature() - Registers a RootRenderFeature, for drawing a component type the engine does not know about.
  • AddParticleRenderer() - Adds the particle stages and features, which the default code-only compositor leaves out.
  • ConfigurePostEffects() - Switches post effects on and tunes them. The default compositor has bloom, ambient occlusion, depth of field, screen-space reflections, fog, outline and FXAA all present but disabled, and only tone mapping in its colour transforms; vignette, film grain and dither are not there at all until added to ColorTransforms.Transforms. See the Post Effects example.
  • GetPostEffects() - The live PostProcessingEffects, or null for a compositor without any (the 2D one), for toggling an effect at runtime.

Cameras

  • Add2DCamera() - Adds a 2D camera and binds it to the compositor's first camera slot.

  • Add3DCamera() - Adds a 3D camera, perspective by default.

  • Add2DCameraController() - Makes the 2D camera pannable and zoomable, with an on-screen key reminder toggled by F2.

  • Add3DCameraController() - Adds free-look movement. The F2 panel also prints the camera's live position and rotation, which is the quickest way to find numbers worth hard-coding.

  • SetCameraPosition() - Moves the existing camera. Use this after Run(setup, ...) rather than adding a second camera that competes for the same slot.

  • SetCameraRotation() - Aims the existing camera, taking yaw, pitch and roll in degrees.

  • GetCameraEntity() - The camera entity itself, for everything the two setters do not cover - reading the transform, attaching a script, replacing the camera outright.

See Camera Controllers for the keys, the on-screen help and every option on both scripts.

Lighting

  • AddDirectionalLight() - Adds a single directional light, with shadows on by default.
  • AddAllDirectionLighting() - Lights the scene from every direction at once, so nothing is left in shadow. Blunt, but it makes a debug scene readable.
  • AddStudioLighting() - A three-point key, fill and rim rig aimed at the scene centre, returned as a tuple so you can adjust each light afterwards.

The setup's gradient sky lights the scene from above; for a photographed sky, UseSkybox() and AddSkybox() ship in the Stride.CommunityToolkit.Skyboxes package - see Code-Only Extensions.

Materials and primitives

  • CreateMaterial() - A basic lit material, with optional colour, metalness and glossiness values.
  • CreateFlatMaterial() - An emissive material unaffected by lighting, which is what you want for 2D and for anything that must stay readable regardless of where the lights are.
  • CreateEmissiveMaterial() - A surface that gives off its own light: a lamp, a sign, a glowing edge. Above an intensity of 1 it blooms under post effects.
  • CreateTexturedMaterial() - A texture where the colour would be, tiled, with the same metalness and glossiness numbers.
  • CreateScreenMaterial() - A screen showing a texture, unlit and clamped: a monitor for a render-texture camera's feed.
  • CreateMaterial(descriptor) - Compiles a descriptor and keeps it on the material, so it can be a layer later. The descriptors behind every helper are in MaterialDescriptors: take one, add a feature, compile it.
  • CreatePrimitive(Primitive3D) - A cube, sphere, capsule and so on as an entity. The shape comes from a Primitive3D factory with its dimensions: Primitive3D.Sphere(0.5f), Primitive3D.Box(new Vector3(2, 1, 1)).
  • CreatePrimitive(Primitive2D) - The 2D equivalent - square, circle, triangle, polygon - from a Primitive2D factory.
Note

With UseBepu() or UseBullet() on the scene setup, both attach that engine's collider as well; IncludePhysics = false on the options leaves it out. See Physics Extensions.

Text renderers

Both register their renderer once, however many times you call them.

  • AddEntityTextRenderer() - Puts the renderer for EntityTextComponent, screen-space text drawn over the scene, on the compositor before the first frame; the component registers it itself when missing. See Entity Text.
  • AddWorldTextRenderer() - Puts the renderer for WorldTextComponent, text that lives in the 3D scene, on the compositor before the first frame; the component registers it itself when missing. See World Text.

Debugging and diagnostics

  • AddProfiler() - Adds Stride's profiler, toggled with Left Shift + Left Ctrl + P.
  • SetDeterministic() - Pins the loop so frame N is the same simulated instant on every run: fixed timestep, draws in step, one update per draw. For replays, lockstep, tests and screenshots.
  • AddGroundGizmo() - Draws the world axes at the origin, optionally labelled. Marks the origin and a unit in the scene.
  • AddOrientationGizmo() - Draws the world axes in a corner of the screen, turning with the camera. The quickest way to work out which way you are facing; see Orientation Gizmo.
  • AddEntityDebugSceneRenderer() - Draws entity names and positions over the scene. In Stride.CommunityToolkit.Rendering.Text.
  • TakeScreenShot() - Saves the current frame to a file. This is what the toolkit's own screenshot capture is built on.

To see colliders, use AddPhysicsDebug() for Bepu or ShowColliders() for Bullet, both in Physics Extensions.

Frame rate

These take IGame, since they need nothing from the scene.

Edit this page