FAQ

The questions that cost a support round. Read the tooltip before assuming a button is broken.

A button is greyed out

Wrong selection context. Extrude wants faces or edges. Bridge wants two open edges. CSG wants two objects. The tooltip names the requirement.

My click selected the wrong mesh

Element modes edit the last-clicked mesh. Object mode moves several. Click the mesh you want, then pick faces.

CSG did nothing

Output log. The watertight pre-flight names the open-boundary count. Fill Hole / weld, or start from a closed primitive.

My GLB has no face gizmo

It is still a MeshInstance3D. Poibuilderize it. You can export it without converting; you cannot face-edit it.

Undo removed my CSG cutter

It comes back. CSG undo restores the cutter node. If it renders but does not pick, that was a historical "undo ghost" — current builds restore owner and gizmos.

The overlay disappeared

PanelRow 2 · DocksPanelPins the floating overlay panel on (it otherwise auto-hides when nothing is selected).Needs: Nothing toggle pins it. Reset PanelRow 2 · DocksReset PanelRecovers the overlay panel and dock to the bottom-left corner if they were dragged away.Needs: Nothing docks it to the bottom-left. It auto-hides when nothing is selected and it is not pinned.

Textures stretch

Auto-UV keeps 1 m repeat on axis-aligned faces. Ramps and merged creases need the UV editor (planar / box projection).

Trim Walls at Top does something weird around my door

Known limitation. Top-swap of a loop with openings does not produce a contiguous cornice at the top edge. Use Bottom placement for those loops, or move only the simple faces to Top. Details on Trims.

The version in the overlay does not match these docs

You are running a different build. The overlay title is PoiBuilder vX.Y.Z. Enable the plugin from the same addons/poibuilder/ these docs were built with.

Is the PSP engine how I run my map?

No. The PSP engine in the repository is a proof of concept and a performance sanity check — it exists to validate the .pbm format and measure it on real hardware. The format is the contract: implement a loader in your own engine from The PBM format specification, using the demo engine's loader as a reference. Details on Export & retro.

My map chugs when I play the PoiBuilder scene

That is expected — the editable scene is the authoring format, not the shipping one. It renders the live splat shader, live decal layers and every realtime light, which measured ~4× the retro bake's frame cost on the benchmark baseline. Run Export...Row 2 · ExportExport...Opens the export dialog: PBM (the retro .pbm map, default) or GLB — modern bake (lightmap-ready) or retro baked (vertex-lit) — with the bake options.Needs: Nothing (always enabled) and play the baked result instead: a modern GLB for the modern pipeline (paint baked into textures, your own lights/LightmapGI on top) or PBM for retro targets. Keep the PoiBuilder scene for building, testing and iterating; details on Export & retro.

Export looks fine in PPSSPP and chugs on the PSP

Desktop emulators like PPSSPP rasterise on your host GPU with gigabytes of VRAM and a massive cache, masking real hardware limits. The real PSP Graphics Engine (GE) has an ~8 KB texture cache. When a surface's sampled mip level fits within the ~8 KB cache, it draws at ~480 Mfrag/s (~2 ns per fragment); when the sampled footprint exceeds the cache, every fragment pays a main-memory bus penalty, dropping fill rate to ~25 Mfrag/s (a 19x performance cliff).

Keep texture sizes power-of-two (≤ 512, clamped automatically on export) and check that close-up surfaces don't force large mip levels into the cache. Detailed architecture constraints, measured costs, and profiling tools are documented in the PSP Optimization Guide and demonstrated in our native PSP demo engine.

Where did my export go?

project/exports/, gitignored on purpose. Regenerated by the export dialog whenever you need it.

Something looks wrong and it is not the tooltip's fault

Check Known issues — the confirmed alpha rough edges (PSP billboards rendering unlit, unexpected PSP shadows on transparent scrolling planes, stamps not spanning two objects, paint lag and dotted strokes, mangled retro UVs after Poibuilderize) are documented there with workarounds.