Why does setting a Bevy sprite to Inherited leave it hidden under its parent?

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.

Visibility::Inherited means that a Bevy entity follows the visibility of its ancestors. It does not mean visible. A child under a hidden root can therefore remain absent after you set the child to Inherited. Bevy 0.17.2 also distinguishes the explicit Visible state from hierarchy inheritance in its visibility source.

Key Takeaways

Inspect the whole parent chain before changing the artwork.

Keep intentional hierarchy inheritance when toggling a complete character.

A visible state does not override camera layers, missing images or off-screen placement.

Establish who owns character visibility

A common arrangement places body, weapon and shadow beneath a character root. Hiding the root is convenient when the whole actor should disappear. A later equipment system might set a newly attached weapon to Inherited and expect it to appear immediately, while the root is still hidden.

Log the root and child visibility together when entering or leaving a menu. Include the state transition that made the root hidden. This is more useful than repeatedly applying visibility to the last child in the hierarchy.

Use the equipment composition guide to distinguish separate drawable parts from a single flattened frame. One image cannot expose independently controllable equipment merely by adding a visibility component.

Choose inheritance or an explicit exception

If the whole actor should follow its root, restore the root's intended state. Do not force every child Visible to compensate for one stale root setting. That breaks the next hide operation.

// Bevy 0.17.2 fragments; not executed here. commands.entity(character_root).insert(Visibility::Inherited); commands.entity(weapon).insert(Visibility::Inherited);

An explicit Visible child can be appropriate for an intentional exception, but describe why it should ignore an ancestor's hidden state. For example, a debug indicator may have different visibility requirements from the character art. It may be clearer to put such an indicator outside the character subtree.

The official hierarchy example shows how parent and child entities relate. It does not determine which gameplay system should own your character's visibility policy.

Observe after propagation

Visibility has derived state used by rendering. If a diagnostic reads values at the wrong schedule point, it may observe a change before propagation has updated the hierarchy result. Compare the user-facing frame after the relevant systems have run, and avoid treating a single early query as final rendering evidence.

Do not write derived visibility values as a long-term workaround. Change the supported public input and let the normal systems calculate the result. When multiple systems write Visibility, identify their order and narrow their responsibilities.

Intended behavior	Recommended ownership
Hide every character part together	Root with inheriting drawable children
Hide only a weapon during one pose	Weapon's own visibility state
Keep a debug marker independently visible	Explicit exception or separate subtree

Rule out adjacent causes

A loaded, hierarchy-visible sprite can still be excluded by RenderLayers. The layer source documents that separate filter. Image readiness is another boundary; the Bevy loading diagnostic covers it.

For acceptance, hide and reveal the root repeatedly, attach equipment while hidden, and then reveal the actor. Confirm no part flashes into an excluded state. Record who writes each visibility input in the animation handoff checklist.

This procedure targets Bevy 0.17.2. It was not executed in a game project, so the final acceptance result must come from your hierarchy and system schedule.

Watch for competing state transitions

Record which system wrote the hidden state and why. A menu transition may hide the actor while a gameplay transition tries to reveal only its body child. Both operations can be individually valid while their combined result remains hidden. Give one transition owner responsibility for restoring the actor root, and let equipment systems manage only equipment-specific exceptions. When reproducing the issue, include the actual menu-to-game sequence instead of testing visibility exclusively in a fresh scene. A startup-only check will miss a stale state left by navigation.