The Blender add-on
Everything lives in the BlendForge tab of the 3D viewport sidebar (press N; the tabs run down its right edge).
Main panel
| Play / Update | Exports the scene and runs it in blendforge.exe. While the game is open the button reads Update and hot-reloads instead. The ▶ button in the viewport header does the same. The square button next to Update stops the game. |
| Live Link | While the game runs, moving, rotating, scaling or hiding objects and editing lights in Blender updates it instantly. Mesh and material edits still need Update. |
| Add Player Start | Adds the spawn arrow at the 3D cursor. The player faces along the arrow. (Any Empty can be made a Player Start with its checkbox.) |
| Add Trigger Volume | Adds an invisible 2 m wireframe box at the 3D cursor, already set to Trigger. Give it a script with on_trigger_enter. |
| Export Level | Saves the scene as a .glb the engine can load, without running it. |
| Package Game | Builds a standalone game. See Shipping your game. |
Object Components
Settings for the selected object. What you see depends on the object type.
Body — how it behaves physically
| Body | Use it for |
|---|---|
| Static (default) | Floors, walls, level geometry. Never moves. |
| Dynamic | Crates, balls, props. Falls, tumbles, can be pushed, picked up and thrown. |
| Kinematic | Things moved by animation or scripts: lifts, doors, moving platforms. Pushes dynamic bodies and carries the player. Parented to a character’s bone it’s a hitbox instead: rays (and shots) find it, but it pushes nothing. An object on a bone left at Static (a gun in the hand) gets no collider. |
| Trigger | An invisible volume that calls on_trigger_enter / on_trigger_exit in its script. Tick Visible In Game for visible pickups. |
| No Collision | Rendered only — decoration you can walk through. |
Shape — the collision shape
| Auto | Exact triangle mesh for static objects, convex hull for dynamic ones. Usually right. |
| Mesh | Exact triangles. Static and kinematic only — dynamic bodies use a convex hull. |
| Convex Hull | A tight shrink-wrap around the mesh. |
| Box / Sphere / Capsule | Simple shapes fitted to the object’s bounds. Fastest; great for crates, balls and characters. |
Other settings
| Mass (kg) | Dynamic only. Default 10. |
| Can Pick Up | Dynamic only. The player can carry and throw it (up to 150 kg). |
| 2D | Dynamic only, for 2D games. X/Z Plane keeps the body in the front view’s plane, turning only about Y (crates). X/Z, No Turning never turns it (characters). |
| Friction | 0 = ice, 0.6 default, 2 = very grippy. |
| Bounciness | 0 = dead stop, 1 = super ball. |
| Visible In Game | Untick for invisible walls and helpers. |
| Cast Shadows | Untick for small or distant objects to save time. |
| Mirror | A flat mesh that shows the scene reflected in it, as a real mirror does, including what’s behind the player. Give it a metallic, smooth material: its colour tints the reflection. The nearest mirror in view reflects the room (it’s drawn a second time, so keep to one or two); others, and every mirror on the Low graphics preset or with reflections off, reflect the sky. |
| Virtual Geometry | For dense meshes (scans, sculpts, high-poly rocks and statues): the engine splits the mesh into small clusters with levels of detail and draws, each frame, just the detail the screen can show (about a pixel per triangle), skipping clusters out of view or facing away. Millions of triangles cost about what the screen shows. Not for meshes with shape keys or armatures. |
| Always Loaded | With World Streaming: keep this object (and what’s parented under it) loaded everywhere, for things scripts need to find() wherever the player is. |
| Player Model | Your own body for the player, replacing the built-in cowboy: it follows the player (origin at the feet, facing +Y). A rigged model (bones named like Mixamo’s: LeftArm, LeftForeArm, LeftHand…) is also seen in first person, holds carried things in both hands, and plays its actions player_idle, player_walk (walking), player_run (sprinting) and player_jump (in the air) as the player moves. Give its meshes No Collision. |
| Template | Hidden and inactive in the game until a script copies it with spawn("Name"). Use it for bullets, enemies, pickups. |
| Replicate | Multiplayer: the host sends this object’s movement to every player, and copies of it spawned on the host appear for everyone. Tick it on things that move. See Multiplayer. |
Lights export as real-time lights (Sun, Point, Spot and Area). Armatures export their animations, which play automatically unless you turn off Autoplay Animations in World.
Script
Attach a Lua script to the object. Pick an existing Blender Text, or click the new-file button to create <Object>.lua from a template. Edit it in Blender’s Text Editor. Scripts are saved inside your .blend. See Lua scripting.
Below it, Logic attaches a Logic graph instead of, or as well as, a script: visual scripting in a node editor. The new-file button creates one. See Logic graphs.
Sound
| Sound | A WAV, MP3, OGG or FLAC file. It’s copied with the level when you export. |
| Volume | 1 = normal. |
| Loop | Repeat forever (hums, music, ambience). |
| Play On Start | Start when the level loads. Otherwise call self:play_sound() from a script. |
| 3D / Radius (m) | Positional sound that fades out by the radius. Turn 3D off for music and UI sounds. |
Particles
Tick the checkbox in the panel header to make the object an emitter. Particles leave along the object’s local +Z axis. Start from a preset — Fire, Smoke, Sparks or Dust — and adjust:
| Rate / Burst | Particles per second, and a one-off burst when the level starts. |
| Lifetime, Speed, Spread | How long they live, how fast they go, and the cone angle. The Random values add variation. |
| Emit Volume | Half-size of a box to spawn in (0 = from a point). |
| Gravity / Drag | 1 falls like objects; negative rises (smoke). Drag slows them. |
| Start/End Color, Start/End Size | Colour and size fade over each particle’s life. |
| Brightness | Above 1 glows through bloom. |
| Glow (Additive) | On for fire, sparks and magic; off for smoke and dust. |
| Emit On Start | Off = silent until a script sets self.emitting = true or calls self:emit(n). |
| Max Particles, Texture | A cap, and an optional PNG sprite (empty = soft dot). |
Blender’s own emitter particle systems are converted automatically too.
Particle System graphs
For richer effects, build them from modules in a node editor, like Unreal’s Niagara. In the Particles panel press New Particle System (or open a DarkRoast Particles node editor), then plug modules into the Emitter node:
| Spawn, Lifetime, Shape, Velocity | How particles start: rate and bursts, how long they live, where they appear (point, box, sphere or ring) and how fast they leave. |
| Gravity & Drag, Turbulence, Vortex, Attract, Floor Collision | What moves them: gravity and drag, swirling noise, spinning round the emitter, pulling in, bouncing and sliding on the floor. |
| Color over Life, Size over Life, Render, Flipbook, Stretch | How they look: colour and size curves, texture and glow, animated sprite sheets, streaks along their motion. |
| Sub-Emitter | Another emitter that bursts out of each particle when it dies or lands: fireworks, splashes. |
A module you leave out keeps the value in the Particles panel, so a graph can be as small as one module. Pick the graph in the panel’s System field; the same graph can drive many emitters. The particles demo in Samples & docs (samples\particles_demo.blend) has fireworks, a fountain, a portal, chimney smoke and sparks.
Sprite (2D)
Tick the checkbox in the header to draw a mesh or Empty as a flat picture. On an image plane it takes the plane’s image and size; on an Empty, pick the Image and set Pixels per Metre and Pivot.
| Columns, Rows | A sprite sheet: frames in equal cells, counted from 1 at the top left. |
| First Frame, Frames, FPS, Loop, Play On Start | The animation it plays. Scripts switch with self:play_sprite{...}. |
| Tint | Colour and opacity. |
| Sorting Layer, Order in Layer | Higher layers (then orders) are drawn over lower ones. |
| Pixel Art, Hard Edges | Sharp pixels; solid-or-invisible pixels (best for pixel art). |
| Lit, Brightness | Shaded by the scene’s lights, or its own colours (brighter than 1 glows). |
| Flip X, Flip Y | Mirror the picture. |
See 2D games for the whole workflow.
Vehicle
Tick the header checkbox on a Dynamic body to make it a car, and tick Wheel on its wheel children (axle along their X). Settings: Engine Torque, Max RPM, Steering, Four-Wheel Drive, Suspension Travel, Stiffness, Damping and Grip. Scripts drive it with self:drive(throttle, steer, brake, handbrake). The whole workflow is in Cars & racing.
AI Agent
Tick the checkbox in the header to make a mesh or Empty walk on the navigation mesh. Set its Speed, Radius and Height, then drive it from a script with self:move_to(pos) — see the guard example.
The navmesh is built automatically from Static objects when the level loads (press F3 in the game to see it). On a static object that isn’t an agent, tick Exclude From Navmesh to keep AI off it.
Character Animation
On a character’s armature (or the object holding it), tick Character Animation and pick its Idle, Walk, Run and (optional) Jump actions, plus how fast the walk and run actions move. The engine then plays them from how the character moves, whatever moves it (an AI agent, physics or a script), with the playback speed following the actual speed. Like the old Blender Game Engine’s action actuators, but automatic.
Anything else comes from its script: an action that isn’t one of those and doesn’t loop (a shot, a hit) takes over until it ends, then it goes back to walking or standing. For a death, set self.auto_animate = false and play the death action. Every copy plays its own actions, including copies loaded with spawn_model.
World
| Use World HDRI / Sky Strength | If the Blender World uses an Environment Texture, it becomes the sky and the image-based lighting. |
| Sky Zenith, Sky Horizon, Ground | Sky colours used when there’s no HDRI. |
| Ambient, Exposure | Overall fill light and brightness. |
| Bloom | Glow around bright things. |
| Fog Density | 0 = none; try 0.01–0.03 for thick fog. |
| Player | First Person: the built-in walking player, with View (start in first or third person) and Player Can Switch (the C key toggles; in third person the camera follows over the shoulder and pulls in when a wall is behind). The player has a body either way: the built-in animated cowboy, or your Player Model; in first person you see your arms, legs and boots. None (Scripts): no built-in player; your scripts move your own character and the camera (2D and top-down games), starting from the scene camera’s view. |
| Orthographic camera | If the scene camera is Orthographic, the game uses it: a flat 2D view of the same height at any distance. |
| Gravity (m/s²) | 9.81 = Earth. Try 1.6 for the Moon. |
| Autoplay Animations | Loop every animation when the level starts. Turn off to start them from scripts with play_animation(). |
| Level Script | A script for the whole level, not tied to an object. Good for scores, timers, spawning and win conditions. |
| Level Logic | A Logic graph for the whole level. |
| World Streaming | For big levels, like Unreal’s World Partition: the export splits the level into a grid of cells (Cell Size, 64 m by default), each written as its own small file next to the level, and the game loads the cells within Load Distance of the player on background threads, unloading them behind. The player start, suns, cameras, Templates, Replicate objects, vehicles, AI agents, anything bigger than a cell, and objects marked Always Loaded stay in the level itself. See the open world demo in Samples & docs. |
| Plugins | The plugins this game uses: tick them; it applies to every level in the .blend. |
Game
| Game Title | Names the packaged folder and exe, and the save-game folder. |
| Fullscreen | Packaged game starts fullscreen. |
| Package Game | See Shipping your game. |
What exports from Blender
- Materials: Principled BSDF with image textures (base colour, metallic/roughness, normal, occlusion, emission) and alpha (blend or clip).
- Glass: set the Principled BSDF’s Transmission Weight (1 for clear glass) and IOR (1.5 for glass). What’s behind it shows through, bent by refraction and tinted by the base colour; Roughness frosts it. Glass casts no shadow.
- Lights: Sun, Point, Spot and Area, in Blender units.
- Cameras: the scene camera, when it’s Orthographic or the Player is None.
- Colour management: View Transform Standard shows colours as authored (for 2D art); Filmic and AgX use the filmic curve.
- Modifiers are applied on export — keep them live while you work.
- Parenting is kept: children move with their parents.
- Animation: keyframed objects, armatures with weights, shape keys and shape-key animation. Animated colliders become moving platforms.
- Instancing: linked duplicates (Alt+D), collection instances and geometry-nodes scatters render efficiently as GPU instances.
- Custom properties on an object are readable in its script as
self.props.