Replace advertisedDescendant mechanism in class Node with a simple search. The advertisedDescendant mechanism was only being used by PhysicsVehicle/Wheel.

gameplay/src/Node.cpp

@@ -1261,21 +1261,6 @@ PhysicsCollisionObject* Node::setCollisionObject(Properties* properties)
     return _collisionObject;
 }
 
-unsigned int Node::getNumAdvertisedDescendants() const
-{
-    return (unsigned int)_advertisedDescendants.size();
-}
-
-Node* Node::getAdvertisedDescendant(unsigned int i) const
-{
-    return _advertisedDescendants.at(i);
-}
-
-void Node::addAdvertisedDescendant(Node* node)
-{
-    _advertisedDescendants.push_back(node);
-}
-
 AIAgent* Node::getAgent() const
 {
     return _agent;

gameplay/src/Node.h

@@ -594,41 +594,6 @@ public:
      */
     PhysicsCollisionObject* setCollisionObject(Properties* properties);
 
-    /**
-     * Returns the number of advertised descendants held in this node.
-     *
-     * Descendant nodes can advertise themselves to others using this
-     * mechanism, such as how the wheels are bound to a physics vehicle
-     * via their common ancestor.
-     *
-     * @return the number of advertised descendants held in this node.
-     */
-    unsigned int getNumAdvertisedDescendants() const;
-
-    /**
-     * Returns the advertised descendant at the specified index.
-     *
-     * Descendant nodes can advertise themselves to others using this
-     * mechanism, such as how the wheels are bound to a physics vehicle
-     * via their common ancestor.
-     *
-     * @param i the index to look-up.
-     *
-     * @return the advertised descendant at the specified index.
-     */
-    Node* getAdvertisedDescendant(unsigned int i) const;
-
-    /**
-     * Adds the specified node to the list of advertised descendants.
-     *
-     * Descendant nodes can advertise themselves to others using this
-     * mechanism, such as how the wheels are bound to a physics vehicle
-     * via their common ancestor.
-     *
-     * @param node the node reference to add.
-     */
-    void addAdvertisedDescendant(Node* node);
-
     /**
      * Returns the AI agent assigned to this node.
      *
@@ -879,14 +844,6 @@ protected:
      * Pointer to custom UserData and cleanup call back that can be stored in a Node.
      */
     UserData* _userData;
-
-    /**
-     * A linear collection of descendants who wish to advertise themselves, typically
-     * to other descendants. This allows nodes of common ancestry to bond. One example
-     * of this is a physics vehicle and its wheels, which are associated via their
-     * lowest common ancestor.
-     */
-    std::vector<Node*> _advertisedDescendants;
 };
 
 /**

gameplay/src/PhysicsVehicle.cpp

@@ -188,13 +188,6 @@ void PhysicsVehicle::initialize()
     body->setActivationState(DISABLE_DEACTIVATION);
     dynamicsWorld->addVehicle(_vehicle);
     _vehicle->setCoordinateSystem(0, 1, 2);
-
-    // Advertise self among ancestor nodes so that wheels can bind to self.
-    // See PhysicsVehicleWheel and Node for more details.
-    for (Node* n = getNode()->getParent(); n; n = n->getParent())
-    {
-        n->addAdvertisedDescendant(getNode());
-    }
 }
 
 PhysicsVehicle::~PhysicsVehicle()

gameplay/src/PhysicsVehicleWheel.cpp

@@ -124,28 +124,31 @@ void PhysicsVehicleWheel::findAncestorAndBind()
 {
     GP_ASSERT(getNode());
 
-    // This is not an efficient algorithm if the number of advertised
-    // descendants gets large. In fact, this search is O(n*m) in the
-    // worst case with n nodes and m advertised descendants per node.
-    // But (1) we are only visiting ancestor nodes, and (2) the number
-    // of advertised descendants is expected to be small since this
-    // mechanism is currently only used for binding wheels onto a vehicle.
+    // Search for the first PhysicsVehicle that shares a common ancestor, and
+    // bind with it. The following code performs a naive search; nothing more
+    // sophisticated is deemed necessary because:
+    // (a) The root of the scene is NOT a node
+    // (b) Scene graphs tend to be relatively flat.
     //
-    // TODO: revisit if the advertised descendants mechanism becomes popular.
+    // The search ends when a vehicle is found or n is null:
+    // 1: Let n = this node
+    // 2: Visit each sibling of n and perform a breadth-first search of its descendants
+    // 3: Let n = the parent of n
+    // 4: Go to 2.
     PhysicsVehicle* host = NULL;
-    PhysicsCollisionObject* collisionObject;
     Node* m;
-    for (Node* n = getNode()->getParent(); n && !host; n = n->getParent())
+    for (Node* n = getNode(); n && !host; n = n->getParent())
     {
-        for (unsigned int i = 0; i < n->getNumAdvertisedDescendants() && !host; i++)
+        // Visit siblings before n
+        for (m = n->getPreviousSibling(); m && !host; m = m->getPreviousSibling())
         {
-            m = n->getAdvertisedDescendant(i);
+            host = findVehicle(m);
+        }
 
-            collisionObject = m->getCollisionObject();
-            if (collisionObject && collisionObject->getType() == PhysicsCollisionObject::VEHICLE)
-            {
-                host = static_cast<PhysicsVehicle*>(collisionObject);
-            }
+        // Visit siblings after n
+        for (m = n->getNextSibling(); m && !host; m = m->getNextSibling())
+        {
+            host = findVehicle(m);
         }
     }
 
@@ -157,6 +160,22 @@ void PhysicsVehicleWheel::findAncestorAndBind()
     }
 }
 
+PhysicsVehicle* PhysicsVehicleWheel::findVehicle(Node* node)
+{
+    PhysicsCollisionObject* collisionObject = node->getCollisionObject();
+    if (collisionObject && collisionObject->getType() == PhysicsCollisionObject::VEHICLE)
+    {
+        return static_cast<PhysicsVehicle*>(collisionObject);
+    }
+
+    PhysicsVehicle* result = NULL;
+    for (Node* p = node->getFirstChild(); p && !result; p = p->getNextSibling())
+    {
+        result = findVehicle(p);
+    }
+    return result;
+}
+
 void PhysicsVehicleWheel::setHost(PhysicsVehicle* host, unsigned int indexInHost)
 {
     _host = host;

gameplay/src/PhysicsVehicleWheel.h

@@ -331,6 +331,13 @@ private:
     // Note: Currently this method is silent on failure to find a host.
     void findAncestorAndBind();
 
+    /**
+     * Breadth-first search for the first vehicle starting from the specified node.
+     *
+     * @param node the starting node for the recursive search.
+     */
+    PhysicsVehicle* findVehicle(Node* node);
+
     /**
      * Sets the host vehicle for this wheel.
      *

gameplay/src/lua/lua_Joint.cpp

@@ -31,7 +31,6 @@ void luaRegister_Joint()
 {
     const luaL_Reg lua_members[] = 
     {
-        {"addAdvertisedDescendant", lua_Joint_addAdvertisedDescendant},
         {"addChild", lua_Joint_addChild},
         {"addListener", lua_Joint_addListener},
         {"addRef", lua_Joint_addRef},
@@ -44,7 +43,6 @@ void luaRegister_Joint()
         {"findNode", lua_Joint_findNode},
         {"getActiveCameraTranslationView", lua_Joint_getActiveCameraTranslationView},
         {"getActiveCameraTranslationWorld", lua_Joint_getActiveCameraTranslationWorld},
-        {"getAdvertisedDescendant", lua_Joint_getAdvertisedDescendant},
         {"getAgent", lua_Joint_getAgent},
         {"getAnimation", lua_Joint_getAnimation},
         {"getAnimationPropertyComponentCount", lua_Joint_getAnimationPropertyComponentCount},
@@ -72,7 +70,6 @@ void luaRegister_Joint()
         {"getMatrix", lua_Joint_getMatrix},
         {"getModel", lua_Joint_getModel},
         {"getNextSibling", lua_Joint_getNextSibling},
-        {"getNumAdvertisedDescendants", lua_Joint_getNumAdvertisedDescendants},
         {"getParent", lua_Joint_getParent},
         {"getParticleEmitter", lua_Joint_getParticleEmitter},
         {"getPreviousSibling", lua_Joint_getPreviousSibling},
@@ -227,48 +224,6 @@ int lua_Joint__gc(lua_State* state)
     return 0;
 }
 
-int lua_Joint_addAdvertisedDescendant(lua_State* state)
-{
-    // Get the number of parameters.
-    int paramCount = lua_gettop(state);
-
-    // Attempt to match the parameters to a valid binding.
-    switch (paramCount)
-    {
-        case 2:
-        {
-            if ((lua_type(state, 1) == LUA_TUSERDATA) &&
-                (lua_type(state, 2) == LUA_TUSERDATA || lua_type(state, 2) == LUA_TTABLE || lua_type(state, 2) == LUA_TNIL))
-            {
-                // Get parameter 1 off the stack.
-                bool param1Valid;
-                gameplay::ScriptUtil::LuaArray<Node> param1 = gameplay::ScriptUtil::getObjectPointer<Node>(2, "Node", false, &param1Valid);
-                if (!param1Valid)
-                {
-                    lua_pushstring(state, "Failed to convert parameter 1 to type 'Node'.");
-                    lua_error(state);
-                }
-
-                Joint* instance = getInstance(state);
-                instance->addAdvertisedDescendant(param1);
-                
-                return 0;
-            }
-
-            lua_pushstring(state, "lua_Joint_addAdvertisedDescendant - Failed to match the given parameters to a valid function signature.");
-            lua_error(state);
-            break;
-        }
-        default:
-        {
-            lua_pushstring(state, "Invalid number of parameters (expected 2).");
-            lua_error(state);
-            break;
-        }
-    }
-    return 0;
-}
-
 int lua_Joint_addChild(lua_State* state)
 {
     // Get the number of parameters.
@@ -1094,54 +1049,6 @@ int lua_Joint_getActiveCameraTranslationWorld(lua_State* state)
     return 0;
 }
 
-int lua_Joint_getAdvertisedDescendant(lua_State* state)
-{
-    // Get the number of parameters.
-    int paramCount = lua_gettop(state);
-
-    // Attempt to match the parameters to a valid binding.
-    switch (paramCount)
-    {
-        case 2:
-        {
-            if ((lua_type(state, 1) == LUA_TUSERDATA) &&
-                lua_type(state, 2) == LUA_TNUMBER)
-            {
-                // Get parameter 1 off the stack.
-                unsigned int param1 = (unsigned int)luaL_checkunsigned(state, 2);
-
-                Joint* instance = getInstance(state);
-                void* returnPtr = (void*)instance->getAdvertisedDescendant(param1);
-                if (returnPtr)
-                {
-                    gameplay::ScriptUtil::LuaObject* object = (gameplay::ScriptUtil::LuaObject*)lua_newuserdata(state, sizeof(gameplay::ScriptUtil::LuaObject));
-                    object->instance = returnPtr;
-                    object->owns = false;
-                    luaL_getmetatable(state, "Node");
-                    lua_setmetatable(state, -2);
-                }
-                else
-                {
-                    lua_pushnil(state);
-                }
-
-                return 1;
-            }
-
-            lua_pushstring(state, "lua_Joint_getAdvertisedDescendant - Failed to match the given parameters to a valid function signature.");
-            lua_error(state);
-            break;
-        }
-        default:
-        {
-            lua_pushstring(state, "Invalid number of parameters (expected 2).");
-            lua_error(state);
-            break;
-        }
-    }
-    return 0;
-}
-
 int lua_Joint_getAgent(lua_State* state)
 {
     // Get the number of parameters.
@@ -2447,41 +2354,6 @@ int lua_Joint_getNextSibling(lua_State* state)
     return 0;
 }
 
-int lua_Joint_getNumAdvertisedDescendants(lua_State* state)
-{
-    // Get the number of parameters.
-    int paramCount = lua_gettop(state);
-
-    // Attempt to match the parameters to a valid binding.
-    switch (paramCount)
-    {
-        case 1:
-        {
-            if ((lua_type(state, 1) == LUA_TUSERDATA))
-            {
-                Joint* instance = getInstance(state);
-                unsigned int result = instance->getNumAdvertisedDescendants();
-
-                // Push the return value onto the stack.
-                lua_pushunsigned(state, result);
-
-                return 1;
-            }
-
-            lua_pushstring(state, "lua_Joint_getNumAdvertisedDescendants - Failed to match the given parameters to a valid function signature.");
-            lua_error(state);
-            break;
-        }
-        default:
-        {
-            lua_pushstring(state, "Invalid number of parameters (expected 1).");
-            lua_error(state);
-            break;
-        }
-    }
-    return 0;
-}
-
 int lua_Joint_getParent(lua_State* state)
 {
     // Get the number of parameters.

gameplay/src/lua/lua_Joint.h

@@ -6,7 +6,6 @@ namespace gameplay
 
 // Lua bindings for Joint.
 int lua_Joint__gc(lua_State* state);
-int lua_Joint_addAdvertisedDescendant(lua_State* state);
 int lua_Joint_addChild(lua_State* state);
 int lua_Joint_addListener(lua_State* state);
 int lua_Joint_addRef(lua_State* state);
@@ -19,7 +18,6 @@ int lua_Joint_destroyAnimation(lua_State* state);
 int lua_Joint_findNode(lua_State* state);
 int lua_Joint_getActiveCameraTranslationView(lua_State* state);
 int lua_Joint_getActiveCameraTranslationWorld(lua_State* state);
-int lua_Joint_getAdvertisedDescendant(lua_State* state);
 int lua_Joint_getAgent(lua_State* state);
 int lua_Joint_getAnimation(lua_State* state);
 int lua_Joint_getAnimationPropertyComponentCount(lua_State* state);
@@ -47,7 +45,6 @@ int lua_Joint_getLight(lua_State* state);
 int lua_Joint_getMatrix(lua_State* state);
 int lua_Joint_getModel(lua_State* state);
 int lua_Joint_getNextSibling(lua_State* state);
-int lua_Joint_getNumAdvertisedDescendants(lua_State* state);
 int lua_Joint_getParent(lua_State* state);
 int lua_Joint_getParticleEmitter(lua_State* state);
 int lua_Joint_getPreviousSibling(lua_State* state);

gameplay/src/lua/lua_Node.cpp

@@ -30,7 +30,6 @@ void luaRegister_Node()
 {
     const luaL_Reg lua_members[] = 
     {
-        {"addAdvertisedDescendant", lua_Node_addAdvertisedDescendant},
         {"addChild", lua_Node_addChild},
         {"addListener", lua_Node_addListener},
         {"addRef", lua_Node_addRef},
@@ -43,7 +42,6 @@ void luaRegister_Node()
         {"findNode", lua_Node_findNode},
         {"getActiveCameraTranslationView", lua_Node_getActiveCameraTranslationView},
         {"getActiveCameraTranslationWorld", lua_Node_getActiveCameraTranslationWorld},
-        {"getAdvertisedDescendant", lua_Node_getAdvertisedDescendant},
         {"getAgent", lua_Node_getAgent},
         {"getAnimation", lua_Node_getAnimation},
         {"getAnimationPropertyComponentCount", lua_Node_getAnimationPropertyComponentCount},
@@ -70,7 +68,6 @@ void luaRegister_Node()
         {"getMatrix", lua_Node_getMatrix},
         {"getModel", lua_Node_getModel},
         {"getNextSibling", lua_Node_getNextSibling},
-        {"getNumAdvertisedDescendants", lua_Node_getNumAdvertisedDescendants},
         {"getParent", lua_Node_getParent},
         {"getParticleEmitter", lua_Node_getParticleEmitter},
         {"getPreviousSibling", lua_Node_getPreviousSibling},
@@ -226,48 +223,6 @@ int lua_Node__gc(lua_State* state)
     return 0;
 }
 
-int lua_Node_addAdvertisedDescendant(lua_State* state)
-{
-    // Get the number of parameters.
-    int paramCount = lua_gettop(state);
-
-    // Attempt to match the parameters to a valid binding.
-    switch (paramCount)
-    {
-        case 2:
-        {
-            if ((lua_type(state, 1) == LUA_TUSERDATA) &&
-                (lua_type(state, 2) == LUA_TUSERDATA || lua_type(state, 2) == LUA_TTABLE || lua_type(state, 2) == LUA_TNIL))
-            {
-                // Get parameter 1 off the stack.
-                bool param1Valid;
-                gameplay::ScriptUtil::LuaArray<Node> param1 = gameplay::ScriptUtil::getObjectPointer<Node>(2, "Node", false, &param1Valid);
-                if (!param1Valid)
-                {
-                    lua_pushstring(state, "Failed to convert parameter 1 to type 'Node'.");
-                    lua_error(state);
-                }
-
-                Node* instance = getInstance(state);
-                instance->addAdvertisedDescendant(param1);
-                
-                return 0;
-            }
-
-            lua_pushstring(state, "lua_Node_addAdvertisedDescendant - Failed to match the given parameters to a valid function signature.");
-            lua_error(state);
-            break;
-        }
-        default:
-        {
-            lua_pushstring(state, "Invalid number of parameters (expected 2).");
-            lua_error(state);
-            break;
-        }
-    }
-    return 0;
-}
-
 int lua_Node_addChild(lua_State* state)
 {
     // Get the number of parameters.
@@ -1093,54 +1048,6 @@ int lua_Node_getActiveCameraTranslationWorld(lua_State* state)
     return 0;
 }
 
-int lua_Node_getAdvertisedDescendant(lua_State* state)
-{
-    // Get the number of parameters.
-    int paramCount = lua_gettop(state);
-
-    // Attempt to match the parameters to a valid binding.
-    switch (paramCount)
-    {
-        case 2:
-        {
-            if ((lua_type(state, 1) == LUA_TUSERDATA) &&
-                lua_type(state, 2) == LUA_TNUMBER)
-            {
-                // Get parameter 1 off the stack.
-                unsigned int param1 = (unsigned int)luaL_checkunsigned(state, 2);
-
-                Node* instance = getInstance(state);
-                void* returnPtr = (void*)instance->getAdvertisedDescendant(param1);
-                if (returnPtr)
-                {
-                    gameplay::ScriptUtil::LuaObject* object = (gameplay::ScriptUtil::LuaObject*)lua_newuserdata(state, sizeof(gameplay::ScriptUtil::LuaObject));
-                    object->instance = returnPtr;
-                    object->owns = false;
-                    luaL_getmetatable(state, "Node");
-                    lua_setmetatable(state, -2);
-                }
-                else
-                {
-                    lua_pushnil(state);
-                }
-
-                return 1;
-            }
-
-            lua_pushstring(state, "lua_Node_getAdvertisedDescendant - Failed to match the given parameters to a valid function signature.");
-            lua_error(state);
-            break;
-        }
-        default:
-        {
-            lua_pushstring(state, "Invalid number of parameters (expected 2).");
-            lua_error(state);
-            break;
-        }
-    }
-    return 0;
-}
-
 int lua_Node_getAgent(lua_State* state)
 {
     // Get the number of parameters.
@@ -2402,41 +2309,6 @@ int lua_Node_getNextSibling(lua_State* state)
     return 0;
 }
 
-int lua_Node_getNumAdvertisedDescendants(lua_State* state)
-{
-    // Get the number of parameters.
-    int paramCount = lua_gettop(state);
-
-    // Attempt to match the parameters to a valid binding.
-    switch (paramCount)
-    {
-        case 1:
-        {
-            if ((lua_type(state, 1) == LUA_TUSERDATA))
-            {
-                Node* instance = getInstance(state);
-                unsigned int result = instance->getNumAdvertisedDescendants();
-
-                // Push the return value onto the stack.
-                lua_pushunsigned(state, result);
-
-                return 1;
-            }
-
-            lua_pushstring(state, "lua_Node_getNumAdvertisedDescendants - Failed to match the given parameters to a valid function signature.");
-            lua_error(state);
-            break;
-        }
-        default:
-        {
-            lua_pushstring(state, "Invalid number of parameters (expected 1).");
-            lua_error(state);
-            break;
-        }
-    }
-    return 0;
-}
-
 int lua_Node_getParent(lua_State* state)
 {
     // Get the number of parameters.

gameplay/src/lua/lua_Node.h

@@ -6,7 +6,6 @@ namespace gameplay
 
 // Lua bindings for Node.
 int lua_Node__gc(lua_State* state);
-int lua_Node_addAdvertisedDescendant(lua_State* state);
 int lua_Node_addChild(lua_State* state);
 int lua_Node_addListener(lua_State* state);
 int lua_Node_addRef(lua_State* state);
@@ -19,7 +18,6 @@ int lua_Node_destroyAnimation(lua_State* state);
 int lua_Node_findNode(lua_State* state);
 int lua_Node_getActiveCameraTranslationView(lua_State* state);
 int lua_Node_getActiveCameraTranslationWorld(lua_State* state);
-int lua_Node_getAdvertisedDescendant(lua_State* state);
 int lua_Node_getAgent(lua_State* state);
 int lua_Node_getAnimation(lua_State* state);
 int lua_Node_getAnimationPropertyComponentCount(lua_State* state);
@@ -46,7 +44,6 @@ int lua_Node_getLight(lua_State* state);
 int lua_Node_getMatrix(lua_State* state);
 int lua_Node_getModel(lua_State* state);
 int lua_Node_getNextSibling(lua_State* state);
-int lua_Node_getNumAdvertisedDescendants(lua_State* state);
 int lua_Node_getParent(lua_State* state);
 int lua_Node_getParticleEmitter(lua_State* state);
 int lua_Node_getPreviousSibling(lua_State* state);