After spending a long time debugging invisible sprites I want to document everything that can cause this, because each issue gives zero error messages and fails silently.
1. Z values are cumulative and the default render script only renders -1 to 1
This is the big one. The default render script renders objects with Z between -1.0 and 1.0 only.
Z values stack:
-
Game object Z in the collection
-
+ Sprite component Z position
-
+ Any parent GO Z
-
= Final rendered Z
If the total pushes outside -1 to 1 the object silently disappears. Check every level. Keep all your 2D Z values as small floats: 0.1, -0.2, -0.5 etc.
2. Camera near_z clips objects
The default camera component has near_z: 0.1. In orthographic 2D this means anything at Z >= -0.1 (from the camera’s perspective) gets clipped.
For 2D games, set your camera to:
near_z: -1.0
far_z: 1.0
This matches the default render script’s expected range and nothing gets clipped.
3. use_camera_projection requires a custom render script
If your camera script calls:
msg.post("@render:", "use_camera_projection")
This does nothing with the built-in default render script. You need a custom render script that handles the set_view_projection message. Without it, camera zoom and follow work but the projection matrix is never applied, causing rendering issues.
4. Too many tilemap tiles crashes the render pass silently
If you paint a very large tilemap and hit the default tile limit (2048), the engine prints this to the console:
ERROR:GAMESYS: Out of tiles to render (2048).
But this error can also prevent other objects from rendering in the same frame. Increase the limit in game.project:
[tilemap]
max_tile_count = 8192
Summary checklist
| Issue | Symptom | Fix |
|---|---|---|
| Z out of -1 to 1 range | Silent disappear | Check cumulative Z values |
| Camera near_z clips object | Silent disappear | Set near_z: -1.0, far_z: 1.0 |
| Missing custom render script | Camera projection ignored | Add custom render script |
| Tile count overflow | Render pass fails | Increase max_tile_count |
Hope this saves someone a few hours!