add a getEntity function for convenience/syntax sugar

README.md

@@ -135,6 +135,17 @@ gameLoop()
 ```
 
 
+### get a single entity
+
+Sometimes you just want a single entity, like for singleton objects (player's character for example).
+
+```javascript
+const h = ECS.getEntities(world, [ 'hero' ])[0]  // kinda kludgy
+
+const h = ECS.getEntity(world, [ 'hero' ])       // same result, less typing
+```
+
+
 ### not filter
 
 Sometimes it's useful to query by components that are _not_ present:
@@ -186,8 +197,6 @@ ECS.getEntities(world, [ 'test_component' ]).length  // because we are not defer
 ```
 
 
-
-
 ### devtools chrome extension
 
 If you'd like to see a real time view of the data in your ECS powered program, there is a dev tools extension!

ecs.js

@@ -330,6 +330,21 @@ export function getEntities (world, componentNames, listenerType, listenerEntiti
 }
 
 
+/**
+ * Get one entity from the world with all provided components. Optionally,
+ * @param {World} world 
+ * @param {string[]} componentNames A component filter used to match entities. 
+ * Must match all of the components in the filter.
+ * Can add an exclamation mark at the beginning to query by components that are not present. For example:
+ * `const e = ECS.getEntity(world, [ 'transform', '!hero' ])`
+ * 
+ * @returns {Entity|void} one entity that matches the given filters or undefined if none match
+ */
+export function getEntity (world, componentNames) {
+    return getEntities(world, componentNames)[0]
+}
+
+
 /**
  * returns true if an entity contains all the components that match the filter
  * all entities having at least one component in the ignore list are excluded.
@@ -667,6 +682,7 @@ export default {
     addComponentToEntity,
     removeComponentFromEntity,
     getEntities,
+    getEntity,
     removeEntity,
     addSystem,
     preFixedUpdate,

test/getEntity.js

@@ -0,0 +1,40 @@
+import ECS from '../ecs.js'
+import tap from 'tap'
+
+
+{
+	const w = ECS.createWorld()
+
+	const h = ECS.getEntity(w, [ 'hero' ])
+
+	tap.equal(h, undefined, 'no match returns undefined')
+}
+
+
+{
+	const w = ECS.createWorld()
+
+	const e = ECS.createEntity(w)
+	ECS.addComponentToEntity(w, e, 'hero')
+
+	const h = ECS.getEntity(w, [ 'hero' ])
+
+	tap.equal(h, e, 'finds 1 matching entity')
+}
+
+
+{
+	const w = ECS.createWorld()
+
+	const e = ECS.createEntity(w)
+	ECS.addComponentToEntity(w, e, 'hero')
+	ECS.addComponentToEntity(w, e, 'a')
+
+	const e2 = ECS.createEntity(w)
+	ECS.addComponentToEntity(w, e2, 'hero')
+	ECS.addComponentToEntity(w, e2, 'b')
+
+	const h = ECS.getEntity(w, [ 'hero' ])
+
+	tap.equal(h, e, 'returns the first match even if there are more than one')
+}