Maps & Steam Workshop
Build your own battlefield.
Shape destructible terrain, fill it with fluid, and send in the bots. A PETAFAB map starts with a plain text JSON file. Edit it, play it, and share it through the in-game Workshop.
Spillway ZIP · 1.2 MB · Complete map JSON, editor schema, thumbnail and original capture
The Markdown reference includes instructions, all material names, the full JSON Schema and Spillway example in one file. It’s also included in both ZIPs under source/.
You’ll need PETAFAB on Steam for Windows or macOS and a text editor. Spillway uses built-in game assets, so there’s nothing to compile.
From a few brushes to a whole world
Two maps. One format.
Spillway
A small arena built from ten brushes, four built-in materials, a fluid tank and two enemy gates. The complete map is shown below and included in the source download.
Tumblebrook
The Claybook-inspired example takes the same format further: layered clay terrain, custom materials, a pressurized cistern, flowing water, lit caves and a final laser boss.
01 / Edit & play
Your first map
- Extract the example. Download Spillway into a new folder, such as
MySpillway. Open that folder:level.jsonandpreview.jpgshould be directly inside it. - Play it once. In PETAFAB, open Workshop → My Levels → Play Folder and select that folder. You can also open the download directly with Play Local ZIP.
- Make a small edit. Open
level.jsonin a text editor. Try one of the changes below, save the file, then press F5 while playing. F5 rereads the current folder or ZIP, including textures and sky assets, and restarts the map with your changes. On a Mac keyboard, you may need Fn + F5. - Tune the look. While playing your local map, press F8 to adjust lighting, fog, bloom and sun settings. Choose Save JSON and look for SAVED LOCALLY. After external edits, press F5 before saving from F8. Reloading discards any tuning changes you have not saved.
You can return to these instructions from Workshop → My Levels → New Level → Modding Guide. The button opens the Steam overlay, or your default browser when the overlay is unavailable.
If a reload fails, the current map keeps running and the error appears on screen. Fix the file, save, and press F5 again. F5 works with maps opened through Play Folder or Play Local ZIP; it does not upload changes to Steam Workshop. Ordinary restart uses the already-loaded map.
Try these changes
- More bots: change both
countvalues in the first wave from3to5. Each gate will send five constructors. - Blue Factory bots: change one group’s
enemyfromconstructortoconstructor2to mix the yellow and blue variants in the same wave. - Harmless fluid: set
fluidDamagePerSecondto0. The liquid still flows and pushes actors. - A different wall: change the wall’s
builtinfromsteeltofactory:steel. - Explore in peace: set
wavesto[]. With no waves or boss, the map becomes a free-exploration space.
The included JSON Schema provides field hints and validation in compatible editors. Keep it next to level.json. Use valid JSON: double-quoted names, commas between entries, and no comments or trailing commas. Local testing earns no Workshop trophies or campaign progress.
Build in Blender
Edit shapes. Export. Play.
Prefer arranging shapes in a 3D viewport? The Blender starter contains a concrete floor, a gate wall with a doorway, a ramp, a beacon and two point lights. Its ten terrain brushes export to the same JSON format used by the game.
ZIP · 154 KB · Editable .blend, level.json, embedded and standalone exporter, schema and full reference · Tested with Blender 5.1.0
- Extract and open. Keep
level.blendandlevel.jsontogether in the extracted folder. Open the scene in Blender and work in Object Mode. - Edit the terrain. In the Brushes collection, duplicate a solid with Shift+D, then move, rotate or scale it. Names such as
010 add Gate walland020 cut Doorwayset the operation and numeric order. A cut removes terrain created by earlier brushes. Assign each solid one material whose name matches an ID inlevel.json. - Export. Save the scene, open the Scripting workspace and select Export Level.py in the Text Editor. Click Run Script (the triangle), or hover over the text and press Alt+P. The embedded exporter updates the adjacent JSON; no add-on installation is needed.
- Play and iterate. In PETAFAB, choose Workshop → My Levels → Play Folder and select the extracted folder. After each export, press F5 in game to reload it. On Mac keyboards, use Fn + F5 if needed.
The exporter supports unmodified cubes, spheres, upright cylinders and cones, plus point lights. Keep the original mesh data names when renaming objects. Arbitrary meshes, modifiers and torus brushes are not supported by this exporter. The included Blender README explains the shape constraints, lights and a step-by-step window-cutting exercise.
Each export replaces brushes and lights. Other JSON fields—including materials, player and bot stats, drop limits, waves, triggers and saved F8 lighting settings—carry over. Add fluids, gates, enemies and trigger areas/actions in JSON. The player-start guide is only a visual reference; move the actual spawn through player.position.
The starter has no enemy waves and is ready for local exploration. Before publishing, add your own preview.jpg thumbnail under 1 MiB beside level.json.
02 / Build the arena
How a level works
Maps use version: 2. The required fields are version, materials, player, brushes, fluids, gates and waves. Empty arrays are valid. Field names are case-sensitive; unknown and duplicate fields are rejected.
Position, scale and direction
Positions are [x, y, z] in metres, with Y pointing up. Terrain covers X/Z from −32 to +32 and Y from 0 to 32. Custom maps start empty; every floor and platform is an explicit brush. Spillway’s first brush creates a destructible concrete floor whose top is at Y = 4. For a sky map, omit that floor and add your own platforms. The player position is the lower capsule center, so a Y coordinate of 4.55 places the player on that slab. Leave headroom and put an ammo pickup nearby: the player starts unarmed.
Yaw is in degrees: 0 faces +Z and 90 faces +X. Simulation timing uses 120 ticks per second: 60 ticks is half a second.
Add shapes, then cut into them
The brushes array runs in order. An add brush creates solid terrain with a declared material; a subtract brush cuts terrain that already exists. After its floor, Spillway adds a wall, then cuts its doorway. It makes the tank in the same way: add a cylinder, then subtract a smaller cylinder to hollow it out.
| Shape | Dimensions |
|---|---|
box | center and full size: [width, height, depth]. Optional yaw, pitch and corner rounding. |
sphere | center and radius. |
cylinder | center, radius and full height. Use topRadius to taper it; zero makes a cone. |
torus | center, centerline radius and tubeRadius. Optional pitch and yaw. |
Materials, fluid and light
Each material has a map-local id, which brushes reference. Its builtin value selects one of the names in the complete reference below. Unprefixed names use the Yard palette: steel means yard:steel. Use factory:steel or rooftop:steel to select that campaign palette. The same name can have a different finish in each palette.
For example, {"id":"wall","builtin":"factory:steel"} defines a material named wall; an additive brush then uses "material":"wall". Names are case-sensitive. The game has 32 physical material slots shared by terrain, foam and bot remains; Spillway uses 11.
Complete built-in material reference — all 32 names
Every name below accepts all three prefixes. The columns describe the surface selected by each palette. These are material choices, not enemy-model selectors.
| Name | Yard (default) | Factory | Rooftop |
|---|---|---|---|
concrete | Cast structural concrete | Cast structural concrete | Cast structural concrete |
steel | Brushed structural steel | Perforated metal grille | Brushed structural steel |
teal | Teal machinery panels with inset status lights | Teal machinery panels with inset status lights | Teal machinery panels with inset status lights |
hazard | Safety stripe paint | Safety stripe paint | Safety stripe paint |
corpse | Ceramic-coated robot armor | Ceramic-coated robot armor | Ceramic-coated robot armor |
pavement | Aggregate industrial pavement | Molded insect-robot shell | Extruded cable insulation |
ivory | Painted enamel cladding | Varnished oak wood | Painted enamel cladding |
trim | Worn structural metal trim | Worn structural metal trim | Worn structural metal trim |
robot_joint | Robot joint metal | Robot joint metal | Robot joint metal |
robot_boss | Ceramic-coated robot armor | Ceramic-coated robot armor | Ceramic-coated robot armor |
robot_visor | Robot visor glass | Robot visor glass | Robot visor glass |
robot_panel | Robot inset polymer panels | Painted enamel cladding | Robot inset polymer panels |
robot_boss_panel | Robot inset polymer panels | Robot inset polymer panels | Robot inset polymer panels |
foam | Cured expanding construction foam | Cured expanding construction foam | Cured expanding construction foam |
foam_turquoise | Cured expanding construction foam | Cured expanding construction foam | Cured expanding construction foam |
foam_pink | Cured expanding construction foam | Cured expanding construction foam | Cured expanding construction foam |
safety | Painted enamel cladding | Linear lighting diffuser | Painted enamel cladding |
lamp_amber | Molded translucent lamp lens | Molded translucent lamp lens | Molded translucent lamp lens |
lamp_red | Molded translucent lamp lens | Molded translucent lamp lens | Molded translucent lamp lens |
rubber | Continuous molded rubber skin | Continuous molded rubber skin | Continuous molded rubber skin |
graybox | Perforated metal grille | Fine mineral floor coating | Graphite-coated rooftop casing |
bee_yellow | Molded insect-robot shell | Bare copper fittings | Molded insect-robot shell |
bee_black | Molded insect-robot shell | Molded insect-robot shell | Molded insect-robot shell |
bee_wing | Thin insect-robot wing metal | Dense small-leaf foliage | Thin insect-robot wing metal |
porcelain | Architectural stone flooring | Architectural stone flooring | Architectural stone flooring |
aluminium | Brushed aluminum fittings | Brushed aluminum fittings | Brushed aluminum fittings |
upholstery | Extruded cable insulation | Woven upholstery linen | Extruded cable insulation |
foliage | Dense small-leaf foliage | Dense small-leaf foliage | Extruded cable insulation |
bark | Extruded cable insulation | Tree bark | Anti-slip rooftop decking |
display | Industrial display face | Industrial display face | Riveted rooftop duct alloy |
lounge_fabric | Extruded cable insulation | Woven upholstery linen | Teal machinery panels with inset status lights |
robot_rocketeer | Ceramic-coated robot armor | Ceramic-coated robot armor | Ceramic-coated robot armor |
Fluid volumes seed the liquid; brushes form the vessel that contains it. A fluid cylinder uses bottom, radius and height. A pipe uses start, end and radius. Keep the whole fluid volume inside the terrain bounds. Breach the tank and the liquid spills.
sun sets directional lighting, lights adds point lights, and render controls the image’s appearance. You can adjust these in the file or use F8 while playing your own map.
Gates and enemy waves
A gate is a spawn volume, separate from its visible terrain frame. Give it a unique id, a floor position at the bottom center of its rear face, full size, and a yaw pointing into the arena. Build a clear floor and exit; keep the entire volume inside X/Z ±31.75 and Y 0…32. Maps support up to 64 gates, 32 main waves and 32 extra waves activated by triggers.
Each wave contains one to four groups. A group names its enemy, count (1–1,000), and either intervalTicks or intervalSeconds. Enemy types are constructor, constructor2, runner, rocketeer and shock_trooper. Custom-map waves can mix enemy types: each group selects its own type and spawns independently.
Select entrances on the wave with "gates": ["west", "east"]. Each group spreads its total count across those gates, taking turns and skipping blocked entrances. More gates do not multiply the count. A group can override this with "gate": "west"; without a wave selection, every group needs its own gate.
{"gates": ["west", "east"], "groups": [
{"enemy": "runner", "count": 20, "intervalSeconds": 0.5}
]}
This sends 20 runners total through two gates. For generated maps, gateMask accepts a hexadecimal string instead: "0x8000000000000001" selects the first and 64th entries in the map’s gate list. Use either gates or gateMask, never both, and keep masks as strings.
All waves share room for 2,011 live bots and active ragdolls combined. When it fills, spawning waits and resumes as space becomes available; remaining bots are not discarded. A map can contain more enemies in total, such as ten waves of 1,000. Crowded gates and a nearby player can also delay spawning.
Yellow and blue constructors
Use constructor for the yellow Yard bot or constructor2 for the blue Level 2 Factory bot. Both have the same health, movement, self-destruct behavior and wave announcements. This wave sends three of each through gates named west and east:
{"groups": [
{"gate": "west", "enemy": "constructor", "count": 3, "intervalSeconds": 0.5},
{"gate": "east", "enemy": "constructor2", "count": 3, "intervalSeconds": 0.5}
]}
The blue bot uses Factory corpse and robot_panel finishes. Its paint can consume two additional physical material slots when both variants appear. To share materials, use botMaterials.constructor2 with the original slot names corpse, robot_panel, robot_joint or robot_visor, mapped to your declared material IDs. The downloadable technical spec lists the full material budgets and remapping rules.
A new wave waits for earlier groups to finish spawning and for the cumulative afterDefeats threshold. Add "afterTrigger": "open_gate" to also wait for a named trigger to fire. If afterDefeats is omitted, that threshold is all enemies in earlier waves. afterSeconds adds a minimum time since the previous wave’s last spawn; delayTicks adds a further delay once the conditions are met.
In Spillway, each gate sends three constructors at half-second intervals. Once all six have arrived and four have been defeated, a 180-tick delay passes, then two runners enter from the west. Clear all eight enemies to win.
For a final encounter, add a top-level boss with a type of barrage, saw or laser and a body-center position. Defeating the boss wins the map. Set announcement: "none" on an individual wave or boss to silence its arrival banner, alarm and voice; boss music still plays.
Tune the fight
Health, speed & loot
These gameplay settings and the trigger system below require PETAFAB build 984 or newer. Add them to your map’s root JSON object.
Player and bot stats
Add healthMultiplier and speedMultiplier to the existing player object, or to a top-level bots object. This example doubles player health, increases walking speed by 25%, and makes every bot faster but easier to kill. Keep your map’s own spawn position.
"player": {"position": [0, 4.55, -16], "healthMultiplier": 2, "speedMultiplier": 1.25},
"bots": {"healthMultiplier": 0.5, "speedMultiplier": 1.5}
Both default to 1. Health accepts 0.01–100 and scales normal health after hero and difficulty modifiers; healing and health bars follow the new maximum. Bot settings include bosses and extra waves. Speed accepts 0–4 and changes player walking or bot pursuit, including flight and jet ascent. It does not change jump height, gravity, knockback, player jetpack boosts, attack timing or projectile speed.
Control random drops
dropLimits sets how many uncollected random drops of each kind may exist. Values are 0–16; omitted kinds keep normal hero-specific behavior. These settings apply to every hero. Zero disables random drops of that kind while allowing you to place it manually or spawn it from a trigger.
"dropLimits": {"mine": 0, "bfg": 0, "lure": 1}
Available kinds are ammo, health, energy, mine, grenade, foam, lure, bfg (Fusion), black_hole and micro_missiles. The limits also affect relative random-drop selection weights; they do not limit carried ammunition or the total drops over a whole run.
Every kind has a hard limit of 16 active pickups across all sources, for 160 total. Authored layouts over that limit are rejected. A trigger skips a pickup spawn at the hard limit and continues its remaining actions; it does not save that pickup for later. Another activation can spawn it after a pickup is collected.
Script encounters
Traps, ambushes & changing terrain
Triggers connect actions to a player or enemy entering an area. Open a wall, create a platform, set off an explosion, release a wave, fire a projectile or drop a weapon. A map supports 1,024 triggers, each with up to four ordered actions. Terrain actions share a budget of 512 brushes across the map.
Download the complete trigger example. Save it as level.json in a new folder and open it with Play Folder. Walk forward toward the wall to open a passage, add a platform, create an explosion and drop a Fusion. The same event arms a delayed runner ambush. The sphere near the platform is a repeatable rocket trap. This local example uses built-in assets; add your own preview.jpg before publishing.
Define the area and activation
Each trigger needs a unique id (1–32 letters, digits, underscores or hyphens) and a nonempty actions array. A box uses center and full size; a sphere uses center and radius. Boxes are aligned to the world axes. The following root-level field spawns a Fusion half a second after the player enters the box:
"triggers": [{
"id": "supply_zone",
"area": {"shape": "box", "center": [0, 6, -6], "size": [8, 4, 4]},
"actors": "player",
"delaySeconds": 0.5,
"actions": [{"type": "pickup", "kind": "bfg", "position": [0, 6, -2]}]
}]
actors is player (the default), enemy or both; “both” means either can activate it. Only living actors count. An actor already inside at round start also activates the area. Triggers fire once by default. Set "repeat": true to fire again after the area becomes empty and an actor re-enters.
Use delaySeconds (0–600) for an activation delay. Leaving the area does not cancel it. A trigger handles one activation at a time and ignores extra requests while waiting or executing. All trigger state resets when the map restarts.
Choose the actions
| Action type | What to configure |
|---|---|
brushes | A brushes list using the same add/subtract shapes and materials as the initial terrain. Brush order matters; changes affect both visible terrain and collision. |
explosion | position, plus optional radius, damage and push (defaults: 3 m, 100 damage, 30 push). Set damage or push to zero independently. The explosion cuts terrain within half its radius. |
wave | The wave ID from extraWaves. Optional gates or gateMask selects entrances for all groups in this activation. |
pickup | A kind from the loot list and a position. Spawns one collectible, including any special weapon, regardless of random-drop limits or hero. The hard 16-per-kind limit still applies. |
projectile | projectile: rocket, grenade or lure, with position and velocity in metres per second. Grenades accept a configurable fuseSeconds. |
enableTrigger | A trigger ID to enable an initially disabled area or relay. |
trigger | A trigger ID to activate, with an optional delaySeconds added to that trigger’s own delay. |
Actions run in array order. If the projectile pool is full, its action and later actions wait for space without repeating earlier actions. A pickup at its cap is skipped instead. The complete reference lists every range and the optional tick-based timing fields.
Grenade traps
{"type": "projectile", "projectile": "grenade",
"position": [0, 8, 0], "velocity": [0, 5, 10], "fuseSeconds": 2}
The fuse starts when the grenade spawns. It defaults to 0.5 seconds and accepts 0–600; zero detonates on the first simulation step. Terrain bounces do not reset the fuse, and hitting an actor can detonate it early. Its 15 child grenades retain their normal short fuses. Trigger-fired rockets and grenades are environmental hazards.
Extra waves and main-wave conditions
Define an extraWaves array using normal wave groups, with a unique id for each wave. This example requires existing gates named west and east:
"extraWaves": [{
"id": "ambush", "gates": ["west", "east"],
"groups": [{"enemy": "runner", "count": 8, "intervalSeconds": 0.5}]
}]
Start it with {"type":"wave","wave":"ambush"}. To use only one entrance for that activation, add "gates":["west"]. Requests while the same extra wave is still spawning are ignored; after all its bots have spawned, it can start again even if survivors remain.
Only main waves and the configured boss determine victory. Extra-wave enemies do not count toward main-wave defeat thresholds and do not need to be cleared to win. For a required encounter, put the wave in waves and add "afterTrigger":"supply_zone"; it waits for that trigger as well as its normal progression conditions.
Enable and chain triggers
Set "enabled": false on a trigger to keep it inactive until an enableTrigger action arms it. Direct activation is also ignored while disabled. If an actor is already inside its area when enabled, it activates on the next simulation step. Enabling a used one-shot trigger again does not reset it.
Omit area to make a relay activated only by another trigger. Use {"type":"trigger","trigger":"next_event","delaySeconds":2} to chain an event after a delay. The target must be enabled. Chained activations always wait at least one simulation step, so loops cannot execute indefinitely in one frame. Names may refer to triggers declared later in the file.
03 / The complete example
Spillway, in one file.
This is the complete, editable level.json from the ZIP. Geometry is defined by the brushes; materials, sky and bots are supplied by PETAFAB. No separate models or textures are needed for this example.
{
"$schema": "./level.schema.json",
"version": 2,
"fluidDamagePerSecond": 40,
"materials": [
{"id": "wall", "builtin": "steel"},
{"id": "tank", "builtin": "teal"},
{"id": "gate", "builtin": "hazard"},
{"id": "plinth", "builtin": "concrete"}
],
"botMaterials": {"constructor": {"robot_joint": "wall"}, "runner": {"robot_joint": "wall"}},
"player": {"position": [0, 4.55, -11], "yaw": 0},
"sun": {"direction": [0.4, 0.72, 0.6], "radiance": [5.5, 4.7, 3.9], "ambient": 2},
"render": {"exposure": 1.15, "contrast": 0.05, "saturation": 0.12, "bloom_strength": 0.65, "fog_density": 0.003},
"lights": [
{"position": [-11, 6.5, 0], "radius": 8, "radiance": [20, 4, 0.5]},
{"position": [11, 6.5, 9], "radius": 8, "radiance": [1, 6, 20]},
{"position": [8, 7.4, 0], "radius": 5, "radiance": [0.6, 9, 6]}
],
"pickups": [
{"kind": "ammo", "position": [0, 4.55, -10]},
{"kind": "grenade", "position": [2, 4.55, -8]}
],
"brushes": [
{"op": "add", "shape": "box", "center": [0, 0, 0], "size": [64, 8, 64], "material": "plinth"},
{"op": "add", "shape": "box", "center": [0, 6, 3], "size": [13, 4, 1.5], "material": "wall"},
{"op": "subtract", "shape": "box", "center": [0, 5.5, 3], "size": [3, 3.5, 3]},
{"op": "add", "shape": "cylinder", "center": [8, 5.5, 0], "radius": 2.8, "height": 3, "material": "tank"},
{"op": "subtract", "shape": "cylinder", "center": [8, 6.1, 0], "radius": 2.3, "height": 3.2},
{"op": "add", "shape": "box", "center": [-12, 6.5, 0], "size": [1, 5, 8], "material": "gate"},
{"op": "subtract", "shape": "box", "center": [-12, 5.8, 0], "size": [2, 4, 5]},
{"op": "add", "shape": "box", "center": [12, 6.5, 9], "size": [1, 5, 8], "material": "gate"},
{"op": "subtract", "shape": "box", "center": [12, 5.8, 9], "size": [2, 4, 5]},
{"op": "add", "shape": "box", "center": [-5, 4.8, -4], "size": [3, 1.6, 1.4], "yaw": 25, "material": "plinth"}
],
"fluids": [
{"shape": "cylinder", "bottom": [8, 4.6, 0], "radius": 2, "height": 2}
],
"gates": [
{"id": "west", "floor": [-12, 4, 0], "size": [4, 4, 4], "yaw": 90},
{"id": "east", "floor": [12, 4, 9], "size": [4, 4, 4], "yaw": -90}
],
"waves": [
{"delayTicks": 120, "groups": [
{"gate": "west", "enemy": "constructor", "count": 3, "intervalTicks": 60},
{"gate": "east", "enemy": "constructor", "count": 3, "intervalTicks": 60}
]},
{"afterDefeats": 4, "delayTicks": 180, "groups": [
{"gate": "west", "enemy": "runner", "count": 2, "intervalTicks": 90}
]}
]
}
04 / Go further
Custom materials & skies
Once your layout plays well, materials can reference your own cooked DDS textures instead of built-in names. Keep those files inside the map folder and use relative paths with forward slashes, such as textures/stone_color.dds.
- Surface textures: pair a 1024 × 1024 BC7 sRGB color DDS with a BC5 linear tangent-space normal DDS using the DirectX (Y−) convention. Both need 11 mip levels and tile once per metre. Material declarations use
colorandnormalpaths. Color RGB stores the surface color; its linear alpha channel packs ambient occlusion (AO) and an emission mask. The converter below produces these files from source images. - Fluid: a top-level
fluidMaterialcan supply its own color/normal pair and surface settings.fluidDamagePerSecondcontrols damage independently. - Sky:
skyboxtakes three unsigned BC6H cubemaps:sky(1024² per face, 11 mips),diffuse(16², one mip), andspecular(256², seven mips).
Which surface properties vary per pixel?
| Property | How to author it |
|---|---|
| Roughness | One number per material: roughness, from 0 to 1, default 0.8. No roughness texture. |
| Metallic | One number per material: metallic, from 0 to 1, default 0. No metallic texture. |
| Ambient occlusion | Color alpha, range [0, 0.5]: 0 = fully occluded; 0.5 or above = not occluded. |
| Emissive mask | Color alpha, range [0.5, 1]: 0.5 or below = no emission; 1 = full emission. |
The alpha channel contains ambient occlusion in its lower half and the emissive mask in its upper half. The mask multiplies the HDR emissive color: surface RGB × the material’s emission strength (0–64, default 0).
Color alpha packing for custom DDS files
Use these linear 8-bit alpha values before BC7 compression:
- 0–127: AO equals alpha / 127, from fully occluded to unoccluded; emission is zero.
- 127 or 128: neutral surface: unoccluded and non-emitting.
- 129–255: emission mask equals (alpha − 128) / 127; texture AO is 1. Alpha 255 gives the full material emission strength.
Alpha is surface data, not transparency. For an ordinary non-emitting surface without baked AO, use 127 or 128. The converter accepts separate grayscale AO and emissive masks, or can derive AO from a height map and relief setting. Without AO or height, it bakes unoccluded AO. It packs this channel and builds the mip chain automatically.
Put editable images and author notes under source/; keep all runtime DDS files outside that folder. Tumblebrook uses custom clay and water materials, layered brush geometry and room lighting to build its waterworks. The schema reference documents the available fields and ranges.
Lights and destructible walls
Each entry in lights defines an unshadowed point light with a position, radius and HDR RGB radiance. Lights stay on by default. Set disableWhenAwayFromTerrain to true to turn a light off when terrain is more than 0.5 metres from its position. This also applies when the map first loads; once off, it stays off until the map restarts.
{
"position": [0, 4.3, 0],
"radius": 8,
"radiance": [20, 4, 1],
"disableWhenAwayFromTerrain": true
}
This light sits 0.3 metres above Spillway’s floor. Walls, floors and ceilings can provide support; actors and fluid cannot. The check uses collision terrain, so leave some margin inside the 0.5-metre limit. Omit the setting or use false for a light that stays on after nearby terrain is destroyed.
05 / Prepare your assets
Texture & skybox converter
Turn PNG material sources and EXR/HDR panoramas into game-ready DDS files. The converter creates mipmaps, packs ambient occlusion and emission, and bakes diffuse lighting and reflections for your skybox.
Windows · x64 CPU with AVX2/FMA · 396 KiB
Mac · Apple silicon · macOS 26+ · 236 KiB · Signed and notarized
Each download includes petafab-cook, the guide and license notices. Extract the ZIP and open a terminal in the extracted folder. On Mac, use Finder/Archive Utility to extract it.
Mac Terminal:
./bin/petafab-cook --help
Windows PowerShell:
.\bin\petafab-cook.exe --help
The examples below use the Mac command. On Windows, replace ./bin/petafab-cook with .\bin\petafab-cook.exe; the arguments are the same.
Source images and normal convention
| Input | Source format |
|---|---|
| Albedo | 1024 × 1024 tileable PNG, 8-bit or 16-bit RGB in sRGB. Alpha is ignored; supply masks separately. |
| Normal | 1024 × 1024 tileable PNG, 8-bit or 16-bit RGB, linear tangent-space DirectX (Y−) with positive Z. |
| AO / emission | Separate 1024 × 1024 tileable PNGs, 8-bit or 16-bit linear grayscale. AO: black = occluded, white = unoccluded. Emission: black = none, white = full. |
| Height | Optional 1024 × 1024 tileable PNG, 8-bit or 16-bit linear grayscale. White is higher than black. |
| Sky | EXR or Radiance HDR, native 2:1 equirectangular panorama, from 4096 × 2048 up to 32768 × 16384. Scene-linear RGB with linear sRGB primaries, without tone mapping. EXR supports scanline or tiled RGB images. |
For OpenGL (Y+) normals, invert only green: G = 255 − G for an 8-bit PNG, or G = 65535 − G for 16-bit. Do not flip the image vertically. The converter preserves imported green-channel direction; normals generated from height already use DirectX. Export normal maps, masks and height as data, without an sRGB transfer function.
Cook albedo, AO and emission
./bin/petafab-cook material --name panel --albedo panel.png --normal panel_normal.png --ao panel_ao.png --emission panel_emissive.png --out MyLevel/textures
This writes panel_color.dds (BC7 sRGB) and panel_normal.dds (BC5 linear), with all 11 mips. Color is filtered in linear light, normals are renormalized, and AO and emission are filtered separately before packing each mip into color alpha. Inputs must already be 1024 × 1024.
Albedo is required. The other inputs are optional: omitting normal and height gives flat normals; omitting AO and height gives an unoccluded surface; omitting the emissive mask gives no emission. Add a material entry to level.json and use its ID on your brushes:
{
"id": "panel",
"color": "textures/panel_color.dds",
"normal": "textures/panel_normal.dds",
"roughness": 0.45,
"metallic": 0.8,
"emission": 4
}
Set a positive emission strength for the mask to glow. The mask multiplies the HDR emissive color: surface RGB × this strength.
Or derive normals and AO from height
./bin/petafab-cook material --name stone --albedo stone.png --height stone_height.png --relief 0.008 --out MyLevel/textures
A height map describes surface displacement for shading. --relief 0.008 means 8 mm from black to white; it does not change brush geometry. Choose height or a normal map, not both. An explicit --ao image overrides height-derived AO. You can add an emissive mask to either workflow.
Bake an HDR skybox
./bin/petafab-cook sky --name dusk --panorama dusk.exr --out MyLevel/sky
The converter bakes lighting on the CPU. It creates three BC6H cubemaps: a 1024² sky with 11 mips, 16² diffuse convolution, and 256² GGX reflections with seven roughness mips down to 4². Radiance must be finite and nonnegative, up to 64512. Add all three paths as a top-level field in level.json:
"skybox": {
"sky": "sky/dusk_sky.dds",
"diffuse": "sky/dusk_diffuse.dds",
"specular": "sky/dusk_specular.dds"
}
Recipes and rapid iteration
Save this as MyLevel/source/cook.json, with source images beside it. Image paths are relative to the recipe; outputs go under the level folder. Omit sky for material-only jobs or materials for sky-only jobs.
{
"version": 1,
"materials": [
{"name": "panel", "albedo": "panel.png", "normal": "panel_normal.png", "ao": "panel_ao.png", "emission": "panel_emissive.png"}
],
"sky": {"name": "dusk", "panorama": "dusk.exr"}
}
./bin/petafab-cook build MyLevel/source/cook.json --out MyLevel
./bin/petafab-cook package MyLevel/level.json --output MyLevel.zip
The recipe describes the converter job; the game’s level.json remains version 2. Cooking writes textures and sky files but does not edit your map JSON. The package command gathers referenced runtime assets and preview.jpg, leaving editable source images out.
To try the sandstone example, copy its example/ folder beside bin/ and run ./bin/petafab-cook build example/source/cook.json --out example. Open the example with Workshop → My Levels → Play Folder. After editing and recooking, press F5 (or Fn + F5) to reload the map and its assets. For ZIP testing, package again before reloading.
The standalone converter guide includes the same workflows, recipe fields and optional sky example. It is also included in the complete level specification and the converter download.
06 / Share your map
Publish to Steam Workshop
- Test your saved map. Open it with Play Folder or Play Local ZIP. Check the spawn, ammo, paths out of every gate, trigger actions, fluid behavior and victory condition.
- Add a thumbnail. Save a JPEG named
preview.jpg, smaller than 1 MiB, besidelevel.json. Use a picture of your edited map. If you make a ZIP manually, put both files at its root, not inside another folder, and preserve referenced DDS paths. - Create the listing. Choose Workshop → My Levels → New Level and select your folder or ZIP. The last local map you played is preselected. Enter a title, description and any tags or change note.
- Choose what to share. Leave Skip source/ folder checked for a playable upload. Uncheck it to include your editable assets and notes. Folder uploads gather the JSON, referenced DDS files and thumbnail automatically.
- Upload and make it public. Open Read Steam Terms, accept the terms for this submission, then choose Upload New Item. New items start Private. Finish any agreement acceptance on the Steam item page, test the published copy, and set its visibility to Public when ready. Keep Steam running until the upload finishes.
Update the same item
Open your existing map’s Community → Update, choose the revised folder or ZIP, and select Update Level. This keeps the item and its subscribers together. For a listing-only edit, clear the selected folder or ZIP to keep the existing content and thumbnail.
After uploading, open the installed map and choose Check for Updates. The details show the installed revision’s local date and time and whether it changed. Play that installed copy to check the version subscribers will receive.
Package limits & common fixes
- Folder not recognized: select the folder containing
level.json, not its parent. For a ZIP, keeplevel.jsonandpreview.jpgat the archive root. - JSON rejected: check editor errors, spelling, required fields and references to material or gate IDs. The game also validates geometry and resource budgets.
- Edits not showing: save in your editor and press F5 during local play. For a ZIP, replace the selected ZIP with your updated archive first. Ordinary restart does not reload external edits.
- Missing textures: include every referenced DDS at the exact relative path. Required runtime files must be outside
source/. - Upload limits: 128 MiB for both the ZIP and expanded contents, at most 128 entries, 32 MiB of JSON, and 69 DDS files. Use ordinary stored or deflated ZIP entries with printable ASCII relative names; avoid encrypted files, links and duplicate names.