Source: backend/backend.js

  1. import { Vector3, Box3 } from "../geometry.js";
  2. import { EntityRef, NodeRef, EdgeRef, DirEdgeRef } from "./entity.js";
  3. import { HookContainer } from "../hook_container.js";
  4. import { asyncFrom } from "../utils.js";
  5. import { NodeTypeRegistry } from "../node_type.js";
  6. import { LayerRegistry } from "../layer.js";
  8. /** Abstract mapper backend, i.e. what map is being presented.
  9.  * The backend translates between the concept of a map and a database, a file, an API, or whatever else is actually being used to store the data.
  10.  * Most methods here are low-level; users of the backend should use methods from EntityRef and its children which delegate to the MapBackend.
  11.  *
  12.  * Underlying structure:
  13.  * The backend consists of a set of entities, which can have arbitrary properties.
  14.  * A special entity, "global", is used for properties of the whole map.
  15.  * Two types of entities have specific handling to form a graph:
  16.  * "node" - an entity with a parent and positional information.
  17.  * "edge" - an entity connecting two adjacent nodes.
  18.  */
  19. class MapBackend {
  20. 	constructor() {
  21. 		this.loaded = false;
  22. 		this.hooks = new HookContainer();
  23. 		this.nodeTypeRegistry = new NodeTypeRegistry();
  24. 		this.layerRegistry = new LayerRegistry();
  25. 		this.entityCache = {};
  26. 	}
  28. 	getEntityCache(id) {
  29. 		let cache = this.entityCache[id];
  30. 		if(cache === undefined) {
  31. 			cache = this.entityCache[id] = {
  32. 				properties: {},
  33. 			};
  34. 		}
  35. 		return cache;
  36. 	}
  38. 	/** Get the database version number. Implementation defined.
  39. 	 * @returns {number}
  40. 	 */
  41. 	getVersionNumber() {
  42. 		throw "getVersionNumber not defined";
  43. 	}
  45. 	/** Get the latest backend version number. Implementation defined. Must be greater than zero.
  46. 	 * @returns {number}
  47. 	 */
  48. 	getBackendVersionNumber() {
  49. 		throw "getBackendVersionNumber not defined";
  51. 	}
  53. 	/** Get a number property on an entity.
  54. 	 * Has a default implementation based on string properties.
  55. 	 * @returns {number}
  56. 	 */
  57. 	async getPNumber(entityId, propertyName) {
  58. 		return parseFloat(await this.getPString(entityId, propertyName));
  59. 	}
  61. 	/** Set a number property on an entity.
  62. 	 * Has a default implementation based on string properties.
  63. 	 */
  64. 	async setPNumber(entityId, propertyName, value) {
  65. 		return this.setPString(entityId, propertyName, value.toString());
  66. 	}
  68. 	/** Set a Vector3 property on an entity.
  69. 	 * Has a default implementation based on string properties.
  70. 	 */
  71. 	async setPVector3(entityId, propertyName, v) {
  72. 		return this.setPString(entityId, propertyName, JSON.stringify(v));
  73. 	}
  75. 	/** Get a Vector3 property on an entity.
  76. 	 * Has a default implementation based on string properties.
  77. 	 * @returns {Vector3}
  78. 	 */
  79. 	async getPVector3(entityId, propertyName) {
  80. 		const object = JSON.parse(await this.getPString(entityId, propertyName));
  81. 		return Vector3.fromJSON(object.x, object.y, object.z);
  82. 	}
  84. 	/** Get a string property on an entity.
  85. 	 * @returns {string}
  86. 	 */
  87. 	async getPString(entityId, propertyName) {
  88. 		entityId;
  89. 		propertyName;
  90. 		throw "getPString not implemented";
  91. 	}
  93. 	/** Set a string property on an entity. */
  94. 	async setPString(entityId, propertyName, value) {
  95. 		entityId;
  96. 		propertyName;
  97. 		value;
  98. 		throw "setPString not implemented";
  99. 	}
  101. 	/** Create a new entity in the backend.
  102. 	 * @param type {string} Type of the new entity.
  103. 	 * @returns {EntityRef}
  104. 	 */
  105. 	async createEntity(type) {
  106. 		type;
  107. 		throw "createEntity not implemented";
  108. 	}
  110. 	/** Creates a new "node" entity.
  111. 	 * @param parentId {number|undefined} ID of the parent node, or undefined if the node has no parent.
  112. 	 * @param nodeType {string} Type of the node. "object" or "point".
  113. 	 * @returns {NodeRef}
  114. 	 */
  115. 	async createNode(parentId, nodeType) {
  116. 		parentId;
  117. 		nodeType;
  118. 		throw "createNode not implemented";
  119. 	}
  121. 	/** Get the parent node of a node by ID, or null if the node has no parent.
  122. 	 * @returns {NodeRef|null}
  123. 	 */
  124. 	async getNodeParent(nodeId) {
  125. 		nodeId;
  126. 		throw "getNodeParent not implemented";
  127. 	}
  129. 	async setNodeParent(nodeId, parentId) {
  130. 		nodeId;
  131. 		parentId;
  132. 		throw "setNodeParent not implemented";
  133. 	}
  135. 	/** Get all direct children of a node.
  136. 	 * @returns {AsyncIterable.<NodeRef>}
  137. 	 */
  138. 	async getNodeChildren(nodeId) {
  139. 		nodeId;
  140. 		throw "getNodeChildren not implemented";
  141. 	}
  143. 	/** Check if a node has any children.
  144. 	 * Has a default implementation based on #getNodeChildren().
  145. 	 * @returns {boolean}
  146. 	 */
  147. 	async nodeHasChildren(nodeId) {
  148. 		for await(const child of this.getNodeChildren(nodeId)) {
  149. 			child;
  150. 			return true;
  151. 		}
  153. 		return false;
  154. 	}
  156. 	/** Get a node's type.
  157. 	 * @returns {string}
  158. 	 */
  159. 	async getNodeType(nodeId) {
  160. 		nodeId;
  161. 		throw "getNodeType not implemented";
  162. 	}
  164. 	/** Create a new edge between two nodes.
  165. 	 * Order of node IDs does not matter.
  166. 	 * @param nodeAId {number} The ID of one of the nodes on the edge.
  167. 	 * @param nodeBId {number} The ID of the other node on the edge.
  168. 	 * @returns {EdgeRef} A reference to the new edge.
  169. 	 */
  170. 	async createEdge(nodeAId, nodeBId) {
  171. 		nodeAId;
  172. 		nodeBId;
  173. 		throw "createEdge not implemented";
  174. 	}
  176. 	/** Get all edges attached to a node.
  177. 	 * @returns {AsyncIterable.<EdgeRef>}
  178. 	 */
  179. 	async getNodeEdges(nodeId) {
  180. 		nodeId;
  181. 		throw "getNodeEdges not implemented";
  182. 	}
  184. 	/** Get the two nodes attached to an edge, in no particular order.
  185. 	 * @returns {AsyncIterable.<NodeRef>}
  186. 	 */
  187. 	async getEdgeNodes(edgeId) {
  188. 		edgeId;
  189. 		throw "getEdgeNodes not implemented";
  190. 	}
  192. 	/** Given an edge and one of the nodes on the edge, get the other node on the edge.
  193. 	 * @param edgeId {number}
  194. 	 * @param nodeId {number}
  195. 	 * Has a default implementation based on #getEdgeNodes().
  196. 	 * @returns {NodeRef}
  197. 	 */
  198. 	async getEdgeOtherNode(edgeId, nodeId) {
  199. 		const [nodeA, nodeB] = await asyncFrom(this.getEdgeNodes(edgeId));
  200. 		return (nodeA.id == nodeId) ? nodeB : nodeA;
  201. 	}
  203. 	/** Remove an edge from the backend.
  204. 	 * Has a default implementation that just removes the entity.
  205. 	 */
  206. 	async removeEdge(edgeId) {
  207. 		return this.removeEntity(edgeId);
  208. 	}
  210. 	/** Remove a node from the backend.
  211. 	 * Has a default implementation that just removes the entity.
  212. 	 */
  213. 	async removeNode(nodeId) {
  214. 		return this.removeEntity(nodeId);
  215. 	}
  217. 	/** Check if an entity exists.
  218. 	 * @returns {boolean}
  219. 	 */
  220. 	async entityExists(entityId) {
  221. 		entityId;
  222. 		throw "entityExists not implemented";
  223. 	}
  225. 	/** Remove an entity from the backend.
  226. 	 * This method should work to remove any entity.
  227. 	 * However, calling code should use #removeEdge() and #removeNode() when applicable instead, for potential optimization purposes.
  228. 	 */
  229. 	async removeEntity(entityId) {
  230. 		entityId;
  231. 		throw "removeEntity not implemented";
  232. 	}
  234. 	/** Flush the backend to storage.
  235. 	 * This may happen automatically, but flush forces it.
  236. 	 * Has a default implementation that does nothing.
  237. 	 */
  238. 	async flush() {
  239. 	}
  241. 	/** Create an EntityRef to an entity in this backend.
  242. 	 * Use getNodeRef, getEdgeRef, or getDirEdgeRef for greater type-specific functionality if the entity is a node or edge.
  243. 	 */
  244. 	getEntityRef(id) {
  245. 		return new EntityRef(id, this);
  246. 	}
  248. 	/** Create a NodeRef to a node in this backend. */
  249. 	getNodeRef(id) {
  250. 		return new NodeRef(id, this);
  251. 	}
  253. 	/** Create an EdgeRef to an edge in this backend. */
  254. 	getEdgeRef(id) {
  255. 		return new EdgeRef(id, this);
  256. 	}
  258. 	/** Create a DirEdgeRef to an edge in this backend, starting from the specified node.
  259. 	 * @param id {number} The ID of the edge to get.
  260. 	 * @param startId {number} The ID of a node attached to this edge.
  261. 	 * @returns {DirEdgeRef} Starting from the specified start ID.
  262. 	 */
  263. 	getDirEdgeRef(id, startId) {
  264. 		return new DirEdgeRef(id, startId, this);
  265. 	}
  267. 	/** Get all nodes within a spatial box.
  268. 	 * @param box {Box3} The box to find nodes within.
  269. 	 * @returns {AsyncIterable.<NodeRef>}
  270. 	 */
  271. 	getNodesInArea(box) {
  272. 		box;
  273. 		throw "getNodesInArea not implemented";
  274. 	}
  276. 	/** Get all nodes in or near a spatial box (according to their radii).
  277. 	 * @param box {Box3} The box to find nodes within or near.
  278. 	 * @param minRadius {number} The minimum radius of nodes to return.
  279. 	 * @returns {AsyncIterable.<NodeRef>}
  280. 	 */
  281. 	getObjectNodesTouchingArea(box, minRadius) {
  282. 		box;
  283. 		minRadius;
  284. 		throw "getObjectNodesTouchingArea not implemented";
  285. 	}
  287. 	/** Get the edge between two nodes, if it exists.
  288. 	 * @param nodeAId {number} The ID of one of the nodes on the edge to find.
  289. 	 * @param nodeBId {number} The ID of the other node on the edge to find.
  290. 	 * @returns {EdgeRef}
  291. 	 */
  292. 	getEdgeBetween(nodeAId, nodeBId) {
  293. 		nodeAId;
  294. 		nodeBId;
  295. 		throw "getEdgeBetween not implemented";
  296. 	}
  298. 	/** Get all nearby nodes within a specified blend distance of the specified node.
  299. 	 * Has a default implementation based on #getNodesInArea().
  300. 	 * @param nodeRef {NodeRef} The node that is the spatial center of the search.
  301. 	 * @param blendDistance {number} How far out to look for nodes? (Necessary to avoid searching the entire map.)
  302. 	 * @returns {AsyncIterable.<NodeRef>} All the discovered nodes. Does not include the original node.
  303. 	 */
  304. 	async * getNearbyNodes(nodeRef, blendDistance) {
  305. 		for await (const otherNodeRef of this.getNodesInArea(Box3.fromRadius(await nodeRef.getCenter(), blendDistance))) {
  306. 			if(otherNodeRef.id !== nodeRef.id) {
  307. 				yield otherNodeRef;
  308. 			}
  309. 		}
  310. 	}
  312. 	/** Get all nodes connected to the specified node by one level of edges (that is, one edge).
  313. 	 * Has a default implementation based on #getNodeEdges().
  314. 	 * @param nodeRef {NodeRef} The node to search for connections on.
  315. 	 * @returns {AsyncIterable.<NodeRef>} The connected nodes.
  316. 	 */
  317. 	async * getConnectedNodes(nodeRef) {
  318. 		for await (const dirEdgeRef of this.getNodeEdges(nodeRef.id)) {
  319. 			yield await dirEdgeRef.getDirOtherNode();
  320. 		}
  321. 	}
  323. 	/** Get all edges within a specified blend distance that intersect with the given edge.
  324. 	 * Has a default implementation based on #getNodesInArea() and #NodeRef.getEdges().
  325. 	 * @param edgeRef {EdgeRef} The edge to search for intersections on.
  326. 	 * @param blendDistance {number} How far out to search for intersections? (Necessary to avoid searching the entire map.)
  327. 	 * @returns {AsyncIterable.<EdgeRef>} Each intersecting edge found.
  328. 	 */
  329. 	async * getIntersectingEdges(edgeRef, blendDistance) {
  330. 		const line = await edgeRef.getLine();
  331. 		const distance = Vector3.UNIT.multiplyScalar(blendDistance);
  333. 		const seen = {
  334. 			[edgeRef.id]: true,
  335. 		};
  337. 		for await (const nodeRef of this.getNodesInArea(new Box3(line.fullMin().subtract(distance), line.fullMax().add(distance)))) {
  338. 			for await (const dirEdgeRef of nodeRef.getEdges()) {
  339. 				if(!seen[dirEdgeRef.id]) {
  340. 					seen[dirEdgeRef.id] = true;
  342. 					if(line.intersects2(await dirEdgeRef.getLine())) {
  343. 						yield dirEdgeRef;
  344. 					}
  345. 				}
  346. 			}
  347. 		}
  348. 	}
  349. }
  351. export { MapBackend };