~~NOTOC~~

====== QuadtreeSprite ======

---- dataentry extension ----
author_mail   : contact@justpinegames.com Tomislav Podhraški
description   : Efficient container for with large number of children DisplayObjects
lastupdate_dt : 2013-03-15
compatible    : v1.3
depends       :            # if the ext. depends on others, list them here
tags          : Sprite, quadtree, big world
homepage_url  : https://github.com/justpinegames/QuadtreeSprite-Extension
download_url  : https://github.com/justpinegames/QuadtreeSprite-Extension/archive/master.zip
----

===== Overview =====

QuadtreeSprite is a Starling extensions which is useful when you need a container for large amount of children DisplayObjects which are usually not visible on the screen at the same time. Perfect use-case: Large 2D world map.

You can check out the demo here:
[[http://justpinegames.com/blog/2013/03/quadtreesprite/]]

There are a few things different in the API so check the usage section below.

Creation:
<code as3>
    // Define the world bounds, if objects is outside them it will always be displayed
    var worldBounds:Rectangle = new Rectangle(...);
    var container:QuadtreeSprite = new QuadtreeSprite(worldBounds);
</code>

Adding/Removing children:
<code as3>
    // Same as in Starling:
    container.addChild(new Quad(...));
    container.removeChild(...);
</code>

Important to note is that you have to **explicitly** update object when it's position or size has changed!
<code as3>
    var object:Quad = ...;
    container.addChild(object);
    object.x = 10;
    container.updateChild(object);
</code>

To change the visible portion of the scene use visibleViewport, everything outside that rectangle will be removed from display list:
<code as3>
    container.visibleViewport = new Rectangle(...);
</code>

When visible objects change you can listen to Event.CHANGE, you should sort here if you need your objects to be in order:
<code as3>
    container.addEventListener(Event.CHANGE, ...);
</code>

You can iterate through the currently visible objects, or all of which the container holds:
<code as3>
    // visible objects
    for (var i:int = 0; i < container.numChildren; ++i) {
        var object:DisplayObject = container.getChildAt(i);
    }

    // all objects
    for (var i:int = 0; i < container.dynamicNumChildren; ++i) {
        var object:DisplayObject = container.dynamicGetChildAt(i);
    }
</code>


===== Changelog =====

  * //2013/03/15 22:07//: First public version