@oasisomniverse/web4-api 2.0.0

package/docs/modules/Map.md

@@ -0,0 +1,1026 @@
+# Map — `oasis.map`
+
+Source controller: [`MapController.cs`](https://github.com/NextGenSoftwareUK/OASIS2/blob/main/ONODE/NextGenSoftware.OASIS.API.ONODE.WebAPI/Controllers/MapController.cs)
+Route prefix: `api/map`
+22 operation(s).
+
+Every method takes a single args object: any key matching a `{token}` in the route is substituted into the URL; everything else becomes the query string (GET/DELETE) or JSON body (POST/PUT). Every call resolves to the standard OASIS envelope:
+
+```ts
+{
+  isError: boolean;
+  isWarning: boolean;
+  message: string;
+  errorCode?: string;
+  result: T; // see each endpoint's Response section below
+}
+```
+
+## Operations
+
+### `createAndDrawRouteOnMapBetweenHolons`
+
+Create and draw a route on the map between two holons.
+
+**POST** `api/map/CreateAndDrawRouteOnMapBetweenHolons/{holonDNA}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `holonDNA` | `HolonDNA` |
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.createAndDrawRouteOnMapBetweenHolons({
+    holonDNA: '<holonDNA>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+
+---
+
+### `createAndDrawRouteOnMapBeweenPoints`
+
+Create and draw a route on the map between two points.
+
+**POST** `api/map/CreateAndDrawRouteOnMapBeweenPoints/{points}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `points` | `MapPoints` |
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.createAndDrawRouteOnMapBeweenPoints({
+    points: '<points>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+
+---
+
+### `draw2DSpriteOnHUD`
+
+Draw a 2D sprint on the Our World HUD.
+
+**POST** `api/map/Draw2DSpriteOnHUD/{sprite}/{x}/{y}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `sprite` | `string` |
+| `x` | `float` |
+| `y` | `float` |
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.draw2DSpriteOnHUD({
+    sprite: '<sprite>',
+    x: '<x>',
+    y: '<y>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+
+---
+
+### `draw2DSpriteOnMap`
+
+Draw a 2D sprint on the map.
+
+**POST** `api/map/Draw2DSpriteOnMap/{sprite}/{x}/{y}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `sprite` | `string` |
+| `x` | `float` |
+| `y` | `float` |
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.draw2DSpriteOnMap({
+    sprite: '<sprite>',
+    x: '<x>',
+    y: '<y>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+
+---
+
+### `draw3DObjectOnMap`
+
+Draw a 3D object on the map.
+
+**POST** `api/map/Draw3DObjectOnMap/{obj}/{x}/{y}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `obj` | `string` |
+| `x` | `float` |
+| `y` | `float` |
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.draw3DObjectOnMap({
+    obj: '<obj>',
+    x: '<x>',
+    y: '<y>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+
+---
+
+### `getMapStats`
+
+Get map statistics for the current avatar
+
+**GET** `api/map/stats`
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `Dictionary<string, object>` - a key/value map keyed by `string`, each value a `object`.
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.getMapStats({});
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": { "<string>": {} }
+}
+```
+
+---
+
+### `getNearbyLocations`
+
+Get nearby locations for the current avatar
+
+**GET** `api/map/nearby`
+
+**Request**
+
+Query parameters:
+
+| Field | Type |
+| --- | --- |
+| `latitude` | `double` |
+| `longitude` | `double` |
+| `radiusKm` | `double (optional)` |
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `MapLocation` (array)
+
+| Field | Type |
+| --- | --- |
+| `Id` | `Guid` |
+| `Name` | `string` |
+| `Description` | `string` |
+| `Latitude` | `double` |
+| `Longitude` | `double` |
+| `Type` | `LocationType` |
+| `IsActive` | `bool` |
+| `Metadata` | `Dictionary<string, object>` |
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.getNearbyLocations({
+    latitude: 1.0,
+    longitude: 1.0,
+    radiusKm: 1.0
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": [{ "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Name": "example string", "Description": "example string", "Latitude": 1.0, "Longitude": 1.0, "Type": {  }, "IsActive": true, "Metadata": { "<string>": {} } }]
+}
+```
+
+---
+
+### `getVisitHistory`
+
+Get visit history for the current avatar
+
+**GET** `api/map/visit-history`
+
+**Request**
+
+Query parameters:
+
+| Field | Type |
+| --- | --- |
+| `limit` | `int (optional)` |
+| `offset` | `int (optional)` |
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `MapVisit` (array)
+
+| Field | Type |
+| --- | --- |
+| `Id` | `Guid` |
+| `AvatarId` | `Guid` |
+| `LocationId` | `Guid` |
+| `Purpose` | `string` |
+| `VisitedAt` | `DateTime` |
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.getVisitHistory({
+    limit: 1,
+    offset: 1
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": [{ "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "AvatarId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "LocationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Purpose": "example string", "VisitedAt": "2026-01-01T00:00:00Z" }]
+}
+```
+
+---
+
+### `highlightBuildingOnMap`
+
+Highlight a building on the map.
+
+**POST** `api/map/HighlightBuildingOnMap/{building}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `building` | `Building` |
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.highlightBuildingOnMap({
+    building: '<building>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+
+---
+
+### `pamMapDown`
+
+Pam the map down.
+
+**POST** `api/map/PamMapDown/{value}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `value` | `float` |
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.pamMapDown({
+    value: '<value>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+
+---
+
+### `pamMapLeft`
+
+Pam the map left.
+
+**POST** `api/map/PamMapLeft/{value}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `value` | `float` |
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.pamMapLeft({
+    value: '<value>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+
+---
+
+### `pamMapRight`
+
+Pam the map right.
+
+**POST** `api/map/PamMapRight/{value}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `value` | `float` |
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.pamMapRight({
+    value: '<value>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+
+---
+
+### `pamMapUp`
+
+Pam the map up.
+
+**POST** `api/map/PamMapUp/{value}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `value` | `float` |
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.pamMapUp({
+    value: '<value>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+
+---
+
+### `search`
+
+Search the map for locations, points of interest, and other map features
+
+**POST** `api/map/search`
+
+**Request**
+
+Body type: `LocationType`
+
+_No fields._
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `MapLocation` (array)
+
+| Field | Type |
+| --- | --- |
+| `Id` | `Guid` |
+| `Name` | `string` |
+| `Description` | `string` |
+| `Latitude` | `double` |
+| `Longitude` | `double` |
+| `Type` | `LocationType` |
+| `IsActive` | `bool` |
+| `Metadata` | `Dictionary<string, object>` |
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.search({
+    query: 'example string',
+    latitude: '<latitude>',
+    longitude: '<longitude>',
+    radiusKm: '<radiusKm>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": [{ "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Name": "example string", "Description": "example string", "Latitude": 1.0, "Longitude": 1.0, "Type": {  }, "IsActive": true, "Metadata": { "<string>": {} } }]
+}
+```
+
+---
+
+### `selectBuildingOnMap`
+
+Select building on map.
+
+**POST** `api/map/SelectBuildingOnMap/{building}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `building` | `Building` |
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.selectBuildingOnMap({
+    building: '<building>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+
+---
+
+### `selectHolonOnMap`
+
+Select holon on map.
+
+**POST** `api/map/SelectHolonOnMap/{holon}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `holon` | `Holon` |
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.selectHolonOnMap({
+    holon: '<holon>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+
+---
+
+### `selectQuestOnMap`
+
+Select quest on map.
+
+**POST** `api/map/SelectQuestOnMap/{quest}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `quest` | `Quest` |
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.selectQuestOnMap({
+    quest: '<quest>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+
+---
+
+### `visitLocation`
+
+Visit a location
+
+**POST** `api/map/visit/{locationId}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `locationId` | `Guid` |
+
+**Request**
+
+Body fields:
+
+| Field | Type |
+| --- | --- |
+| `purpose` | `string (optional)` |
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.visitLocation({
+    locationId: '<locationId>',
+    purpose: 'example string'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+
+---
+
+### `zoomMapIn`
+
+Zoom map in.
+
+**POST** `api/map/ZoomMapIn/{value}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `value` | `float` |
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.zoomMapIn({
+    value: '<value>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+
+---
+
+### `zoomMapOut`
+
+Zoom map out.
+
+**POST** `api/map/ZoomMapOut/{value}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `value` | `float` |
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.zoomMapOut({
+    value: '<value>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+
+---
+
+### `zoomToHolonOnMap`
+
+Zoom to holon on map.
+
+**POST** `api/map/ZoomToHolonOnMap/{holon}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `holon` | `Holon` |
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.zoomToHolonOnMap({
+    holon: '<holon>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+
+---
+
+### `zoomToQuestOnMap`
+
+Zoom to quest on map.
+
+**POST** `api/map/ZoomToQuestOnMap/{quest}`
+
+Route parameters:
+
+| Field | Type |
+| --- | --- |
+| `quest` | `Quest` |
+
+**Request**
+
+No request body.
+
+**Response**
+
+Standard `OASISResult` envelope (see top of this page) with:
+
+`result` type: `bool`
+
+**Example**
+
+```js
+const { isError, message, result } = await oasis.map.zoomToQuestOnMap({
+    quest: '<quest>'
+  });
+if (isError) throw new Error(message);
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "isError": false,
+  "message": "",
+  "result": true
+}
+```
+