Introduce sceneOnly flag for components (#5465)

* Introduce sceneOnly flag for components * Move sceneOnly and multiplicity checks into Component constructor --------- Co-authored-by: Noeri Huisman <mrxz@users.noreply.github.com>
aframevr · Feb 17, 2024 · 807b1de · 807b1de
1 parent 093fcb8
commit 807b1de
Show file tree

Hide file tree

Showing 19 changed files with 123 additions and 14 deletions.
diff --git a/docs/core/component.md b/docs/core/component.md
@@ -584,6 +584,22 @@ AFRAME.registerComponent('foo', {
 });
 ```
 
+### `sceneOnly`
+
+The `sceneOnly` flag indicates if a component can only be applied to the scene
+entity. Since `sceneOnly` is set to `false` by default, the component can be added
+to any entity. For example, any entity could have a geometry component.
+
+But if a component has `sceneOnly` set to `true`, then the component can only be
+applied to `<a-scene>`:
+
+```js
+AFRAME.registerComponent('foo', {
+  sceneOnly: true,
+  // ...
+});
+```
+
 ### `events`
 
 The `events` object allows for conveniently defining event handlers that get

diff --git a/src/components/scene/ar-hit-test.js b/src/components/scene/ar-hit-test.js
@@ -229,6 +229,8 @@ module.exports.Component = register('ar-hit-test', {
     }
   },
 
+  sceneOnly: true,
+
   init: function () {
     this.hitTest = null;
     this.imageDataArray = new Uint8ClampedArray(512 * 512 * 4);

diff --git a/src/components/scene/background.js b/src/components/scene/background.js
@@ -6,6 +6,7 @@ module.exports.Component = register('background', {
     color: { type: 'color', default: 'black' },
     transparent: { default: false }
   },
+  sceneOnly: true,
   update: function () {
     var data = this.data;
     var object3D = this.el.object3D;

diff --git a/src/components/scene/debug.js b/src/components/scene/debug.js
@@ -1,5 +1,6 @@
 var register = require('../../core/component').registerComponent;
 
 module.exports.Component = register('debug', {
-  schema: {default: true}
+  schema: {default: true},
+  sceneOnly: true
 });
diff --git a/src/components/scene/device-orientation-permission-ui.js b/src/components/scene/device-orientation-permission-ui.js
@@ -30,6 +30,8 @@ module.exports.Component = registerComponent('device-orientation-permission-ui',
     cancelButtonText: {default: 'Cancel'}
   },
 
+  sceneOnly: true,
+
   init: function () {
     var self = this;
 

diff --git a/src/components/scene/embedded.js b/src/components/scene/embedded.js
@@ -8,6 +8,8 @@ module.exports.Component = registerComponent('embedded', {
 
   schema: {default: true},
 
+  sceneOnly: true,
+
   update: function () {
     var sceneEl = this.el;
     var enterVREl = sceneEl.querySelector('.a-enter-vr');

diff --git a/src/components/scene/fog.js b/src/components/scene/fog.js
@@ -17,16 +17,13 @@ module.exports.Component = register('fog', {
     type: {default: 'linear', oneOf: ['linear', 'exponential']}
   },
 
+  sceneOnly: true,
+
   update: function () {
     var data = this.data;
     var el = this.el;
     var fog = this.el.object3D.fog;
 
-    if (!el.isScene) {
-      warn('Fog component can only be applied to <a-scene>');
-      return;
-    }
-
     // (Re)create fog if fog doesn't exist or fog type changed.
     if (!fog || data.type !== fog.name) {
       el.object3D.fog = getFog(data);

diff --git a/src/components/scene/inspector.js b/src/components/scene/inspector.js
@@ -25,6 +25,8 @@ module.exports.Component = registerComponent('inspector', {
     url: {default: INSPECTOR_URL}
   },
 
+  sceneOnly: true,
+
   init: function () {
     this.firstPlay = true;
     this.onKeydown = this.onKeydown.bind(this);

diff --git a/src/components/scene/keyboard-shortcuts.js b/src/components/scene/keyboard-shortcuts.js
@@ -7,6 +7,8 @@ module.exports.Component = registerComponent('keyboard-shortcuts', {
     exitVR: {default: true}
   },
 
+  sceneOnly: true,
+
   init: function () {
     this.onKeyup = this.onKeyup.bind(this);
   },

diff --git a/src/components/scene/pool.js b/src/components/scene/pool.js
@@ -19,6 +19,8 @@ module.exports.Component = registerComponent('pool', {
     dynamic: {default: false}
   },
 
+  sceneOnly: true,
+
   multiple: true,
 
   initPool: function () {

diff --git a/src/components/scene/real-world-meshing.js b/src/components/scene/real-world-meshing.js
@@ -18,6 +18,8 @@ module.exports.Component = register('real-world-meshing', {
     planeMixin: {default: ''}
   },
 
+  sceneOnly: true,
+
   init: function () {
     var webxrData = this.el.getAttribute('webxr');
     var requiredFeaturesArray = webxrData.requiredFeatures;

diff --git a/src/components/scene/reflection.js b/src/components/scene/reflection.js
@@ -26,6 +26,7 @@ module.exports.Component = register('reflection', {
   schema: {
     directionalLight: { type: 'selector' }
   },
+  sceneOnly: true,
   init: function () {
     var self = this;
     this.cubeRenderTarget = new THREE.WebGLCubeRenderTarget(16);

diff --git a/src/components/scene/screenshot.js b/src/components/scene/screenshot.js
@@ -50,6 +50,8 @@ module.exports.Component = registerComponent('screenshot', {
     camera: {type: 'selector'}
   },
 
+  sceneOnly: true,
+
   setup: function () {
     var el = this.el;
     if (this.canvas) { return; }

diff --git a/src/components/scene/stats.js b/src/components/scene/stats.js
@@ -14,6 +14,8 @@ var ThreeStats = window.threeStats;
 module.exports.Component = registerComponent('stats', {
   schema: {default: true},
 
+  sceneOnly: true,
+
   init: function () {
     var scene = this.el;
 

diff --git a/src/components/scene/xr-mode-ui.js b/src/components/scene/xr-mode-ui.js
@@ -26,6 +26,8 @@ module.exports.Component = registerComponent('xr-mode-ui', {
     XRMode: {default: 'vr', oneOf: ['vr', 'ar', 'xr']}
   },
 
+  sceneOnly: true,
+
   init: function () {
     var self = this;
     var sceneEl = this.el;

diff --git a/src/core/a-entity.js b/src/core/a-entity.js
@@ -310,12 +310,7 @@ class AEntity extends ANode {
     // Initialize dependencies first
     this.initComponentDependencies(componentName);
 
-    // If component name has an id we check component type multiplicity.
-    if (componentId && !COMPONENTS[componentName].multiple) {
-      throw new Error('Trying to initialize multiple ' +
-                      'components of type `' + componentName +
-                      '`. There can only be one component of this type per entity.');
-    }
+    // Initialize component
     component = new COMPONENTS[componentName].Component(this, data, componentId);
     if (this.isPlaying) { component.play(); }
 

diff --git a/src/core/component.js b/src/core/component.js
@@ -36,6 +36,19 @@ var emptyInitialOldData = Object.freeze({});
  */
 var Component = module.exports.Component = function (el, attrValue, id) {
   var self = this;
+
+  // If component is sceneOnly check the entity is the scene element
+  if (this.sceneOnly && !el.isScene) {
+    throw new Error('Component `' + this.name + '` can only be applied to <a-scene>');
+  }
+
+  // If component name has an id we check component type multiplicity.
+  if (id && !this.multiple) {
+    throw new Error('Trying to initialize multiple ' +
+                    'components of type `' + this.name +
+                    '`. There can only be one component of this type per entity.');
+  }
+
   this.el = el;
   this.id = id;
   this.attrName = this.name + (id ? '__' + id : '');
@@ -699,6 +712,7 @@ module.exports.registerComponent = function (name, definition) {
     isSinglePropertyObject: NewComponent.prototype.isSinglePropertyObject,
     isObjectBased: NewComponent.prototype.isObjectBased,
     multiple: NewComponent.prototype.multiple,
+    sceneOnly: NewComponent.prototype.sceneOnly,
     name: name,
     parse: NewComponent.prototype.parse,
     parseAttrValueForCache: NewComponent.prototype.parseAttrValueForCache,

diff --git a/tests/components/scene/fog.test.js b/tests/components/scene/fog.test.js
@@ -5,7 +5,6 @@ suite('fog', function () {
   setup(function (done) {
     this.entityEl = entityFactory();
     var el = this.el = this.entityEl.parentNode;
-    var self = this;
 
     el.addEventListener('loaded', function () {
       // Stub scene load to avoid WebGL code.
@@ -18,8 +17,14 @@ suite('fog', function () {
 
   test('does not set fog for entities', function () {
     var entityEl = this.entityEl;
-    entityEl.setAttribute('fog', '');
+    try {
+      entityEl.setAttribute('fog', '');
+      assert.fail();
+    } catch (e) {
+      assert.equal(e.message, 'Component `fog` can only be applied to <a-scene>');
+    }
     assert.notOk(entityEl.object3D.fog);
+    assert.notOk(entityEl.components['fog']);
   });
 
   suite('update', function () {

diff --git a/tests/core/component.test.js b/tests/core/component.test.js
@@ -642,6 +642,65 @@ suite('Component', function () {
     });
   });
 
+  suite('sceneOnly components', function () {
+    var el;
+    var TestComponent;
+    setup(function () {
+      el = entityFactory();
+      delete components.test;
+      TestComponent = registerComponent('test', { sceneOnly: true });
+    });
+
+    test('allows instantiating sceneOnly component on scene element', function () {
+      el.sceneEl.setAttribute('test', '');
+      assert.ok(el.sceneEl.components['test']);
+    });
+
+    test('throws error when instantiating sceneOnly component on entities', function () {
+      try {
+        el.setAttribute('test', '');
+        assert.fail();
+      } catch (e) {
+        assert.equal(e.message, 'Component `test` can only be applied to <a-scene>');
+      }
+      assert.notOk(el.components['test']);
+    });
+  });
+
+  suite('multiple components', function () {
+    var el;
+    setup(function () {
+      el = entityFactory();
+      delete components.test;
+    });
+
+    test('allows multiple instances on element with ids when component has multiple flag', function () {
+      var TestComponent = registerComponent('test', { multiple: true });
+      var first = new TestComponent(el, 'data', 'first');
+      var second = new TestComponent(el, 'data', 'second');
+      assert.notOk(el.components['test']);
+      assert.equal(el.components['test__first'], first);
+      assert.equal(el.components['test__second'], second);
+    });
+
+    test('allows instance without id even when component has multiple flag', function () {
+      var TestComponent = registerComponent('test', { multiple: true });
+      var component = new TestComponent(el, 'data', '');
+      assert.equal(el.components['test'], component);
+    });
+
+    test('throws error when instantiating with id when component does not have multiple flag', function () {
+      var TestComponent = registerComponent('test', { multiple: false });
+      try {
+        var component = new TestComponent(el, 'data', 'some-id');
+        assert.fail();
+      } catch (e) {
+        assert.equal(e.message, 'Trying to initialize multiple components of type `test`. ' +
+                                'There can only be one component of this type per entity.');
+      }
+    });
+  });
+
   suite('third-party components', function () {
     var el;
     setup(function (done) {