Blitz3D+ World Editor User Guide

This guide covers scene editing, reusable resources, particles, appearance, audio, animation sets, terrain, project saves/exports and live debugging. It reflects the development editor source as of 2 October 2026.

The editor is included in Extended Blitz3D+ installations for Windows 64-bit and the Mac; Blitz3D+ on Mac and iOS explains how to start it on a Mac. It is not included in Original installations.

Help for a control

Hover over a World Editor button, checkbox or dropdown and press F1. The new resource editors also provide topics for their input fields, lists, source text and preview canvases. The User Guide window opens beside the editor at the section explaining that control, even if another control has keyboard focus. Disabled controls can also explain their requirements. An open dropdown closes without applying the item under the pointer. On many Mac keyboards, hold fn as you press F1.

Back and Forward revisit guide pages and sections. Contents opens the index below. The window stays beside your work, including beside an open dialog, so you can follow the steps as you read. Close it when you are done; the next topic reopens the same window. You can also open it with Help > User Guide.

Contents

1. Opening the editor
2. Your first scene
3. Understanding the workspace
4. Navigating and arranging views
5. Blip and AI assistants at work
6. Selecting and organising objects
7. Moving, rotating and scaling
8. Editing object properties
9. Managing assets
10. Preparing models
11. Shared models and pictures
12. Creating and assigning materials
13. Creating a physics scene
14. Reusable resource workflows
15. Particle effects
16. Scene environments
17. Walking characters
18. Baked lighting
19. Big worlds
20. Camera effects
21. Audio resources
22. Animation sets
23. Terrain resources
24. Native UI resources
25. Problems and playing
26. Playing the world
27. Changing the world while you play
28. Talking to Blip while you play
29. Playing in VR
30. Your own game, linked
31. Saving and managing files
32. Save All
33. Project dependencies
34. Embedding and extracting resources
35. Moving resource references
36. Recovering an interrupted save
37. Exporting a resource project
38. Editing a running program
39. Keyboard and mouse reference
40. Troubleshooting
41. Current scope and further reading

Opening the editor

Standalone editing

Run b3dworldedit.exe from your Blitz3D+ installation's bin folder. Use File > Open World... to open a .world file, or pass a file when launching. From the installation folder in PowerShell:

.\bin\b3dworldedit.exe
.\bin\b3dworldedit.exe .\samples\world-editor\starter.world

The included starter.world contains a camera, a light and a placement pivot. It is a useful starting point for learning the controls.

Started with --assets (.\bin\b3dworldedit.exe --assets), the editor opens as an asset library, with Assets filling its window, and a world created there starts as an empty asset collection. A world created in the ordinary editor starts with a Default Light and saved ambient lighting. Either way, you can open and save worlds that contain both scenes and assets.

If working from source, open samples\world-editor\WorldEditor.bb in the IDE and compile/run it in Extended mode. Use an editor and runtime from the same installation/build.

Live editing

A program running under the Extended debugger can open the editor with DebugWorld. Live mode attaches to that program's world; standalone mode opens a document. See Editing a running program for the full workflow.

Your first scene

This exercise creates two objects, changes their appearance, and saves a world.

1. Launch the normal World Editor and choose File > New World. Open Scene if necessary.
2. Click the Primitives tab below the views and click Cube. It appears at the editor camera's focus point and becomes selected.
3. Press F, or choose View > Frame Selected, to fit the cube in the active view.
4. In the inspector's Object section, set Name to First cube and press Enter. In Transform, with Space set to Local, set Position to 0, 1, 0, committing each field with Enter.
5. Click the viewport, press Ctrl+D (⌘D on a Mac), and left-drag the copy sideways. Alternatively, hold Shift while starting a drag on the original to copy and move in one gesture. Release to finish.
6. Choose File > New Resource > Material..., then Blank material. Enter Blue paint in the name field.
7. Click Colour / tint..., choose blue, and inspect the live preview. Click Save on the toolbar and choose Blue paint.material.
8. Select a cube and find the Materials section in the inspector, or right-click the cube and choose Materials.... Click Material bindings..., choose Whole model, select the saved material, and click Replace with selected. Validation happens automatically. Repeat for the other cube to share the material.
9. Choose File > Save World As... and save as My First World.world in your project folder.
10. Check the Problems button on the toolbar; it reads No problems when the world is valid. Click the button beside Play, choose FPS, then click Play to walk around your world as a game would show it. Playing the world explains the other ways to play.

Creating an object does not automatically move the editor camera. Use F whenever you want to see a new selection clearly. New objects always start at the top level of the scene, whatever is selected. To put an object inside another one, right-click the parent and choose Add Child.

Understanding the workspace

The editor works on one open .world document. The window has the object hierarchy on the left, the 3D views in the centre and the inspector on the right. Below the views, a panel with three tabs holds the document's other tools:

Click Hide at the panel's right to give the views the full height. Click Show, or any of the panel's tabs, to bring it back at the same height. Drag the divider above the panel to change its height.

The inspector shows what you are working on: the selected scene object, the selected asset card while you work in Assets, or the world's settings when nothing is selected. Click a view or the hierarchy to return it to the scene. Menus and keys follow the same rule: while you work in Assets, Edit > Delete, Undo and Select All act on asset cards; otherwise they act on scene objects.

The menu bar groups commands by what they act on:

The toolbar sits under the tabs and holds the tools you use most. From left to right: New resource, which offers every kind of resource, Open resource and Save; Undo and Redo; then, while Scene is showing, the modes: Move, Rotate, Scale, Sculpt and Paint, whose settings are on the tool options row below. At the right are Play, the button beside it that names the program Play runs, and the Problems count. In a resource's own tab or window, New resource starts another resource of the same kind there, offering to save the current one first, and Open resource opens only files of that kind. Save saves what the tab shows: the world in Scene, or the resource open in a resource tab, as Ctrl+S does; its tooltip says which. File > New World, Open World and Save World work on the world from any tab. The active mode is highlighted. In a narrow window the tool buttons show only their icons; hover over any button for its name and shortcut. Narrower still, Problems makes room (it is also on the menus and the tabs below the views), and then Play shows only its icon. In live mode, Play and Problems are replaced by Pause, Continue and a coloured strip showing the session: grey while connecting, amber while the program runs (pause it to edit), green while paused, and red once it has disconnected. While the physics preview runs, Play reads Stop physics.

Under the toolbar, Scene has a row of tool options for the chosen mode. With Move, Rotate or Scale it holds the axis choice, Snap with its step size (Stretch takes its place while Scale is chosen), and Face snap (C); with Sculpt, the brushes and their settings; with Paint, the ground layer to paint or Regions, and Auto paint.... In a narrow window the row gives way: lists and sliders narrow, the brushes become a list, and Softness keeps its value until there is room for it again.

Right-click an object in a view or in the hierarchy for the commands that apply to it, including Add Child. Right-click empty space for Add, Select All, Frame All, World Environment and World Gravity. Commands that cannot apply to the current selection are greyed out, and a shortcut for one of them says why in the status bar, for example Select an object first. In a resource tab, the explanation appears in that tab's status line.

Opening a material, a physics definition, the prefab tools or any other resource (a particle effect, environment, camera effects, sound, audio mix, animation set, terrain or terrain material) adds a tab beside Scene for that document, as does File > Project Dependencies.... Each document tab has the same layout: the resource's own page, with a viewport beside a pane that starts with its Name and holds its settings in collapsible sections (click a heading to show or hide one), and Source. Drag in a particle, environment, camera effects, animation set or terrain viewport to turn the view around what it shows, and use the mouse wheel to zoom, as in the Material Editor's preview; a new preview after an edit keeps the view. The tab's title marks unsaved changes with *. The toolbar above saves it and undoes and redoes its edits, and File > Save Resource As... writes it to a file of its own. To close a tab, drag it out into a window of its own and close the window. The toolbar, Edit > Undo and Redo follow the tab you are looking at, so they never undo work in a tab you cannot see. Assets, Shared, the Material Editor and every resource tab can each move into a separate window without losing their content:

• Assets: drag its tab up out of the panel, or click in Assets and choose View > Open in Separate Window. The window shows the cards with the selected asset's details beside them. To bring it back, click Return Assets here in the panel, choose View > Return to editor in the window, or drag the window's title bar onto the panel's tabs.
• Shared: the same way as Assets, with Return Shared here in the panel. The window shows the preview above the details (see The Shared page).
• Material Editor: drag its tab out of the tab strip, or choose View > Open in Separate Window while it is showing. Choose Return to editor in its View menu, or drag its title bar onto the editor's tab strip.
• Resource tabs (a physics definition, the prefab tools, a particle effect, environment, camera effects, sound, audio mix, animation set, terrain or Project Dependencies): the same way as the Material Editor. The window holds the whole tab, with the toolbar's New resource, Open resource, Save, Undo and Redo across its top acting on that resource. Its title names the resource and marks unsaved changes, and a preview keeps playing beside Scene. Closing the window closes the document, asking first about unsaved changes. While a physics definition has one of its dialogs open, it stays where it is until the dialog closes.

A tab strip highlights when it is a valid return target; dropping elsewhere simply moves the window. View > Assets and View > Material Editor bring the corresponding tool forward. The other resource editors on the View menu do the same for the resource open in them, or start a new one of their kind when none is open. Closing a floating Assets window hides it until View > Assets is used again, and closing the Shared window hides it until the panel's Shared tab is clicked; closing the Material Editor asks about unsaved material changes.

The editor remembers where each tool was and its last normal window position for this user. The Material Editor and every resource always open in a tab; pull one out to give it a window, which goes where that kind's window was last. View > Reset Tool Windows returns Assets and Shared to the panel and the Material Editor and resource documents to their tabs, reopens the panel at its default height and clears the saved positions, without closing the world or a material draft.

View > Theme chooses how the editor looks. Match Windows, the default, follows Windows' light or dark setting for apps and changes with it. Light and Dark keep one look, and Classic is the plain look of earlier versions. The editor remembers the choice for this user. While Windows high contrast is on, the editor uses the colours chosen there.

The asset library (--assets) has no scene: it shows Assets across the whole window, with the details beside the cards.

An asset is a reusable resource declaration, such as a model file or material. An entity is an object placed in the scene. Several entities can use one model asset. Removing an entity does not delete that model file.

Drag the dividers to change pane sizes. A guide line follows the drag and the panes resize on release; Escape cancels it. Resizing the main window keeps the sidebar widths and the panel's height, and gives the extra space to the views.

The window title shows an asterisk when the standalone world has unsaved changes. The status bar shows whether the world is saved, how many objects and assets it has, how many objects are selected, and the latest message. Inspector changes update the open document; saving to disk remains explicit.

Navigating and arranging views

Moving the editor camera

Click a viewport to give it keyboard focus. These controls move the editor view without changing scene objects:

In live mode while the program is running, plain right-drag can orbit; when paused it is used for editing height. Using Alt for orbit avoids that change of meaning.

Frame fits the selected object or group, including visible descendants, into the active viewport. Double-clicking a hierarchy row also frames it. The editor camera, grid, bounds, axis handles, and camera/light outlines are editor aids; they are not saved entities or objects added to a live game.

Ground grid

Standalone Scene views show a ground grid at height 0, in the style of the Maplet modeller: blue 1-unit squares across 80 units around the view's focus point, with a lighter line every 10 units that reaches 200 units across. The grid stays fixed to whole world units while the pointer moves; a small green cross marks the point under the pointer. While Snap is on, the cross moves in steps of the move interval.

Objects in front of the grid hide it, and it shows over anything below height 0. When you pan far enough, the grid moves on in whole 10-unit steps, so its lines stay on the same world positions. Choose View > Grid to hide or show the grid in every view; the editor remembers the choice for this user. Live views are drawn by the running program, which shows its own grid.

Direction and projection

Each viewport has a direction selector: Free, Top, Bottom, Front, Back, Left, Right, followed by available scene cameras. Its separate projection selector offers Perspective and Orthographic.

Perspective shows depth and foreshortening. Orthographic is useful for aligning objects in plan or elevation. Any direction can use either projection. Switching projection retains the view's orientation, focus and apparent framing.

Orbiting away from a perspective direction preset changes its direction label to Free. In orthographic views, the orbit gesture pans instead, the wheel changes magnification, and W/A/S/D navigation moves in the view plane. Standalone navigation still requires Alt.

Following a scene camera

Choose a Camera: entry in the direction selector to see through that camera. The view follows its world position and rotation, including parent transforms and roll, and uses its projection, zoom, clipping, aspect, clearing, fog, shadows and effects. The editor pane determines the available viewport size.

The projection control reads From camera and navigation is locked while following. Choose Free or a direction to return to the editor camera. Renaming the followed camera keeps the association; deleting it returns the view to an editor camera. Different panes can follow different cameras.

Camera following can show settings already present in a scene even where the inspector has no control to author those settings.

Splitting views and saving layouts

Open a viewport's View... menu to choose Split left / right, Split top / bottom, Close this view, or Frame selection. Drag split dividers to adjust proportions. The darker border marks the active view. All views share the scene, selection and edit history.

The editor allows up to eight views, with a maximum of three split levels, and always keeps at least one view. Narrow panes abbreviate some labels, including the View... button as ....

The View > Layout menu arranges all the views at once:

View > Camera Sync controls how editor cameras move together. The current choice is ticked:

Linking starts from the active view. View orientations stay independent. Layout files retain splits, proportions, directions, projections, camera framing, active view and sync settings. They do not save the world or move program cameras.

Document camera choices can be retained in presets. Live camera identities belong to one debugging session and are not saved in portable presets. Invalid preset files leave the current layout in place. Layout files have their own versioning: the current layout format is version 2 and also reads version 1 layouts.

Blip and AI assistants at work

When Blip, the IDE's helper, changes the world, you can watch him at work in the views. A small Blip flies to what he is changing, hops while he thinks, spins as each change lands and waves when he is done. Then he flies back to rest beside your view, at its lower right, so a Blip at the work always means work in progress. Left alone for a couple of minutes, he falls asleep there, and later he goes, until you ask him something again. He is bigger or smaller with the effort level you choose in his panel.

Far away, or behind something, he shows as an icon with his name and what he is doing. While he works outside a view, an arrow at its edge points to him: click the icon or the arrow to bring the view to his work. What he has just changed flashes in his colour. He is not part of the world: he is not saved, you cannot select him, and he never appears in the pictures he takes of the world.

AI assistants that work in the editor through its MCP server (see AI assistants) show as round markers in their own colours, with their names, while they work, and go once they have finished.

In a buddy session, everyone sees everyone's Blip, ringed in the colour of the person he belongs to. While Blip answers Sam, Sam's Blip is labelled "Blip (asked by Sam)" as he works; between requests he rests beside Sam's view marker, and sleeps and goes as he does for Sam.

Untick View > Blip and AI Assistants to hide them all; the editor remembers the choice for this user. Blip can hide himself too, if you ask him.

Selecting and organising objects

Selection and search

Click geometry or a hierarchy row to select an object. Camera and light outlines can be selected by their lines or interiors. Use Ctrl-click to toggle objects in a multiple selection. Drag empty viewport space for a selection rectangle; Ctrl-drag adds to the current selection. Ctrl+A selects eligible world entities.

Click empty space, or press Escape when no gesture is active, to clear the selection. During a gesture, Escape cancels that gesture first.

When a selected parent contains visible children, grabbing those children keeps the parent selected. Use Ctrl-click or the hierarchy to explicitly choose a child. Selecting both a parent and child does not cause the child to move, copy or delete twice.

Type in the Filter objects field above the hierarchy to find objects by name, ID, component type, model asset ID or tag: coin finds every coin. Clear it to restore the full tree. Filtering is a browsing aid; it does not hide scene geometry. Each hierarchy row has an icon for its kind of object, and the world itself is the top row.

Creating objects

The Primitives tab, the first tab below the views, shows the objects a scene can be given; each button pictures its object above the name. Click one to create it at the active editor focus point, or drag it into a view to create it where you let go: the shape follows the pointer, standing on the object under it or on the ground, and Esc cancels the drag. The same objects are in the Add menu and in the menu for right-clicking empty space, which create them at the focus point:

Below them, More shapes offers ready-set shapes named for what they make: Pyramid (four flat sides meeting at a point), Prism (a six-sided column), Arch (half a tube stood on its side) and Ring (a short tube, like a washer). Each is an ordinary shape afterwards, so the Shape section changes it like any other. The Add menu and the menu for right-clicking empty space have the same shapes, with the presets under More Shapes. A running program's world offers the shapes up to Wedge.

Primitives are described inside the world and need no external model file. For imported models, import the file in Assets and double-click its card or its preview, or choose Add > Model from Assets... to show Assets filtered to models. The editor places an instance and selects it in the scene.

You can also drag a card from Assets into a view. While you drag, a small copy of the card follows the pointer, saying what letting go there would do. Over a view, the model follows the pointer, standing on the object under it or, over empty space, on the ground, and goes where you let go; an outline and a ring mark where, however large or small the model is. Esc cancels the drag, and letting go outside the views places nothing. Particle effects and physics assets dragged into a view also go where you let go. A material dropped on an object is used for the whole object, as Whole model in its Materials section does; the object is outlined while the pointer is over it, and Ctrl+Z undoes the change. A terrain takes only a terrain material (File > New Resource > Terrain Material): dropped on a terrain placed from a terrain definition, it opens that definition's tab and uses the material there, as its Use material... does, ready for you to save. Other assets do what double-clicking their card does.

An object dropped onto a terrain also sticks to it while View > Stick to Surfaces is ticked, as it is to begin with: sculpt the terrain, change its size or move it, and the object stays on the ground where you put it. The hierarchy marks it [on terrain name], and its On surface section has the details. Objects dropped onto an animated model sit on it and move with it; objects dropped onto other objects rest on them without sticking.

New objects always go at the top level of the scene, whatever is selected. To create an object inside another one, right-click the parent, in a view or in the hierarchy, and choose Add Child. Its Model from Assets... item opens Assets; the next model you double-click or drag into a view becomes a child of that parent, and the status bar names the parent until then. Leaving Assets without placing a model cancels it. The placement position is converted into the parent's local space. Add Child also works beneath program objects in a paused live world. Imported model nodes cannot be used as editable parents.

Parenting and grouping

To make a group, create a Pivot, give it a useful name, and drag existing objects onto its hierarchy row, or right-click the pivot and use Add Child for new objects. Move, rotate or copy the pivot to operate on its descendants.

Drag one hierarchy object onto another to change its parent. Drop on the world root to detach it. Hover over a branch to expand it; dragging near the tree edges scrolls. Escape or dropping outside a valid row cancels.

You can also enter an entity ID in Object > Parent. Clearing that field and pressing Enter detaches the object. Parent IDs are not the display names entered in Name.

Reparenting preserves the object's world position by recalculating its local position. Do not assume its world rotation and scale will also remain identical under a differently rotated or scaled parent; check them after the drop. An object that stands on a surface is placed by the surface, not its parent: reparenting never moves it, and moving its group leaves it where it stands. Each successful reparent is one undoable scene edit. Cycles and changes involving protected or imported objects are rejected. Live reparenting is limited to editor-created objects while paused.

Imported model hierarchies

In Assets, turn on Keep hierarchy and animation in the model's import options to retain its internal nodes. This is useful for static GLB models as well as animated models. With it off, the default, the model loads as one collapsed mesh.

Expand the placed model in Scene to inspect its meshes and pivots. Source names and parent relationships are retained, with descriptive labels for unnamed nodes. Rows marked [imported] are read-only: select, search, frame and inspect their local transforms, but edit the placed model object to move, copy or delete the whole asset.

Ctrl-click geometry to select an imported node. Selecting a node this way replaces selected ancestors or descendants in the same branch; selected siblings and unrelated branches can remain. Rectangle selection and Select All operate on world entities. Saving keeps the original model reference and rebuilds imported rows when reopened.

Locking objects

Use Edit > Lock Selected, Edit > Unlock Selected or Edit > Unlock All. Lock and Unlock are also on the menu for right-clicking an object, and Unlock All on the menu for right-clicking empty space.

A locked object and its descendants stay visible but cannot be picked in the viewport, box-selected or edited. Picking passes through them. Locked rows show [locked], selection bounds are muted, and there are no axis handles. You can select a locked root in the hierarchy to inspect or unlock it. An inherited lock must be removed from the ancestor, or with Unlock all.

Locks also prevent moving an unlocked parent if that would indirectly change a locked child. Undo/redo cannot bypass protection; a blocked history operation remains available after the relevant protection is removed.

Restricting work with Focus on Selected

Select the objects you want to work on, then choose Edit > Focus on Selected, or right-click one of them and choose Focus on Selected. Only that fixed set and its descendants can be selected or edited. Other objects remain visible and can still provide snapping references. The command changes to Unfocus All.

Focus stays active even if you clear the selection or delete the last focused object. To choose a different focus set, choose Edit > Unfocus All, select the new set, and focus again. Creating and copying objects are disabled while focus is active. Locks still apply within the focused set.

Frame Selected (F) moves the camera. Focus on Selected restricts editing. They perform different actions.

Locks and focus are shared across all views and survive scene refreshes, but are session settings rather than saved .world data. Opening another document or closing the editor clears them. In live mode they constrain editor operations only; the program can still change those objects.

Moving, rotating and scaling

Choose the editing tool with the Move, Rotate and Scale buttons on the toolbar, and the axis with the dropdown on the tool options row below them, or use the shortcuts below with the viewport or hierarchy focused. Start a drag on the selected geometry to use the chosen axis.

The selection also shows axis handles: red for X, green for Y and blue for Z, with arrows for Move, rings for Rotate and squares for Scale. A handle turns yellow under the pointer. Drag a handle's tip or outer part to move, rotate or scale along that axis for that one drag; the axis chosen on the toolbar applies again afterwards. Move and Rotate handles follow the world axes; Scale handles follow the object's own axes. Locked or imported selections have no handles.

Scaling a shape from the Primitives tab changes its size, not its scale: a box gets wider, a capsule taller, and rounded edges, tube walls and capsule ends keep their size. Round shapes take the average of their X and Z change. The view shows the shape stretched during the drag and rebuilds it at its new size when you release. To scale the object itself, squashing those features too, tick Stretch, which takes the place of the move interval on the toolbar while Scale is chosen. Objects with children, models, spheres and the endless Plane always scale. An object saved with a scale keeps it; Apply scale to size in its Shape section turns that scale into its size.

Press X, Y or Z to constrain a mode to an axis. Press U to restore that mode's default: ground/height movement, Y rotation, or uniform scaling. An explicitly chosen axis carries across mode changes until you change it.

In an orthographic view, unconstrained movement follows the view plane. For a constrained axis pointing directly into the screen, dragging upward increases its coordinate.

Hold Ctrl during a drag for precision. Ctrl-click before a drag is a selection gesture; begin the normal drag before adding Ctrl for precision. Release the mouse to commit the complete gesture as one edit. Escape cancels and restores the starting state. Losing mouse capture or viewport focus also cancels unfinished gestures.

Copies and deletion

Hold Shift when starting a drag to duplicate selected subtrees and position the copies. Ctrl+D duplicates in place. Copies retain their descendants. Selected descendants are handled as part of their selected parent, rather than duplicated again.

Press Delete in Scene, or choose Edit > Delete or Delete on the menu for right-clicking an object, to delete the selection and its descendants. Duplicate is on the same menus. In live mode, deletion is limited to editor-created objects; a selection containing program-owned objects or descendants is protected.

Step snapping

Tick Snap on the tool options row and choose a move interval beside it: 0.1, 0.25, 0.5, 1 or 2 units. Move uses that interval; rotation uses 15-degree increments; scale uses 0.1 increments. This is useful for repeating architectural spacing or matching simple dimensions. The green cross of the ground grid moves in the same steps.

Face snapping

Hold C, or enable Face snap (C), to bring nearby opposing bounds faces into contact during movement or scaling. During rotation, C provides 15-degree steps.

Once a face is captured it stays attached until you move sufficiently far away or disable snapping. Copies can snap to their originals. Group scaling keeps one common factor and stops when the first neighbouring face is reached, including another selected root. Live snapping highlights the engaged face in green.

Face snapping uses world-aligned bounding-box faces. It does not perform exact mesh collision or align arbitrary polygon normals. For an irregular or rotated mesh, inspect the result and use numeric transforms when exact contact matters.

Undo and redo

Use the Undo and Redo toolbar buttons, Edit > Undo and Edit > Redo, or Ctrl+Z / Ctrl+Y in Scene. The Edit menu names the change that will be undone or redone. Standalone Scene also supports Ctrl+Shift+Z for redo. Creation, deletion, duplication, transform gestures, reparenting and normal inspector edits are undoable. A released transform drag is one history entry.

Committed scene and resource edits share workspace undo/redo. Resource windows retain local draft history until Save commits them. Undo changes staged sources; Save All publishes them. Invalid documents retain their repair controls.

Editing object properties

Select one editable object to work with its inspector. Its heading shows the object's name and kind. Below it, the inspector is one scrolling column of sections: Object and Transform for every object; Shape for a shape from the Primitives tab, or Shape along path for a path; Camera, Light or Materials for the corresponding object type, and Light cookie for a light in a standalone world (see Light cookies); Level of detail for a model (see Level of detail); Zone, Zone look, Zone sound, Zone trigger and Zone walking for a zone; Walking for anything characters can walk on or round, and Walk link for a walk link (see Walking characters); Reflection probe for a reflection probe; in a standalone world, a section for each resource the object uses (see Resources an object uses); and Physics and Prefab. With nothing selected, the inspector shows World settings instead.

Click a section's heading to collapse or expand it; the arrow points down while it is open. Collapsed sections stay collapsed as you select other objects. The mouse wheel scrolls the inspector anywhere over it. Over a dropdown it scrolls the inspector rather than changing the dropdown, unless you have clicked into that dropdown first. Tabbing to a field below the visible part scrolls it into view.

With several objects selected, the heading shows how many. The sections show the most recently selected object, read-only; move, rotate or scale the selection together in a view.

Dropdowns and checkboxes commit immediately to the open scene. Text fields commit on Enter or when focus leaves the field. Invalid input returns to the stored value and reports an error. These commits do not replace File > Save.

To change a number without typing, hold Alt (Option on a Mac) over it: the pointer becomes a left-right arrow. Drag left or right to step the number down or up, or hold Shift as well for steps ten times larger. A whole number steps by one, and a number with decimals in its last decimal place, at most hundredths; rotations of whole degrees are shown without decimals, so they step a degree at a time. While you drag a Transform number, the object moves with it in the views. Releasing the mouse button commits the value as one undoable edit, as Enter does; pressing Escape before releasing puts it back. This works in every text field that holds only numbers, including those in resource tabs.

World settings

Click empty space, or press Escape, to clear the selection; the inspector then shows settings for the whole world. Physics > World Gravity... and World Gravity on the empty-space menu open the same settings, and World Environment on that menu opens the world's environment in its tab. The settings are in sections, Environment, Time of day, Soundscape, Ambient light, Shadows, Baked lighting, Physics and Loading; click a section's heading to hide or show it. A hidden section shows its current values after its title.

• Environment chooses the world's sky, lighting and reflections from the environments in the world, or No environment. After them, the list offers starter environments for the usual game settings: Clear day, Hot desert, Frozen world, Tropical forest, Sunset, Moonlit night, Stormy, Underwater, Outer space, Alien world and Volcanic. Choosing New from starter: Hot desert, for example, adds a copy of that starter to the world and uses it, as one edit that Edit > Undo takes back; it needs no files. Edit opens the chosen environment in its tab, and New starts one there. While the world uses an environment, the ambient light comes from it, so the ambient fields are unavailable.
• Time of day changes the world's look through the day: the sun can cross the sky, or each time can have a look of its own. See Time of day.
• Soundscape chooses what the listener hears outside every zone: music, ambience and sounds around it, such as birdsong over a meadow. Edit opens it in its tab, and New starts one there. Times of day and zones can bring in their own. See Soundscapes.
• Ambient light is the light every surface receives even where no light reaches it. Enter whole numbers from 0 to 255 for red, green and blue, or click Choose... to pick a colour: the scene shows each colour as you choose it, OK keeps it as one edit that Edit > Undo takes back, and Cancel puts the old light back. Low values give dark shadows; a new world starts at 70, 70, 76.
• Enable shadows turns the world's shadows on; a new world has them off. Shadow lights sets how many lights can cast shadows at once, from 1 to 8, and Shadow quality chooses Off, Low, High or Ultra; point lights cast shadows only at High or Ultra. A new world, and a world file that doesn't give a quality, use High, the same default as ShadowQuality in a program. While the world uses an environment, the environment decides whether shadows are on, so Enable shadows is unavailable. Each light and camera has its own shadow setting too (see Light).
• Baked lighting works out light bounced between surfaces, soft shadows and the glow of bright surfaces ahead of time, and keeps it beside the world. See Baked lighting.
• Gravity sets the pull on movable physics objects, in metres per second squared, both in Physics > Play Physics and in your game. Most scenes use the default 0, -9.81, 0.
• Loading says how much the world loads at the start, and can make a big world load distant objects as the player gets near. See Big worlds.
• Walking, closed until you open it, sets the sizes of character that walk the world, the areas they walk on and what each costs, and shows how much of the world they can walk on. See Walking.
• Online, closed until you open it, lets people play the world together online, each as a copy of the player object, with bots in the empty places. See Playing together online.

Press Enter or leave a field to apply it. Each change is one undoable edit, and entering the value a field already has changes nothing. In live mode these settings belong to the running program and cannot be edited.

Object and Transform

Changing Space changes the displayed values without moving the object. Local Reset aligns it with its parent. Global Reset puts it at the world origin with zero world rotation and unit world scale. Reset is one undoable edit. Global scale follows Blitz3D's component-wise parent-scale convention, including mirrored parents.

Visibility affects the scene in every viewport. There is no per-view hide state: hiding a roof for a top-down interior view also hides it in the other views. A hidden object can still be found in the hierarchy to make it visible again.

Tags

Tags are words that a program, and the world's zone triggers, find objects by: tag the player player, every coin coin, every enemy enemy. Type them in the Tags field of the Object section, separated by spaces, and press Enter; each tag is letters, digits, _ and -, and Coin and coin are the same tag. The field saves them sorted, each once, as one undoable edit. A world saves them as the object's tags metadata.

Select several objects to tag them all at once: the field shows the tags they all have. A tag typed in is added to every one, and a tag taken out is taken from every one, while each object keeps its other tags. The whole change is one undoable edit. The hierarchy's Filter objects field finds objects by their tags too.

In a program, EntityHasTag asks whether an object has a tag, CountTaggedEntities and GetTaggedEntity visit every object with one, and TagEntity and UntagEntity change them while it runs, including on objects the program makes. Copies keep their tags. While the World Editor is attached to a running program, pause it to change an object's tags there; the program sees them at once.

Custom properties

Custom properties are named values an object keeps for your program, such as score = 10 on a coin. Open Custom properties under the Object section, click Add, type the property's name in Name and press Enter, then its value in Value. Choose a property in the list to rename it, change its value or Remove it. Values are kept as text; hold Alt and drag in Value to change a number. Each change is one undoable edit, and the section's heading counts the object's properties.

A name is 1 to 64 letters, digits, _, - and dots. tags belongs to the Tags field, and names starting b3d. belong to the editor and engine, so neither can be a property's name.

A world saves the properties in the object's metadata. A program reads one with WorldEntityMetadata$(entity, "score"), and lists them with CountWorldEntityMetadata and WorldEntityMetadataKey$. CountWorldEntities and GetWorldEntity visit every object of a loaded world in file order, and FindWorldEntityByName finds one by its name:

world = LoadWorldAsync("level1.world")
While Not WorldReady(world) : Wend
For i = 0 To CountTaggedEntities(world, "coin") - 1
	coin = GetTaggedEntity(world, "coin", i)
	total = total + Int(WorldEntityMetadata$(coin, "score"))
Next

Behaviours

Behaviours make an object do something while the world plays, with no code: a coin that spins and can be picked up, a platform that slides back and forth, a door that opens when the player walks up.

Select the object and click Add behaviour... in its Behaviours section, then choose one from the list. It works at once, with settings suited to the object; change them under the list. Choose one of the object's behaviours in the list to change its settings, untick Runs when the world plays to keep it waiting until a trigger or your program starts it, or click Remove. Each change is one undoable edit.

Behaviours run whenever the world updates: in your program at each UpdateWorld, in the World Editor's Play, and in the physics preview, Physics > Play Physics, which plays a world with behaviours even when it has no physics. Stop puts everything back. Speeds are per second, and UpdateWorld 1 is 1/60 of a second. A hidden or disabled object's behaviours wait. A behaviour adds its movement to the object's, so a coin can spin and bob, and your program can still move it. An object that a behaviour moves and that has a physics body moves as a kinematic body, so it carries and pushes the dynamic bodies in its way.

A collectible is touched with the collision radius (EntityType and EntityRadius) of the collecting object, or of the nearest object above it in the hierarchy that has one, as a first-person camera's walker does; otherwise with the collecting object's model, or else its position. The World Editor's FPS player collects with its walker. A collected object goes at the next UpdateWorld, so your program can still read it after the one that collected it.

A behaviour's ID is its kind's name, such as spin or move, with -2 added for a second of the same kind. In a program, EnableBehaviour and BehaviourEnabled switch a behaviour off and on by its ID, and StartBehaviour starts one that waits for a trigger. LoadWorldAsync with WORLD_LOAD_BEHAVIOURS_OFF loads every behaviour switched off, for programs that drive everything themselves. What behaviours do comes to the program as world events: after each UpdateWorld, CountWorldEvents counts them, and WorldEventName$ is collected (with the collectible as WorldEventEntity and the collector as WorldEventOther), arrived when a move reaches an end, or removed when the world takes an object away, as well as a trigger's entered and left:

UpdateWorld
For i = 0 To CountWorldEvents(world) - 1
	If WorldEventName$(world, i) = "collected"
		score = score + Int(WorldEntityMetadata$(WorldEventEntity(world, i), "score"))
	EndIf
Next

samples/behaviours has coins to collect, a gate that a doorway opens, and a crate the gate pushes out of its way.

Switches, doors, timers and spawners

Four behaviours make a world react, with no code: a plate that opens a gate while you stand on it, a button that opens a door for a few seconds, a lamp that comes on by itself, and a pickup that comes back after you collect it. Add each with Add behaviour... on the object it belongs to. What it needs is made in the same step, and the object stays selected, with the new behaviour chosen; one Ctrl+Z takes it all away again.

• Door: select the door and add Door. It slides open as the player comes near, and closes once they have gone. It gets a collider that moves with it, an Open position marker under it one door's width along its longer side, and a sensing area beside it, which stays put as the door moves. Click Edit open position and drag the marker where the door should be when it is open. Moves Swings on a hinge makes a Hinge marker at its left edge, with Edit hinge, Hinge side and Swings by (90 degrees); the slide's settings stay for changing back. Takes is the seconds it takes to open, Opens When the player comes near or From a switch or code, Closes after the seconds it waits once everyone has gone, and Starts closed or open. Something in its way stops it: closing, it opens again and tries later; opening, it waits. A body that falls is pushed; a player, a wall or a fixed body blocks it. A door moves its object, so the object cannot also spin, bob, move or walk: give those to a child of the door.
• Switch: select a plate or a button and add Switch. It turns on while something tagged player is in a sensing area made round it, and off when the last has gone. Turns on When something stands on it makes it a pressure plate: it gets a collider, and its sensing area moves to its top, so only what stands on it counts, not what brushes past its side. The World Editor's players and objects with physics can stand on a plate; a camera on its own cannot, so use When something comes near for it. Set off by takes several tags, such as player crate, any of which will do. Stays on While something is there, Until it is used again (on with one visit, off with the next), or For a time, with For its seconds. Controls chooses the door it opens: the switch opens the door as it turns on and closes it as it turns off, and the door then opens only from the switch; choosing No door lets the door open by itself again. A door takes one switch: for two plates that open one gate, put both in one switch's sensing area. Advanced settings has Can be used again (untick it for a switch that works once each time the world plays) and Light up while on.
• Timer: add Timer to an object, set Wait, and add what it does under What it does, such as After 3 seconds, show Lamp. On a model it waits for a switch, a trigger or your program to start it; tick Start when the world starts to start it with the world. Repeat starts it again each time it is up. It keeps time while its object is hidden, so a hidden lamp's timer can show it.
• Spawner: on a model, Spawner is Respawn this object. The object and everything under it become a prefab kept in the world, and the object a spawn point in the same place, keeping its name, so the scene looks the same: when the world plays, a fresh copy stands where the object stood, and another comes 3 seconds after it is collected or removed. A collected copy is gone for good, even if its collectible only hides it. If other objects refer to the object, the editor lists them first: they go on referring to it, which is the spawner now, and Problems lists any that no longer make sense, such as a trigger that hides it. On a marker, Spawner spawns the prefab chosen in Assets, or the world's first. Spawns chooses the prefab, Makes Another when one goes, Just one or Another every so often, At most how many there are at once (hidden ones count), and After or Every the seconds. In Advanced settings, If it goes says whether what it made goes with it, and Inputs chooses the objects of this world a prefab needs.

What it does lists each one's responses as sentences, such as When it turns on, open Gate. Choose a moment in When (a switch's turning on or off, a door's opening, being open, closing, being shut or something in its way, a timer's time being up, a spawner's making one or failing to), an action in Do, and click Add. The actions are a trigger's (hide, show, enable, disable or remove an object, play a sound, start or stop a behaviour) and the four's own commands: Open a door, Close a door, Open or close a door, Turn a switch on or off, Reset one, Start, Stop or Reset a timer, Start, Stop or Reset a spawner, and Spawn one. Choose a row to change its Object and its behaviour, Select its object, or Remove action. Responses run at the world's next step.

While the selected object's switch, door, timer or spawner is chosen, the views draw a door's way to its open position, its hinge, and a line from a switch to its door. Edit sensing area selects a switch's or door's sensing area, to move it or change its size in its Zone section. The markers and areas are ordinary objects in the hierarchy, each saying whose it is (helperOf): removing the behaviour removes them, and so does deleting its object, with the actions that act on it, after the deletion lists them.

Physics > Play Physics plays them in the views. The chosen one's state shows above its settings, such as Now open, 100% open, with Try and Do it to give it a command in the preview alone; Stop puts everything back as it was. The World Editor's Play plays them too. Play Online Test plays them too. Online, only the server runs them, so every player sees the same plate, door, timer and pickups, and someone who joins late finds them as they are. Each player's computer builds what a spawner makes for itself, under the server's names, so a spawner whose prefab has a body that moves by itself, or a joint, plays offline only: Play Online Test says so, and fixed or kinematic physics in the prefab plays online. A crate, or anything else that physics moves, is each player's own online, so in an online world make plates that players stand on.

A world with a door or a plate steps its own physics in UpdateWorld, which adding the first one sets (the world's physicsStep setting). Your own program that loads such a world leaves StepPhysics out for it: WorldPhysicsAutomatic says which, so one game loop plays both kinds. In a program, CommandBehaviour gives one a command, BehaviourState says what it is doing, and WorldEventBehaviour which one sent an event, such as a door's opened or a timer's elapsed. samples/behaviours/switchyard.world has all four, and Switchyard.bb plays it.

Behaviours of your own code

When no built-in behaviour does what you want, write your own. Choose Add behaviour..., then New behaviour... at the end of the list, type a name such as Chase player, and press Enter or click Make it. The World Editor writes its code into a behaviours folder beside the world, as ChasePlayer.bb, and gives the behaviour to the object; a world never saved is saved first, as the code goes beside it. To start you off, the code chases: it turns the object towards the nearest object tagged player, moves it there, and sends a caught event when it catches up. Open code opens the file, usually in the IDE, to make it do what you want. The behaviour then has its own place in the Add behaviour... list, after the built-in ones, for other objects.

The code is a Type that implements the Behaviour interface. Each object with the behaviour gets an object of the type, whose fields keep its own state, such as a timer, and the world calls its methods:

Interface Behaviour
	Method Start(owner)
	Method Update(owner, seconds#)
	Method Event(owner, name$, other)
	Method Finish(owner)
End Interface

Start comes before its first Update; Update after each UpdateWorld while the behaviour runs, with the seconds of game time that passed; Event when a world event names its object, such as collected, a trigger's entered, or one that SendWorldEvent sent, with the other object the event names; and Finish when the world removes its object, or the program finishes the world. A hidden or disabled object's behaviours wait, as built-in ones do.

Its settings are in the Behaviours section, in a list like Custom properties: choose one to change its value, or click Add setting and name it as the code reads it. Settings are text, which the code reads with BehaviourSetting, giving the value to use when a setting is not set; giving the behaviour to an object fills in the settings its code reads this way, with those values:

Self.speed = Float(BehaviourSetting(owner, "speed", "2"))

Tags are the way to find other objects: CountTaggedEntities and GetTaggedEntity list the objects with a tag, as the chaser does. Events go both ways: a behaviour hears the events of the world's triggers and built-in behaviours, and the ones it sends with SendWorldEvent reach your program and the other behaviours at the next UpdateWorld. A trigger zone's Start a behaviour switches one on, and makes it wait for the trigger; in a program, EnableBehaviour and StartBehaviour do the same.

A new behaviour's code also implements BehaviourInstance, two more methods: Bind(owner, id$), before Start, gives it its own component ID, so two of the same kind on one object each read their own settings with BehaviourSetting(owner, key, default, id); and Release(), once, when it is let go, even after its object has gone, to give back what it holds. Code without them still runs.

The World Editor also writes behaviours.bb in that folder, which includes each behaviour's code and runs it: keep your code in the other files there, as it is written again when you add a behaviour and when you press Play. Play runs the behaviours with the players, and finishes them when the player quits. Your own program includes the file, calls UpdateBehaviours after each UpdateWorld, and FinishBehaviours before it frees the world or ends:

Include "behaviours/behaviours.bb"
...
UpdateWorld
UpdateBehaviours world

Programs need Extended mode for them, and a mistake in the code stops Play with the compiler's message. The physics preview in the views runs only the built-in behaviours. In the online IDE, Open code shows the code beside the World Editor, which keeps running, and a mistake that stops Play is shown there too, with its line marked. The guard in samples/behaviours is one: it chases you when you come near, and its caught event sends you back to the start.

On surface

An object can stand on a terrain or mesh and stay on it. Reshape the ground with Sculpt, change the terrain's size or heights, or move and turn the terrain, and the object keeps its place on the surface at the same height above it: a tree stays on its hill, and a taller terrain lifts the tree without stretching it. Objects dropped onto a terrain stick to it automatically while View > Stick to Surfaces is ticked, as it is to begin with. The hierarchy marks them [on surface name].

Dragging an object that stands on a surface slides it over the surface, keeping its height above it, so it climbs hills and follows dips; past the edge of a terrain it stops at the edge. Esc puts it back. In Transform, Local for such an object means relative to its point on the surface, and Global is where it is in the world. Its parent still groups it, hides and shows it and is deleted with it, but does not move it.

Deleting the surface leaves the objects that stood on it where they were, in the same undo step. Problems lists objects standing over a hole in a terrain, and objects whose mesh changed so much that they were put on its nearest point. A terrain cannot be parented under an object that stands on it, which would make the object follow itself.

Static meshes take objects only when you tick the box: dropped onto one, an object rests on it without sticking. A model kept with its animation, or a mesh with morph targets, does take dropped objects: they sit on it at Turn with surface 100%, so a hat dropped on a character's head moves and turns with the head when the model is animated. The section is not shown for a running program's world. In a world file, sticking is the entity's anchor component, and in a program it is AnchorEntity.

Levelling the ground

A house, a car park or a tower on a hillside needs level ground. Select the object and, in its On surface section, tick Level the ground under it: the terrain under it becomes a level pad just below its base, cut into the slope above it and built up below, with banks back to the hillside. The terrain keeps its own heights underneath, so moving the object moves its pad and the hillside it leaves comes back as it was; unticking gives the hillside back too. The box is offered while the object is over a terrain. When you drop or move an object at least 2 m across onto ground that rises more than 25 cm across it, the status line says its ground is uneven, and so does the section.

Ticked, the section offers Ground shaping settings. Each change is one undoable edit:

While a levelling object is selected, its footprint is outlined on the ground in yellow and the outer edge of its banks is dashed. An object that stands on the terrain stands on the terrain's own heights, not on its pad, so sculpting under it raises or lowers it with its pad. Sculpting near a pad changes the hillside under it: the pad stays level and its banks follow. While sculpting, pads are hatched, and the status line says when the brush is over one. Problems lists pads higher or lower than their terrain reaches.

A Footprint path levels the ground by its outline: changing a path that lies on the ground to Footprint levels its points at their average height and the ground under it, and its Follow ground shows Shape the ground, with Bank slope and Widest bank. Roads shape the ground with Shape the ground too. In a world file, levelling is the entity's ground-shape component, and in a program it is ShapeTerrain.

A cabin on a hillside

Terrains, objects that stand on them, levelled ground and roads work together. This is the quickest way to a cabin on a wooded hillside with a road past it; the finished scene, with hills that rise and fall, is the Hillside sample.

1. On the Primitives tab, click Terrain. Flat ground appears, selected, and Sculpt starts: drag on it to raise hills, and hold Ctrl to dig valleys.
2. Drag tree models from Assets onto the hills: each sticks to the ground where it lands. To plant a whole wood, give the terrain a Scatter recipe in its tab instead.
3. Drag a Cube from the Primitives tab onto a hillside, or a house model from Assets. It sticks to the ground, and if the ground under it is uneven, the status line says so.
4. In its On surface section, tick Level the ground under it. The hillside is cut and built up into a level pad under it, with banks back to the slope, and scattered trees keep off the pad.
5. Drag a Path onto the hills, choose Ribbon for its shape and set Follow ground to Shape the ground. The road cuts a level shelf across the hillside, climbing no more steeply than Steepest (%). Drag its point handles to lay it out.
6. Sculpt the hills again: the trees and the cabin ride the ground, the cabin's pad stays level and the road's shelf follows the hills. Drag the cabin somewhere else, and the hillside it leaves comes back.
7. Choose Play and the FPS player to walk round it.

Open samples/hillside/hillside.world to see a finished one: its program, Hillside.bb, makes two of the hills rise and fall, and anchors the scattered trees so that they ride them.

Shape

The Shape section sets a shape's real size in world units, so you rarely need its scale. It shows only what the shape has:

Shapes convert in place to the kind that does what you asked, keeping their materials and physics: rounded edges turn a cube into a box that looks the same, a hollow or an opening turns a cylinder into a tube, and a top radius turns a cone into a frustum. Each change is one undoable edit. A value the shape cannot take, such as a wall as thick as the radius, is refused with the reason, and the field returns to the stored value. The fields take Alt and a drag like the Transform fields. A running program's shapes are edited in a standalone world document.

Paths

A Path carries a shape along a smooth line through points. Add one from the palette, then use its Shape along path section:

• Shape chooses what follows the path: Pipe (hollow), Trough (a pipe open at the top, for slides and gutters), Rod and Rail (solid round bars), Ribbon (a flat strip for roads and walkways; a thickness makes a slab), Wall and Kerb (standing on the path), or Footprint, which treats the points as an outline seen from above and raises it into a solid block, such as a room, platform or house. The section then shows that shape's sizes and Smoothness.
• Closed loop joins the last point back to the first. Smooth curve curves through the points; off, they are joined by straight lines. Keep upright keeps the cross-section level, as roads, slides and walls need; off, it turns with the path through loops.
• Follow ground lays the path on a terrain and keeps it there as the terrain is sculpted, resized or moved. Whole path lays its whole length on the ground, so it rises and falls with every hill: roads, tracks, footpaths and walls. A wall stands upright on the ground, and a footprint keeps its top level above the highest ground under it. Points only rests just the points on the ground and spans the dips between them, for pipes and rails on supports. Each point's Y is then its height above the ground. For a ribbon on the whole path, Drape across the ground lets it follow the ground from side to side too, like a carpet; off, it stays level across, as a road does, so on a side slope one edge sinks in and the other lifts. Sink is how far the shape's underside goes into the ground, 0.03 by default, so its edges never float; a flat ribbon floats that far above the ground instead. Shape the ground runs the path on a shelf cut into the hillside instead, level from side to side and climbing no more steeply than Steepest (%), 10 by default, with Bank slope and Widest bank setting the banks beside it: roads and railways over hills.
• Points lists the points, relative to the object. Choose one to edit its position, its Roll, which banks the cross-section there, and Corner, which makes a sharp, mitred corner. Add point adds one after the chosen point, halfway to the next. Remove point removes the chosen one.
• Tick Click in the view to add points, then click surfaces in the view: each click adds a point where it lands, after the chosen point, raised by a pipe's or rod's radius so it rests on the surface. On the ground, the point rests on it. Press Esc or untick it to finish.

While a path is selected, the view shows its points as small handles joined by a line, the chosen one in yellow. Drag a handle across the ground to move that point; type its Y to change its height. Each change is one undoable edit, and a footprint whose outline crosses itself is refused. Moving or scaling the path object moves or stretches its whole layout; its cross-section keeps its size.

With Stick to Surfaces on (the View menu), a path dropped from the palette onto a terrain, or whose points are clicked onto one, lies on that terrain's ground straight away, as Whole path. Moving the path object then slides it over the ground, and resizing the terrain carries it to the same hills, as it carries objects that stand on the terrain. Deleting the terrain leaves the path where it is, no longer following the ground.

Camera

Select a camera and open Camera to edit:

These are the selected scene camera's settings. To inspect their result, choose that camera in a viewport's Camera: list. An independent editor camera has its own view configuration.

Light

Select a light and open Light. Choose its Type:

Changing type retains settings hidden by the new type. Light outlines update with the object: parallel arrows for directional lights, rays for points, and a cone for spots. They stay readable as you zoom and can be clicked to select the light.

Colour is the light's red, green and blue, whole numbers from 0 to 255. Type them, or click Choose... for the colour picker: the scene is lit in each colour as you choose it, OK makes it one undoable edit, and Cancel puts the colour back. A warm white such as 255, 225, 190 suits a lamp, and a cool one such as 200, 220, 255 suits moonlight.

New scene documents have a normal, editable Default Light point light. Scene rendering uses the world's own saved lights and ambient setting. Existing worlds are opened with their existing lighting.

Cast shadows, on for a new light, lets the light cast shadows once the world's Enable shadows is on (see World settings). Shadow priority is a whole number, 0 by default: when more lights could cast shadows than the world's Shadow lights allows, the ones with higher priorities get them first. These are the settings LightShadows changes in a program.

Intensity multiplies the light's colour. Baking chooses how bakes use the light: Mixed (the default) keeps its direct light and shadows realtime and bakes its bounced light, Baked only bakes all of it, and Realtime only leaves it out. Soft shadows softens its baked shadows, Falloff chooses Classic or Physical fading with distance, and Baked shape makes a point or spot light a Panel or a Tube in bakes. See Lights in the bake.

Light cookies

A light can shine through a pattern, as sunlight falls through a window or under trees: this is called a light cookie. The Cookie button on the Primitives tab adds a light ready set with one (see Creating objects), and Add > Light Cookie has the same choices. To give any light a cookie, select it and open Light cookie, below Light:

A spot light's pattern fills its cone, so widen Outer cone in Light to make the pattern bigger, and turn or move the light to move it. A point light can't show a pattern; it keeps one for when you make it a spot or directional light again, and the section says so. A pattern only shows where its light isn't drowned out: where another light already lights the place fully, such as a new world's Default Light close by, the bars and shade are lit anyway. Adding a light cookie, and its Light cookie section, then name that light; lower its Intensity or Radius, or move the pattern somewhere darker. Patterns light the scene as it runs: baked light ignores them, so a light with Baking set to Baked only shows none. Every change is one step that Edit > Undo takes back, including a picture and the asset it adds.

The world file keeps it as the light's cookie, and needs Blitz3D+ with light cookies to load; LoadWorld and LoadWorldAsync show the cookie in your game with no code. In a program, LightCookie, LightCookieSize and LightCookieStrength do the same; see the light cookie guide. A running program's lights take their cookies from its code, so Light cookie is not offered in live mode; saving a live snapshot keeps the cookies its world file gave its lights.

Level of detail

A detailed model costs as much to draw far away as it does up close. The Level of detail section of a model's inspector makes simpler versions of it, and draws them once they would look the same: far away, or small on screen.

• Use simpler versions far away turns them on. A model you add with 2,000 triangles or more has it ticked already; tick it for any other model. The section then lists the versions and their triangles, how far from the camera each one takes over in the main view, and which one is drawn now. Collisions, picking and physics keep using the full model, and baked lighting looks the same on every version.
• Quality chooses how close a version may be used. Balanced lets a version differ from the full model by about a pixel; High keeps full detail further away, and Fast saves more.
• Preview shows one version in the views at any distance, so you can judge it up close. Only the views change, until you select something else.
• More... shows Versions, the most to make (Automatic makes up to four, each with about half the triangles of the one before); Fade between versions, which blends each version into the next rather than switching at once; and Stop drawing beyond, a distance past which the model is not drawn at all (0 draws it at any distance). Their values are kept while they are hidden.

Animated characters get versions too, which move with their skeletons and make the same faces. A model with few triangles gains nothing, so it gets no versions, and the section says so. A model whose shape does not simplify well is drawn at full detail, and Problems lists it. A model that came with hand-made versions in its world file keeps them until you tick the box, which replaces them with versions made for you. In a program, AutoEntityLODs does the same.

A model saved by Prepare Model brings its own levels of detail in its file, and draws them whether the box is ticked or not; the section says how many it has. Change them in Prepare Model, where you can see each one and choose where it takes over.

Interiors

An interior is the inside of a building, a dungeon or a cave, built by a short program with the Maplet module: it carves rooms out of solid rock, fills back pillars, stairs and floors, and checks that the rooms join up. The World Editor runs the program for you and brings in what it builds: the model, interior.glb with its textures in it, with a static collider; a zone for each room the program marks, named after it; its point lights; and a marker where the player starts. They are the interior's children, so they move with it. Interiors are built by the IDE, so open the World Editor from the IDE (or the online IDE) to add them, and save the world first.

• Add > Interior starts a new interior from a small program, a room with an alcove and a lamp, in its own folder beside the world, interiors/room/room.bb, and places it at the focus point.
• The Interior section of an interior's inspector names its program. Edit program opens it in the IDE; change it there, or ask Blip to. Rebuild builds it again and brings in the result: rooms, lights and the start are updated in place, so a zone keeps the look you gave it, and a room the program no longer makes loses its zone. Objects you added inside the interior stay as they are. An interior built before Blitz3D+ wrote .glb models has an interior.b3d; rebuilding it moves it over to interior.glb.
• When the program's checks fail, the interior stays as it was, and the status bar says what failed. The program's own floor plans and views, saved with SavePlan and SaveView, are in the interior's folder.
• Open in Maplet+ (in Blitz3D+ on Windows and the Mac; the online IDE has no Maplet+) opens the interior in Maplet+, a level editor in which you carve and fill shapes by hand. The first time, the World Editor asks before it switches the interior to its Maplet+ project: the project, room.mapletplus, is a copy of the last build's, and from then on a short program, room-maplet.bb, builds the interior from it, loading the project and marking the same rooms. The old program is kept, but no longer builds it. Each time you save in Maplet+, the World Editor builds the interior again by itself. To mark more rooms, add them to the -maplet.bb program and press Rebuild.

An interior's faces point into its space, so it is seen from inside: put it underground, behind a hill or inside a building's outer walls.

Resources an object uses

In a standalone world, the inspector has a section for each resource the selected object uses, and a Sound section for any object:

• Camera effects for a camera: choose effects from the list, or No effects.
• Animation set for an animated model: choose a set, or The model's own clips. The list offers only the sets whose clips the model has. A character placed from a set names that set instead.
• Terrain and Particle effect name the definition a placed terrain or effect uses.
• Sound: choose a spatial sound, or No sound. The sound plays from the object once your program calls ActivateWorldSounds.

Choosing in a list applies at once, and Edit > Undo reverses it. Edit opens the chosen resource in its tab beside Scene. New starts one there: New from clips starts an animation set with the model's clips, and a new sound first asks for a WAV or Ogg file. In a new resource's tab, a button such as Use on the selected camera or Attach to the selected object saves it and applies it to the object; otherwise save it, then choose it in the list.

Managing assets

Adding files

1. Click Import Assets... on the Assets tab below the views, or choose File > Import Assets....
2. Select one or more source files. The editor recognises each file's type from its extension.
3. The new cards are selected, and the inspector shows the last one's preview, Name / ID, Class, Loading and import options.

An image is imported as a texture. To use it as terrain, select its card and set Class to Terrain / heightmap. Importing records the files' locations; it does not copy them into the world file or delete the originals.

Use Place in Scene for models, prefabs, physics definitions, particles, animation sets and terrain definitions. Physics assemblies may need a target mapping. Environment, camera-effect and spatial-sound cards instead apply or attach their settings to the appropriate scene target. Raw textures, sounds, shaders, materials and UI descriptors are resources rather than direct scene placements. See Edit the selected resource for the matching editor.

Missing files

When an asset's file has been moved, renamed or deleted, its card says File missing, and the objects that use it show a placeholder in its place (see Checking the document). The Problems report lists it too. Give the asset its file back in either of these ways:

• Import the file again with Import Assets.... A file with the same name as an asset's missing file, ignoring case, repairs that asset instead of adding a new one, so the objects that use it show it again. Import several files at once to repair several assets.
• Select the asset's card. The inspector shows File missing and the path the world names. Click Locate file... and choose the file, which may have another name. Other assets that named the same missing file use it too.

Either way the asset keeps its name, class and import options. Edit > Undo takes a change of file back. In the online IDE, a project keeps only the files in it: an imported file from outside the project is copied beside the world first, and an asset whose file is outside the project shows File outside the project, because the file will be gone the next time the world opens. Import the file again, or use Locate file..., to keep a copy in the project.

Finding and selecting assets

Below the views, the Assets tab has one row: Import Assets..., Remove, the class filter, search and Clear. In a narrow window the filter narrows, then Clear and Remove make room for the search; Remove stays on each card's right-click menu. In its own window, Assets has a row of actions above the filter and search.

Combine the filter with the search field. Filters include all assets, model formats, individual resource classes, loading policies and Errors. Search is case-insensitive and matches the asset ID, source path/filename, class, policy and extension. Clear clears the search. Changing filters clears the card selection so hidden cards are not accidentally removed.

Click a card to select it; click between cards to clear the selection. Ctrl-click toggles additional cards and Shift-click selects a range. Right-click a card for Place in World, Import Assets..., Remove from World, Undo Remove and Select All Visible.

Use the scrollbar or wheel to browse. With the catalogue focused, arrow keys move between cards, Home/End select the first/last card, and Page Up/Page Down scroll by a page.

Preview controls

The selected asset's preview is at the top of the inspector, or beside the cards when Assets has its own window. For 3D previews, left-drag orbits, right-drag or Shift + left-drag pans, and the wheel zooms. Frame fits the preview object; Reset restores its default camera. Wireframe changes preview rendering without changing saved models.

Textures and materials are displayed on preview fixtures. Heightmaps use a temporary terrain. Shader previews depend on the shader's intended use; a preview failure is reported on the card/details. Prefabs preview the supported prototype contents.

For an animated model, turn on Keep hierarchy and animation in its import options. Choose a clip from Animation and click Play animation. Changing the selected sequence during playback switches clips; Stop animation rewinds to its start. Child-node animations are included. A model without clips displays No animations. Preview animation does not start playback on placed scene instances.

For a sound, click Play / Stop sound. Other resource types show playback as unavailable.

Previews load on demand: the selected asset has priority, then visible cards. Pending/error states appear on the cards. Catalogue preview order is independent of the loading policy saved for the world.

Asset card previews

Asset cards show prefab geometry, collider outlines, a stopped sample of the first second of a particle effect, environment lighting and camera effects. Terrain materials appear on a small terrain surface. Audio cards show saved defaults without playing sound or changing the mix; native UI cards show the control count. Open the resource editor for a full preview, especially for delayed particle effects or prefabs requiring scene inputs. Cards rebuild when their resource revision changes.

Names, import options and loading

Name / ID is the stable alias used to refer to the resource inside this world. Change it and click Rename. IDs must be non-empty and unique. Renaming updates supported references inside the document, but does not rename the source file or rewrite names embedded in your program's code.

Class, Loading and the Import options below them apply as soon as you change them. An asset's class cannot change while scene objects use it.

The texture options set the flags that LoadTexture describes, which the world saves with the texture. Flags without a control here, such as colour (1), are kept as they are. A cubic environment map needs the loader's six-face layout.

Dependencies may need a stronger policy because of their consumers. Materials assigned to scene models are made Required by material assignment. Validation rejects policies incompatible with the way a resource is used.

Statistics and removal

Details include source size, preview state and errors. Models report children, material slots/surfaces, vertices, triangles and animation sequences. Textures report dimensions and aspect ratio. Terrain reports side length and an estimated full-resolution triangle count.

Material slots (surfaces) is a surface count, not a count of unique appearances. Source file size is a disk figure. Engine texture/geometry totals include other renderer resources and the editor's own previews; exact per-collection resident memory and decoded sound duration are not available here.

To remove unused declarations, select their cards and click Remove, choose Edit > Remove Selected Assets, or press Delete with the catalogue focused. Referenced resources and protected live assets cannot be removed. The operation removes declarations only; it leaves source files on disk. In a standalone world a removal is one step of the document's history, so Edit > Undo (it reads Undo Remove Assets) takes it back and Redo repeats it, like any other edit. In a live session, Undo Remove Assets restores only the latest removal batch, until another asset edit replaces that record.

Preparing models

A model straight from a modelling program, a scan or Blip is rarely ready for a game: it may be in pieces, too detailed, too coarse, or at the wrong size, and every copy far away costs as much to draw as one up close. Prepare Model gets it ready once, before the game runs. Select a model in Assets and choose Prepare Model..., or right-click its card. A Prepare tab opens beside Scene, with the prepared model on the left and its settings on the right. The model's own file never changes: saving writes a new .glb beside it, with every level of detail in it, which loads ready to draw.

A detailed model (2,000 triangles or more) starts with three levels of detail suggested, each with about half the triangles of the one before; a simple one starts with none. Nothing else is changed until you ask for it. Keep hierarchy and animation keeps a character's parts, bones and clips; untick it for a model that never moves, which then becomes one mesh.

Preparation steps

Tick a step to use it. The steps run in the order listed, on a copy of the model, and the line below them says how many triangles the result has.

• Join parts into one skin (FuseMesh) joins overlapping closed parts, such as a character built from separate pieces, into one smooth skinned mesh that bends at the joins. Triangles is about how many the result has; Blend is how wide the rounded joins are and Detail the size of the smallest detail kept, both in metres, or blank to choose them from the model's size. Every part must be closed: the status line says so when one is not, and the last good preview stays.
• Smooth (SmoothMesh) rounds a coarse model off. Each of the Times has four times the triangles; Rounded (PN) bulges flat faces out into curves, Standard smooths them. Bones and clips stay as they were.
• Simplify (SimplifyMesh) keeps fewer triangles where the shape barely changes, for a model with more detail than it needs everywhere. Keep is the share to keep. Keep open edges stops holes and borders moving; Remove small parts lets tiny separate pieces go.
• Fit size (FitMesh) scales the model evenly so that its height, width, depth or largest side is the Size in metres, and places it standing on the ground, centred, or where it is. An animated model is scaled as a whole, so its bones and clips stay as they are.

Settings apply when you finish typing or move to another one, and the preview is made again. The toolbar's Undo and Redo step through the tab's own changes. The Source page holds everything as JSON; see Resource source.

Levels of detail for a game

Choose how many Levels the model has, up to eight. Each level is either Simplified, keeping a share of the prepared model's triangles, or From a model file: a simpler version you made yourself, such as rock_lod2.glb exported from a modelling program. Choose file... picks it; its parts go to the model's parts of the same names, and it keeps its own materials. A character's level must have the same skeleton, matched by bone names.

Takes over at is how far from the camera, in metres, the level is drawn instead of the one before, as a full HD screen shows the world. Leave it blank and the level takes over where its loss of detail would look smaller than a pixel; the field's hint shows where that is. Each level must take over further away than the one before. Distances are for the model at its own size: an object placed twice as big switches twice as far away, and a game window half as wide switches nearer. Below each level, the tab says how many triangles it has.

Levels made from the model keep its materials and lightmap coordinates, so baked lighting covers them. A level from another file has its own materials, so a model with one is lit by light probes in a bake, as one with hand-made levels is.

Seeing each level

The list above the preview chooses what it shows. Full detail and each Level show that version at any distance, so you can judge it up close; drag to turn the view and use the mouse wheel to zoom. By distance, as in a game switches the levels as a game would: the slider moves the camera away, and the line below the preview says how far it is and which level is drawn. In this view the preview is as narrow as a full HD screen's would be, so the model looks as big as it would in the game at that distance. Wireframe shows the triangles.

Saving the prepared model

Save (Ctrl+S, or the toolbar's Save) writes the prepared model, with all its levels, as one .glb file beside the original, named after it, such as rock-prepared.glb, and adds it to Assets under the tab's Asset name. Use it for the objects that use the original, ticked at first, moves every object placed with the original model to the prepared one in the same step; Edit > Undo in Scene moves them back. File > Save Resource As... chooses the file instead. Save the world to keep the new asset.

The new asset remembers how it was made. Select it and choose Prepare Model... to carry on from there; saving then replaces its file. In a game, LoadMesh and LoadAnimMesh load the file with its levels ready, and copies share them. In a program, PrepareModel does what the tab does, SaveMesh writes the file, and SimplifyEntityLOD, SetEntityLODMesh and SetEntityLODDistance make and place the levels.

Shared models and pictures

The Shared page

The Shared page, beside Assets below the views, shows the shared asset library: models and pictures that Blitz3D+ members had Blip make, and shared for every member to use, and ones the library's contributors added. Type a few words to search them, choose Models or Pictures, narrow them down (Animated, With a skeleton, Low-poly; Sprites, Textures, Backgrounds) and choose the order, as the module manager orders modules: Popular (downloaded by the most members lately), Top rated, New, or Best match for the words you typed. Each card shows the asset's picture, its name, its rating in stars with the average and how many members rated it, and how many members downloaded it.

Click a card to see the asset in the preview beside the cards: drag to turn it, use the wheel to zoom, and press W (or tick Wireframe) to see its triangles. A character's animations are listed under the preview; Play plays the one chosen. The details give its description, its size in metres, its skeleton and animations, who made it, its rating, how many members downloaded and used it, and the licence: any member may use, change and include it in any program or game, free or paid, without credit, but nobody may sell or give away its files on their own.

Once you have added an asset, to a world or to a program, you can rate it from 1 to 5 stars with the list beside Add to world; choose Remove my rating there to take your rating back. You can't rate what you shared yourself, and an account can rate once it is three days old. Ratings decide Top rated, where an asset with few ratings counts as average until more members have rated it.

Add to world saves the asset beside the world, as models/<name>.glb or pictures/<name>.png (with a number when that file exists), and adds it to the world's assets; a world not saved yet keeps it in the program's folder. Drag a model's card into a view to add it and place it where you let go, or double-click the card to place it at the view's focus point. Either is one change, which Edit > Undo takes back; the saved file stays. Pictures are added as textures, which materials use. Each model stands with its feet at y 0 and faces the camera (-z), and its animations play by name: PlayAnim model,"Walk",0.2.

The library needs your Blitz3D+ account. On Windows and the Mac, Sign in opens the online IDE in your browser, which asks you to allow the World Editor; it then signs in by itself. The online IDE signs its World Editor in for you. Opening an asset counts towards a daily limit on how many different shared assets each member may fetch, so that nobody copies the whole library; looking again at one you opened needs nothing more, as the editor keeps what it fetched. Report... tells the moderators about an asset that breaks the library's rules, or that is broken.

Like Assets, the Shared page can have a window of its own: drag its tab up out of the panel, or click in it and choose View > Open in Separate Window. The window shows the preview above the asset's details, and its toolbar saves the world and undoes what Add to world did; dragging a card from it into a view works as before. To bring it back, click Return Shared here in the panel, choose View > Return to editor in the window, or drag the window's title bar onto the panel's tabs. Closing the window hides it until you click the panel's Shared tab again.

View > Asset library in the IDE opens the same page on its own, for the program you are working on: Add to project saves the asset in the program's folder, and Save... puts it where you choose. HD textures fetches the model with textures 2048 pixels across, rather than 1024.

Adding your own

Members the library trusts as its contributors also see Add to library... beside Sign out. It adds a model (.glb) or a picture (.png or .jpg) of your own. Choose the file, or start from the asset chosen in Assets, which is filled in for you; give it a name, and if you like a description, a category and a few tags to find it by, and for a picture what it is for. While the window is open, the preview shows it as the library will: turn a model to show its best side, as its card shows it as you leave it. Tick the box to share it under the library's licence, which you may do only for what you made or are allowed to share, and click Add to library.

The page sends it, then the library checks it automatically, as it checks what Blip made, before anyone else sees it. The line beside the buttons says how it went: in the library, waiting for a moderator, or not shared, and why. A model is shared just as it is, so it should stand with its feet at y 0 and face the camera (-z), one unit to a metre, with its textures inside the .glb; the library keeps its textures at most 2048 pixels across, and 1024 in the standard file. A server's administrator makes a member a contributor.

Creating and assigning materials

The Material Editor opens as a tab by default, including when editing a scene object's material. Use View > Open in separate window to detach it, or Return to editor to bring it back. It always opens as a tab; a window you pull it out into goes where its window was last. Its right-hand pane starts with the material's name. Material authoring is available in standalone worlds; live debugging does not edit material files.

Open or create a material

Choose File > New Resource > Material... and select a starting point:

For an existing material, select its asset card and click Edit Material.... For a model asset, click Extract materials.... Scene objects have a Materials section listing their bindings, with named parts and editing choices behind Material bindings....

Drop textures or a folder onto the material preview to add maps through the same review page. Drop a single GLB/GLTF to start extraction. Dropping files on the Assets grid offers a choice between creating a material and adding ordinary asset references. File/folder pickers are available for the same operations.

Adjust the appearance

The tab is the same as the other resource tabs: the preview on the left, and on the right the material's name, its Look card and its settings in sections. Drag the divider to change the space each side gets. Click a section heading to open or close it; Tab and Space work too. Sections open and close independently, a closed heading says what the section holds (for example Surface layers - Clear coat 0.8), and the editor remembers which ones you opened for each look. Scroll the pane when the open sections need more room.

Every setting is a direct control and applies as you change it. A slider updates the preview while you drag it and makes one undo step when you let go. Each slider has a field beside it: type a value and press Enter, or move to another control, to apply it. A typed value may go beyond the slider's range. Invalid values keep the last valid material and show a message. Choose... opens the colour picker, and the material follows it as you choose: OK keeps the colour as one undo step, and Cancel puts the old one back. It converts display colours to the material's linear values.

A Standard material has these sections:

A Classic material has Surface (colour, shininess and opacity), Texture maps (its numbered stages), Rendering and Details. A shader look has Shader settings in place of Surface. The toolbar's Undo and Redo affect this material draft; they are separate from world/scene history. Ctrl+S saves. Ctrl+Z/Ctrl+Y act on the draft outside a text field; inside a text field, normal text editing applies.

Choose a look

The Look card shows the material's current look: a sphere drawn with it, its name and what it is for. Click Change look..., the card's sphere, or choose Looks in the preview's view list, to show the gallery in place of the preview.

The gallery shows a sphere for every look, drawn with this material's colour and maps, under the headings Surfaces, Nature and weather, and Effects: Standard (PBR), Classic Blitz3D and the 19 built-in surface shaders, such as Toon, Foliage, Fur, Snow, Water and Glass. Click a sphere or its name to apply that look. The change is one undo step, and the gallery stays open so you can try another. Back to preview, Escape, or Material in the view list, returns to the large preview. Under Other, Shader file... uses a surface .b3shader file of your own; once chosen, it appears there by its file name.

Each look keeps its own settings, saved in the material file: switch back to Standard and its roughness, layers and maps are as you left them. The colour map moves to the new look's colour texture, and the normal map to its normal texture, where the look has one. A look without a colour map leaves it waiting for the next look that has one. The spheres of looks other than the current one are approximations with the shader's default settings; the large preview shows the look exactly. Camera post-processing effects are not material looks.

When you edit a scene object's own copy of a shared material, changing its look gives the object a separate material when saved, as a texture change does.

Shader settings

A built-in look shows its own settings first, under Shader settings: sliders, colour swatches, choice lists and direction fields, with names, ranges and tips from the hints in the shader's .b3shader file. Toon, for example, offers Bands from 1 to 8, Shadow colour, Rim strength and Lighting. Settings in a named group, such as Water's Waves or Fur's Motion, sit under a heading you can close; More settings starts closed. Where the shader multiplies the material's colour, Colour appears at the top. Sliders update the preview as you drag them.

A shader file of your own gets the same controls. Without hints in its file, the names come from its parameter names and each slider runs from 0 to four times the default; Details says so. Add ui lines to the file to give its settings better names and ranges: see Editor hints in the shader guide. The shader's texture inputs are rows in Texture maps, under the names its hints give them.

Layers, glass and shimmer

A Standard material's less common features each have a section with a check box to turn them on. Turning one on picks a value that shows at once; turning it off keeps its other settings, so turning it back on restores them.

Inspect texture maps

The Texture maps section lists the look's maps, one row each with a picture, its role and its file name; an empty row says a map can be added. Standard lists Colour, Roughness, Metalness, Normal and Height, plus any others assigned; Roughness and Metalness have separate rows even when stored in one packed image. Classic lists its stages, Stage 1, Stage 2 and so on, each drawn over the ones before it; a shader look lists its texture settings. Click a row to select it, then use the buttons below the list: Replace... chooses an image for that role (and fills an empty row), Remove removes it (undoably), View shows it in the preview area, and Add maps... adds several at once through the import review. Replacing or removing Roughness keeps Metalness, and vice versa.

An image with see-through parts keeps its transparency; one without is loaded opaque, so its dark parts never turn clear. On a Classic stage above Stage 1, a see-through image is laid over the stages below it: its Blend becomes Alpha, unless the stage already has a blend of its own. Road markings or a decal saved as a PNG with a clear background therefore show over the surface on Stage 1, with the surface showing through the clear parts, without changing any settings. Replacing an image keeps the map's other settings. See Blending Textures.

Repeat across and down set how many times the maps repeat over the surface; press Enter to apply. Linked keeps the two together. Each map's own transform is scaled by the same factor, so maps transformed differently keep their difference; environment maps are excluded. Map settings shows the selected map's own frame, scale, offset, rotation, UV set, blend and flags, applied with Enter. Blend says how a Classic stage is laid over the stages before it, and applies as soon as you choose: Alpha shows the image where it is opaque and the stages below where it is clear, Multiply (the usual) darkens them by the image, Add brightens them, Multiply 2x multiplies and doubles, Dot3 uses the image for bump lighting, and Off leaves the stage out. Flags are the image's texture flags, as LoadTexture takes them. For an imported affine transform, the exact six-number UV matrix is shown instead of the scale/offset/rotation fields. Colour maps use their role's sRGB interpretation; normal, roughness, metalness and other data maps use linear data. Settings cannot create missing UV coordinates on the model.

In the Texture view, use Fit, 100% or other zoom choices; the mouse wheel zooms and dragging pans. RGBA shows transparency against a checkerboard. RGB, R, G, B and A inspect colour or individual data channels without material tone mapping. Dimensions and the file path appear below the image, with Replace..., Remove and Folder, which opens the source directory. Very large displayed images are bounded to keep the editor responsive. A missing or unreadable image reports its file and error; use Replace to relink it.

Create a material from downloaded textures

Cancel leaves the import review without creating a draft. The role dropdown sets how the selected file is used, the channel dropdown selects R/G/B/A data, and Invert selected channel reverses that data before import.

1. Choose New... > From textures....
2. Choose files or a folder. The review lists images, dimensions and proposed roles; selecting a row shows its thumbnail.
3. If there are several sets or resolutions, choose one in the set list. Other sources remain visible as Ignore. You can override individual roles.
4. Check the name. Resolve duplicate roles before creating. Roughness and metalness inputs must have matching dimensions.
5. Choose Create draft, inspect the result, then Save.

Recognised filename tokens include COL/colour/albedo, ROUGH/roughness, MTL/metallic/metalness, NRM/normal, EMISSIVE/emission and AO/occlusion. Packed ORM means R=occlusion, G=roughness and B=metalness. Existing packed metal/roughness images can also be used. When separate and packed maps coexist, the review initially recommends the separate sources; explicitly ignore those sources to use the packed image instead.

A gloss/smoothness image is inverse roughness. Review its channel and inversion. Normal maps default to the OpenGL convention; Flip normal green (DirectX) converts a source that uses the opposite convention. This choice concerns the source image, not the graphics API used by Blitz3D+.

The editor packs separate roughness and metalness images internally. You do not have to make an MR image yourself. It keeps original inputs and their conversion choices in optional authoring metadata, while the runtime uses the generated packed texture. If original authoring inputs are later unavailable, the material still renders and either existing channel can be replaced independently.

For the PBRgen lava set, Colour, Roughness, Metalness, Normal, Emissive and Displacement are usable. Reflection/specular maps are recognised but must be ignored by this import path. Adding the emissive map enables self lighting automatically. The original download and any manually generated MR file stay untouched.

New displacement maps default to a scale of 0.1 world units. Existing strengths, including zero, are preserved. In the Displacement section, set a signed scale in world units, midpoint (default 0.5) and explicit mip level (default 0). The selected source channel and optional inversion become an 8-bit height map. Use the dense sphere or plane preview to inspect relief. The effect moves existing vertices; it cannot add detail to a coarse scene mesh. Save, undo/redo, UV editing and scene application use the normal material workflow. Collision and picking continue to use the original mesh. UV seams or split normals need compatible samples and displacement directions to avoid cracks.

Extract from GLB or GLTF

Cancel leaves the extraction review without creating a material.

Choose From model..., or select a model asset and click Extract materials.... The review lists authored material names. Select one to highlight its parts in the source preview; other parts are dimmed. Read the compatibility messages, then choose Create draft. Extraction creates one material at a time.

Supported factors, alpha, layers, UV sets and exact texture transforms are retained. Embedded, external and data-URI images are copied into the draft; a shared source image is exported once. Unsupported required features block extraction. Optional unsupported features and sampler approximations are reported. The original model is never rewritten.

Save produces a standalone material with owned texture dependencies. The source model is provenance, not a runtime dependency. Some models do not contain every map in the download: the example PBRgen GLB omits emission, so use Add maps... to add its separate emissive PNG afterwards, or start from the texture folder instead.

Preview controls

The view list switches between Material, the shaded preview; Looks, the gallery of looks; and Texture, the selected map. When the preview is narrow, its toolbar continues on a second row.

Choose Sphere, Cube, Plane, or Source model when available. Drag left/right to spin the object and up/down to tilt it; the camera stays facing forwards. Plane is a horizontal tile, initially tilted towards you so its surface is visible. Dragging sideways spins it like a turntable. Tilt stops before the object flips upside down. Use the wheel to zoom in for a close look at the surface. Studio supplies neutral lighting and soft studio surroundings for the surface to reflect; Details uses a grazing light and dimmer surroundings to make normal-map relief easier to inspect. A Standard material reflects the studio only in the preview, and only when it has no environment map of its own. In a world it reflects its own map, a reflection probe round it once the lighting is baked, or a map a program gives it with ApplyEnvironmentMap; without any of them, metals look darker there than in the preview. Compare saved shows the saved baseline with the same geometry and lighting; uncheck it to return to the draft. These choices do not change material files or scene lighting.

Editor 3D views use HDR with ACES tone mapping at zero exposure. To use the same output in a program, call HDRRendering True, ToneMapMode 2 and ToneMapExposure 0 after opening 3D graphics. Your scene still needs appropriate lighting. Another application's environment lighting, displacement and post-processing can produce a different appearance.

Advanced settings

The Rendering section holds the brush effects as check boxes (Ignore lights, Use vertex colours, Flat shading, Ignore fog, Show both sides) and the explicit Blend and Depth policies. Leave Automatic and Default in place unless you need to change them.

Details says where the material is stored, its type and its rendering flags value, and lists any values a shader sets itself. When you edit a scene object's own copy of a shared material, Details also lists the values the object changes: choose one and click Use shared value to return it to the shared material's value. Edit on Source page opens the material's full source for anything the settings do not show. Values the settings do not show are kept when you edit the others.

Assign to a scene object

The material dropdown chooses the resource for Replace with selected. Close returns to the scene; accepted binding changes remain in the world document.

1. Select the object and click Material bindings... in its Materials section. The section lists the current bindings by part, or says the model uses its own materials.
2. Choose Whole model or a named part.
3. Select the material and click Replace with selected. Preparation and validation run automatically; a failed assignment leaves the previous one in place.
4. Save the world to persist the assignment.

Use model's original removes the selected authored binding. Whole-model and individual-part bindings cannot overlap; remove a Whole model binding before assigning individual parts. Imported part assignments carry a revision check. If a model's part mapping changes, review the parts and replace the assignment again.

Edit this object... is the default editing scope. Ordinary appearance changes become instance overrides, leaving other users of the shared material unchanged. A texture or look change creates a separate material when saved. The editor states this before saving. Edit shared material... edits the reusable definition; its usage count covers the current world only. Other worlds may also reference an external file.

For a GLB/GLTF part still using its original imported material, Edit this object starts extraction for that part. Saving creates the resource and assigns it to that part of the chosen object. In Details, Use shared value returns a value the object changes to the shared material's.

Material undo and redo

Undo restores the previous accepted edit in this material draft; Redo reapplies an undone edit. This is separate from scene history. Ctrl+Z/Ctrl+Y use the draft history outside text fields; text fields retain their own editing shortcuts. Save publishes the current draft.

Save and recover

For shared world/resource publication, see Save All and Recovering an interrupted save. Terrain-compatible materials use the terrain material editor.

New materials default to an external .material file. New/imported textures are copied into a uniquely owned subfolder beside it, with relative references in the saved material. Existing embedded materials remain embedded on Save. Its Source page offers Embed in this world and Make a local copy; File > Save Resource As... saves a copy. Embedding stores the definition in the world; images remain separate dependencies.

Save checks the current preview, input files, destination and relevant world bindings before publishing. Editing while a background operation is running prevents its old result from replacing the newer draft. A conflict leaves the draft available; reopen the changed source or save a copy. Closing or switching a dirty material offers Yes to save, No to discard, or Cancel to keep editing. Cancelling the filename picker keeps the draft open.

Saving an external material writes that file immediately. Save the world as well to keep new assets, assignments, embedded definitions and object overrides. Closing or discarding the world does not undo material files already saved. Editor-owned staging folders are journalled; abandoned, unpublished folders can be recovered without deleting source downloads or published images.

The Source page shows the JSON for expert repairs. Validate source updates the draft, and Revert puts back the text; Save writes it.

Creating a physics scene

Physics authoring is available in a standalone Full editor. A live DebugWorld session is for inspection; create and save physics definitions in a standalone .world document. The scene uses the V1 blitz3d.physics definition and a world-owned physics context.

Add physics to an object

Place a model, or create an object with Add. Right-click it and choose Add Physics, or choose Physics > Add Physics, or click Add physics in the inspector's Physics section. The editor fits a collider, attaches it, and shows the Physics section. No separate definition needs to be created or selected.

The Body type choice applies immediately. Before physics is added, it shows the body type the object suggests, which Add Physics uses:

• Movable (Dynamic): falls under gravity and responds to collisions. This is the default for most objects.
• Fixed in place (Static): stays in place, for floors, walls and scenery. Planes, quads, paths, and objects that are very large or wide and flat suggest this.
• Moved by code (Kinematic): follows motion supplied by your program or its behaviours, and pushes other bodies.

A shape from the Primitives tab (every primitive except the endless Plane) gets a collider made from the shape itself. It follows later changes in the Shape section with no refit, and the Physics section names it and any approximation:

• Cubes and boxes get matching boxes, spheres matching spheres and capsules matching capsules.
• Cylinders, cones, frustums, wedges and solid tubes get a convex collider that matches them. A rounded box that moves is slightly simplified.
• A hollow tube that moves is built from wall pieces, so its bore stays open: a ball can roll through it. A moving torus keeps its hole the same way. Fixed tubes, tori and paths use their exact shape.
• A moving path is split into at most 64 pieces that keep its openings open. If it needs more, the scene preview reports that it cannot load; make the path fixed, shorter or simpler.

A stretched shape has its scale applied to its size first, in the same step, since physics bodies need an even scale. Models and shapes with children get a fitted collider: moving ones a convex collider around their geometry, which fills hollows (the inspector states this), and fixed ones their triangles, preserving hollows. Switching a triangle collider to a moving body refits a convex collider. A quad that has never had its size set gets a thin box with its top at the visible surface.

Plane works with Add physics and defaults to Fixed in place (Static). Its collider is a thin box with its top at the plane surface, covering 100,000 × 100,000 local units, centred on the object. Position, rotation and scale apply to this ground area. The visible Plane is infinite, but collision is finite: objects beyond the collider's edges fall through. The Physics section states the coverage; change Size X/Z through Advanced settings > Edit body and collider... if needed. Refit restores the default ground area, including the appearance's scale. Use Quad for a floor with visible edges matching its collider.

A stretched model's appearance is preserved under the body automatically, with its nonuniform scale baked into the collider. Positive scale is required; inherited parent scale must remain uniform.

A fitted collider's points, and a fixed body's triangles too, are kept in a .b3collider file beside the world, named after the object (ToyCar-collider.b3collider, say), which the world's physics names. The fit takes up to 1,048,576 points and as many triangles, as many as physics does, and a model as detailed as ToyCar (320,845 points, 108,936 triangles) fits in under a second. A model past that is refused at once, saying how many it has; use a simplified collision model or a primitive collider through Advanced settings. Until you save, the editor holds the file unsaved: the Scene view, Play Physics and the Physics section, which says how many points and triangles the collider has and in which file, all use it, and the world's title shows *. Save writes the file before the world. A refit makes a new file, and Edit > Undo names the old one again, so files from earlier fits stay beside the world. A moving body's convex collider uses only the points; physics wraps them in a convex shape of at most 44 corners, so a detailed model's collider is a slightly simplified version of its outline. In a buddy session's shared world, a fit's points and triangles reach everyone with the fit itself.

Play physics: a floor and a falling sphere

1. Create a Plane and set Position to 0, 0, 0.
2. Right-click it and choose Add Physics. It is fixed automatically.
3. Create a Sphere, set Position to 0, 4, 0, right-click it and choose Add Physics. It is Movable (Dynamic).
4. Choose Physics > Play Physics. The sphere falls onto the floor in the views. Click Stop physics, which takes the place of Play on the toolbar meanwhile, to restore the authored positions. To see it from the ground instead, play the world with FPS.
5. Save the world normally. Adding physics and changing the body type are undoable with Ctrl+Z. Body type changes affect only the selected object, automatically copying a shared or external definition when necessary.

Advanced settings... in the Physics section contains Refit collider to object, detailed definition editing, joints and reusable definitions; the same commands are in the Physics menu. Gravity is part of World settings; most scenes can use the default 0, -9.81, 0. Refit deliberately replaces the collider geometry; ordinary behaviour changes preserve existing properties whenever the shape supports that behaviour.

The definition opens as a Physics tab beside Scene, on Body and collider. Advanced contains density, triggers, physical materials, motion, damping, body/collider lists and joints. Source contains JSON inspection and repair. Save publishes definition edits; hidden controls retain their existing values.

Connect bodies with scene joints

Select a placed body and choose Physics > Connect with Joint..., or click Add scene joint... under Advanced settings in the Physics section. Choose two body identities, including their owning entity and body ID; nested prefab bodies show their placement path in the picker. Select distance, hinge, ball, slider or fixed. For a hinge between the floor and box, set a world joint point, click Set local anchors from point, and set the axis to 0, 0, 1. Pick surface point... fills the world point from a viewport click and calculates both local anchors; Pick axis... uses a second surface point for a hinge or slider axis. Right-click or Escape cancels a pick without changing the numeric fields. The coloured viewport marks the world point, both actual anchors and the applicable axis. Click Apply joint to cook the whole candidate world before committing one undoable edit. If it reports a missing body, misaligned anchor or invalid axis, correct the fields and apply again.

The scene-joint kind dropdown chooses the constraint type, and the two body dropdowns choose the placed identities. Use limits enables lower/upper travel bounds for hinge and slider joints; Use motor enables their speed and maximum force settings. Cancel closes the dialog without applying its edits.

An internal joint connects bodies inside one .physics definition and is edited with Joints... in the physics definition's tab. A scene joint connects placed body identities and is saved in the .world. Removing a body or target with dependent scene joints prompts for a reviewed, atomic removal. Duplicate or delete the selected scene object using the regular Scene controls; review any reference mapping or dependency message before applying.

To reuse a definition, select its physics asset in Assets and choose Edit Physics.... The editor has body and shape lists, physical materials, initial state, internal joints, geometry and source repair. Its tab marks unsaved changes, and its status line says when its file changed on disk. Diagnostics... shows full validation messages with field paths and available source line numbers; use it when the status text is too short to explain a rejected edit or invalid file. File > Save Resource As... creates an external .physics resource. In Scene, select an existing entity, click Advanced settings... in its Physics section, choose a single-body asset under Use a saved physics definition and click Attach selected definition. Wait for the candidate cook to finish before editing the new body. Use Place assembly... for a multi-body asset: the editor cooks the complete placed scene, then shows the body-to-target mapping for review before Place assembly. Each body must have a distinct valid target. The Asset card's Place in World uses the same placement flow.

Undo edit and Redo edit in the Physics definition window restore accepted draft edits, including body target mappings. Ctrl+Z undoes, and Ctrl+Y or Ctrl+Shift+Z redoes when a non-text control in that window has focus. Text fields retain their normal text editing shortcuts. This history is separate from Scene history. Validate source text before using draft history; unapplied source text stays in its text area. A successful physics definition Save starts a new draft history, while world edits remain in Scene history.

Editing a shared external definition affects its listed consumers. Consumers... shows them before Save. Saving an external .physics file updates that file first and leaves the owning world document with unsaved changes; save the world too before closing it. For just one selected component, Make Local... embeds an independent clone, or Save as New Physics... creates and binds a separate .physics file. Save the world after either rewire. The collider definition owns dimensions and offsets; target transforms must keep positive uniform inherited scale and no shear. A dynamic body cannot be attached, placed or reparented beneath an active animation controller; stop the animation first or use a static or kinematic body. Triangle mesh and terrain colliders require a static body. Geometry... exposes exact numeric size and offset, hull/mesh point triples, mesh triangle indices and a terrain heightmap dependency.

For a placed body in a stopped Scene, open Physics > Edit Body and Collider... > Geometry... > Drag size / offset in viewport. Drag a square grip to change collider size or a round grip to change its offset. Release the mouse to apply the gesture to the draft and rebuild its preview; press Escape or right-click to cancel it. The Geometry fields remain available for exact values. Save the physics definition, then save the world.

Run the saved world in Blitz

The following Extended-mode loop loads the saved world from the program's current directory. Put My Physics Scene.world beside the program, or change the path. It creates a camera for a world that has none. The world owns its physics context, and ordinary UpdateWorld does not advance that context.

Graphics3D 960,640,0,2
Local scene:Int=LoadWorldAsync("My Physics Scene.world")
If scene=0 Then RuntimeError "Cannot start world load"
While WorldReady(scene)=False
    If WorldLoadState(scene)=WORLD_LOAD_FAILED Then RuntimeError WorldLoadError(scene)
    UpdateAsyncLoads 2
Wend
SetWorld scene
Local context:Int=WorldPhysicsContext(scene)
If context=0 Then RuntimeError "World has no physics context"
Local camera:Int=CreateCamera()
PositionEntity camera,5,5,-9
Local lookAt:Int=CreatePivot()
PositionEntity lookAt,0,1,0
PointEntity camera,lookAt
Local timer:Int=CreateTimer(60)
While KeyDown(1)=False
    Local ticks:Int=WaitTimer(timer)
    If ticks>6 Then ticks=6
    For tick:Int=1 To ticks
        StepPhysics context,1.0/60.0,4
    Next
    RenderWorld
    Flip
Wend
FreeWorld scene
EndGraphics
End

Reopen the .world in the editor and check Problems and play it to confirm the saved file loads. b3dworldc can validate it from a command line. A failed cook or stale external source leaves the previous valid preview available; read the Physics editor's status and repair the source or selection before trying Save again.

The shipped editor-created-physics.world was saved by the editor's body and scene-joint controls. Run it with EditorCreatedPhysics.bb from the samples/physics folder for a complete stepped example.

Scene physics settings

Add physics becomes Remove physics once the object has physics; Remove physics removes the attachment, keeping the visible object. Advanced settings... expands the section with the extra controls, and Back to physics returns to the simple view without resetting them. Edit body and collider... opens the attached definition. Refit collider to object replaces the collider geometry with a fit to the current object; use this after changing the shape when you want a fresh fit. Changes require a stopped physics preview. Gravity is edited in World settings.

Body and collider definition controls

Rename applies the definition ID. The Body and Collider lists select which part you are editing. Behavior selects static, dynamic or kinematic motion. Shape selects box, sphere or capsule for the simple editor; Update collider validates and applies the displayed size and shape to the draft. Detailed geometry... opens dimensions, offsets and complex shape data.

In Advanced, Manage bodies... and Manage colliders... open their respective lists. Add box collider adds a collider to the selected body. Motion and damping... edits initial state. Joints... edits constraints within this definition. Trigger only (no collision) makes the selected collider a sensor; it detects contact without physical collision response. Select a physical material in the material dropdown, set density if needed, then click Update properties. Physical materials... edits friction and restitution presets.

Like the other resource tabs, its Definition page has a viewport beside its settings: the definition's name, which applies on Enter, then the Body and collider and Advanced sections; Used by... starts Advanced. Used by... lists consumers affected by a shared definition edit; Close returns to the draft. In Source, Validate source applies valid JSON to the draft, and Diagnostics... opens the full errors and warnings. Closing Diagnostics preserves the draft. The toolbar's Save validates and publishes the draft; File > Save Resource As... writes an external .physics definition. If new body targets need review, Validate and save confirms the displayed mappings after validation, while Cancel returns without publishing. The toolbar's Undo and Redo, and Edit > Undo and Redo, while the tab is showing, traverse accepted draft edits. While one of its dialogs is open the tab waits for it. Closing its window closes the definition and asks about unsaved changes.

Manage bodies

The body dropdown chooses a body in the current definition. Add body creates another body; Duplicate copies the selected body with a new ID. Rename applies the ID field and updates references. Remove removes the selected body subject to dependency checks. Target mappings and any dependent joints must remain valid. Close returns to the definition; accepted list edits remain in its draft until Save.

Manage colliders

The collider dropdown selects a shape on the current body. Add box creates a unit box, Duplicate copies the selected shape with a new ID, and Rename applies the ID field. Remove deletes the selected collider; a body must keep at least one. Close returns to the definition with accepted edits in the draft.

Motion and damping

Edit the selected body's initial position, quaternion rotation, linear and angular velocity, damping and gravity scale. Apply body state validates the values, updates the draft and rebuilds its preview. Cancel leaves these input edits unapplied. Save in the definition's tab to publish accepted changes.

Physical materials

The materials dropdown selects a friction/restitution preset. Add creates one; Duplicate copies the selected preset. Apply changes commits its ID, friction (0–10) and restitution (0–1) to the draft, updating shape references on rename. Remove removes a preset only when its references allow it. Close returns to the definition. Assign a preset to the selected collider with its material dropdown and Update properties.

Detailed collider geometry

The shape dropdown chooses box, sphere, capsule, convex hull, triangle mesh or terrain geometry. The heightmap dropdown chooses the terrain's heightmap dependency. Fields appropriate to the selected shape describe size, offset, points and triangles. Triangle mesh and terrain require a static body. Apply geometry validates the fields and updates the draft; Cancel discards unapplied field edits.

Drag size / offset in viewport... starts direct collider editing for a placed body in a stopped Scene. Drag square grips for size and round grips for offset. Release applies the gesture; Escape or right-click cancels. Save the definition and world to keep accepted changes.

Joints inside a definition

The joint dropdown selects an existing constraint; the kind dropdown selects distance, hinge, ball, slider or fixed. Body A and Body B must select different bodies in this definition. Use limits enables lower/upper travel bounds for a hinge or slider. Use motor enables its target speed and maximum force. Inapplicable controls retain their values when hidden.

Add joint adds the entered constraint; Apply changes updates the selected one. Both validate body choices, anchors, axes and applicable limits. Remove deletes the selected joint. Close returns to the definition; Save publishes accepted draft changes. For constraints between placed objects, use Add scene joint instead.

Attach and place reusable physics

The physics asset dropdown chooses an existing definition. Attach selected definition attaches a compatible single-body definition to the selected object. Place assembly... prepares a multi-body placement and opens a mapping review. Place assembly confirms distinct valid targets after the candidate world cooks successfully; Cancel leaves the scene unchanged. The Assets Place in Scene button uses this flow for physics assets.

Make a physics definition local

Make definition local... prepares an embedded copy for just this component. Save reusable definition... prepares a separate external .physics resource and binds this component to it. Review the affected component, file and references. The dialog's apply button commits the selected operation after validation; Cancel leaves the original binding intact. Save the world after changing the binding.

Prefab controls

Open prefab tools... in the inspector's Prefab section opens a Prefab tab beside Scene for the selected object's prefab placement, or prepares the object and its children as a reusable prefab. Like the resource tabs, it has a viewport beside its Prefab actions and its Inputs and overrides. Apply instance validates the displayed inputs and overrides for this placement. Open shared source opens the shared definition for editing; changes can affect all its instances. Make Local creates an independent instance retaining the effective parts and shared media. Save as New Prefab... writes a separate reusable definition. Controls requiring an existing instance are disabled for ordinary objects. Applying shows the placed or edited instance in Scene; the tab stays open. Close asks before discarding unapplied text. Prefab edits are applied to the scene, so undo them in Scene; inside the text, Ctrl+Z undoes typing.

Place an asset in the world

Place in Scene (or Place in World in the card's right-click menu) uses the selected asset to create a scene placement at the editor focus point. Models, animation sets, terrain definitions and particles can be placed directly. Prefabs may require typed inputs; physics assemblies open a target mapping review. Environment, camera-effect and spatial-sound actions use the scene or selected object as described in their sections.

Edit the selected resource

The selected card’s Edit... button opens the matching resource editor: material, physics, particles, appearance, audio, animation set or terrain. A model instead offers Extract materials..., and Prepare Model... beside it (see Preparing models). Terrain-compatible materials open their dedicated terrain-material preview. These authoring operations require a standalone document. Hover over the Edit button and press F1 to open the relevant workflow; inside the editor, each action has its own help topic.

Material More menu

File > Save Resource As... writes a separate material file. On the Source page, Embed in this world stores the definition in the world document and Make a local copy gives the selected binding an independent material. These actions preserve the material draft until you confirm their operation; save the world when a binding or embedded resource changes.

Material source and repair

Validate source validates the edited JSON and updates the material draft and preview. Invalid source leaves the previous valid draft available and reports the error. Until edited text is validated or reverted, the Material page and Save wait for it. Use the toolbar's Save to persist accepted changes.

Reusable resource workflows

A resource stores settings you can reuse in this world or another one. The editors below work on standalone documents. Stop scene physics before changing scene bindings. While attached to a running program, save a snapshot and reopen it offline to make structural resource changes.

Start from the selected scene object where possible: its inspector names the resources it uses, with Edit and New beside each (see Resources an object uses), and its right-click menu has Sound..., Animation Set..., Terrain..., Particle Effect... and Camera Effects.... File > New Resource starts any kind of resource. File > Open Resource... opens a resource file in the tab for its kind; a file the world already uses opens as that resource. Existing resources can also be imported into Assets and opened with the selected card's Edit... button.

Resource saving

Save applies the visible controls and waits for a valid, prepared preview. Save As... chooses an external resource file. These actions preserve the distinction between a resource definition and its use in the world:

Use File > Save All to publish the world and resource drafts together; see Save All. Material instance overrides and physics binding migrations keep their existing scope controls. Closing a resource's window asks before discarding unsaved work. If the world or source file changed after the resource was opened, reopen the current resource and reconcile the draft instead of repeatedly retrying a stale save.

Resource history

In each resource tab, the toolbar's Undo and Redo, Edit > Undo and Redo, and Ctrl+Z/Ctrl+Y outside a text field also step through that tab's draft while it is showing. Once an edit is committed to the workspace, Scene/Assets Edit > Undo and Redo include shared-resource changes and their world bindings. Undoing a step that changes assets or resource files first closes resource tabs through their normal save/discard flow; undoing a scene edit leaves them open. Undo changes staged documents; it does not rewrite files on disk. Use Save All to publish the resulting state.

Each sculpting stroke is one step in the same history, so Edit > Undo puts the ground back and Redo sculpts it again, in turn with other edits.

Resource source

Every resource tab except the Material Editor keeps the complete resource JSON on a Source page, including dependencies and settings without dedicated controls. Validate source accepts the edited text, and Revert returns it to the current draft. Until edited source is validated or reverted, the settings stay unavailable. Invalid source leaves the last valid preview available and reports the error in the tab's status line.

Keep the resource's format and version intact. Dependency paths are relative to the resource file; an embedded definition uses its containing file's directory. Use the format links in each section for field names and limits. Opening advanced settings does not discard values that the ordinary controls do not expose.

Particle effects

The quickest way to start is the Particles button on the Primitives tab, or Add > Particle Effect: choose one of the ready-made effects and it is placed at the editor focus point, kept in the world, and selected. Use File > New Resource > Particle Effect for a new effect that is not placed yet, or File > Open Resource... for an existing .particles file. In Assets, select a particle card and choose Edit Particles.... To reopen a placed effect's shared definition, select it in Scene and click Edit effect in its Particle effect section, or right-click it and choose Particle Effect....

The effect opens as a Particles tab beside Scene, laid out like the other resource tabs, its settings starting with the effect's name. The toolbar above saves the effect and undoes and redoes its edits. The tab's title shows * until you save. Opening an effect that is already open shows its tab. The Effect page has the live preview on the left and the settings on the right; drag the divider between them to give either more room. The Source page holds the complete JSON; see Resource source.

1. To begin again from a ready-made effect, choose it in Start from.
2. Set the effect length and whether it loops.
3. Choose an emitter and change its values. Each field applies when you press Enter or move to another control, and the preview restarts.
4. Use Pause and Restart to inspect the result.
5. Save the definition, then select its card in Assets and use Place in Scene.
6. Move the new effect to the required scene position, then save the world or use Save All.

An effect with required entity inputs uses the selected scene object for those bindings; select the intended attractor before placing it. Physics-world inputs bind to the scene's physics context. The preview runs in its own world, so preview simulation does not advance scene physics. Working in Scene while the tab is open leaves the effect editable. If the effect itself changes in the world, for example when its save is undone, close the tab and open the effect again.

Ready-made particle effects

Add > Particle Effect, the Primitives tab's Particles button and the effect tab's Start from offer the same ready-made effects:

Each is an ordinary effect: change any of its settings afterwards. Start from replaces the open effect's emitters, length and loop with the chosen effect's, as one edit that Edit > Undo takes back. An effect still named after a ready-made effect takes the new name; a name of your own stays. If any emitter bounces off objects with physics, every new emitter does too. The single-emitter effects start from the same values as ParticlePreset, with larger particles because they are drawn as soft dots rather than squares.

Particle emitters

The emitter dropdown selects which emitter the fields edit. Add creates another emitter; Remove removes the selected one, retaining at least one emitter. Changing the selection applies the current fields first, so correct any reported errors before switching. A value that is not a number leaves the effect unchanged, and the status line says why.

A new emitter starts as soft dots. Bursts, textures, materials, models, attractors and other advanced values are on the Source page. See the particle resource reference.

Particle collisions

Tick Bounce off objects with physics in an emitter's Collisions section to make its particles bounce off scene objects that have physics, such as a floor after Add physics. Save the effect: every placed copy of it is then bound to the scene's physics, and Physics > Play Physics shows the particles hitting those objects. In the tab's own preview, Floor gives them a floor to hit.

Collisions work one way: particles bounce off objects but never push them. Each emitter decides for itself, so sparks can bounce while smoke passes through. Turning collisions off keeps the values typed for them while the tab stays open. Effects placed where no physics is available still play, without collisions. GPU particle emitters cannot collide.

Particle preview

Each change prepares a fresh preview. Pause freezes it; the same button resumes playback. Restart resets the effect's particles and timing. Floor adds a floor just below the effect's base, which particles that bounce off objects with physics hit; it is ticked for you when an effect's particles collide, or when you turn collisions on. Drag to turn the view and use the mouse wheel to zoom. The preview runs only while its tab is showing. In it, attractors sit at the centre and only the floor is there to hit; place the effect in the scene to see it with its real targets. Loading failures retain the last valid preview, with the reason shown in the status text.

The asset card is a stopped sample of the first second. Use the effect's tab for long delays, short bursts and timing changes; a quiet card does not mean the effect has no emitters. The samples/particles example shows a saved effect running in a program.

Scene environments

With nothing selected, the inspector's Environment list chooses the world's environment, or a starter to begin from; Edit opens it and New starts one. World Environment on the empty-space menu opens the world's environment too, or a new one. Open a saved .environment with File > Open Resource..., or select its card and choose Edit Appearance....

The environment opens as an Environment tab beside Scene, laid out like the other resource tabs. The Environment page has the preview on the left and the settings on the right. Each field applies when you press Enter or move to another control, and the preview follows. The Source page holds the complete JSON; see Resource source.

Start from replaces all of the environment's settings with a starter's, keeping a name of its own; Edit > Undo takes it back. Start from a starter close to the look you want, then change it.

Ambient R / G / B sets the ambient colour using whole values from 0 to 255. Every colour here has a Choose... button: the colour picker shows each colour in the preview as you choose it, OK keeps it as one undo step, and Cancel puts the colour back.

Light from a sun or moon adds a light that shines on the whole world from the sky. Its Colour, its Height in degrees above the horizon, and its Direction in degrees, which turns it around the world like an object's yaw (0 shines towards +Z), place it; a painted sky draws its disc, Disc size degrees in radius, where the light comes from. A moon is a dim, bluish sun. Casts shadows lets it cast shadows while the environment's shadows are on. The world's own lights keep shining too.

Cast shadows turns the environment's shadows on; distance, strength, depth bias and normal bias tune their coverage and surface artefacts.

Sky chooses None, Painted from colours or Image. A painted sky needs no file: its Top, Horizon and Ground colours blend into one another, Stars and Clouds add stars and clouds (0 for none, up to 1), and Cloud colour colours the clouds. Image asks for an equirectangular LDR image for both the sky and the reflection map, and Choose... picks another; sky and reflection intensity apply to an image. Use the Source page if the sky and reflection need separate images.

Fade distant things into fog adds fog that starts at Starts at units from the camera and Hides everything at its far distance. A camera with fog of its own keeps it. Fog in the colour of the horizon blends the scene into the sky.

Opening or editing an environment does not change the scene. Use in this world saves it if it has unsaved changes and makes it the world's environment.

Blending environments

A game can fade one environment into another, such as day into night or fine weather into a storm, with FadeWorldEnvironment. To see what such a blend looks like, use Preview a blend with below the Environment list in World settings: choose another of the world's environments, then drag the slider. At the left the views show the world's own environment; at the right, all of the other one. The sky fades from one to the other, the sun turns towards the other's sun or fades into its moon, and the light, fog and shadows move between them. The preview is only for the views: it is not saved, and the world's environment stays as it is.

Time of day

Time of day, in World settings, changes the world's look through the day. Choose:

• Sun moves with the clock: the sun rises, crosses the sky and sets, and the moon follows the same path by night. The environments you place at times of day give the colours, sky, light and fog; the clock gives the sun's direction.
• Fixed looks: each time shows its environment exactly as it was made, sun included, and changes into it over its Fade in hours. This suits a day of distinct moods, such as morning, midday, sunset and night, with no movement in the sky.
• New from starter: Day and night: a ready-made clock that uses the Clear day, Sunset and Moonlit night starters, adding them to the world if it does not have them.

Day lasts sets how many minutes a whole day takes in the game (0 stops the clock), and Starts at the hour the world loads at. With the sun moving, Sunrise and sunset set the hours it rises and sets, Sun rises towards its direction (like an object's yaw: 0 is +Z, 90 is -X), and Noon tilt how far the noon sun leans from overhead. Times can be typed as 6:30 or 6.5.

Times of day lists the environments placed through the day. Choose one to change its hour, environment or Soundscape, Add time to add another three hours later, and Remove to remove it. Between two times, the look blends from one to the other. A time's soundscape is what the listener hears from then, such as crickets at night; The world's soundscape keeps the one in World settings.

Preview the time moves the views' clock without changing the world; Set as start time makes the previewed time the world's start. The clock moves while the world plays, in Physics > Play Physics and in your game, where UpdateWorld moves it and SetWorldTimeOfDay, WorldTimeOfDay and SetWorldTimeSpeed control it.

Zones

A zone is a region of the world with a look and sound of its own: the inside of a cave, a hut or a ship, a stretch of desert, the space under the water. Cameras inside a zone show its environment and camera effects, and the listener inside it hears its soundscape and audio mix. Outside the zone, the world looks and sounds as it did; across the zone's fade, one blends into the other, so walking into a cave dims the daylight gradually and leaving it brings the daylight back.

To add one, click Zone on the Primitives tab or choose Add > Zone. With nothing selected, the zone is a box 10 by 6 by 10 units standing on the focus point, or on the point where you drop the button. With objects selected, such as the walls of a building, it fits round them with a metre to spare. Move, turn and scale it like any other object: a box turns and scales with its object, and a sphere scales with it. Zones are drawn in the views as orange wire shapes, yellow while selected, with their fade as a fainter shape round them. Programs never see the wire shapes.

A zone's inspector has four sections:

• Zone: its Shape (Box, Sphere or Painted region, below), its Size or Radius in world units, its Fade, how far outside the shape its look and sound fade out (0 switches at the edge), and its Priority. Where zones overlap, the zone with the higher priority wins: give a cave inside a forest zone a higher priority than the forest, and inside the cave it looks like the cave. Large zones with long fades make climate regions, such as a desert and a snowfield far apart whose fades meet in the plains between them.
• Zone look: the Environment cameras inside show, from the world's environments or, after them, the starters; choosing New from starter: Underwater, for example, adds a copy of that starter to the world and uses it. Camera effects switch on for a camera at least half inside the zone, such as a blue tint under water; a camera's own effects come back when it leaves. Edit opens the chosen environment or effects in its tab.
• Zone sound: the Audio mix applied while the listener is at least half inside, such as a cave's echo, and the Soundscape heard inside, blended in across the fade, such as dripping water and a cave's own music. The editor's views are not a listener, so you hear them when the program runs; to hear a soundscape now, click Edit and Play in its tab.
• Zone trigger: actions to run when the player, or anything with a tag you choose, comes inside. See Zone triggers.

A zone can also cover a painted region of a terrain: a swamp, a forest or the south shore, wherever its ground is painted, however ragged its edge. While painting regions, choose the region and click Make a zone on the tool options row: the new zone, named after the region, covers it up to 30 m above the ground and is selected, ready for its look, sound and trigger. Or choose Painted region as a zone's Shape: the ground under the box or sphere is painted as a new region, named after the zone, on the terrain's Zones map (made the first time, so that zones never change the regions trees grow in), and the zone covers the same place as before, as high. The Zone section then shows Region (and Terrain when the world has several): choose another region, or New region..., and click Paint to change its ground, then Done on the tool options row to come back. Height is how far above the ground the zone reaches, or below it with a minus sign, as for a cave under a hill. The zone follows the ground as you sculpt it and the region as you repaint it. It is drawn as the region's outline on the ground, with its height's outline above it and its fade's outside it, and has no handles: moving its object changes nothing. Choosing Box or Sphere again fits one round the region's ground; the region stays on the terrain. Deleting the terrain makes its region zones boxes round the ground they covered, and Problems lists a region zone whose terrain or region is gone. Saved worlds with painted region zones need Blitz3D+ with region zones.

The editor's views use zones as a game's camera would: move a view into a zone and it shows the zone's look. To work inside a building while seeing the light outside, untick View > Zone Looks; the editor remembers the choice for this user. Saved worlds with zones need Blitz3D+ with environment blending. In a program, UpdateWorld and RenderWorld run zones with no code; ZoneWeight tells you how far inside a zone any object is, and CameraZoneLooks keeps a camera, such as a map view, on the world's own look. samples/appearance/zones.world has a hut, a desert and a snowfield to walk between.

Zone triggers

A zone can also be a trigger: when the player walks in, a door opens, a sign appears, a sound plays. Select the zone and tick Run actions when tagged objects enter in its Zone trigger section.

Entered by objects tagged says what sets it off: objects with that tag, player to begin with. When nothing in the world has the tag yet, the section says so and offers Use the camera as the player, which tags the world's camera. Physics > Play Physics runs triggers, but the editor's own view is not in the world, so only objects in it with the tag set them off. The World Editor's Play runs them too, and there the camera you walk with takes the world camera's tags, and is the player if nothing else in the world is. Only the zone's shape counts, not its fade, and a hidden zone triggers nothing.

When chooses which of the trigger's lists of actions the section shows: Each one that comes in, run as each tagged object enters; Each one that goes out; The first one comes in, run once as the zone stops being empty; and The last one goes out, as it becomes empty again. Each list's name says how many actions it has. The actions for coming in run at once, and the others at the world's next step, so a zone with both can show a step between them. The list under it shows the chosen list's actions, which run in order. Choose one in the list under it and click Add: Hide an object, Show an object, Enable an object, Disable an object and Remove an object act on the object nearest the zone to begin with, and Play a sound plays the world's first sound definition from the zone. Start a behaviour and Stop a behaviour act on the nearest object with a behaviour, and its move between points if it has one; Behaviour chooses which of the object's behaviours. Starting a move that starts at once makes it wait for the trigger instead, so the trigger is what sets it off: a door opens when the player walks up. Starting a behaviour of your own code makes it wait too. Removing a behaviour removes the actions that start or stop it. Choose an action in Then to change its Object or Sound, or click Remove action. Hiding an object stops it being drawn and taking part, as HideEntity does; disabling it leaves it drawn but stops its collisions, physics and its own zone. The actions also give a switch, door, timer or spawner its commands, such as Open a door or Spawn one, acting on the nearest one to begin with. Only the first time makes the trigger run its actions once, then stop; it goes only with actions for coming in, so for a switch that works once, use a Switch.

An object a trigger acts on cannot be deleted while the trigger names it; remove the action first. In a program, UpdateWorld runs triggers with no code. Each entry and exit also comes to the program as an event: CountWorldEvents counts them, WorldEventName is entered or left, WorldEventEntity is the zone and WorldEventOther the object, for a score, a message or the next level. samples/appearance/triggers.world has a door that opens and a crate to collect.

Walking characters

Characters that walk the world, a guard on patrol, villagers going about their day or an enemy chasing the player, find their way with the engine's navigation commands (FindNavPath and the rest). They walk on a walkable map that the editor and your game work out by themselves from what the player collides with: ground and floors, stairs and slopes they can climb, with holes round walls, furniture and anything too tall to step onto. You do not have to set anything up. The map is built in square tiles, a few at a time, so it keeps up as you edit: move a house and its hole moves a moment later.

View > Walkable Ground tints the map over the scene: blue where characters can walk, yellow on paths they prefer, cyan on water, orange where they would rather not go, and grey on places nothing can reach from the rest, such as a roof. Walk links are drawn as magenta arcs. The views show it by themselves the first time a world says how characters walk, and while a walk link, or a zone that says how characters walk, is selected.

Walking

The Walking section of an object's inspector says how walking characters treat it.

• Characters is Automatic to begin with: the map treats the object as it collides. Below the list, the section says what Automatic chose and why, such as "walk on it (its shape)" for a floor, "walk on it (its collider)" for an object with fixed physics, or "not in the map (it moves)" for something that can move. Walk on it keeps the object in the map even while it moves, as a lift or a raft. Walk round it makes it something characters walk round but never on, such as a market stall, a fence or a table. Ignore it leaves it out, as tall grass or a bead curtain that characters walk through. A setting reaches the object's children too, so a pivot holding a building can be walked round as a whole.
• Ground is what its surfaces are to characters walking on them: Ground, Path, which characters prefer, Rough, Water and Avoid, which they go round when it is not much further, Can't go, which they never cross, and the world's own areas (see World settings, below).
• For a path, Walking characters prefer this path takes the place of Ground. A ribbon, a road or a footpath, has it ticked to begin with.
• Walk round it where it stops is for something that moves and stops, such as a door or a cart: characters walk round it wherever it stands still.

A zone's Zone walking section says what characters make of the ground inside it: Walk as normal, Prefer it, Rough ground, Water, Avoid it, Can't go in, or one of the world's own areas. A zone across a lawn set to Avoid it keeps characters to the paths round it; one over a pit set to Can't go in keeps them out. A painted region zone marks its region's ground wherever it is painted, however its edge winds, and floors and bridges up to the zone's height above it; repainting the region moves the marked ground with it, so a swamp's zone set to Rough ground stays rough as the swamp grows.

Each change is one undoable edit. In a program, EntityNavigation, EntityNavArea and EntityNavObstacle do the same.

World settings > Walking, closed until you open it, has the rest:

• What the map is like now: how many square metres the chosen size of character can walk on, in how many parts that don't join up, and how many tiles are still being worked out. Show walkable ground is the same as View > Walkable Ground.
• Character sizes starts with Person, 0.35 m from its middle to its side and 1.8 m tall, which climbs steps up to 0.45 m and slopes up to 45 degrees. Add size... adds Small (0.25 by 1 m), Large (0.6 by 2.4 m) or a custom size, each with a map of its own, or Flying, like a drone (0.4 by 0.8 m), or Swimming, like a fish (0.25 by 0.5 m); Remove removes the chosen one. The chosen size's Name, Moves, Radius, Height, Step (empty for a quarter of its height) and Slope change it, and the views show its map.
• Moves says whether the chosen size walks, flies or swims. One that flies finds its way through any open air it fits through, round and over buildings and in at windows; one that swims stays inside zones whose Zone walking is Water, so give the sea a zone first. Its radius keeps it that far from anything solid on every side and its height keeps half of it above and below, and it has no step or slope. With Show walkable ground on and the size chosen, the views outline where it can't go, and Test a Route flies or swims it.
• Areas and their costs lists the areas with what a metre of each counts as: Ground 1, Path 0.75, Rough 2, Water 5 and Avoid 10, and Closed, which is never crossed. Choose one to change its Cost, or tick Can't go. New area and Add add an area of the world's own, such as Mud, which objects and zones can then be.
• Advanced... shows Keep the map up to date while the game runs, on to begin with (untick it for a game that calls UpdateNavigation itself), Tile cells, the size of the map's tiles, Map range, and the chosen size's Cell size and Cell height, the detail its map is made at.
• A big world, more than about 1.4 km across, such as one with a Large or Huge terrain, has its map worked out only within Map range of the views (250 m to begin with) and along every route, wherever it goes, rather than all at once, which would take minutes. The section's first line says when a world is big. Test a Route works anywhere and finds the same way as the whole map would, and the walkable area it shows counts only what has been worked out so far. A Map range of 0 works out all of it. Save World still writes the whole map, which takes a while in a big world.

Problems lists a tile that could not be worked out, a walk link whose end is not on walkable ground, and a size of character that no doorway in the world fits. Save World writes the map beside the world, as a .b3nav file named after it, and names it in the world's settings, so the game starts without working it out again: tiles whose objects have changed since are worked out again as it loads.

Walk links and routes

A walk link is how characters go where they cannot walk: up a ladder, across a gap they jump, down a drop, or through a door that takes them somewhere else. Choose Add > Walk Link, then click where it starts and where it ends, each on the ground. It is a pivot named Walk link, with its far end, Walk link end, under it: move either end to change it, or the link to move both. Its Walk link section names its far end, and sets its Kind (Jump, Drop, Ladder, Door, Lift or Teleport, which your game reads with NavLinkKind to play the right animation), Both ways (untick it for a drop), its Cost (how many metres of walking a metre across it counts as, so a slow ladder is only taken when it saves enough) and Open (a closed link, such as a locked door, is never crossed; NavLinkOpen opens it in the game).

View > Test a Route, also on the views' right-click menu, finds a route as your characters would: click where it starts, then where it ends. The route is drawn in yellow with its length beside it. When characters cannot get there, the route stops where they would, a red line shows how far short, and the status bar says why: the start or the end is off the walkable ground, or nothing joins them. Click another start to test again; right-click or Escape stops. Routes use the size chosen in World settings > Walking.

Walking jobs

Give a character a job and it walks by itself while the world plays, finding its way along the walkable map, round walls and anything in its way. Select it, click Add behaviour... in its Behaviours section, and choose one of the four walking jobs. It starts with settings suited to it, and the card says what it does and what it walks as, such as "Walks as Person, with walk and run from robot.animset": its size of character is the one that fits it, and a character from an animation set plays its idle, walk and run clips at the speed it walks.

• Walk to walks to a point a few metres in front of it to begin with. Pick a point in a view, type one, or choose an object to walk to, wherever it is by then. Runs runs, and Then it stops there, comes back, or disappears.
• Patrol walks along the nearest path, or, without one, between two new places either side of it, which you move where it should go. Add a place... adds an object, or a new marker where you click; select a place in the list to move it up or down, select it in the views, or remove it. It goes round again or back the way it came, with a wait at each place (Wait at each).
• Wander walks about within a Radius of where it starts, pausing now and then. Keep to keeps it inside a zone of any shape, or on a painted region of a terrain, chosen from the terrain's regions, as people walk a village's painted streets.
• Follow walks after the player, or a Target you choose, keeping within the distance in Keep within. In Play, the player is you; in the editor's own play, tag the camera player.

Each job starts when the world loads, or waits for a trigger zone to start it. A character does one job at a time: adding another replaces it. While the character is selected, the views draw the way it goes. Play Physics walks them in the editor's views, and puts them back when it stops; Play walks them as your game would, stepping out of your way, and walking into one shoves it aside before it carries on. Deleting a place a patrol uses takes it out of the patrol; deleting the only place a job has takes the job too.

The character's Walking section says what it walks as, and is left out of the walkable map, as it walks. Advanced walking... shows how it walks, all automatic to begin with: the Size it walks as, its Walking speed and Running speed (blank for 1.4 and 4 metres a second, in proportion to its size), how carefully it steps round others (Avoidance), its Weight, by which it pushes and is pushed, Can be pushed, and Plays its animations by itself. A clip's Ground speed in the Animation Set Editor says how fast it moves the character over the ground, so its feet don't slide; Measure works it out from the clip's root motion.

Problems names a character with a job but no walkable ground where it stands, one bigger than every size of character, which would need a map of its own, and a wanderer whose painted region has gone. In a program, WalkEntity, WanderEntity, FollowEntity and the other walking commands do the same.

Crowds

A crowd is many people who walk about an area by themselves: shoppers in a market, a village going about its day, an audience at a stage. Click Crowd on the Primitives tab, or choose Add > Crowd. The new crowd is a box 20 metres across standing on the focus point, as tall as the hills under it, with 20 people: copies of the last character you placed, or of the robot from the animation-sets sample when the world has none yet. They stand in the views at once, and wander when you press Physics > Play Physics or Play. Its box is drawn in violet, and turns and scales with the crowd.

Its Crowd section says where they are, who they are, how many and what they do:

• Area is Box, with its Size, Circle, with its Radius, or Painted region: ground you paint on a terrain, such as a village's streets. Switching a box to a painted region paints the ground it covered as a new region on the terrain's Zones map; Paint then opens Paint regions on it, to paint more or rub some out, and Done comes back to the crowd, its people on the region as painted. Region chooses another region instead, one already painted, so a market zone's sound and its shoppers can cover the same ground. Switching back fits a box round the region. A region crowd is drawn as its region's outline.
• Who lists the characters the people are copies of: animation sets and animated models from the world's assets. Add one from the list below it, choose one to change its Weight (4 against 1 is four people in five), or Remove it. Variety: sizes, colours and steps differ, on to begin with, makes each person a little taller or shorter, in one of four tints, and out of step with the others, so copies don't march together.
• How many is a number of people, or tick Fill to for as many as the area takes at a density: a busy market is about 10 to each 100 square metres.
• They says what they do: Wander in the area, keeping to it; Walk along paths, the paths listed below, both ways and keeping to the right, which suits pavements and corridors; Go between places, the objects or zones listed below (a zone means somewhere inside it), waiting a while at each, which keeps a market busy without filling up; Stand around, facing what Facing names, such as a stage; or Gather at it, round it. Each starts with the nearest path, places or object, and the list's Add... and Remove change them.
• Advanced... holds the rest, which you can usually leave alone: Speeds, the slowest and fastest walk (0 for each character's own); Avoiding, how carefully people step round each other and you, from Walk through each other (cheapest) to Careful; Detail, the distances within which people move and animate in full detail, and beyond which they move every fourth step and stop animating (40 and 120 metres to begin with); Shown, how many people are shown at once, the nearest to the camera, while the rest walk on unseen (0, to begin with, shows everyone: for a city of thousands, a few hundred keeps it quick); a Tag each person carries, for zone triggers and your program (leave it empty unless you need it: zone triggers test every tagged person every step); a painted region's Height above the ground; the Seed, which gives other people in other places; and Same for every player online.

Online, a crowd is a background crowd to begin with: each player's computer runs its own copy, and nothing is sent, so a busy town costs the network nothing. Tick Same for every player online when the people matter to the game, so everyone sees the same ones.

People far from every camera cost little: beyond the detail distances they move only every fourth step, without stepping round others, and their animation stops, though a program that reads a bone still finds it where it would be. So a market of hundreds runs smoothly. The people are owned by the crowd, not its children: they walk anywhere in its area, and deleting the crowd deletes them. Each change in its section is one undoable edit, and deleting a path or place a crowd uses takes it off the crowd's list.

Problems names a crowd whose area has too little walkable ground for its people, one whose painted region has gone, one with no character to copy, and one of more than 200 tagged people that zone triggers test every step. In a program, CreateCrowd, CrowdModel, CrowdActivity, CrowdSize and CrowdEntityLimit do the same, and WalkDetail sets where detail falls for every walker.

Baked lighting

Baking works out, ahead of time, how light travels round the world: light bounced off walls and floors, so a red wall tints the floor beside it; soft shadows; the glow of bright surfaces; and the sky's light coming in through doors and windows. The result is kept in lightmaps for the static scenery and in light probes, placed through the world, for things that move. It costs little to draw, so a game runs as fast with it as without, and indoor scenes look far more real.

Bake the world's lighting

With nothing selected, open Baked lighting in the inspector. Choose a Quality: Preview takes seconds and is for trying ideas, High suits most finished worlds, and Final is the slowest and finest. Then click Bake lighting. On a graphics card with DirectX Raytracing, such as an NVIDIA RTX card, the bake runs on the card and is several times faster; otherwise it uses every core of the CPU. The views keep working while it bakes and fill in as it goes; the bar shows how far it has got, and Cancel stops it, leaving the lighting the world had. A world that has never been saved is saved first, because the bake is kept beside it.

When the bake ends, the editor saves it in a folder beside the world, named after it (courtyard.lighting beside courtyard.world), and names it in the world's settings, as one step that Edit > Undo takes back. Save the world to keep it. LoadWorld and LoadWorldAsync then show the bake in your game, with no code. Copy the folder with the world when you share it.

Clear shows realtime lighting again, as one undoable step; the bake's folder stays, so Undo brings it back. Show changes only the views: Lighting only shows the light on plain white surfaces, Lightmap detail shows each lightmap texel as a checker square, so you can see where the lightmap is coarse, Light probes shows the probes that light moving objects as small crosses in the colour of their light, and Problem texels shows in red the lightmap texels inside other objects, such as a floor running under a wall: they take their neighbours' light, so if light leaks along an edge, make the objects meet rather than overlap. Advanced... holds Bounces, how many times light bounces between surfaces (empty uses the quality's own; 0 bakes only direct light and the sky's), and Texels per unit, how sharp lightmaps are (empty uses the quality's own). Sharper lightmaps take longer to bake and more memory. Sky light is the light the sky gives the bake: The world's, its ambient light or its environment's sky, or A colour of its own, with its colour and Choose.... Sky brightness scales it: 0 leaves an indoor world lit only by its lamps.

The sky lights the bake with the world's ambient light, or its environment's, unless Sky light gives it a colour of its own. Fullbright surfaces and glowing materials light it too, so a pale ceiling panel painted to glow lights a room without a light. Materials with normal maps keep their bumps under baked light: the bake also keeps the direction each spot's light mostly comes from.

Out of date

Moving, reshaping, adding or removing a static object, or changing a baked light, makes the bake out of date: the section says so, and how many objects and lights changed. Until you bake again the views show the old bake on everything that did not change, and the changed objects show realtime lighting. Lights, colours and objects your game changes while it runs do not change the bake.

Objects in the bake

Select a model or terrain to see its Baked lighting section. Automatic decides for you and says what it decided and why:

Automatic bakes static meshes and terrains, and lets probes light anything animated, with a dynamic or kinematic body, with collisions, small, fullbright or with hand-made levels of detail. Anything a player can pick up, push or knock over must be Moving: a baked shadow is part of the texture under it, and would stay behind when the object moves. Lightmap detail scales how sharp the object's lightmap is: 2 is twice as sharp, 0.5 half.

Lights in the bake

A light's Light section has its Intensity, which multiplies its colour, and how it bakes:

• Mixed (the default): its direct light and shadows stay realtime, so they still fall on moving objects, and its bounced light is baked.
• Baked only: all of its light is baked. It costs nothing while the game runs, but it cannot move or change.
• Realtime only: it is left out of bakes.

Soft shadows is how big the light is, which softens its baked shadows: a radius in world units, or for a directional light an angle in degrees (the sun is about 0.27). Falloff is Classic, Blitz3D's range divided by distance, or Physical, which fades as real light does and reaches nothing beyond its range; physical lights need a higher intensity, such as 10 to 40 for a room's light. Baked and realtime light fade the same way, so switching a light between them never changes how bright it is.

Baked shape gives a point or spot light the shape of a real lamp in bakes. Point or bulb is the default. Panel (rectangle) is a flat panel, Size wide along the light's sideways axis and high along its up axis, which shines only from its front, the way the light faces: turn the light to face down (90 degrees about X) for a ceiling panel, or into the room for a window. Tube is a tube Size long along its sideways axis, like a fluorescent tube. The view outlines a selected light's panel or tube, with a short line from a panel's middle the way it shines. Shadows from a shaped light are soft along its length, and a long one lights a long room evenly. Its realtime light still comes from a point, so choose Baked only for a shaped light.

Reflection probes

Shiny materials reflect the room around them once it has a reflection probe: a point from which a bake captures what can be seen, with an upright box round it. Standard materials inside the box, the smoother and more metallic the clearer, reflect what the probe saw, corrected for where they stand in the box, so a polished floor shows the walls beside it in the right place.

Click Reflection on the Primitives tab or choose Add > Reflection Probe. With the walls, floor and ceiling of a room selected (Ctrl+click them), its box fits round them and the probe stands in their middle; otherwise the box is 10 by 4 by 10 units, standing on the focus point. Its Reflection probe section sets the box's size, and Fit to selected objects fits it again round whatever else is selected with it. Then bake the lighting: the probe captures the room as baked, and Bake lighting again after moving it. Probes are drawn in the views as pale blue boxes, bright while selected; the box stays upright and does not turn or scale with the object. Put one probe in each room or hall; where boxes overlap, a surface uses the smallest one that holds it. Not offered in a running program's world.

Big worlds

A world loads everything at the start unless you tell it otherwise. A big world, such as a town or a long road, can instead start with what is near the player and load the rest as the player gets near: it starts sooner, and fits in memory however big it grows. Every object is still there from the start, with its collisions, name and behaviours; only the data behind it, its mesh and textures, comes and goes. Your game's code works the same.

Load distant objects later

With nothing selected, open Loading in the inspector. It says how much the world loads at the start. Tick Load distant objects later, and the world loads distant objects as the player gets near: the section then says about how much the world needs at the start, and in all. When a world needs more than 500 MB at the start, the section suggests it, with a Turn on button. Each change is one undoable edit.

Start near is where the player starts: what is near it loads before the world is ready. Automatic starts at a marker whose name says spawn, or else at the first camera. You can choose any camera or marker, or This view, where the views look from now.

Each object loads where it would cover a few pixels of the screen, so big things load from farther away than small ones; nobody sets a distance for each object. What is far away goes again only when memory runs short. Things that load while in view fade in. When the camera jumps, such as a respawn or a teleporter, it waits a moment for what fills its view, and the rest fades in.

Advanced loading settings

Advanced... shows the rest. They apply while the world loads distant objects later, and are kept while it does not.

• Memory budget: how many megabytes the world's data may use before what is far away goes. Leave it empty for the graphics card's own budget.
• Detail distance: scales how far away everything loads, from 50% (less memory) to 200%. Raise it if things appear close to a fast player.
• Wait after a jump: how long, from 0 to 2 seconds, a camera that jumps waits for what fills its view. Lengthen it if things appear after jumps, shorten it if jumps feel slow.
• Fade in over: how long, from 0 to 1 second, things that load in view take to fade in.
• Show what's loaded: the views show what a game camera where they look from would load: loaded objects as they are, the rest as blue outlines. Move the view to see the distances work. Only the views change.

Always keep loaded

Select an object and click Advanced... in its Object section for Always keep loaded. Its data, and its children's, then stays loaded wherever it is, ready the instant the game wants it, such as a vehicle a cut scene jumps to. Keep it for the few things that need it: it counts against memory all the time.

Models and saving

Models placed from the world's assets are what load later, and the sounds objects play load where they can be heard. Primitives, terrains, particle effects and models the world needs whole, such as those with physics, load at the start. When the world saves, the editor measures each model, so that a world can leave the distant ones unloaded at the start: save the world before trying it. A world that loads distant objects later and needs more than 1.5 GB streams in the editor's views too: they load what they show, and the section says so. Play loads the world as your game does, so it loads distant objects later when the world does. A program can load any world this way with LoadWorldAsync(file$, WORLD_LOAD_STREAMING); see the Async World Loading guide.

Camera effects

Select a camera in Scene: its Camera effects section lists the camera effects in the world. Choose one to use it, or No effects. Edit opens the chosen preset as a Camera effects tab, and New starts a draft there; right-clicking the camera and choosing Camera Effects... opens the same tab. To edit a preset without binding it yet, use File > Open Resource... or Edit Appearance... on its asset card. Environments and camera effects share one tab: opening one closes the other, asking first if it has unsaved changes.

Choose an effect from the list to edit it. Earlier and Later move it within its processing stage, and Remove removes it; a move into another stage is rejected. Effect enabled turns it on or off, and the field below edits its main value: Intensity for bloom, Strength for grayscale and vignette, Exposure for colour adjustment. To add an effect, choose Bloom, Grayscale, Vignette or Colour adjustment under Add an effect and click Add; it goes into its own stage. Effects run on the scene's light first, then for the display, then on the finished picture.

Needs the application's HDR and Tone map declare what the effects need from the application. They do not change its presentation settings. A mismatch is reported in the status line while the preview prepares; configure HDR and tone mapping in the application, or revise the effects. The Source page has the remaining shader parameters and texture bindings.

Appearance preview

The preview is a separate sample scene. Its lighting and effects belong to that preview; the editor's scene and other cameras keep their own settings. Read the status line at the bottom of the tab if preparation fails. Save and Close follow the resource saving rules.

The Scene list above an environment's preview chooses what it is shown on: a Stone circle on open grass, where the sun's shadows and the sky show; a Forest round a clearing, where fog among the trees shows; a Village street; or a Sphere close up. Each starts from a view of its own, which you can turn and zoom; the editor remembers the scene you chose. An environment with a sun or moon lights the scene by itself, as it would light a world with no lights of its own; without one, a lamp lights the scene so you can see it. Camera effects are always shown on the sphere.

Using appearance presets

Use in this world and Use on the selected camera save the preset if it has unsaved changes, then bind an environment to the world or camera effects to the camera selected in Scene. Camera effects need an editable camera: with anything else selected, the status line says to select one. In Assets, the placement action becomes Use in Scene for environments or Use on Camera for effects. Save the world after changing the binding.

To inspect a camera's effect stack in Scene, choose that camera in a viewport's Camera: selector. The free editor camera does not inherit another camera's effects. See appearance resources and samples/appearance for a runnable example.

Audio resources

A .sound definition stores a clip and its playback defaults. A .soundscape is what a place sounds like, made of sound definitions. An .audiomix stores shared mixer settings. Opening, validating or saving any of them stays silent; Play explicitly starts an audition.

Use File > New Resource > Sound..., Soundscape or Audio Mix, or File > Open Resource... for a .sound, .soundscape or .audiomix file. In Assets, select any of them and choose Edit Audio.... Save and Save As use the resource saving rules.

The resource opens as a Sound, Soundscape or Audio mix tab beside Scene, laid out like the other resource tabs. Each field applies when you press Enter or move to another control; checkboxes and lists apply at once. The Source page holds the complete JSON; see Resource source. Sounds, soundscapes and mixes share one tab: opening one closes the other, asking first if it has unsaved changes.

Sound settings

Change... beside the audio file selects a WAV or OGG clip. Loop repeats it. Choose its Playback group: sound effects, music, interface or ambience. Volume and reverb/echo sends range from 0 to 1. Pitch Hz is the playback frequency; 0 plays it as recorded. Pan ranges from -1 at the left to 1 at the right.

Spatial (3D) makes position control the sound's direction, so Pan is unavailable. Reverb send is heard only while a mix's reverb room is active. Filters and further effect settings are on the Source page.

Audio mixes

A mix has master volume, a master limiter, volumes for the four fixed groups, a reverb room, return volume and change-over time in milliseconds. The Source page holds group filters, EQ and echo delay/feedback.

To hear a mix, choose a test clip with Choose... under Listen, select its Test clip group, then use Play. The audition loops the clip with 50% reverb and 25% echo sends so the room and group settings can be heard. The test clip is an audition aid, not a saved part of the mix, and its group does not change the mix.

Soundscapes

A soundscape is what a place sounds like, in three parts, each optional. Music is one track, played on its own; put its sound in the Music group so the audio mix's music volume applies. Beds loop the whole time, such as wind, rain or a machine's hum. One-shots are sets of sounds of which one plays now and then somewhere around the listener, such as birdsong or a distant bell. Each list offers the sound definitions in the world; choosing one makes it part of the soundscape. To add a sound first, use File > New Resource > Sound....

• Music: the Track, its Volume, how many seconds it takes to Fade in and Fade out, and Pick up where it stopped when it comes back. Only one piece of music plays at a time: where soundscapes overlap, the one heard most takes over after two seconds, so stepping back and forth through a doorway does not restart it.
• Beds: Add bed, then choose its Sound and Volume. A bed is louder the more its soundscape is heard.
• One-shots: Add set, then add its Sounds. A sound plays Every so many seconds, a random time between the two numbers, at a Distance from the listener between the two, and at a Volume between the two. Further from the soundscape, they come less often.

Play plays the soundscape as heard from the middle of a zone, and dragging Heard at fades it as if walking out. Use as the world's soundscape saves it and chooses it in World settings; zones choose theirs in their Zone sound section, and times of day in Time of day. In a program, UpdateWorld mixes a world's soundscapes for its listener with no code; FadeWorldSoundscape brings in one the place does not have, such as rain, and WorldSoundscapeEnabled turns them off for a cutscene. samples/audio/resources/soundscapes.world has a meadow with a workshop to walk into.

Audio preview

Play waits for the current draft to be prepared, then starts the audition. Stop ends playback; for a mix audition it also restores the previous mixer settings. Closing the tab ends its audition and restores the mix. Effect tails fade and clear on restoration.

The editor permits one owned audio audition at a time. Read the status line if initialization, clip preparation or mixer restoration fails. An audio card only shows authored defaults; open the resource and use Play to listen.

Attaching sound

Select an editable scene object: its Sound section lists the spatial sounds in the world. Choose one to attach it, or No sound to remove it; Edit > Undo reverses either. Edit opens the attached sound, and New... chooses a WAV or Ogg clip for a new one. In a new sound's tab, keep Spatial (3D) on, then choose Attach to the selected object; it saves the sound first if it has unsaved changes. With nothing selected, the status line says to select an object. Right-clicking the object and choosing Sound... also opens its sound, or starts a new one. Save the world to retain the sound-emitter binding.

Loading a world does not start its emitters. Application code selects the appropriate audio world and explicitly calls ActivateWorldSounds or PlaySoundEmitter. Loading a mix also does not apply it: use InitAudioEffects and ApplyAudioMix explicitly. See audio resources and samples/audio/resources.

Animation sets

An .animset saves clip aliases, playback defaults, event markers and root-motion settings for an animated model. It uses the model's existing named clips; it is not an animation timeline editor.

1. Import an animated model and enable Keep hierarchy and animation in its asset options. Wait for the model preview to load.
2. Select the model in Scene and click New from clips in its Animation set section, or right-click it and choose Animation Set.... The new set starts with the model's named clips.
3. Edit the clip defaults; each field applies when you press Enter or move to another control. Wait for the preview, then choose Play clip.
4. Save the set, or use File > Save Resource As... to create an external .animset.
5. Choose the saved set in the model's Animation set section, or select the set in Assets and choose Place in Scene to create configured characters. Save the world.

The set opens as an Animation set tab beside Scene, laid out like the other resource tabs. The Clips page has the preview on the left and the settings on the right; the Source page holds the complete JSON, see Resource source.

To reopen a set, click Edit in a model's Animation set section, use File > Open Resource..., or choose Edit Animation Set... on its card. Saving a new set does not change the model it was made from; choose it in that model's Animation set section to use it there.

Animation clips

Select a row in the clip list. Name in your program is the alias application code passes to PlayAnimationSet; Model clip must exactly match a named clip in the imported model. Speed is the playback rate. Crossfade (ticks) controls the transition in engine ticks. Plays chooses Looping, Back and forth or Once.

The preview checks the names, clips and defaults against the model whenever they change, and the status line says if one does not match. Switching rows first applies the current values. Use the Source page to add or remove clips; the list edits existing entries.

Animation preview

Play clip starts the selected clip in an independent preview. If the preview is being rebuilt, wait for its ready status and choose Play clip again. Stop reloads the stopped preview. Event names appear in the status line as playback crosses their markers.

Placed characters load stopped. Application code calls PlayAnimationSet to begin playback. Separate instances keep independent playback and event state. See animation sets and samples/animation-sets for a two-character example.

Animation root motion

None leaves root-motion extraction disabled. Extract for your program makes the motion available to application code. Move the character applies it to the character. Bone or node path identifies the source node; use an unambiguous path from the imported model. Include vertical motion and Include turning (yaw) decide which movement components are included; they apply only while root motion is used.

Check the preview's status before saving: missing or ambiguous model nodes cannot supply the requested motion. Test the chosen mode in the program's movement system as well as in the animation preview.

Animation events

The optional Events box holds a JSON list for the selected clip. Each entry names an event, a time and a unit. For example:

[{"name":"step","time":0.5,"unit":"normalized"}]

normalized expresses a fraction of the clip; frames uses a frame position. The events apply when you leave the box; then use Play clip to check the markers. These are event names for application code to consume, not executable scripts.

Terrain resources

A .terrain descriptor combines a heightmap, dimensions, display settings, appearance and optional scatter recipes. Heightmaps remain separate files. The quickest start is the Terrain button on the Primitives tab: it adds flat ground, selects it and starts Sculpt. File > New Resource > Terrain... also starts from flat ground, 256 metres across; to start from an image instead, choose Browse... in its tab, or select a heightmap card in Assets and choose Edit Terrain.... To edit a placed terrain's definition, select it in Scene and click Edit terrain in its Terrain section, or right-click it and choose Terrain.... File > Open Resource... opens an existing descriptor, and File > New Resource > Terrain Material starts a terrain material.

The terrain opens as a Terrain tab beside Scene, and a terrain material as a Terrain material tab, laid out like the other resource tabs. The page has the preview on the left and the settings on the right. Each field applies when you press Enter or move to another control; the JSON boxes apply when you leave them. The Source page holds the complete JSON; see Resource source.

Set the dimensions and appearance, check the preview, then Save, or File > Save Resource As.... Select the resulting terrain-definition card in Assets and choose Place in Scene. Opening the tab alone does not add a landscape to Scene.

Terrain dimensions

Heightmap identifies the source relative to the descriptor; Browse... selects a PNG, TIFF, BMP or .b3height file. The importer requires a supported power-of-two terrain grid. An exported .b3height retains exact height and hole data.

Width / height / depth scales the source grid to the landscape's dimensions. Leave the dimension fields blank to use source units. Detail budget, Smooth detail changes (morph), Shading and Detail near / far control terrain display; 0 / 0 sets the distances automatically. Inspect the preview before saving.

Terrain preview

The terrain tab owns a separate preview, rebuilt whenever the descriptor changes; a terrain material previews appearance on a small hill surface. The preview shows sculpted heights, saved or not. Wait for the current preview before extracting a material.

Sculpting terrain

Select a terrain in Scene and choose Sculpt on the toolbar, or press 4. The tool options row above the views then shows the brushes, from Raise / lower to Holes, and their settings. Drag on the ground to shape it with the brush outlined under the pointer; each drag is one step in Edit > Undo. Every placement of the same terrain changes together, and objects that stand on it rise and fall with its ground. Under a levelled pad, sculpting changes the terrain's own heights: the pad stays level and its banks follow. Esc, Sculpt again, or choosing Move, Rotate or Scale, stops sculpting; Paint changes to painting, and Sculpt goes back to the brush it had. Alt-drag and the middle and right buttons still move the view.

Shift smooths with any tool but Holes. Beside the brushes, Size sets the brush's size (shown across, in metres; [ and ] change it), Strength how fast it works, and Softness how much of it fades towards its edge (the inner circle shows where the fading starts). With Flatten, Flatten to sets the height it levels to, as a percentage of the terrain's height; leave it blank to flatten to where each drag starts. The terrain's Terrain section says when it cannot be sculpted or painted, and why.

Heights stop at the terrain's top and bottom, and the status line says when a stroke reaches one. To make room above, raise Height in the terrain's tab, which stretches the ground already there. A heightmap terrain's edges wrap round: a brush over one edge changes the opposite edge too, which is outlined while it does. A tiled terrain's edges, such as a new one's from the Primitives tab, do not.

Sculpted heights are saved with the world. A terrain added from the Primitives tab keeps them in a folder of tiles beside the world, and Save writes the tiles that changed (Large terrains). A heightmap terrain keeps them in a .b3height file: on the first stroke, a terrain whose heights come from an image moves them to a new .b3height file of its own, named after the image and kept beside the world (or beside the terrain's .terrain file), and the world, or the terrain's .terrain file, names it from then on; the image itself never changes. A terrain with a .b3height file of its own keeps it, and Save replaces it, unless something else has changed the file since. Until you save, the Scene view, the terrain's tab, its scatter and its colliders all show the unsaved heights; the world's title shows *.

Sculpting is not available while physics plays or in a running program's world. In a buddy session's shared world, everyone's strokes reach everyone else as they finish; two people can sculpt different parts of the same terrain at once, and a stroke over ground someone else has just changed is taken back, as other clashing edits are. Edit > Undo there undoes your own strokes only. A step that would change a .terrain or .material file (the first stroke on an image heightmap inside a .terrain file, say) cannot be made in a shared world, which does not share those files, so make it before sharing the world. In a program, SculptTerrain is the same brush, and RefreshPhysicsTerrain updates a Box3D collider after a stroke. The samples/terrain-resources example demonstrates edits, export/reload and collider refresh.

Painting terrain

Select a terrain and choose Paint on the toolbar, or press 5. The Paint list on the tool options row then names the terrain's ground layers, such as grass or rock: choose one, and drag on the ground to paint it with the same brush as sculpting, its Size, Strength and Softness. Each drag is one step in Edit > Undo. Ctrl+click picks the layer under the pointer. Every placement of the same terrain changes together, and Esc stops painting.

A terrain without layers, such as a new one from the Primitives tab, lists grass (adds layers): the first click gives it four ready-made layers, grass, rock, sand and snow, as one step in Edit > Undo, and then you paint them. A terrain whose material has one picture keeps it as its first layer, with rock, sand and snow after it. Save copies the ready-made pictures beside the world (ground_grass.png and so on). A heightmap terrain has up to eight layers, and a tiled terrain up to 256 ground types (Large terrains). After its layers, the Paint list offers Add dirt layer for each of the editor's ready-made pictures the terrain does not use yet, and Add a layer from an image..., which asks for a picture of your own; the new layer is one step in Edit > Undo, and the brush then paints it. To change a layer's picture, open the terrain's material and choose its layer images, as in Terrain materials.

A heightmap terrain's layers are mixed by its blend map, an image whose red, green, blue and alpha say how much of layers 1 to 4 show at each point; a terrain with more than four layers has a second blend map for layers 5 to 8, made when you add the fifth layer, with none of them anywhere yet (splat-2.png, say), and a stroke changes both. Painting is saved in those images, as a PNG with an alpha channel. On the first stroke, a blend map that another terrain also uses, or that is not a PNG with alpha, moves to a new PNG of the terrain's own (splat-painted.png, say), and the material names it from then on; the old image never changes. When the material is a .material file used by several terrains, painting one paints them all, as the status line says. Until you save, the Scene view shows the unsaved painting and the world's title shows *.

Auto paint..., at the end of the tool options row while painting, opens a small window that paints the whole terrain from its shape in one step: Steep slopes steeper than a number of degrees get one layer (rock), High ground above a height another (snow), Low ground below a height another (sand), and the rest the Elsewhere layer (grass). Heights are percentages of the terrain's height, as Flatten to is; a new terrain's ground starts at 25%, so the default 22% paints sand where you dig below it. Blend softens the borders, which wander a little as natural ground does. Choose (none) to leave a row out, then click Paint whole terrain; it is one step in Edit > Undo, and the brush can touch up the result. On a terrain without layers it first adds the ready-made ones. On a tiled terrain, a Region row keeps the rules to one region (Large terrains).

In a shared world, painting is shared as sculpting is. In a program, PaintTerrainLayer is the same brush, and ExportTerrainLayers saves the result.

Painting regions

Regions divide a terrain into named parts, such as woods, fields or kingdoms, which scatter recipes and programs can use: trees only in the woods, say. While painting, choose Regions at the end of the Paint list; the tool options row then offers the Map and Region lists, a name field, Add map or Add region, and the brush's Size. Regions belong to region maps, and the first step is a map: type a name, such as Vegetation, and click Add map. Then type a region's name, such as Oak woods, click Add region, and drag on the ground to paint it. While you paint, the ground shows the map's regions, each in its own colour, instead of its layers.

Each point of a map is in one region at most, so painting a region takes the ground out of the map's others; choose Erase in the Region list to take ground out of all of them. For regions that overlap, such as a kingdom holding several woods, add another map: choose New map... in the Map list, name it and click Add map. A terrain has up to eight maps of up to 255 regions each. Ctrl+click picks the region under the pointer, each drag is one step in Edit > Undo, and in a shared world region painting is shared as other painting is. Make a zone makes the region being painted a zone with a look and sound of its own (see Zones).

A tiled terrain keeps its region maps in its tiles, a pixel a cell however large the terrain is, and Save writes them there; a map that was a picture moves into the tiles the first time you paint it. A heightmap terrain's maps are pictures: Save writes each as a greyscale PNG beside the terrain's heights, named after the terrain and the map (hills-vegetation.png, say). The world or .terrain file keeps the region names and colours. In a program, TerrainRegion says which region a point is in, TerrainRegionName names it, and PaintTerrainRegion is the brush. To keep scatter to regions, see Terrain scatter.

Terrain materials

Use material... assigns an existing terrain-compatible .material. Make reusable material... writes the current embedded appearance to a new file and updates the terrain draft to reference it. Save the terrain descriptor to retain that reference. Mesh-only materials cannot be used as terrain appearance.

Import/select the terrain material in Assets and choose Edit Material... to open it as a Terrain material tab. Choose base image... uses the legacy single-image mode. Choose layer image... sets the chosen Layer 1–8; Choose blend map... supplies RGBA weights for layers 1 to 4, Choose blend map 2... for layers 5 to 8, and Choose normal map... adds the terrain normal map. Add layers in order, starting with Layer 1; choose the blend map before adding Layer 2. Adding Layer 5 to a material without a second blend map makes one beside the material, the first's size and with none of layers 5 to 8 anywhere, for you to paint in the Scene. Blend and normal maps require layer mode.

Apply uses the entered Repeats (UV scale); Tint... changes the selected layer's colour, starting from its current tint; the preview follows the colour picker, and OK applies it. The More settings box and the Source page keep other authored values. Changes to a shared terrain material affect its consumers after the resource is saved and they are reloaded. See terrain resources.

Terrain scatter

The optional Scatter box holds JSON recipes referring to model aliases declared on the Source page. Recipes specify count, seed, scale range, slope limits and whether instances align with the surface. Scatter is deterministic for the same source and seed; generated objects follow the recipe rather than becoming individually authored scene objects.

Below the box, choose a Recipe and where it grows. Grows on keeps it to ground where one painted layer, such as grass, makes up most of the mix. The terrain's region maps each have a list: choose Only in a region to grow only there, or Never in one to keep out of it. The lists of different maps must all hold, so Only in Oak woods with Only in North grows oak woods in the North. In the recipe these are groundLayer (with an optional minimumGroundWeight, a half by default), regions and avoidRegions, which name regions by ID (the name in lower case with hyphens); several regions of one map in regions mean any of them, and the list then says Several.

The preview checks recipes and dependencies whenever they change. The terrain reference describes their fields and limits. After each sculpting stroke, scatter is placed again on the new ground, so a recipe's slope limit may now keep a model off a slope it was on.

Large terrains

The Terrain button on the Primitives tab, and Add > Terrain, offer four sizes: Small, 256 metres across, Medium, 1 km, Large, 4 km, and Huge, 16 km. Click the button and choose one; dragging the button into a view adds the size chosen last. The new terrain is flat, a quarter of the way up its height range so that you can dig as well as raise, centred where you click or drop it, selected, and ready to sculpt. Bigger terrains have more height range: 64 metres for Small, 256 for Medium, 512 for Large and 1,024 for Huge.

These terrains are tiled. Their heights and ground types are kept in a folder of tiles beside the world (terrain-tiles, say), and the editor loads the tiles near the camera in full and draws distant ones from coarser versions, as a game does. The tiles never get in the way: brushes, painting, regions, paths, Edit > Undo and objects that stand on the ground all work across them as on one piece of ground. Save writes only the tiles that changed, and a tile never shaped needs no file. Unlike a heightmap terrain's, a tiled terrain's edges do not wrap round.

The terrain's Terrain section says how big it is and how fine its ground is: "4.1 km across, 1 m a cell". Make bigger adds a tile's width of ground all round, continuing the edges' heights and ground types outwards. The ground already there stays where it was, and so do the objects that stand on it, its paths and its regions. A terrain grows to at most 32 tiles across. Its tiles then move to a new folder (terrain-2-tiles, say), which Save writes, and the old folder stays as it was, so Edit > Undo can take it back. Make bigger also makes a heightmap terrain tiled, as the status line says; Undo takes that back too. A terrain described in a .terrain file is described in the world from then on, since other worlds may use the file, which stays as it was.

Advanced settings..., in the same section, shows two more controls:

• Ground detail chooses how finely the ground can be shaped: half a metre, a metre or two metres a cell. Finer ground uses more memory and disk for the same width. It is chosen before a terrain is first shaped, and the terrains you add afterwards take it too.
• Show tiles maps the tiles of the terrains on show in the corner of the view: bright where a tile is loaded in full, dim where it is drawn from its coarse versions. It helps when checking what a game will load as the camera moves.

A tiled terrain's ground layers are ground types. A terrain has up to 256, each with a name, such as Desert sand. Paint's first click gives a terrain without any grass, rock, sand and snow, as on a heightmap terrain. After them, the Paint list offers Add dirt for each ready-made picture the terrain does not use yet, and Add a ground type from an image...; a new type is named after its picture. Up to eight ground types can meet in one place, a block of the terrain 256 cells across. Painting a ninth there replaces the weakest of them, and the status line says which were there. In the terrain's tab, the Material part lists the Ground types by name, and Add type... adds one from a picture.

Auto paint... on a tiled terrain has one more row: Region keeps its rules to one region of the terrain's region maps, so that the desert can have sand on gentle slopes and rock above while the mountains have snow high up. Painting one region reads only the part of the terrain it covers. A terrain more than 64 tiles in all, such as a Huge one, is too big to paint whole in one step: choose a region, and paint each area in turn.

To make a large terrain from a heightmap, choose File > New Resource > Terrain..., then Browse... in its tab. An image more than 4096 pixels across, or not a square power of two, becomes a tiled terrain of the size that holds it, up to 32 tiles of 1024 cells across, and Save writes the tiles beside the terrain.

The Problems report lists what a tiled terrain said about its tiles as it loaded them: a tile file gone missing, whose ground shows flat, or edges between two tiles that did not match and were repaired. In a buddy session, tiled terrains are sculpted and painted together as heightmap terrains are.

In a program, LoadTiledTerrain loads a folder of tiles, GrowTerrain is Make bigger, TerrainTileLoaded says which tiles are loaded in full, and PaintTerrainLayerRule takes a region.

Native UI resources

Assets recognizes .ui descriptors and shows their control count. The World Editor does not provide a visual form designer or instantiate application windows from these cards. Author the descriptor against the native UI reference, or start from samples/native-ui.

In Extended Windows application code, LoadNativeUI constructs a hidden hierarchy. Look up controls by their stable IDs with FindNativeGadget, then call ShowNativeUI when ready. Use ordinary gadget events and NativeGadgetID to handle actions; NativeCanvasRole identifies application-owned canvas roles. FreeNativeUI releases the hierarchy. UI files and image dependencies can be explicit roots in a project export plan.

Problems and playing

Checking the document

The editor checks the whole standalone world as you work. The Problems button on the toolbar shows the number of errors and warnings, or No problems; click it, or choose View > Problems, to open the full report on the Problems tab below the views. The summary reports valid status, errors and warnings. Each diagnostic includes a severity, code, document path and explanation. A path such as $.entities[2]... identifies the relevant part of the world data.

A missing asset file is reported with the asset's name and what to do: import the file again, or select the asset and click Locate file... (see Missing files).

The report and the toolbar count refresh shortly after each change to the document. Click Refresh in Problems to check again at once, especially after changing a source file outside the editor. Read warnings as well as errors: they can explain missing or unsupported content. After the world's own, the report lists what tiled terrains said about their tiles as they loaded them.

Validation checks the authored document and references. Successful validation alone does not prove that every texture can decode, a shader can prepare, or all runtime resources fit in memory. Use previews, and play the world, for those checks.

When a model, picture, heightmap or sound file that the world uses is missing or cannot be read, the editor still shows everything else. Each object whose model could not be loaded shows as a magenta checkered box, 1 unit wide and 1 high, standing where the model would; its heading in the inspector says why, for example shown as a placeholder: blip.glb is missing. The asset's card says File missing, or Preview error for a file that cannot be read, and names the file, the status bar counts the assets that could not be loaded, and Problems lists each one. The box is only the editor's stand-in: the world still names the file, and a game that loads it stops with an error naming the file. You can go on working meanwhile: edits, Undo and Save work as usual, and Save keeps the file's path, so the asset comes back with its file. Play waits until every file is there, naming the first that is missing. Import the file again, or select the asset and click Locate file... (see Missing files); or put the file back where the asset expects it, then open the world again.

A material, physics asset, terrain, particle effect or sound can lose a file of its own too, such as a material's picture or a physics asset's collider data. Its tab still opens and works: the preview shows a placeholder for the file (a magenta checker for a picture, a box for collider data), the status line names it, and your changes and Save keep its path, so it shows again once the file is back. Problems lists the file. Choosing a file that is not there, such as a misspelt name in the Source page, is refused.

Playing the world

Play on the toolbar runs a program on the world you are editing, so you can see it the way your game will. The button beside Play names the program; click it to choose another. F5 and Play > Play do the same as the button, and the Play menu lists the same choices.

1. Click the button beside Play and choose a program, or keep the one it shows.
2. Click Play. The editor saves the world first; a world that has never been saved asks where to save it.
3. The IDE compiles and runs the program in its own window, with the world's path as its command line, as Run does: compile errors, the console and the debugger work as usual. The editor stays open, so you can change the world and play again; a new play ends the one before.

FPS, Fly, Orbit, Fixed and Player run the world's physics (while linked to the editor, only when asked: see below), particles and sounds, show its sky and camera effects, and say their keys in the corner (H hides them). Escape ends them, and R goes back to the start. They are ordinary Blitz3D+ programs in Extended mode, in samples/world-editor/play: open one in the IDE to see how it loads the world, or copy one as the start of your own game. Your own program gets the world's path from CommandLine$(), and can load it with LoadWorldAsync.

Play runs programs when the IDE opens the World Editor, with World Editor on the IDE's toolbar or Edit in World Editor on a world in its file list. In the online IDE the program takes the editor's place while it runs; End, or the program's own way out, brings the editor back on the same world. An editor started some other way offers only the physics preview. In live mode the running program is already playing its world, so Play is not offered.

Changing the world while you play

In the desktop IDE, the program Play runs stays linked to the editor. Every change you make in the editor, or that Blip makes, shows in the running program at once: moves straight away, other changes a moment later. You can keep the editor on one screen and the game on another. While they are linked, the program holds the world still, so that what you see is what you are editing: the world's physics waits until you ask Blip to run it (see below), and the next change puts everything back where it is placed. The editor's views show where you are in the game, with a marker labelled Playing, and what you select in the game (right-click) is selected in the editor too.

Talking to Blip while you play

Blip, the IDE's helper, can change the world for you while you walk about in it. Hold T (or a gamepad's left bumper), say what you want, and let go, looking at what you mean: "put a lamp there", "make that tree twice as big", "a ring of pillars round this", "take me to the fountain", "let the crates fall". He works out "that" and "there" from what you pointed at as you said them: the middle of the view in FPS and Fly, the mouse pointer in Orbit and Fixed. He outlines what he understood, flies over to it as he makes the change through the editor, and comes back to say what he did, aloud and in a caption under him. He is the same size as in the editor's views, bigger or smaller with the effort level you choose in his window. Backspace (or B) undoes his last change, and when he asks before removing several objects, Y or N answer him.

Blip's window opens the first time you hold T, or with the IDE's View > Blip helper; sign in there (through the Modules tab) to talk to him. You can also type to him in his window. Talking to him needs a microphone, and the site's speech service; what you say is sent to the IDE's server and on to ElevenLabs to be heard, and his words go to Anthropic's Claude, as typed requests do.

Playing in VR

With a PC VR headset connected (Windows only), choose In VR on the Play menu, below the programs, and press Play: the program runs in the headset as well as in its window. Every player works in VR: the head looks, and turning is in steps, which is more comfortable.

With controllers, the right controller's ray points (your gaze does without them), the right trigger selects, the left trigger is the talk button, B undoes Blip's last change, A and B answer his questions, and the grip picks an object up to move it: let go to put it down, which is one change in the editor. If the headset is not ready, the program says why and carries on in its window.

Playing together online

The Online section of the World settings makes a world one that people play together: up to 100 in a room, each playing a copy of the player object, with bots filling the empty places, so the room never feels empty. Most worlds are played alone, so the section stays closed until you open it.

1. Add the object the players will be, such as a sphere from the Add palette.
2. Click empty space to see the World settings, open Online, and tick Let people play this world together online. The editor picks the player object (one that already moves like a marble or a walker, else a sphere, else the first model), gives it a Marble or Walker behaviour, and, when nothing in the world has fixed physics for the players to stand on, adds a large floor under it. All of it is one edit, which Edit > Undo takes back.
3. Choose Play online test, there or on the Play menu, to try it.

Play online test saves the world, and the IDE runs it on your own computer twice: as a server room, with no window, which fills itself with the bots, and, once its room is open, as a player who joins it, in its own window as Play runs programs (in the online IDE, the server runs in a part of the page no one sees, and you play in the program pane). It plays with the Player program, or with your own program when Your Program is chosen. The two meet through Blitz3D+'s Shared World service, so the computer needs the internet; nothing is spent, and no account is needed. It plays the world as saved, without the link to the editor, and the server stops when the player's window closes. The IDE's console shows what the server prints, after Server:. To try it with other bots or a slow connection, or with up to four players on your computer in the desktop IDEs, ask Blip to run the online test. For your own program, the IDE's Program > Run online test... offers the same (Try it on your own computer). The online IDE runs one player, and the World Editor opens again when it ends.

The settings are kept in the world file as settings.online, and switching Online off keeps them for next time. In your own program, the commands that do the same are StartSharedWorld, SharedRoomPlayers, SharedRoomBots and SetSharedPlayerEntity: samples/marble-arena is a whole game made that way, with a scoreboard, and its world plays with no code too.

Switches, doors, timers and spawners play online too, the server alone running them: see Switches, doors, timers and spawners.

Your own game, linked

Your own program can be linked as the players are, so that you can build its world while playing the real game, and ask Blip to change both the world and the code: "make the enemies faster" changes the program, which then restarts where you were standing. Include samples/world-editor/play/play_link.bb (copy it beside your program, or Include it by its path), and:

1. Call PlayLinkPrepare(name$) before Graphics3D.
2. Load the world with PlayLinkLoadWorld(path$) instead of LoadWorldAsync.
3. Call PlayLinkUpdate() once a frame before RenderWorld, and PlayLinkDraw() after it, before Flip.
4. Write three functions of your own: PlayLinkCamera(), the camera you look through; PlayLinkWorldChanged(world), which finds your entities again after the world is rebuilt from a change, and makes your camera and other entities again in it; and PlayLinkMoveUser(x#,y#,z#,yaw#), which puts the player standing there.
5. Hold your gameplay still while PlayLinkEditing() is True.

Name what your program makes with NameEntity, and make it pickable, so that Blip knows what you point at. Run any other way, the program loads its world from the file as usual. samples/world-editor/crate-chase/CrateChase.bb is a complete game that does all of this: open crate_chase.world, choose CrateChase.bb with Choose Program File..., and press Play.

In live mode, the panel below the views has only Primitives and Assets, where Refresh live assets rereads the program's resources. The Problems check and Play are unavailable while attached.

Saving and managing files

World files

File > Save World writes the current document. File > Save World As... chooses another destination and adopts it after a successful save. A .world file contains scene declarations, asset references, saved settings, and any embedded resource definitions. Scene and Assets changes are saved together.

Saving validates the document and publishes the file atomically, so a failed save does not replace the destination with a half-written file. New, Open and Exit prompt about unsaved world changes. There is no automatic disk save after each inspector change.

Save As adjusts relative asset paths for the new world's location. It does not copy the external model, texture, sound or shader files into the destination folder. Keep dependencies in a deliberate project structure, for example:

MyGame/
  scenes/
    courtyard.world
  models/
    arch.glb
  materials/
    stone.material
  textures/
    stone.png
  layouts/
    modelling.views.json

Paths in a .world are relative to that file. Paths inside an external .material or .prefab are relative to that resource file. Embedded resources use the containing file's directory. To move a project, copy the world and its dependencies together while retaining their relative layout, then reopen and test it.

Embedding stores a resource description; raw models, images and audio remain separate files. Use the workflows below to save related changes together, change resource locations and export their dependencies.

Save All

Choose File > Save All to save the world and drafts from every open resource editor as one validated set. This includes new/embedded definitions, named shared files, material instance overrides and physics binding migrations. Validate or revert any edited Source page first. Sculpted terrain heights are written to their .b3height files first, and fitted colliders to their .b3collider files, as Save does. Named resources keep their current paths; use File > Save Resource As... in their tabs to choose another file.

Save All waits for prepared previews, physics cooking and required portable material texture copies. It asks for the world's filename on its first save and finds a common project folder containing the changed documents. Conflicting edits to the same value, stale files or invalid dependencies stop the operation and retain the drafts for correction; the status line of the tab you are using says why. While another save is in progress, Save All is unavailable, and choosing it says what it is waiting for. Saving does not start audio, animation or scene physics.

Publication uses a recovery journal. If a write fails after publication has begun, follow the recovery message instead of assuming every file was saved. Ordinary File > Save remains scoped to the world. Save All before moving a world with Save As when it depends on staged resource files or identities.

Project dependencies

Open File > Project Dependencies.... It opens as a Project dependencies tab beside Scene. Select a document on the left and one of its direct dependencies on the right. The details identify paths, staged changes and the documents that use it. Go to dependency selects that resource's descriptor in the document list; it is available for descriptor dependencies, not raw media. Refresh rereads the current workspace report.

This tab shows the open world's dependency closure. Consumers outside that closure are not automatically discovered or rewritten. Reference operations may ask you to save/discard open resource drafts before proceeding. They stage changes; Save All publishes them. Edit > Undo and Redo, in this tab or in Scene, reverse the staged operation. The tab's status line explains anything that stops an operation, such as physics running or a world that has never been saved.

Embedding and extracting resources

Select a descriptor dependency in Project Dependencies and choose Embed to store its definition inside the owning document. Raw textures, models and audio remain external. Embedding validates identity and sharing constraints; multiple aliases of the same external resource may need consolidation or a local copy first.

Extract... moves an embedded definition into a new external descriptor and rewrites its owner's reference. Save the world once before choosing the destination. Use a new filename, review the staged result, then Save All. These operations preserve known dependency paths and do not delete source files. Unknown extension payloads can block relocation when their paths cannot be rewritten safely.

Moving resource references

Choose an external descriptor dependency and Move references... to stage a copy at a new path, rebase its dependencies and update known consumers. The original file is retained. Save the world once first, choose an unused destination, review the affected documents, then Save All.

Use this operation when changing a resource's project location. Renaming it with a file manager bypasses these reference updates. A revision conflict leaves the workspace unchanged; refresh/reopen and resolve the changed source before retrying.

Recovering an interrupted save

If Save All reports an interrupted publication, keep the project's .b3d-save-journal folder and any referenced copied media. Choose File > Recover Interrupted Save..., then the project folder. The editor restores the original document set after verifying its backups and destinations. Reopen affected documents afterwards.

Recovery refuses to overwrite unrelated external changes. The command-line tool also supports finishing a saved transaction; see Saving and exporting resource projects for b3dworldc --recover and recovery limits.

Exporting a resource project

1. Use Save All so disk files contain the intended world and resource changes.
2. Choose File > Export Project... and select an export-plan JSON file.
3. Choose the parent folder for the export. The editor creates a new World Export-... subfolder and names it in the status bar.
4. Run the exported project from its new location, using matching application binaries.

The plan lists explicit roots, including resources loaded only by application code. Export follows declared dependencies and copies them with rebased paths; it does not infer arbitrary filenames from program text or build the game's executable. The courtyard, animation-set, terrain and native-UI samples include plans. See the export plan reference for the exact format. Distribution currently uses loose files; there is no single-file resource container.

Editor state versus scene data

Using the world in a game

Load the result with LoadWorldAsync, wait until WorldReady, handle failure, and select the ready world with SetWorld. Select its audio world as appropriate. Stable IDs let code find saved entities and resources.

An editor view is not a saved game camera. If the world is to render directly in your game, add and position a Camera, or create a camera from code after loading. Use the viewport Camera: selector to check a saved camera's view.

See the asynchronous world loading guide for complete loading loops, world switching and manual/streaming resource use. The editor does not write this game code for you, but the programs Play runs are short examples of it: samples\world-editor\play\FPS.bb and its neighbours load the saved world with LoadWorldAsync.

Editing a running program

Starting a live session

Open samples\world-editor\01_Live_Debug_World.bb in the IDE and run it with debugging enabled. Its DebugWorld GetWorld(),False call opens the editor while the sample keeps running. Click Pause on the toolbar to edit, and Continue to resume.

In your own Extended debug program, call:

DebugWorld GetWorld(),True

True opens the editor and pauses; False opens it for observation. A normal debugger break or a later DebugWorld call can pause the attached program again. Closing the editor detaches it and does not terminate the program.

On Windows, to open the editor without changing your code, click World Editor, the globe on the debugger toolbar, while the program runs or is stopped. It acts like DebugWorld on the current world: the program pauses at its current statement, and the editor opens or comes to the front. The button is available once the program has opened 3D graphics with Graphics3D, in either language mode.

On Windows, the IDE's Program > Choose DebugWorld editor... selects a custom compatible editor executable. Program > Use bundled DebugWorld editor restores the shipped editor. Ordinary use needs no custom configuration or session file handling.

Inspecting and changing the live world

Live mode shows actual program objects, rather than a separately loaded scene preview. You can inspect the hierarchy, select and frame objects, arrange split views and follow scene cameras while observing. Keyboard navigation works only while a viewport has focus.

Objects your program never named with NameEntity are listed by kind, such as Camera, Light, Model or Pivot, and the inspector heading calls them unnamed. The label is only how the editor shows them: their names stay empty in the program and in saved snapshots until you type one in Name. Searching for a kind, or for unnamed, finds them.

Pause before mutating objects. When paused, supported operations include:

• Name, enabled/visible state, local/global transforms, and the exposed camera/light settings.
• Multiple selection, transform dragging, axis constraints, precision, step snapping and face snapping.
• Creating pivots, cameras, lights and primitives, and placing model assets.
• Shift-drag or Ctrl+D to copy native subtrees, including procedural geometry supported by the host.
• Undo and redo of supported edits.
• Delete and reparent for editor-created objects.

Program-owned objects can be inspected and transformed, but cannot be deleted or reparented by this editor. Copies are editor-owned. Deleting a selection is rejected if it includes program-owned objects or descendants. New objects can be parented beneath an existing editable program object.

On Continue, the program resumes using the edited runtime objects. Its code may immediately overwrite values you changed. An unfinished drag is cancelled if you continue or lose capture/focus. Live edits do not rewrite your .bb source or automatically update the .world originally loaded by the program.

The live hierarchy arrives a few thousand rows at a time and shows every entity, however many the program has. Search operates on the loaded hierarchy. A running program's selection holds up to 32,768 objects; Select All in a larger hierarchy selects that many and says so in the status bar. Controls also depend on the operations supported by the attached debug host; use matching current editor/runtime builds.

Live assets

Assets lists supported resources with known source declarations. Procedural geometry without a source file may be an entity in the scene without being a reusable card in Assets.

Existing live resource declarations are protected: they cannot be renamed, edited or removed. While paused, Import Assets... creates editable session declarations. Double-click a model card to place it at the focus point. Once used for placement, its declaration becomes part of the protected live catalogue. Refresh live assets rereads supported resources from the host.

Material authoring remains disabled while attached. For material work, save a snapshot and open it in a standalone editor.

Saving a live snapshot

Pause, choose File > Save or Save As..., then choose the scene scope:

Click Choose file..., choose the .world destination, and read the result message. Both scopes include required supported source assets and new asset declarations. Saving leaves the live world in place and does not restart or rebind the program.

A snapshot is a saved scene description, not a complete saved game. Runtime-only animation, particle, physics and audio state can be omitted. Unsupported parents with saveable descendants are represented as pivots so hierarchy and local transforms survive. Unsupported leaves and unavailable content can be omitted with a warning. Review the reported omissions, then open and test the snapshot standalone.

New objects only produces an additions layer. Loading a .world creates a separate world; it does not merge into your active game automatically. To merge an additions layer, load it, copy its root entities into the target world, and then release the temporary world. The sample README includes a complete LoadWorldLayer helper for this operation.

Keyboard and mouse reference

Scene shortcuts act when the viewport or hierarchy has focus. Camera movement requires viewport focus. Click back into the view after editing text. Asset preview gestures differ from Scene gestures. The tables name Windows keys; Keys on a Mac gives the keys to press on a Mac.

Keys on a Mac

On a Mac, the editor takes the keys Mac programs use, and its menus show them:

Scene selection and editing

Camera navigation

In orthographic views, orbit gestures pan. When following a scene camera, editor camera navigation is disabled.

Assets

Use the File menu or toolbar to save. In a standalone world, Scene and Assets share the document's undo history. In a live session, scene edits have the session's history and Undo Remove Assets its own one-step record.

Troubleshooting

Current scope and further reading

This guide documents available editor controls. Material, physics, particle, appearance, audio, animation-set and terrain resource editors are available offline. Terrains are shaped with the Sculpt brush in Scene; painting their ground layers is not available yet. Workspace undo and recoverable Save All include new/embedded drafts and binding migrations. Live structural resource editing remains an offline/restart workflow.

The scene inspector has common transforms, camera settings, light type/range/cones, model material bindings and physics controls. Other saved world settings or component fields may be retained without an inspector control. Use the relevant format/runtime documentation for those features. Source / Repair edits a material or physics resource; it is not a general world JSON editor.

Useful examples and references:

• World Editor starter scene — camera, lighting and a placement pivot.
• Live debugging sample — complete running scene with Pause/Continue editing.
• Shared material scene and sample program — two objects sharing a material with instance differences.
• Editor-created physics scene and sample program — a saved floor, dynamic body and hinge stepped by a plain Blitz program.
• Complete asset collection — a catalogue fixture for previews and load testing.
• World Editor sample README — additional behaviour notes and the live layer-loading helper.
• Loading worlds asynchronously — loading, switching worlds and streaming.
• Reusable resources and materials — file structure, dependencies and material APIs.
• Shader guide — shader and Standard material background.
• TextureBlend reference and LoadTexture reference — numeric texture settings.

The editor's Help > About World Editor identifies the tool. This user guide is also available from the bundled Help Guides index.

Native prefabs

Open the nested prefab scene to try this workflow. Double-click a prefab asset to place it, providing any required typed inputs in the placement editor. Expand a scene placement to see its stable local parts. Select a placement or part and use the Prefab inspector tab to edit bindings and property overrides or open its shared source. The source editor changes the containing descriptor, including embedded nested resources. Shared-source saves affect all consumers and validate the current world before publication; save the world separately.

Make Local keeps effective parts and media while allocating fresh authored IDs; ordinary world undo restores the placement. Save as New Prefab captures a selected object and its children with a new resource identity. External scene references become required input slots. The asset viewer previews input-free prefabs; use a bound scene for prefabs with required inputs. The live editor does not expose these authoring operations. See the resource guide for reference and override syntax, ownership and attachment rules.

Back to contents · Back to Guides