miniplex/dist/miniplex.cjs.dev.js

A developer-friendly entity management system for games and similarly demanding applications, based on ECS architecture.

'use strict';

Object.defineProperty(exports, '__esModule', { value: true });

var bucket = require('@miniplex/bucket');
var id = require('@hmans/id');
var queue$1 = require('@hmans/queue');

function _arrayLikeToArray(arr, len) {
  if (len == null || len > arr.length) len = arr.length;
  for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i];
  return arr2;
}

function _arrayWithoutHoles(arr) {
  if (Array.isArray(arr)) return _arrayLikeToArray(arr);
}

function _iterableToArray(iter) {
  if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
}

function _unsupportedIterableToArray(o, minLen) {
  if (!o) return;
  if (typeof o === "string") return _arrayLikeToArray(o, minLen);
  var n = Object.prototype.toString.call(o).slice(8, -1);
  if (n === "Object" && o.constructor) n = o.constructor.name;
  if (n === "Map" || n === "Set") return Array.from(o);
  if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen);
}

function _nonIterableSpread() {
  throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
}

function _toConsumableArray(arr) {
  return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _unsupportedIterableToArray(arr) || _nonIterableSpread();
}

function _getPrototypeOf(o) {
  _getPrototypeOf = Object.setPrototypeOf ? Object.getPrototypeOf.bind() : function _getPrototypeOf(o) {
    return o.__proto__ || Object.getPrototypeOf(o);
  };
  return _getPrototypeOf(o);
}

function _superPropBase(object, property) {
  while (!Object.prototype.hasOwnProperty.call(object, property)) {
    object = _getPrototypeOf(object);
    if (object === null) break;
  }
  return object;
}

function _get() {
  if (typeof Reflect !== "undefined" && Reflect.get) {
    _get = Reflect.get.bind();
  } else {
    _get = function _get(target, property, receiver) {
      var base = _superPropBase(target, property);
      if (!base) return;
      var desc = Object.getOwnPropertyDescriptor(base, property);
      if (desc.get) {
        return desc.get.call(arguments.length < 3 ? target : receiver);
      }
      return desc.value;
    };
  }
  return _get.apply(this, arguments);
}

function _createForOfIteratorHelper(o, allowArrayLike) {
  var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"];
  if (!it) {
    if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") {
      if (it) o = it;
      var i = 0;
      var F = function () {};
      return {
        s: F,
        n: function () {
          if (i >= o.length) return {
            done: true
          };
          return {
            done: false,
            value: o[i++]
          };
        },
        e: function (e) {
          throw e;
        },
        f: F
      };
    }
    throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
  }
  var normalCompletion = true,
    didErr = false,
    err;
  return {
    s: function () {
      it = it.call(o);
    },
    n: function () {
      var step = it.next();
      normalCompletion = step.done;
      return step;
    },
    e: function (e) {
      didErr = true;
      err = e;
    },
    f: function () {
      try {
        if (!normalCompletion && it.return != null) it.return();
      } finally {
        if (didErr) throw err;
      }
    }
  };
}

function _toPrimitive(input, hint) {
  if (typeof input !== "object" || input === null) return input;
  var prim = input[Symbol.toPrimitive];
  if (prim !== undefined) {
    var res = prim.call(input, hint || "default");
    if (typeof res !== "object") return res;
    throw new TypeError("@@toPrimitive must return a primitive value.");
  }
  return (hint === "string" ? String : Number)(input);
}

function _toPropertyKey(arg) {
  var key = _toPrimitive(arg, "string");
  return typeof key === "symbol" ? key : String(key);
}

function _defineProperty(obj, key, value) {
  key = _toPropertyKey(key);
  if (key in obj) {
    Object.defineProperty(obj, key, {
      value: value,
      enumerable: true,
      configurable: true,
      writable: true
    });
  } else {
    obj[key] = value;
  }
  return obj;
}

function ownKeys(object, enumerableOnly) {
  var keys = Object.keys(object);
  if (Object.getOwnPropertySymbols) {
    var symbols = Object.getOwnPropertySymbols(object);
    enumerableOnly && (symbols = symbols.filter(function (sym) {
      return Object.getOwnPropertyDescriptor(object, sym).enumerable;
    })), keys.push.apply(keys, symbols);
  }
  return keys;
}
function _objectSpread2(target) {
  for (var i = 1; i < arguments.length; i++) {
    var source = null != arguments[i] ? arguments[i] : {};
    i % 2 ? ownKeys(Object(source), !0).forEach(function (key) {
      _defineProperty(target, key, source[key]);
    }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)) : ownKeys(Object(source)).forEach(function (key) {
      Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
    });
  }
  return target;
}

function _classCallCheck(instance, Constructor) {
  if (!(instance instanceof Constructor)) {
    throw new TypeError("Cannot call a class as a function");
  }
}

function _defineProperties(target, props) {
  for (var i = 0; i < props.length; i++) {
    var descriptor = props[i];
    descriptor.enumerable = descriptor.enumerable || false;
    descriptor.configurable = true;
    if ("value" in descriptor) descriptor.writable = true;
    Object.defineProperty(target, _toPropertyKey(descriptor.key), descriptor);
  }
}
function _createClass(Constructor, protoProps, staticProps) {
  if (protoProps) _defineProperties(Constructor.prototype, protoProps);
  if (staticProps) _defineProperties(Constructor, staticProps);
  Object.defineProperty(Constructor, "prototype", {
    writable: false
  });
  return Constructor;
}

function _assertThisInitialized(self) {
  if (self === void 0) {
    throw new ReferenceError("this hasn't been initialised - super() hasn't been called");
  }
  return self;
}

function _setPrototypeOf(o, p) {
  _setPrototypeOf = Object.setPrototypeOf ? Object.setPrototypeOf.bind() : function _setPrototypeOf(o, p) {
    o.__proto__ = p;
    return o;
  };
  return _setPrototypeOf(o, p);
}

function _inherits(subClass, superClass) {
  if (typeof superClass !== "function" && superClass !== null) {
    throw new TypeError("Super expression must either be null or a function");
  }
  subClass.prototype = Object.create(superClass && superClass.prototype, {
    constructor: {
      value: subClass,
      writable: true,
      configurable: true
    }
  });
  Object.defineProperty(subClass, "prototype", {
    writable: false
  });
  if (superClass) _setPrototypeOf(subClass, superClass);
}

function _isNativeReflectConstruct() {
  if (typeof Reflect === "undefined" || !Reflect.construct) return false;
  if (Reflect.construct.sham) return false;
  if (typeof Proxy === "function") return true;
  try {
    Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function () {}));
    return true;
  } catch (e) {
    return false;
  }
}

function _possibleConstructorReturn(self, call) {
  if (call && (typeof call === "object" || typeof call === "function")) {
    return call;
  } else if (call !== void 0) {
    throw new TypeError("Derived constructors may only return object or undefined");
  }
  return _assertThisInitialized(self);
}

function _createSuper(Derived) {
  var hasNativeReflectConstruct = _isNativeReflectConstruct();
  return function _createSuperInternal() {
    var Super = _getPrototypeOf(Derived),
      result;
    if (hasNativeReflectConstruct) {
      var NewTarget = _getPrototypeOf(this).constructor;
      result = Reflect.construct(Super, arguments, NewTarget);
    } else {
      result = Super.apply(this, arguments);
    }
    return _possibleConstructorReturn(this, result);
  };
}

var _Symbol$iterator;

/**
 * A utility type that marks the specified properties as required.
 */

/**
 * A utility type that removes all optional properties.
 */

/* Utility types */

/* Query configuration */

var World = /*#__PURE__*/function (_ref) {
  _inherits(World, _ref);
  var _super = _createSuper(World);
  function World() {
    var _this;
    var entities = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : [];
    _classCallCheck(this, World);
    _this = _super.call(this, entities);

    /* When entities are added, reindex them immediately */
    /* QUERIES */
    _defineProperty(_assertThisInitialized(_this), "queries", new Set());
    /* IDs */
    _defineProperty(_assertThisInitialized(_this), "entityToId", new Map());
    _defineProperty(_assertThisInitialized(_this), "idToEntity", new Map());
    _defineProperty(_assertThisInitialized(_this), "nextId", 0);
    _this.onEntityAdded.subscribe(function (entity) {
      _this.reindex(entity);
    });

    /* When entities are removed, remove them from all known queries, and delete
    their IDs */
    _this.onEntityRemoved.subscribe(function (entity) {
      _this.queries.forEach(function (query) {
        return query.remove(entity);
      });
      if (_this.entityToId.has(entity)) {
        var _id = _this.entityToId.get(entity);
        _this.idToEntity["delete"](_id);
        _this.entityToId["delete"](entity);
      }
    });
    return _this;
  }
  _createClass(World, [{
    key: "update",
    value: function (_update) {
      function update(_x, _x2, _x3) {
        return _update.apply(this, arguments);
      }
      update.toString = function () {
        return _update.toString();
      };
      return update;
    }(function (entity, update, value) {
      /* Apply the update */
      if (typeof update === "function") {
        var partial = update(entity);
        partial && Object.assign(entity, partial);
      } else if (typeof update === "string") {
        entity[update] = value;
      } else if (update) {
        Object.assign(entity, update);
      }

      /* If this world knows about the entity, reindex it. */
      this.reindex(entity);
      return entity;
    }

    /**
     * Adds a component to an entity. If the entity already has the component, the
     * existing component will not be overwritten.
     *
     * After the component was added, the entity will be reindexed, causing it to be
     * added to or removed from any queries depending on their criteria.
     *
     * @param entity The entity to modify.
     * @param component The name of the component to add.
     * @param value The value of the component to add.
     */)
  }, {
    key: "addComponent",
    value: function addComponent(entity, component, value) {
      /* Return early if the entity already has the component. */
      if (entity[component] !== undefined) return;

      /* Set the component */
      entity[component] = value;

      /* Trigger a reindexing */
      this.reindex(entity);
    }

    /**
     * Removes a component from an entity. If the entity does not have the component,
     * this function does nothing.
     *
     * After the component was removed, the entity will be reindexed, causing it to be
     * added to or removed from any queries depending on their criteria.
     *
     * @param entity The entity to modify.
     * @param component The name of the component to remove.
     */
  }, {
    key: "removeComponent",
    value: function removeComponent(entity, component) {
      /* Return early if the entity doesn't even have the component. */
      if (entity[component] === undefined) return;

      /* If this world knows about the entity, notify any derived buckets about the change. */
      if (this.has(entity)) {
        var future = _objectSpread2({}, entity);
        delete future[component];
        this.reindex(entity, future);
      }

      /* Remove the component. */
      delete entity[component];
    }
  }, {
    key: "query",
    value:
    /**
     * Creates (or reuses) a query that matches the given configuration.
     *
     * @param config The query configuration.
     * @returns A query that matches the given configuration.
     */
    function query(config) {
      var normalizedConfig = normalizeQueryConfiguration(config);
      var key = configKey(normalizedConfig);

      /* Use existing query if we can find one */
      var _iterator = _createForOfIteratorHelper(this.queries),
        _step;
      try {
        for (_iterator.s(); !(_step = _iterator.n()).done;) {
          var _query = _step.value;
          if (_query.key === key) {
            return _query;
          }
        }

        /* Otherwise, create new query */
      } catch (err) {
        _iterator.e(err);
      } finally {
        _iterator.f();
      }
      var query = new Query(this, normalizedConfig);
      this.queries.add(query);
      return query;
    }

    /**
     * Creates (or reuses) a query that holds entities that have all of the specified
     * components.
     *
     * @param components One or more component names to query for.
     * @returns A query that holds entities that have all of the given components.
     */
  }, {
    key: "with",
    value: function _with() {
      for (var _len = arguments.length, components = new Array(_len), _key = 0; _key < _len; _key++) {
        components[_key] = arguments[_key];
      }
      return this.query({
        "with": components,
        without: [],
        predicates: []
      });
    }

    /**
     * Creates (or reuses) a query that holds entities that do not have any of the
     * specified components.
     *
     * @param components One or more component names to query for.
     * @returns A query that holds entities that do not have any of the given components.
     */
  }, {
    key: "without",
    value: function without() {
      for (var _len2 = arguments.length, components = new Array(_len2), _key2 = 0; _key2 < _len2; _key2++) {
        components[_key2] = arguments[_key2];
      }
      return this.query({
        "with": [],
        without: components,
        predicates: []
      });
    }

    /**
     * Creates (or reuses) a query that holds entities that match the given predicate.
     * Please note that as soon as you are building queries that use predicates, you
     * will need to explicitly reindex entities when their properties change.
     *
     * @param predicate The predicate that entities must match.
     * @returns A query that holds entities that match the given predicate.
     */
  }, {
    key: "where",
    value: function where(predicate) {
      return this.query({
        "with": [],
        without: [],
        predicates: [predicate]
      });
    }

    /**
     * Reindexes the specified entity. This will iteratere over all registered queries
     * and ask them to reevaluate the entity.
     *
     * If the `future` parameter is specified,
     * it will be used in the evaluation instead of the entity itself. This is useful
     * if you are about to perform a destructive change on the entity (like removing
     * a component), but want emitted events to still have access to the unmodified entity
     * before the change.
     *
     * @param entity The entity to reindex.
     * @param future The entity that the entity will become in the future.
     */
  }, {
    key: "reindex",
    value: function reindex(entity) {
      var future = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : entity;
      /* Return early if this world doesn't know about the entity. */
      if (!this.has(entity)) return;

      /* Notify all queries about the change. */
      var _iterator2 = _createForOfIteratorHelper(this.queries),
        _step2;
      try {
        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
          var query = _step2.value;
          query.evaluate(entity, future);
        }
      } catch (err) {
        _iterator2.e(err);
      } finally {
        _iterator2.f();
      }
    }
  }, {
    key: "id",
    value:
    /**
     * Generate and return a numerical identifier for the given entity. The ID can later
     * be used to retrieve the entity again through the `entity(id)` method.
     *
     * @param entity The entity to get the ID for.
     * @returns An ID for the entity, or undefined if the entity is not in the world.
     */
    function id(entity) {
      /* We only ever want to generate IDs for entities that are actually in the world. */
      if (!this.has(entity)) return undefined;

      /* Lazily generate an ID. */
      if (!this.entityToId.has(entity)) {
        var _id2 = this.nextId++;
        this.entityToId.set(entity, _id2);
        this.idToEntity.set(_id2, entity);
      }
      return this.entityToId.get(entity);
    }

    /**
     * Given an entity ID that was previously generated through the `id(entity)` function,
     * returns the entity matching that ID, or undefined if no such entity exists.
     *
     * @param id The ID of the entity to retrieve.
     * @returns The entity with the given ID, or undefined if no such entity exists.
     */
  }, {
    key: "entity",
    value: function entity(id) {
      return this.idToEntity.get(id);
    }
  }]);
  return World;
}(bucket.Bucket);
_Symbol$iterator = Symbol.iterator;
var Query = /*#__PURE__*/function (_Bucket) {
  _inherits(Query, _Bucket);
  var _super2 = _createSuper(Query);
  function Query(world, config) {
    var _this2;
    _classCallCheck(this, Query);
    _this2 = _super2.call(this);
    _defineProperty(_assertThisInitialized(_this2), "_isConnected", false);
    _this2.world = world;
    _this2.config = config;
    _this2.key = configKey(config);

    /* Automatically connect this query if event listeners are added to our
    onEntityAdded or onEntityRemoved events. */
    _this2.onEntityAdded.onSubscribe.subscribe(function () {
      return _this2.connect();
    });
    _this2.onEntityRemoved.onSubscribe.subscribe(function () {
      return _this2.connect();
    });
    return _this2;
  }

  /**
   * An array containing all entities that match this query. For iteration, it
   * is recommended to use the `for (const entity of query) {}` syntax instead.
   */
  _createClass(Query, [{
    key: "isConnected",
    get:
    /**
     * True if this query is connected to the world, and will automatically
     * re-evaluate when entities are added or removed.
     */
    function get() {
      return this._isConnected;
    }

    /**
     * A unique, string-based key for this query, based on its configuration.
     */
  }, {
    key: "entities",
    get: function get() {
      if (!this._isConnected) this.connect();
      return _get(_getPrototypeOf(Query.prototype), "entities", this);
    }
  }, {
    key: _Symbol$iterator,
    value: function value() {
      if (!this._isConnected) this.connect();
      return _get(_getPrototypeOf(Query.prototype), Symbol.iterator, this).call(this);
    }

    /**
     * Connects this query to the world. While connected, it will automatically
     * re-evaluate when entities are added or removed, and store those that match
     * its query configuration.
     *
     * @returns The query object.
     */
  }, {
    key: "connect",
    value: function connect() {
      if (!this._isConnected) {
        this._isConnected = true;

        /* Evaluate all entities in the world */
        var _iterator3 = _createForOfIteratorHelper(this.world),
          _step3;
        try {
          for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
            var _entity = _step3.value;
            this.evaluate(_entity);
          }
        } catch (err) {
          _iterator3.e(err);
        } finally {
          _iterator3.f();
        }
      }
      return this;
    }

    /**
     * Disconnects this query from the world. This essentially stops the query from
     * automatically receiving entities.
     */
  }, {
    key: "disconnect",
    value: function disconnect() {
      this._isConnected = false;
      return this;
    }

    /**
     * Returns a new query that extends this query and also matches entities that
     * have all of the components specified.
     *
     * @param components The components that entities must have.
     * @returns A new query representing the extended query configuration.
     */
  }, {
    key: "with",
    value: function _with() {
      for (var _len3 = arguments.length, components = new Array(_len3), _key3 = 0; _key3 < _len3; _key3++) {
        components[_key3] = arguments[_key3];
      }
      return this.world.query(_objectSpread2(_objectSpread2({}, this.config), {}, {
        "with": [].concat(_toConsumableArray(this.config["with"]), components)
      }));
    }

    /**
     * Returns a new query that extends this query and also matches entities that
     * have none of the components specified.
     *
     * @param components The components that entities must not have.
     * @returns A new query representing the extended query configuration.
     */
  }, {
    key: "without",
    value: function without() {
      for (var _len4 = arguments.length, components = new Array(_len4), _key4 = 0; _key4 < _len4; _key4++) {
        components[_key4] = arguments[_key4];
      }
      return this.world.query(_objectSpread2(_objectSpread2({}, this.config), {}, {
        without: [].concat(_toConsumableArray(this.config.without), components)
      }));
    }

    /**
     * Returns a new query that extends this query and also matches entities that
     * match the given predicate.
     *
     * @param predicate The predicate that entities must match.
     * @returns A new query representing the extended query configuration.
     */
  }, {
    key: "where",
    value: function where(predicate) {
      return this.world.query(_objectSpread2(_objectSpread2({}, this.config), {}, {
        predicates: [].concat(_toConsumableArray(this.config.predicates), [predicate])
      }));
    }

    /**
     * Checks the given entity against this query's configuration, and returns
     * true if the entity matches the query, false otherwise.
     *
     * @param entity The entity to check.
     * @returns True if the entity matches this query, false otherwise.
     */
  }, {
    key: "want",
    value: function want(entity) {
      return this.config["with"].every(function (component) {
        return entity[component] !== undefined;
      }) && this.config.without.every(function (component) {
        return entity[component] === undefined;
      }) && this.config.predicates.every(function (predicate) {
        return predicate(entity);
      });
    }

    /**
     * Evaluate the given entity against this query's configuration, and add or
     * remove it from the query if necessary.
     *
     * If `future` is specified, the entity will be evaluated against that entity
     * instead. This is useful for checking if an entity will match the query
     * after some potentially destructive change has been made to it, before
     * actually applying that change to the entity itself.
     *
     * @param entity The entity to evaluate.
     * @param future The entity to evaluate against. If not specified, the entity will be evaluated against itself.
     */
  }, {
    key: "evaluate",
    value: function evaluate(entity) {
      var future = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : entity;
      if (!this.isConnected) return;
      var wanted = this.want(future);
      var has = this.has(entity);
      if (wanted && !has) {
        this.add(entity);
      } else if (!wanted && has) {
        this.remove(entity);
      }
    }
  }]);
  return Query;
}(bucket.Bucket);
var normalizeComponents = function normalizeComponents(components) {
  return _toConsumableArray(new Set(components.sort().filter(function (c) {
    return !!c && c !== "";
  })));
};
function normalizePredicates(predicates) {
  return _toConsumableArray(new Set(predicates));
}
function normalizeQueryConfiguration(config) {
  return {
    "with": normalizeComponents(config["with"]),
    without: normalizeComponents(config.without),
    predicates: normalizePredicates(config.predicates)
  };
}
function configKey(config) {
  return "".concat(config["with"].join(","), ":").concat(config.without.join(","), ":").concat(config.predicates.map(function (p) {
    return id.id(p);
  }).join(","));
}

/**
 * A simple queue (powered by [@hmans/queue](https://github.com/hmans/things/tree/main/packages/hmans-queue))
 * that can be used to schedule work to be done later. This is mostly provided as a convenience
 * to make upgrading from Miniplex 1.0 (which had queuing functionality built-in) a little easier,
 * and it will be deprecated in a future version.
 */
var queue = queue$1.createQueue();

Object.defineProperty(exports, 'Bucket', {
  enumerable: true,
  get: function () { return bucket.Bucket; }
});
exports.Query = Query;
exports.World = World;
exports.queue = queue;