wsg/docs/user/errors.md

Errors and refusals — what the API does when you exceed it

Every budget in WSG is pre-sized: tables are allocated before the render loop, so going past a ceiling is not something that can be discovered halfway through a frame. It is refused at the call that exceeds it, with a message naming what was called, and the scene is left exactly as it was.

That last part is the contract, and it is locked: a refusal is not “accepted then panicked inside the first frame”. A test builds the scene one entry past each ceiling, asserts the call returns Err, and then renders — the render must not panic.

Two shapes

Shape	Who returns it	How to read it
Result<_, String>	Scene authoring calls (create_mesh, add_sprite, add_material_shader, add_lod_level, add_light, register_shader)	the string is written for a human: it names the ceiling and, where it matters, the counts that got there
Result<_, BatchError>	instance-batch calls (add_instance_batch and friends)	a typed enum, so you can match on it: CapacityReached { batches, entities }, InstanceCapacityReached { used, requested }, UnknownMesh, DuplicateLabel

Both are refusals, never a panic and never a log line. If you are calling from a scripted or generated client: check the Err, do not grep the log for a symptom — there is none.

A media file is missing (examples only)

Fourteen examples load demo media — glTF models, HDR environments, the six skybox JPEGs — that are not in the published package (lib/Cargo.toml, exclude; 18 MB measured, and the reason the .crate weighs 2.3 MB). From a crates.io download those examples print a Demo media banner naming the missing directory, then return a load error naming the same path.

That is the intended shape of the failure. The fix is not in the library: clone the repository and run the example from the clone (the root README's Demo media section gives the two commands). Nothing in wsg-lib itself reads those files — every test that reads media reads fixtures that ship inside the crate (lib/assets/tests/), which is why the test suite is green from a package download while those examples are not.

Ceilings you can hit

Ceiling	Constant	What you get back	What does not happen
Transform slots — entities and instance batches share one table	MAX_BATCHES	Cannot add <entry>: MAX_BATCHES (<ceiling>) reached (<n> entities + <m> instance batches).	no half-inserted entity, no orphan batch
GPU mesh tables (one row per mesh, indexed positionally by the GPU)	MAX_BATCHES	Cannot add <entry>: the GPU mesh tables hold at most <ceiling> entries (got <n>). Reduce the mesh count, or grow MAX_BATCHES together with the bbox/LOD buffers and their bind groups.	the table is not lengthened, the frame is not killed
Instances across all batches	MAX_INSTANCES	BatchError::InstanceCapacityReached { used, requested }	no truncated batch, no silently dropped instances
Lights	MAX_LIGHTS	Cannot add another light: MAX_LIGHTS (<ceiling>) reached.	no light list corruption
LOD levels of one mesh	MAX_LOD_LEVELS	Mesh '<mesh>' already has the maximum of <ceiling> LOD levels.	no new level appended
Registering a shader by path	—	Shader file '<path>' for id '<id>' is not a readable file… — checked at registration, not at first draw	no silent fallback to the built-in shader (that fallback existed, and it hid 31 examples pointing at a folder that does not exist)

Two of these are worth internalising, because both were once silent failures:

• Entities and batches share MAX_BATCHES. A scene of 250 entities leaves 6 batch slots, not 256. The message prints both counts precisely so you do not have to guess which side filled the table.
• A mesh row is a GPU index. The row index is what the bounding-box and LOD tables address, so a refusal is not an optimisation — accepting a 257th row would make the next write_buffer run past the end of a fixed buffer. That is the failure the ceiling exists to prevent.

Removing things

Removal is O(1) and leaves holes rather than shifting rows: a freed mesh row is marked empty and its index is reused, so the rows around it do not move — an index you kept stays valid, and a stale handle is refused rather than made to refer to something else. remove_sprite releases the entity, its slot, its generated material and its generated mesh; a mesh you passed in yourself survives removal of a sprite that used it.

Machine-checked

The rows above are not prose you have to trust:

• every ceiling named here is read back out of the shipped source — add a budget guard without documenting it, or invent a ceiling in this page, and doc_consistency fails;
• the behaviour is locked by au_dela_du_budget_de_slots_un_sprite_est_refuse_et_le_rendu_ne_panique_pas and its neighbours in lib/src/scene/sprite_tests.rs;
• removing a guard is a case in campaigns/mutate-sprite-arena.py, seen red.

See also scene-interaction.md for raycasting/picking APIs and stats.md for what the stats feature prints when a frame is slow.