[next] Return of the Stage

[ivanpopelyshev]

Work in progress - need reviews

• New name for InnerStage class.
• New name for animationDeltaMax

What if we rename detachChild into removeLater , silendRemoveChild or stealChild ?

The time has come! Russian Christmas update!

Follow #4179 , I kept it very simple.

This is colossal PR that was waited too long, people really want correct added and removed events and a way to track all animations that exist in main stage tree. This is critical for projects that need to free resources and count references to them, also for projects that require managable tweens and animations.

InnerStage tracks sets of DisplayObjects and Containers that exist in the stage, some in detached stage. 170 lines of serious algorithm code were always on used-side.

parentStage property always points to the stage where the object is registered.

As a default implementation that can be easily changed in plugins and in user-side code, any object that has animate method will be called when the time comes. It can be changed both by overriding Stage methods and handling added and removed events.

There can be nested stages.

Better Events

added and removed are fired for whole subtree.

var stage = new PIXI.Stage();
var container = new PIXI.Container();
var child = new PIXI.DisplayObject();

container.addChild(child); // nothing
stage.addChild(container); // child is ADDED!

Additional way of moving objects in the same stage without firing events: detachChild. It exists in cocos2d-x as a flag to removeChild, which is not verbose.

var container1 = new PIXI.Container();
var container2 = new PIXI.Container();
var stage = new PIXI.Stage();

stage.addChild(container1);
stage.addChild(container2);

var child = new PIXI.Container();
container1.addChild(child); //ADDED
container1.detachChild(child);// event doesnt fire
//some calculations
container2.addChild(child); // event doesnt fire because its in the same stage
//some calculations
container2.detachChild(child);

stage.innerStage.flushDetached(); // actual REMOVED, we dont need related resources anymore!

Generated Resources: Dispose vs Destroy

Alternative to destroy method, just override onRemoved or register a handler.

This snippet automatically frees videomemory of unstaged text:

var text = new PIXI.Text('stuff');
text.on('removed', () => { text.texture.baseTexture.dispose(); } );

Fallback

Use PIXI.Container as a root.

app = new PIXI.Application( { stage: new PIXI.Container() } );

added and removed events wont be fired in that case.

Solution for remove at animate problem

Suppose you animate spine object or AnimatedSprite and want to remove that thing from the stage from inside of event.

myAnimatedObject.on('someEventInsideAnimation', () => {
    if (myAnimatedObject.dead) 
    {
         myAnimatedObject.parent.removeChild(myAnimatedObject);
    }
});

That can really affect neighbour elements, or even throw an exception. Any event fired from inside animation or old updateTransform can trigger that response.

With detachChild it will work just fine.

[ivanpopelyshev]

@endel original Added/Removed events PR author , #1870

Flash has two type of events: added and added_to_stage, right? Do we need both or only added_to_stage that i want to make default in this PR?

Just a reference, found your code related to stage: https://github.com/gamestdio/pixi-engine/blob/master/src/PixiPatches.ts#L8

[endel]

Hi @ivanpopelyshev,

Here's the description of "added_to_stage" event, from Flash:

event.target: The DisplayObject instance being added to the on stage display list, either directly or through the addition of a sub tree in which the DisplayObject instance is contained. If the DisplayObject instance is being directly added, the "added" event occurs before this event.

AFAIK, it's not possible to have Stage as a child of another Stage on Flash. It's always used only as the root element.

On pixi-engine, I've monkey-patched the addChild/removeChild methods to expose the "added"/"removed" events globally and catch them from another scope, because they don't bubble / propagate on pixi.js.

On Flash the events always bubble through the whole display list, and it is possible to listen for events from the root (or any of its parents), and manipulate any deeper DisplayObject added, which comes as target of the event.

IMHO having a detachChild method would cause more confusion. Can we have a real world example of when detachChild would be necessary? 😅

Cheers!

[cursedcoder]

55-56 missing dots :)

[cursedcoder]

ok, I think this can be addressed as separate PR, we can add this to CI or somewhere

[cursedcoder]

let's move to the docblock?

[cursedcoder]

As for me, I don't quite get a reason to have multiple stages.

Would be cool to add short example/use-cases in docs?

[cursedcoder]

I think something like your description is a great thing to put here.

Just maybe make it more compact.

[bigtimebuddy]

@GoodBoyDigital and I have discussed and we have decided to close this omnibus PR because of the unwanted complexity it would add to v5, it's incompleteness (failing tests), added API surface, and a failure to see community enthusiasm for this approach.

However, there may be smaller incremental PRs within this one (e.g., the ability to provide a "stage" container for Application options, adjustments to inherited animation time/ticks, a way to add/remove children without events) but overall all the functionality within this Stage implementation is probably best as an external plugin or system for Pixi.

[lock]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.