# Build a PETAFAB level in Blender

Copy this starter folder for each new map. Keep [level.blend](level.blend) and [level.json](level.json) together. The example has been tested with Blender 5.1.0. The example includes a gate wall with a doorway, a ramp, a beacon and two point lights. You can edit these in **Object Mode**.

## Cut a window in the gate wall

1. In the Outliner, expand **Brushes** and select `020 cut Doorway`. Its wireframe shows the volume that cuts through `010 add Gate wall`.
2. With the pointer in the 3D Viewport, press **Shift+D**, then **X**, type **4** and press **Enter**. This places a copy four metres to the side, still inside the wall.
3. Press **S**, **Z**, type **0.5** and press **Enter** to halve its height. The cutter now sits above the floor, leaving a sill. Keep it deep enough to pass through both faces of the wall.
4. Press **F2**, name the copy `100 cut Window` and press **Enter**. The number puts the cut after the wall. Cutters need no material.
5. Follow [Export and play](#export-and-play) to see the opening in PETAFAB. Blender shows the cutter as a wireframe while you work.

For a recess, move the cutter partway into the wall. For a round cut, use a sphere or upright cylinder in **Brushes** and give it a name such as `110 cut Socket`. You can set **Object Properties → Viewport Display → Display As** to **Wire** to see through a new cutter. The word `cut` in its object name determines the operation.

## Add and arrange solids

Select a solid in **Brushes** and press **Shift+D** to duplicate it. Use **G** to move, **R** to rotate and **S** to scale. You can also add a primitive from **Add → Mesh**. Name the object `number add description`, for example `030 add Lintel stripe`. Operations run in numeric order. Ties use the full object name in alphabetical order. A later addition can fill an earlier cut.

Assign one material to each addition in **Material Properties**. Its Blender name must match a material ID in `level.json`. The starter includes `concrete`, `steel`, `teal`, `hazard` and `lamp_amber`.

Keep the original **mesh data name** when you rename the object in the Outliner. The exporter recognizes Cube, Sphere, Icosphere, Cylinder and Cone meshes. Rotate boxes around Blender Z for yaw and local X for pitch. Scale spheres uniformly. Keep cylinders and cones upright with equal X and Y scale. The two end radii of a cone set its taper. Use unmodified primitives. The first object in **Brushes**, `000 add Concrete floor`, creates the floor. Remove it for a sky map and build your own platforms. **Guides** shows the player start.

## Place point lights

Duplicate a light in **Point Lights**, or add **Light → Point** to that collection. Move it with **G**. In Light Data Properties, set its color, power and exposure. Enable **Custom Distance** to set its influence radius in metres. The default game radius is 8 m. The exporter converts power to RGB intensity using linear color × power × 2<sup>exposure</sup> / (4π), with the temperature tint when enabled.

## Export and play

1. Save the scene in **Object Mode**. Open the **Scripting** workspace. In the Text Editor, select **Export Level.py** and click **Run Script** (the triangle), or hover over the text and press **Alt+P**. The script is embedded in `level.blend` and runs without installing an add-on.
2. Look for the exported brush and point-light counts. If export fails, fix the reported problem and run it again. The previous `level.json` stays usable.
3. In PETAFAB on Steam, open **Workshop → My Levels → Play Folder** and select the extracted folder. Walk up to the gate to check your window. After each Blender export, press **F5** in game to reload the folder and restart the map (on Mac keyboards, **Fn + F5** if needed). Ordinary restart uses the already-loaded map. If reloading fails, the current map keeps running; fix the error and try again.
4. Press **F8** in game to tune the graphics and sun. Choose **Save JSON** and wait for **SAVED LOCALLY** to keep those settings between exports. After an external edit or export, press **F5** before saving from F8. Reloading discards unsaved tuning changes.
5. To publish, add your own map thumbnail: a JPEG under 1 MiB named `preview.jpg` beside `level.json`. A thumbnail is not included in this starter. Open **Workshop → My Levels → New Level**. The folder you just played is already selected. The game packages your saved map and thumbnail for Steam.

On every export, the script reads the current `level.json` beside the scene. It writes **Brushes** as ordered `brushes` and **Point Lights** as `lights`. It converts Blender world positions from Z up and +Y forward to game metres with Y up and +Z forward. Your F8 settings, material declarations, player spawn, pickups, fluids and encounters carry over.

Set `announcement` in the JSON for any wave or boss. For example, `"announcement": "swarm"` plays the huge-swarm warning and `"announcement": "none"` makes the arrival silent. The Blender exporter preserves these choices. [Full level reference](https://sebastianaaltonen.com/assets/modding/petafab-level-format.md) (also included as `source/petafab-level-format.md` in the ZIP).

The ZIP also includes the exporter at `source/export_blender_level.py`. For batch export, run this from the extracted folder with Blender on your PATH:

```sh
blender --background level.blend --python-exit-code 1 --python source/export_blender_level.py
```

The exporter replaces the complete `brushes` and `lights` arrays. Manual changes inside those arrays, including `disableWhenAwayFromTerrain` on a light, must be reapplied after exporting. Other JSON fields are preserved. The player-start guide is a visual reference; edit `player.position` in JSON to move the actual spawn.

This workflow exports primitive terrain and point lights. Arbitrary meshes, modifiers and torus brushes are not supported by this exporter. Add fluids, gates, enemies and pickups in JSON using the included `level.schema.json` and [full reference](https://sebastianaaltonen.com/assets/modding/petafab-level-format.md). The starter has no enemy waves and is ready for local exploration.

For enemy waves, use `constructor` for yellow Yard bots or `constructor2` for blue Factory bots. Separate groups can spawn both variants in the same wave. The full reference explains their material reservations and `botMaterials.constructor2` overrides.

In PETAFAB, **Workshop → My Levels → New Level → Modding Guide** opens the online instructions in the Steam overlay, or your default browser when the overlay is unavailable.

[Online Blender guide](https://sebastianaaltonen.com/petafab/modding/#blender)

