Tips & troubleshooting
Debug tools, command-line options, known limits, and fixes for the most common problems.
Debug keys (development build)
| F1 | Stats overlay: frame time, draw calls, lights, physics bodies. |
| F3 | Show the navigation mesh the AI walks on. |
| F5 | Force-reload the level from disk. |
The console window behind the game shows load info, warnings and anything your scripts print().
Common problems
The game won’t start, or closes straight away
It shows a message saying why (no OpenGL 4.5, the graphics card or driver failing), and every run writes a log: %APPDATA%\BlendForge\<game name>\log.txt (paste that into Explorer’s address bar). Updating the graphics driver fixes most of these. Intel and AMD integrated graphics are supported. (Builds before 2026-10-21 failed on Intel graphics with shader storage buffer binding must be less than 16 in the log: download the current one.)
“DarkRoast engine not found”
Open Edit → Preferences → Add-ons → BlendForge and set Engine executable to your blendforge.exe. If you moved the DarkRoast folder, update the path.
Package Game says blendforge_player.exe is missing
blendforge_player.exe must sit in the same folder as blendforge.exe. Re-extract the Windows build zip.
I fall through the floor
- Check the floor’s Body isn’t No Collision or Trigger.
- A single flat Plane works, but very thin geometry plus fast movement can tunnel — give floors some thickness (Solidify modifier) or use a Box shape.
- Make sure the Player Start is above the floor, not inside it.
My object doesn’t move / fall
Objects are Static by default. Set it to Dynamic to fall and tumble, or Kinematic to move it from a script or animation.
My trigger never fires
- Its Body must be Trigger, and the script must define
on_trigger_enter(self, other)(spelled exactly). - The trigger needs volume. A flat plane has none — use a cube scaled thin.
- Add
print("entered", other.name)to check it’s being called.
Pressing E does nothing
The script needs on_interact, the object needs collision (not No Collision), and you need to be close and looking at it. A prompt appears next to [E] when it’s in reach.
find("Name") returns nil
Names are exact and case-sensitive. Duplicates are named Name.001, Name.002… — use find_all("Name") to get them all. Objects marked Template are only found by spawn().
Error: attempt to index a nil value
You used something that doesn’t exist, usually a find() that returned nil or a variable that was never set. The red message includes the line number. Guard with if obj then ... end.
My changes don’t show up
Live Link only streams moves, visibility and lights. For meshes, materials, components and scripts press Update. If something still looks stale, press F5 in the game or close it and press Play.
No sound
Check the file exists and is WAV, MP3, OGG or FLAC; save the .blend so relative paths resolve; for 3D sounds make sure you’re within the Radius; and check the in-game volume in the pause menu.
The level is too dark or washed out
Tune World → Exposure and Ambient first. Blender light wattages carry over, so a light that looks right in Eevee should look close in-game. If the World uses an HDRI, try Sky Strength.
Performance tips
- Use linked duplicates (Alt+D), collection instances or geometry-nodes scatters for repeated objects — they draw as one GPU batch. The forest sample draws 3000 trees this way.
- Untick Cast Shadows on small props and distant scenery.
- Prefer Box, Sphere or Capsule collision shapes for dynamic objects.
- Hundreds of point lights are fine; keep shadow-casting point and spot lights to the ones that matter.
- Use F1 to see what’s expensive.
- Slow on a laptop? Pause → Settings & controls → Quality: Low renders at two thirds of the window (TAA rebuilds the full picture) and leaves out the costly effects. Integrated graphics start on Low by themselves.
Known limits
- Cars copied with
spawn()don’t get wheels: place every car in Blender. - Sprites don’t cast shadows, and each is its own draw call. 2D physics locks bodies to the X/Z plane only (side views).
- Only the 8 strongest shape keys per mesh apply at once.
- The navmesh is a single tile built at load — levels larger than about 1 km aren’t supported for AI yet.
- Live Link streams transforms, visibility and lights; mesh and material edits need Update.
- Windows only for now. The renderer is OpenGL 4.5, or Vulkan 1.3 with
--vulkan; VR is OpenGL-only so far.
Command line
Run blendforge.exe directly for testing and automation:
blendforge.exe [level.glb] [--size W H] [--fullscreen] [--camera x y z yaw pitch]
[--screenshot out.png] [--frames N] [--script extra.lua] [--timeout seconds]
[--host [port]] [--join address[:port]] [--vr] [--vr-scale x] [--vr-graphics light|full]
[--vulkan] [--plugin folder]
blendforge.exe --cook level.glb [more.glb ...]--size W H, --fullscreen | Window size or fullscreen. |
--camera x y z yaw pitch | Start from a fixed viewpoint. |
--screenshot out.png --frames N | Render N frames, save a screenshot and exit. Good for thumbnails. |
--script extra.lua | Run an extra Lua file alongside the level — for automated playtests. It also gets screenshot(file) and look(yaw, pitch). |
--timeout seconds | Quit after a time limit. |
--host [port], --join address[:port] | Start a multiplayer game as the host (port 27960 unless given), or join one. Packaged games take these too. |
--vr | Play in a VR headset through OpenXR (a Quest over Link or Air Link, or SteamVR). With no headset the reason goes in the log and the game plays on the desktop. A packaged game can start in VR with "vr": true in its game.json. Every 10 seconds the log says whether frames keep up with the headset; when they don’t, the headset smooths them out and the picture smears and judders. |
--vr-scale x | Each eye drawn at x times the headset’s recommended size: 1.3 is sharper and slower. Saved, so it sticks (--vr-scale 1 goes back). Over Link, the Meta Quest Link app’s Render Resolution and bitrate limit sharpness too. |
--vr-graphics light|full | VR draws light by default, to keep up with the headset: no volumetric fog, real-time GI, contact shadows or ambient occlusion, smaller sun shadows with harder edges, and lamps that reach 26 m rather than 80 (a street of ten lamps shades about three times faster). full uses the desktop’s settings. Saved. |
--vulkan | Draw with the Vulkan 1.3 renderer instead of OpenGL: everything the OpenGL renderer draws, real-time GI and the path tracer included, and on NVIDIA RTX / GTX 16 cards variable rate shading. It needs a Vulkan 1.3 driver (any current NVIDIA, AMD or Intel one). VR still needs OpenGL: --vr is ignored with --vulkan. |
--plugin folder | Load a plugin, or a folder of them, as well as those in plugins\ beside the exe. |
--cook | Pre-compress a level’s textures (BC7). Package Game does this for you. |
Licences
The engine is free for any use, including games you sell, but its source code isn’t released, so it can’t be rebuilt or extended with new Lua functions from outside. The add-on is GPL 3.0 or later, and the samples and docs are MIT. Every packaged game carries ENGINE-LICENSE.txt and THIRD-PARTY-NOTICES.txt; keep them with the game when you share it. See Licensing on the download page.