Getting started

Install DarkRoast, connect it to Blender, and play your first level.

1. What you need

Windows 10 or 11, 64-bit.
A graphics card with OpenGL 4.5 — practically anything from the last ten years.
Blender 4.0 or newer.

2. Install the engine

Download Windows build from the download page.

Unzip it somewhere permanent, for example C:\BlendForge. You’ll get:

`blendforge.exe`	The engine you test with. Has a console window, stats overlay and hot reload.
`blendforge_player.exe`	The shipping version Package Game copies into your finished game.
`blendforge_addon.zip`	The Blender add-on. Don’t unzip it — Blender installs it as a zip.
`*.dll`	Visual C++ runtime, so nothing else needs installing.

SmartScreen? The programs are code-signed by Sentient Bean LLC, but Windows may still ask until they’ve built up download reputation. Click More info → Run anyway.

3. Install the Blender add-on

In Blender open Edit → Preferences → Add-ons.
Click the ⌄ menu at the top right and choose Install from Disk…
Pick blendforge_addon.zip and make sure BlendForge is ticked.
Expand BlendForge in the list and set Engine executable to C:\BlendForge\blendforge.exe. A green tick reading Using: … means it’s found.

4. Your first level

Start a new General file in Blender. Keep the cube, camera and light.
Add a floor: Add → Mesh → Plane, then scale it up (S 20 Enter).
Move the cube up so it’s sitting on or above the floor.
In the 3D viewport press N to open the sidebar and click the BlendForge tab on its right edge.
Put the 3D cursor where you want to start and click Add Player Start. The arrow points the way the player faces.
Select the cube and in Object Components set Body to Dynamic.
Click Play (or the ▶ button in the viewport header).

The game window opens. Walk with WASD, look with the mouse, left-click the cube to pick it up and right-click to throw it.

Everything is Static by default. Floors and walls just work. Only change the Body of things that should move, fall, or detect the player.

5. Change it while it runs

Leave the game open and go back to Blender:

Live Link (on by default) — move objects, hide them, or change light colours and strength, and the running game updates immediately.
Update — while the game is open the Play button reads Update. Click it after editing meshes, materials, components or scripts to hot-reload the level.

6. Add your first script

Select the cube. In Object Components → Script click the new-file button. This creates Cube.lua from a template.
Change any area of Blender to the Text Editor to see it (the Scripting workspace has one ready).

Replace the on_update function with:

function on_update(self, dt)
  self:rotate(0, 0, 45 * dt)   -- spin 45 degrees per second
end

Set the cube’s Body to Kinematic (scripts and animation move Kinematic bodies; physics moves Dynamic ones) and click Play / Update.
Look at the cube and press E — the template’s on_interact shows a message.

Controls

Key	Action	Gamepad
`WASD` / mouse	Move / look	Left stick / right stick
`Space`	Jump	A
`Shift`	Sprint
`E`	Use the thing under the crosshair	X
Left click	Pick up / drop	RB
Right click	Throw	RT
`Ctrl` (hold)	Crouch: lower, slower, and you stay down under anything low	B
`V`	Fly mode (`Q`/`E` down/up), while testing your level; packaged games don’t fly unless the level allows it (`player_options{fly=true}`)
`C`	First / third person (if the level allows it): you play as an animated cowboy	Right stick click
`R`	Respawn
`Esc`	Pause menu: resume, restart, volume, mouse speed, controls, quit	Start

Every control can be rebound in Pause → Settings & controls.

Graphics quality: the first time a game runs, it picks Low, Medium, High or Ultra for your graphics card (Low on Intel and AMD integrated graphics). Change it under Pause → Settings & controls.

VR: start a level or a packaged game with --vr to play in a Meta Quest (Link or Air Link) or SteamVR headset. Left stick moves, right stick snap-turns; the right controller aims (a red dot shows where) and its trigger grabs or shoots, the left trigger throws, the right grip uses, the left grip reloads (respawn), A jumps, B crouches, X holsters, Y pauses and a right stick click switches weapon. The HUD and menus float in front of you: point at a menu and pull the trigger to click. Add --vr-scale 1.3 for a sharper picture if the graphics card keeps up; VR draws lighter than the desktop unless you add --vr-graphics full (both are saved). Standing, your eyes are put at the player’s eye height, the characters’ own, whatever your real height (a second after the headset starts tracking; crouching for real still crouches). With no headset it plays on the desktop.

Try the samples

The Samples & docs download has a samples folder. Open samples\test_level.blend and press Play to explore a level with coins, doors, a lift, a gate, a ball spawner, sounds and an animated tentacle — click any object to read its script. No Blender? Drag samples\test_level.glb onto blendforge.exe.

For racing, open samples\racing_demo.blend: your car against three AI drivers over three laps. See Cars & racing.

For 2D, open samples\2d_demo.blend: a pixel-art side-scroller (A/D or arrows to run, Space to jump). See 2D games.

← Help home The Blender add-on →