oxygen-core/src/systems/EntitySystem/Entity.js

Oxygen game engine (Xenon Core for browsers)

import Component from './Component';
import EntitySystem from '.';
import { mat4, quat, vec3 } from '../../utils/gl-matrix';
import { findMapKeyOfValue } from '../../utils';

const zVector = vec3.fromValues(0, 0, 1);
const cachedTempVec3 = vec3.create();

/**
 * Entity - actor of the scene, container for behaviour components.
 *
 * @example
 * const entity = new Entity();
 * entity.deserialize({ name: 'hey', components: { Hello: { hello: 'world' } } });
 * const hello = entity.getComponent('Hello');
 * console.log(hello.hello);
 */
export default class Entity {

  /** @type {EntitySystem|null} */
  get owner() {
    return this._owner;
  }

  /** @type {string|null} */
  get name() {
    return this._name;
  }

  /** @type {string|null} */
  set name(value) {
    if (!!value && typeof value != 'string') {
      throw new Error('`value` is not type of String!');
    }

    this._name = value || '';
  }

  /** @type {string|null} */
  get tag() {
    return this._tag;
  }

  /** @type {string|null} */
  set tag(value) {
    if (!!value && typeof value != 'string') {
      throw new Error('`value` is not type of String!');
    }

    this._tag = value || '';
  }

  /** @type {boolean} */
  get active() {
    return this._active;
  }

  /** @type {boolean} */
  set active(value) {
    if (typeof value !== 'boolean') {
      throw new Error('`value` is not type of Boolean!');
    }

    this._active = value;
  }

  /** @type {string} */
  get path() {
    let result = `/${this._name}`;
    let current = this._parent;
    while (!!current) {
      result = `/${current.name}${result}`;
      current = current._parent;
    }
    return result;
  }

  /** @type {Entity} */
  get root() {
    let result = this;
    let current = this._parent;
    while (!!current) {
      result = current;
      current = current._parent;
    }
    return result;
  }

  /** @type {Entity|null} */
  get parent() {
    return this._parent;
  }

  /** @type {Entity|null} */
  set parent(value) {
    this.reparent(value);
  }

  /** @type {number} */
  get childrenCount() {
    return this._children.length;
  }

  /** @type {number} */
  get indexInParent() {
    const { _parent } = this;
    return !_parent ? -1 : _parent._children.indexOf(this);
  }

  /** @type {mat4} */
  get transformLocal() {
    return this._transformLocal;
  }

  /** @type {mat4} */
  get transform() {
    return this._transform;
  }

  /** @type {mat4} */
  get inverseTransform() {
    return this._inverseTransform;
  }

  /** @type {vec3} */
  get position() {
    return this._position;
  }

  /** @type {quat} */
  get rotation() {
    return this._rotation;
  }

  /** @type {vec3} */
  get scale() {
    return this._scale;
  }

  /** @type {vec3} */
  get globalPosition() {
    const result = vec3.create();
    vec3.set(cachedTempVec3, 0, 0, 0);
    return vec3.transformMat4(result, cachedTempVec3, this._transform);
  }

  /** @type {*} */
  get componentNames() {
    return this._components.keys();
  }

  /** @type {Function|null} */
  get childrenSorting() {
    return this._childrenSorting;
  }

  /** @type {Function|null} */
  set childrenSorting(value) {
    if (!value) {
      this._childrenSorting = null;
      return;
    }
    if (!(value instanceof Function)) {
      throw new Error('`value` is not type of Function!');
    }

    this._childrenSorting = value;
    this.sortChildren();
  }

  /** @type {*} */
  get meta() {
    return this._meta;
  }

  /**
   * Constructor.
   */
  constructor() {
    this._owner = null;
    this._name = '';
    this._tag = '';
    this._active = true;
    this._children = [];
    this._parent = null;
    this._components = new Map();
    this._transformLocal = mat4.create();
    this._transform = mat4.create();
    this._inverseTransform = mat4.create();
    this._position = vec3.create();
    this._rotation = quat.create();
    this._scale = vec3.fromValues(1, 1, 1);
    this._childrenSorting = null;
    this._meta = {};
    this._dirty = true;
  }

  /**
   * Destructor (disposes internal resources).
   *
   * @example
   * entity.dispose();
   * entity = null;
   */
  dispose() {
    const { _children, _components } = this;

    this.reparent(null);

    for (let i = _children.length - 1; i >= 0; --i) {
      _children[i].dispose();
    }

    for (const component of _components.values()) {
      component.dispose();
    }

    this._owner = null;
    this._name = null;
    this._tag = null;
    this._children = null;
    this._parent = null;
    this._components = null;
    this._transformLocal = null;
    this._transform = null;
    this._inverseTransform = null;
    this._position = null;
    this._rotation = null;
    this._scale = null;
    this._childrenSorting = null;
    this._meta = null;
  }

  /**
   * Make this entity and it's children active.
   *
   * @example
   * entity.activete();
   * entity.active === true;
   */
  activate() {
    this.active = true;

    const { _children } = this;
    for (let i = 0, c = _children.length; i < c; ++i) {
      _children[i].activate();
    }
  }

  /**
   * Make this entity and it's children inactive.
   *
   * @example
   * entity.deactivete();
   * entity.active === false;
   */
  deactivate() {
    this.active = false;

    const { _children } = this;
    for (let i = 0, c = _children.length; i < c; ++i) {
      _children[i].deactivate();
    }
  }

  /**
   * Serialize this entity into JSON data.
   *
   * @return {*} Serialized JSON data.
   *
   * @example
   * entity.name = 'serialized';
   * const json = entity.serialize();
   * json.name === 'serialized';
   */
  serialize() {
    const name = this._name || '';
    const tag = this._tag || '';
    const active = this._active;
    const position = [ ...this._position ];
    const scale = [ ...this._scale ];
    const rotation = this.getRotation() * 180 / Math.PI;
    const result = {
      name,
      tag,
      active,
      meta: {},
      transform: {
        position,
        rotation,
        scale
      },
      components: {},
      children: []
    };

    for (const key in this._meta) {
      result.meta[key] = this._meta[key];
    }

    for (const [key, value] of this._components) {
      result.components[key] = value.serialize();
    }

    for (const child of this._children) {
      result.children.push(child.serialize());
    }

    return result;
  }

  /**
   * Deserialize JSON data into this entity.
   *
   * @param {*}	json - Serialized entity JSON data.
   *
   * @example
   * entity.deserialize({ name: 'deserialized' });
   * entity.name === 'deserialized';
   */
  deserialize(json) {
    if (!json) {
      return;
    }

    if (typeof json.name !== 'undefined') {
      this.name = json.name;
    }

    if (typeof json.tag !== 'undefined') {
      this.tag = json.tag;
    }

    if (typeof json.active !== 'undefined') {
      this.active = json.active;
    }

    const { meta, transform, components } = json;

    if (!!meta) {
      const { _meta } = this;

      for (const name in meta) {
        _meta[name] = meta[name];
      }
    }

    if (!!transform) {
      const { position, rotation, scale } = transform;

      if (typeof position === 'number') {
        this.setPosition(position, position);
      } else if (!!position && position.length >= 2) {
        this.setPosition(position[0], position[1]);
      }

      if (typeof rotation === 'number') {
        this.setRotation(rotation * Math.PI / 180);
      }

      if (typeof scale === 'number') {
        this.setScale(scale, scale);
      } else if (!!scale && scale.length >= 2) {
        this.setScale(scale[0], scale[1]);
      }
    }

    if (!!components) {
      const { _components } = this;

      for (const name in components) {
        if (_components.has(name)) {
          _components.get(name).deserialize(components[name]);
        }
      }
    }
  }

  /**
   * Set entity local position.
   *
   * @param {number}	x - Local X position.
   * @param {number}	y - Local Y position.
   * @param {number}	z - Local Z position.
   *
   * @example
   * entity.setPosition(40, 2);
   */
  setPosition(x, y, z = 0) {
    if (typeof x !== 'number') {
      throw new Error('`x` is not type of Number!');
    }
    if (typeof y !== 'number') {
      throw new Error('`y` is not type of Number!');
    }
    if (typeof z !== 'number') {
      throw new Error('`z` is not type of Number!');
    }

    vec3.set(this._position, x, y, z);
    this._dirty = true;
  }

  /**
   * Set entity local Z axis rotation.
   *
   * @param {number}	rad - Z axis radian angle.
   *
   * @example
   * entity.setRotation(90 * Math.PI / 180);
   */
  setRotation(rad) {
    if (typeof rad !== 'number') {
      throw new Error('`rad` is not type of Number!');
    }

    quat.setAxisAngle(this._rotation, zVector, rad);
    this._dirty = true;
  }

  /**
   * Set entity local rotation from euler degrees.
   *
   * @param {number}	x - X axis degree rotation.
   * @param {number}	y - Y axis degree rotation.
   * @param {number}	z - Z axis degree rotation.
   *
   * @example
   * entity.setRotationEuler(15, 30, 45);
   */
  setRotationEuler(x, y, z) {
    if (typeof x !== 'number') {
      throw new Error('`x` is not type of Number!');
    }
    if (typeof y !== 'number') {
      throw new Error('`y` is not type of Number!');
    }
    if (typeof z !== 'number') {
      throw new Error('`z` is not type of Number!');
    }

    quat.fromEuler(this._rotation, x, y, z);
    this._dirty = true;
  }

  /**
   * Get entity local Z axis radian rotation.
   *
   * @return {number} Z axis local radian rotation.
   *
   * @example
   * console.log(entity.getRotation());
   */
  getRotation() {
    return quat.getAxisAngle(cachedTempVec3, this._rotation) * cachedTempVec3[2];
  }

  /**
   * Get entity local euler axis rotation in degrees.
   *
   * @param {vec3}	result - Result vec3 object.
   *
   * @example
   * const euler = vec3.create();
   * entity.getRotationEuler(euler);
   * console.log(euler);
   */
  getRotationEuler(result) {
    if (!result) {
      throw new Error('`result` cannot be null!');
    }

    const rad2deg = 180 / Math.PI;
    const angle = quat.getAxisAngle(cachedTempVec3, this._rotation);
    vec3.set(
      result,
      cachedTempVec3[0] * angle * rad2deg,
      cachedTempVec3[1] * angle * rad2deg,
      cachedTempVec3[2] * angle * rad2deg
    );
  }

  /**
   * Set entity local scale.
   *
   * @param {number}	x - Local X scale.
   * @param {number}	y - Local Y scale.
   * @param {number}	z - Local Z scale.
   *
   * @example
   * entity.setScale(2, 3);
   */
  setScale(x, y, z = 1) {
    if (typeof x !== 'number') {
      throw new Error('`x` is not type of Number!');
    }
    if (typeof y !== 'number') {
      throw new Error('`y` is not type of Number!');
    }
    if (typeof z !== 'number') {
      throw new Error('`z` is not type of Number!');
    }

    vec3.set(this._scale, x, y, z);
    this._dirty = true;
  }

  /**
   * Get entity children at given index.
   *
   * @param {number}	index - Child index.
   *
   * @return {Entity} Child entity instance.
   */
  getChild(index) {
    if (typeof index !== 'number') {
      throw new Error('`index` is not type of Number!');
    }

    const { _children } = this;

    if (index < 0 || index >= _children.length) {
      throw new Error('`index` is out of bounds!');
    }

    return _children[index];
  }

  /**
   * Kills all entity children (calls dispose on them and removes them from entity).
   *
   * @example
   * entity.killChildren();
   */
  killChildren() {
    const { _children } = this;
    const container = new Set(_children);

    for (const child of container) {
      child.dispose();
    }
    container.clear();
  }

  /**
   * Rebind entity to different parent.
   *
   * @param {Entity|null}	entity - New parent entity or null if not bound to any entity.
   * @param {number}	insertAt - Child index at given should be placed this entity in new parent
   *
   * @example
   * entity.reparent(system.root);
   */
  reparent(entity, insertAt = -1) {
    if (!!entity && !(entity instanceof Entity)) {
      throw new Error('`entity` is not type of Entity!');
    }
    if (typeof insertAt !== 'number') {
      throw new Error('`insertAt` is not type of Number!');
    }

    const { _parent } = this;

    if (entity === _parent) {
      return;
    }

    this._parent = entity;

    if (!!_parent) {
      const { _children } = _parent;
      const found = _children.indexOf(this);

      if (found >= 0) {
        this._setOwner(null);
        _children.splice(found, 1);
      }
      _parent.sortChildren();
    }

    if (!!entity) {
      if (insertAt < 0) {
        entity._children.push(this);
      } else {
        entity._children.splice(insertAt, 0, this);
      }
      this._setOwner(entity.owner);
      entity.sortChildren();
    }
  }

  /**
   * Find entity by it's name or path in scene tree.
   *
   * @param {string}	name - Entity name or path.
   *
   * @return {Entity|null} Found entity instance or null if not found.
   *
   * @example
   * entity.findEntity('./some-child');
   * entity.findEntity('/root-child');
   * entity.findEntity('/root-child/some-child');
   */
  findEntity(name) {
    if (typeof name !== 'string') {
      throw new Error('`name` is not type of String!');
    }

    let current = this;
    while (!!current && name.length > 0) {
      const found = name.indexOf('/');

      if (found === 0) {
        while (!!current._parent) {
          current = current._parent;
        }

        name = name.substr(found + 1);
      } else {
        const part = found > 0 ? name.substr(0, found) : name;

        if (part === '.') {
          // do nothing

        } else if (part === '..') {
          current = current._parent;

        } else {
          const { _children } = current;
          let found = false;

          for (let i = 0, c = _children.length; i < c; ++i) {
            const child = _children[i];

            if (child.name === part) {
              current = child;
              found = true;
              break;
            }
          }

          if (!found) {
            return null;
          }

        }

        if (found < 0) {
          return current;
        }

        name = name.substr(found + 1);
      }
    }

    return current;
  }

  /**
   * Attach component to this entity.
   *
   * @param {string}	typename - Component type name.
   * @param {Component}	component - Component instance.
   *
   * @example
   * entity.attachComponent('MyComponent', new MyComponent());
   * entity.attachComponent('Hello', new Hello());
   */
  attachComponent(typename, component) {
    if (typeof typename !== 'string') {
      throw new Error('`typename` is not type of String!');
    }
    if (!(component instanceof Component)) {
      throw new Error('`component` is not type of Component!');
    }

    const { _components } = this;

    if (_components.has(typename)) {
      throw new Error(
        `Given component type is already attached to entity: ${typename}`
      );
    }

    _components.set(typename, component);
    component._owner = this;
    if (!!this._owner && !!this._owner.triggerEvents) {
      component.onAttach();
    }
  }

  /**
   * Detach component by it's type name.
   *
   * @param {string}	typename - Component type name.
   *
   * @example
   * entity.detachComponent('Hello');
   */
  detachComponent(typename) {
    const { _components } = this;
    let component = typename;

    if (typeof typename === 'string') {
      component = _components.get(typename);
    } else if (component instanceof Component) {
      typename = findMapKeyOfValue(_components, component);
    } else {
      throw new Error('`typename` is not type of either Component or String!');
    }

    if (_components.delete(typename)) {
      component._owner = null;
      if (!!this._owner && !!this._owner.triggerEvents) {
        component.onDetach();
      }
    } else {
      throw new Error(`Trying to remove non-attached component type: ${typename}`);
    }
  }

  /**
   * Find component by it's type name.
   *
   * @param {string|Function}	typename - Component type (class or name).
   *
   * @return {Component|null} Component instance if found or null otherwise.
   *
   * @example
   * class Hello extends Component {}
   * entity.attachComponent('Hello', new Hello());
   * const hello1 = entity.getComponent('Hello');
   * const hello2 = entity.getComponent(Hello);
   */
  getComponent(typename) {
    if (typeof typename === 'string') {
      return this._components.get(typename) || null;
    } else if (typename instanceof Function) {
      for (const c of this._components.values()) {
        if (c instanceof typename) {
          return c;
        }
      }
      return null;
    }

    throw new Error('`typename` is not type of either String or Function!');
  }

  /**
   * Perform action on entity.
   *
   * @param {string}	name - Action name.
   * @param {*}	args - Action parameters.
   *
   * @example
   * class Hi extends Component { onAction(name, wat) { if (name === 'hi') console.log(wat); } }
   * entity.attachComponent('Hi', new Hi());
   * entity.performAction('hi', 'hello');
   */
  performAction(name, ...args) {
    if (typeof name !== 'string') {
      throw new Error('`name` is not type of String!');
    }
    if (!this._active) {
      return;
    }

    const { _components, _children } = this;
    let status = false;
    let a = args;

    for (const component of _components.values()) {
      status = !!component.onAction(name, ...a) || status;
      a = component.onAlterActionArguments(name, a) || a;
    }

    if (status) {
      return;
    }

    for (let i = 0, c = _children.length; i < c; ++i) {
      _children[i].performAction(name, ...a);
    }
  }

  /**
   * Perform action only on components (do not pass action further to children).
   * See: {@link performAction}
   *
   * @param {string}	name - Action name.
   * @param {*}	args - Action parameters.
   */
  performActionOnComponents(name, ...args) {
    if (typeof name !== 'string') {
      throw new Error('`name` is not type of String!');
    }
    if (!this._active) {
      return;
    }

    const { _components } = this;
    let a = args;

    for (const component of _components.values()) {
      !!component.onAction(name, ...a);
      a = component.onAlterActionArguments(name, a) || a;
    }
  }

  /**
   * Perform custom callback action on entity components of given type and it's children.
   *
   * @param {string|null}	id - Affected component type (can be null if want to call every component).
   * @param {Function}	action - Custom action callback. Callback gets one argument with component instance.
   *
   * @example
   * entity.performOnComponents('Hello', component => console.log(component.hello));
   */
  performOnComponents(id, action) {
    if (!!id && typeof id !== 'string') {
      throw new Error('`id` is not type of String!');
    }
    if (!(action instanceof Function)) {
      throw new Error('`action` is not type of Function!');
    }

    if (!!id) {
      const component = this.getComponent(id);
      if (!!component) {
        action(component);
      }
    } else {
      const { _components } = this;
      for (const component of _components.values()) {
        action(component);
      }
    }

    const { _children } = this;
    for (let i = 0, c = _children.length; i < c; ++i) {
      _children[i].performOnComponents(id, action);
    }
  }

  /**
   * Perform custom callback action only on entity and optionally it's children.
   *
   * @param {Function}	action - Custom action callback. Callback gets one argument with child instance.
   * @param {boolean}	deep - True if should be called on it's children.
   *
   * @example
   * entity.performOnChildren(e => console.log(e.name));
   */
  performOnChildren(action, deep = false) {
    if (!(action instanceof Function)) {
      throw new Error('`action` is not type of Function!');
    }

    const { _children } = this;
    for (let i = 0, c = _children.length; i < c; ++i) {
      const child = _children[i];

      action(child);
      if (!!deep) {
        child.performOnChildren(action, deep);
      }
    }
  }

  /**
   * Update entity ant it's children transforms.
   *
   * @param {mat4}	parentTransform - Parent transformation.
   * @param {boolean}	forced - If true ignore optimizations and update anyway.
   *
   * @example
   * entity.updateTransforms();
   */
  updateTransforms(parentTransform, forced = false) {
    if (!this._active) {
      return;
    }

    const {
      _children,
      _transform,
      _inverseTransform,
      _transformLocal,
      _position,
      _rotation,
      _scale
    } = this;

    if (!!forced || this._dirty) {
      mat4.fromRotationTranslationScale(
        _transformLocal,
        _rotation,
        _position,
        _scale
      );

      mat4.multiply(_transform, parentTransform, _transformLocal);
      mat4.invert(_inverseTransform, _transform);

      forced = true;
      this._dirty = false;
    }

    for (let i = 0, c = _children.length; i < c; ++i) {
      _children[i].updateTransforms(_transform, forced);
    }
  }

  /**
   * Sort children by entity childrenSorting function if set.
   */
  sortChildren() {
    const { _childrenSorting, _children } = this;
    if (!_childrenSorting) {
      return;
    }

    _children.sort(_childrenSorting);
  }

  /**
   * Transform coordinate from this entity local space into other entity local space.
   *
   * @param {vec3} target - Result vec3 value.
   * @param {vec3} coord - Input vec3 value.
   * @param {Entity} entity - Other entity.
   */
  transformCoord(target, coord, entity) {
    if (!(entity instanceof Entity)) {
      throw new Error('`entity` is not type of Entity!');
    }

    vec3.transformMat4(cachedTempVec3, coord, this.transform);
    vec3.transformMat4(cachedTempVec3, cachedTempVec3, entity.inverseTransform);
  }

  _setOwner(owner) {
    const { _owner, _components, _children } = this;
    if (!!owner === !!_owner) {
      return;
    }

    if (!!_owner && !!_owner.triggerEvents) {
      for (const component of _components.values()) {
        component.onDetach();
      }
    }

    this._owner = owner;

    if (!!owner && !!owner.triggerEvents) {
      for (const component of _components.values()) {
        component.onAttach();
      }
    }

    for (let i = 0, c = _children.length; i < c; ++i) {
      _children[i]._setOwner(owner);
    }
  }

}