Merge pull request #24 from apples/1.0

Preparing for v1.0

README.md

@@ -59,14 +59,14 @@ struct Game {
         // db.create_entity() returns an entity ID.
         auto player = db.create_entity();
 
-        // db.create_component() copies the given component into the entity.
-        db.create_component(player, NameCom{"The Player"});
-        db.create_component(player, PositionCom{12, 42});
+        // db.add_component() emplaces the given component into the entity.
+        db.add_component(player, NameCom{"The Player"});
+        db.add_component(player, PositionCom{12, 42});
 
         auto enemy = db.create_entity();
-        db.create_component(enemy, NameCom{"An Enemy"});
-        db.create_component(enemy, PositionCom{7, 53});
-        db.create_component(enemy, IsEnemyTag{});
+        db.add_component(enemy, NameCom{"An Enemy"});
+        db.add_component(enemy, PositionCom{7, 53});
+        db.add_component(enemy, IsEnemyTag{});
     }
 
     void run_game() {
@@ -77,7 +77,7 @@ struct Game {
                       << std::endl;
         });
 
-        // The Not<> annotation can be used to skip unwanted entities.
+        // The deny<> annotation can be used to skip unwanted entities.
         db.visit([](const NameCom& name, deny<IsEnemyTag>){
             std::cout << name.name << " is not an enemy." << std::endl;
         });

include/ginseng/ginseng.hpp

@@ -755,19 +755,19 @@ class database {
         free_entities.push_back(eid);
     }
 
-    /*! Create new component.
+    /*! Adds a component to an entity.
      *
-     * Creates a new component from the given value and associates it with
-     * the given Entity.
-     * If a component of the same type already exists, it will be
-     * overwritten.
+     * If a component of the same type already exists for this entity,
+     * the given component will be forward-assigned to it.
+     * 
+     * Otherwise, moves or copies the given component and adds it to the entity.
      *
      * @param eid Entity to attach new component to.
      * @param com Component value.
      * @return ID of component.
      */
     template <typename T>
-    com_id create_component(ent_id eid, T&& com) {
+    com_id add_component(ent_id eid, T&& com) {
         using com_type = std::decay_t<T>;
         auto guid = get_type_guid<com_type>();
         auto& ent_coms = entities[eid].components;
@@ -788,13 +788,13 @@ class database {
 
     /*! Create new Tag component.
      *
-     * Creates a new Tag component associates it with the given Entity.
+     * Adds the tag to the entity if it does not already exist.
      *
      * @param eid Entity to attach new Tag component to.
      * @param com Tag value.
      */
     template <typename T>
-    void create_component(ent_id eid, tag<T> com) {
+    void add_component(ent_id eid, tag<T> com) {
         auto guid = get_type_guid<tag<T>>();
         auto& ent_coms = entities[eid].components;
 
@@ -804,20 +804,20 @@ class database {
     }
 
     template <typename T>
-    void create_component(ent_id eid, require<T> com) = delete;
+    void add_component(ent_id eid, require<T> com) = delete;
 
     template <typename T>
-    void create_component(ent_id eid, deny<T> com) = delete;
+    void add_component(ent_id eid, deny<T> com) = delete;
 
     template <typename T>
-    void create_component(ent_id eid, optional<T> com) = delete;
+    void add_component(ent_id eid, optional<T> com) = delete;
 
     template <typename T>
-    void create_component(ent_id eid, ent_id com) = delete;
+    void add_component(ent_id eid, ent_id com) = delete;
 
-    /*! Destroy a component.
+    /*! Remove a component from an entity.
      *
-     * Destroys the given component and disassociates it from its Entity.
+     * Removes the component from the entity and destroys it.
      *
      * @warning
      * All ComIDs associated with components of the component's Entity will
@@ -828,7 +828,7 @@ class database {
      * @param eid ID of the entity.
      */
     template <typename Com>
-    void destroy_component(ent_id eid) {
+    void remove_component(ent_id eid) {
         auto guid = get_type_guid<Com>();
         auto& com_set = *get_com_set<Com>();
         com_set.remove(eid);
@@ -895,21 +895,22 @@ class database {
      *
      * The following parameter categories are accepted:
      *
-     * - Component Data: Any `T` except rvalue-references, matches entities that have component `T`.
-     * - Component Tag: `tag<T>` value, matches entities that have component `tag<T>`.
-     * - Component Require: `require<T>` value, matches entities that have component `T`, but does not load it.
-     * - Component Optional: `optional<T>` value, checks if a component exists, and loads it, does not fail.
-     * - Inverted: `deny<T>` value, matches entities that do *not* match component `T`.
-     * - Entity ID: `ent_id`, matches all entities, provides the `ent_id` of the current entity.
+     * - `T`, matches entities that have component `T`, and loads the component.
+     * - `tag<T>`, matches entities that have component `tag<T>`.
+     * - `require<T>`, matches entities that have component `T`, but does not load it.
+     * - `optional<T>`, matches all entities, loads component `T` if it exists.
+     * - `deny<T>`, matches entities that do *not* match component `T`.
+     * - `ent_id`, matches all entities, provides the `ent_id` of the current entity.
      *
-     * Component Data and Optional parameters will refer to the entity's matching component.
-     * Entity ID parameters will contain the entity's EntID.
+     * `T` and `optional<T>` parameters will refer to the entity's matching component.
+     * `ent_id` parameters will contain the entity's `ent_id`.
      * Other parameters will be their default value.
      *
      * Entities that do not match all given parameter conditions will be skipped.
      *
-     * @warning Entities are visited in no particular order, so adding and removing entities from the visitor
-     *          function could result in non-deterministic behavior.
+     * @warning Entities are visited in no particular order, so creating and destroying
+     *          entities or adding or removing components from within the visitor
+     *          could result in weird behavior.
      *
      * @tparam Visitor Visitor function type.
      * @param visitor Visitor function.

src/test.cpp

@@ -41,12 +41,12 @@ TEST_CASE("Components can be added, accessed, and removed from entities", "[gins
         double y;
     };
 
-    db.create_component(ent, ComA{7});
+    db.add_component(ent, ComA{7});
     REQUIRE(db.has_component<ComA>(ent) == true);
     ComA *com1ptr1 = &db.get_component<ComA>(ent);
     REQUIRE(com1ptr1 != nullptr);
 
-    db.create_component(ent, ComB{4.2});
+    db.add_component(ent, ComB{4.2});
     REQUIRE(db.has_component<ComB>(ent) == true);
     ComB *com2ptr1 = &db.get_component<ComB>(ent);
     REQUIRE(com2ptr1 != nullptr);
@@ -57,14 +57,14 @@ TEST_CASE("Components can be added, accessed, and removed from entities", "[gins
     REQUIRE(&db.get_component<ComB>(ent) == com2ptr1);
     REQUIRE(db.get_component<ComB>(ent).y == 4.2);
 
-    db.destroy_component<ComA>(ent);
+    db.remove_component<ComA>(ent);
     REQUIRE(db.has_component<ComA>(ent) == false);
     REQUIRE(db.has_component<ComB>(ent) == true);
 
     REQUIRE(&db.get_component<ComB>(ent) == com2ptr1);
     REQUIRE(db.get_component<ComB>(ent).y == 4.2);
 
-    db.destroy_component<ComB>(ent);
+    db.remove_component<ComB>(ent);
     REQUIRE(db.has_component<ComA>(ent) == false);
     REQUIRE(db.has_component<ComB>(ent) == false);
 }
@@ -82,10 +82,10 @@ TEST_CASE("Databases can visit entities with specific components", "[ginseng]")
     auto make_ent = [&](bool give_Data1, bool give_Data2)
     {
         auto ent = db.create_entity();
-        db.create_component(ent, ID{next_id});
+        db.add_component(ent, ID{next_id});
         ++next_id;
-        if (give_Data1) { db.create_component(ent, Data1{7}); }
-        if (give_Data2) { db.create_component(ent, Data2{nullptr}); }
+        if (give_Data1) { db.add_component(ent, Data1{7}); }
+        if (give_Data2) { db.add_component(ent, Data2{nullptr}); }
         return ent;
     };
 
@@ -196,7 +196,7 @@ TEST_CASE("optional can be used instead of components", "[ginseng]")
     struct Data2 {};
 
     auto ent = db.create_entity();
-    db.create_component(ent,Data{});
+    db.add_component(ent,Data{});
 
     int visited = 0;
     optional<Data> mdata;
@@ -224,7 +224,7 @@ TEST_CASE("deleted entites are not revisited", "[ginseng]")
     int visited = 0;
     db.visit([&](ent_id eid){
         ++visited;
-        db.create_component(eid, Data{});
+        db.add_component(eid, Data{});
     });
     REQUIRE(visited == 3);
 

src/test_primary.cpp

@@ -23,7 +23,7 @@ TEST_CASE("Primary components are visited in cache-freindly order", "[ginseng]")
     auto make_ent = [&]()
     {
         auto ent = db.create_entity();
-        db.create_component(ent, ID{next_id});
+        db.add_component(ent, ID{next_id});
         ++next_id;
         return ent;
     };
@@ -35,11 +35,11 @@ TEST_CASE("Primary components are visited in cache-freindly order", "[ginseng]")
     eids.push_back(db.create_entity());
     eids.push_back(db.create_entity());
 
-    db.create_component(eids[1], ID{next_id++});
-    db.create_component(eids[3], ID{next_id++});
-    db.create_component(eids[0], ID{next_id++});
-    db.create_component(eids[4], ID{next_id++});
-    db.create_component(eids[2], ID{next_id++});
+    db.add_component(eids[1], ID{next_id++});
+    db.add_component(eids[3], ID{next_id++});
+    db.add_component(eids[0], ID{next_id++});
+    db.add_component(eids[4], ID{next_id++});
+    db.add_component(eids[2], ID{next_id++});
 
     std::vector<ID*> ptrs;
     ptrs.reserve(5);
@@ -51,11 +51,11 @@ TEST_CASE("Primary components are visited in cache-freindly order", "[ginseng]")
     db.visit([&](ent_id eid, ID& id) { ptrs.push_back(&id); });
     REQUIRE(std::is_sorted(begin(ptrs), end(ptrs)));
 
-    db.create_component(eids[0], Data{7.5});
-    db.create_component(eids[3], Data{7.5});
-    db.create_component(eids[1], Data{7.5});
-    db.create_component(eids[2], Data{7.5});
-    db.create_component(eids[4], Data{7.5});
+    db.add_component(eids[0], Data{7.5});
+    db.add_component(eids[3], Data{7.5});
+    db.add_component(eids[1], Data{7.5});
+    db.add_component(eids[2], Data{7.5});
+    db.add_component(eids[4], Data{7.5});
 
     ptrs.clear();
     db.visit([&](ID& id) { ptrs.push_back(&id); });

src/test_stress.cpp

@@ -22,7 +22,7 @@ TEST_CASE("Component sets can handle many components", "[ginseng]")
     auto make_ent = [&]()
     {
         auto ent = db.create_entity();
-        db.create_component(ent, ID{next_id});
+        db.add_component(ent, ID{next_id});
         ++next_id;
         return ent;
     };

src/test_tags.cpp

@@ -20,7 +20,7 @@ TEST_CASE("tag types do not use dynamic allocation", "[ginseng]")
     struct Sometag2 {};
 
     auto ent = db.create_entity();
-    db.create_component(ent, tag<Sometag>{});
+    db.add_component(ent, tag<Sometag>{});
 
     int visited;