Disclosure: This draft was generated with AI and checked against the cited primary sources, with a separate AI editorial review. It was prepared for the FrameSprite team, which has a commercial interest in FrameSprite. Proposed examples are not executed tests unless explicitly identified as recorded fixture results.
Check RenderLayers on both the camera and each renderable entity when a Bevy character body appears but its child equipment does not. RenderLayers are not inherited from the parent. The camera and renderable must share a layer. This is separate from hierarchy visibility and image loading, as documented in the Bevy 0.17.2 layer implementation.
Key Takeaways
- Parent-child ownership does not copy a render layer to equipment.
- Confirm an actual camera/entity layer intersection.
- Keep the body and equipment visible in a minimal single-camera scene first.
List the renderable entities
A character root may be only a gameplay entity. Its body, sword and shadow can be separate Sprite children. Inspect the component on the Sprite entity itself, not just on the root shown at the top of the hierarchy.
Create a short inventory with entity ID, parent ID, image handle, Visibility and RenderLayers. For the intended camera, record its layers and target. This makes an invisible sword a concrete mismatch to investigate rather than a reason to regenerate the PNG.
If the image is still loading, first follow the Bevy dependency-readiness guide. An absent image and a layer mismatch can produce similar screenshots but need different fixes.
Align the camera and selected drawables
A small setup fragment illustrates a dedicated preview layer:
// Bevy 0.17.2, unexecuted setup fragments.
commands.entity(preview_camera).insert(RenderLayers::layer(1));
commands.entity(body).insert(RenderLayers::layer(1));
commands.entity(weapon).insert(RenderLayers::layer(1));
Do not paste this into every entity indiscriminately. A portrait camera may intentionally exclude world shadows, and a main camera may intentionally exclude preview equipment. Decide which renderables belong to the view, then assign the shared layer.
The official pixel-grid example uses camera and layer separation in a render-to-texture setup. It is useful evidence of the mechanism, not a ready-made policy for your character hierarchy.
Test visibility and layers independently
Visibility can still hide a correctly layered drawable. The visibility implementation describes hierarchy-related visibility separately. Temporarily use a simple visible root and a known loaded image when testing the layer intersection.
| Body | Weapon | Preview camera | Interpretation |
|---|---|---|---|
| Layer 1 | Layer 0 | Layer 1 | Weapon has no shared layer |
| Layer 1 | Layer 1 | Layer 1 | Inspect loading, visibility, position and target |
| Layers 0 and 1 | Layer 1 | Layer 0 | Body may appear while weapon is excluded |
Avoid inferring a layer problem from a single successful frame. Switch the active camera or open the preview and gameplay views together. A drawable assigned to both may appear twice if both cameras render into the same final view.
Preserve the asset contract
Layer selection should not change frame order, alpha or the position of the weapon inside its source image. The equipment-layering guide explains the artwork tradeoff; this procedure addresses which renderable a particular camera draws.
Store the camera-layer policy with the sprite delivery checklist, especially when a preview feature creates a second camera.
Acceptance requires the intended body, weapon and shadow to appear in the correct views and remain absent from excluded views. Test after reparenting equipment. This is a source-based diagnostic for Bevy 0.17.2; the setup has not been executed here.
Check newly attached equipment
Test equipment created after the initial character setup, not only parts spawned at startup. A system that assigns layers to existing children once can miss a sword attached later. Put the intended view assignment in the equipment creation or attachment path and validate it when that path runs. When an item is moved between world and preview views, update the layer policy deliberately. Copying a layer from an arbitrary sibling is fragile because that sibling may serve a different camera or represent an intentionally excluded shadow.
Sources and editorial ownership
Primary references checked on October 20, 2026:
- RenderLayers inheritance and intersection
- Official layered camera example
- Visibility propagation implementation
Editorial owner: FrameSprite Workflow Team. Editorial and verification policy. Report a documentation correction.
Top comments (0)