scene: deprecate foreground_mobjects in favour of z_index ordering

[Drunsdo]

Source

Two related sites in manim/scene/scene.py (as of HEAD ):

Line 220 — the attribute declaration in Scene.__init__:

self.mobjects: list[Mobject] = []
# TODO, remove need for foreground mobjects
self.foreground_mobjects: list[Mobject] = []

Line 760 — the public method that maintains the attribute:

# TODO, remove this, and calls to this
def add_foreground_mobjects(self, *mobjects: Mobject) -> Scene:
    ...
    self.foreground_mobjects = list_update(self.foreground_mobjects, mobjects)
    self.add(*mobjects)
    return self

Problem

Scene maintains two separate mobject lists: self.mobjects for the general scene contents, and self.foreground_mobjects for objects that should be rendered on top regardless of insertion order. The in-source TODOs at lines 220 and 760 mark this mechanism as redundant.

The Mobject class already exposes a z_index attribute that controls draw order. Any object that needs to appear in the foreground could instead be assigned a higher z_index, removing the need for a separate list and the public methods that maintain it (add_foreground_mobjects, and likely bring_to_front, bring_to_back too).

Suggested approaches

• Audit all uses of foreground_mobjects and the methods that mutate it to identify what behaviour they provide beyond z_index.
• If the behaviours overlap, deprecate foreground_mobjects, the public method add_foreground_mobjects, and any related methods. Emit a warning that points users to z_index.
• After a deprecation period, remove the attribute and the redundant methods.

This is a breaking change for users who interact with foreground_mobjects directly or via bring_to_front(), so the deprecation path matters.