erlc-v2 1.0.0-beta.2 → 1.0.1

package/README.md

@@ -2,11 +2,11 @@
 
 JavaScript client for the ER:LC API v2.
 
-Built for Node 18+ with no runtime dependencies.
+Built for Node 18+.
 
-## Beta Notice
-
-This wrapper is in beta (`1.0.0-beta.x`) and is not guaranteed to work 100% in all environments or API states.
+## Stable Release
+
+This wrapper is now on a stable release track (`1.0.0+`).
 
 ## Responsibility and API Safety
 
@@ -51,17 +51,17 @@ main()
   .finally(() => client.destroy());
 ```
 
-## Quick Start (ESM)
+## Quick Start (ESM)
 
 ```js
 import { Client } from "erlc-v2";
 
-const client = new Client({
-  serverKey: "YOUR_SERVER_KEY",
-});
-```
-
-## Options
+const client = new Client({
+  serverKey: "YOUR_SERVER_KEY",
+});
+```
+
+## Options
 
 ```ts
 new Client({
@@ -69,77 +69,77 @@ new Client({
   globalKey?: string, // optional
   logging?: boolean, // default: false
   logger?: { info, warn, error, debug },
-  cache?: {
-    enabled?: boolean, // default: true
-    ttlMs?: number, // default: 1500
-    maxSize?: number, // default: 500
-    provider?: "memory" | "redis", // default: auto (redis if redis config is present)
-    redisUrl?: string, // optional (requires `npm i redis`)
-    redisPrefix?: string, // default: "erlc-v2:cache"
-    redisClient?: object, // optional pre-configured Redis client
-  },
-  rateLimit?: {
-    enabled?: boolean, // default: true
-    strictSerial?: boolean, // default: true (global one-at-a-time queue)
-    bucketLimit?: number, // default: 1
-    totalLimit?: number, // default: 1
-    unauthLimit?: number, // default: 3
-  },
+  cache?: {
+    enabled?: boolean, // default: true
+    ttlMs?: number, // default: 1500
+    maxSize?: number, // default: 500
+    provider?: "memory" | "redis", // default: auto (redis if redis config is present)
+    redisUrl?: string, // optional (requires `npm i redis`)
+    redisPrefix?: string, // default: "erlc-v2:cache"
+    redisClient?: object, // optional pre-configured Redis client
+  },
+  rateLimit?: {
+    enabled?: boolean, // default: true
+    strictSerial?: boolean, // default: true (global one-at-a-time queue)
+    bucketLimit?: number, // default: 1
+    totalLimit?: number, // default: 1
+    unauthLimit?: number, // default: 3
+  },
   polling?: {
     enabled?: boolean, // default: true
     intervalMs?: number, // default: 2500 (min enforced: 250)
     bypassCache?: boolean, // default: true
   },
-});
-```
-
-Legacy aliases (`perBucketConcurrency`, `globalConcurrency`, `unauthorizedThreshold`) are still accepted.
-
-## Redis Cache (Optional)
-
-You can use Redis instead of in-memory cache by passing either `cache.redisUrl` or `cache.redisClient`.
-
-If you use `redisUrl`, install the Redis client package:
-
-```bash
-npm i redis
-```
-
-Example with connection URL:
-
-```js
-const { Client } = require("erlc-v2");
-
-const client = new Client({
-  serverKey: "YOUR_SERVER_KEY",
-  cache: {
-    provider: "redis",
-    redisUrl: "redis://localhost:6379",
-    redisPrefix: "myapp:erlc",
-    ttlMs: 2000,
-  },
-});
-```
-
-Example with your own Redis client instance:
-
-```js
-const { createClient } = require("redis");
-const { Client } = require("erlc-v2");
-
-(async () => {
-  const redis = createClient({ url: process.env.REDIS_URL });
-  await redis.connect();
-
-  const client = new Client({
-    serverKey: "YOUR_SERVER_KEY",
-    cache: {
-      redisClient: redis,
-      redisPrefix: "myapp:erlc",
-    },
-  });
-})();
-```
+});
+```
+
+Legacy aliases (`perBucketConcurrency`, `globalConcurrency`, `unauthorizedThreshold`) are still accepted.
+
+## Redis Cache (Optional)
+
+You can use Redis instead of in-memory cache by passing either `cache.redisUrl` or `cache.redisClient`.
+
+If you use `redisUrl`, install the Redis client package:
+
+```bash
+npm i redis
+```
+
+Example with connection URL:
+
+```js
+const { Client } = require("erlc-v2");
+
+const client = new Client({
+  serverKey: "YOUR_SERVER_KEY",
+  cache: {
+    provider: "redis",
+    redisUrl: "redis://localhost:6379",
+    redisPrefix: "myapp:erlc",
+    ttlMs: 2000,
+  },
+});
+```
+
+Example with your own Redis client instance:
+
+```js
+const { createClient } = require("redis");
+const { Client } = require("erlc-v2");
+
+(async () => {
+  const redis = createClient({ url: process.env.REDIS_URL });
+  await redis.connect();
+
+  const client = new Client({
+    serverKey: "YOUR_SERVER_KEY",
+    cache: {
+      redisClient: redis,
+      redisPrefix: "myapp:erlc",
+    },
+  });
+})();
+```
 
 ## API
 
@@ -152,6 +152,8 @@ Core:
 Convenience methods:
 
 - `await client.players.list()`
+- `await client.map.render(options?)`
+- `await client.map.renderUser(userId, options?)`
 - `await client.staff.list()`
 - `await client.logs.kills()`
 - `await client.logs.joins()`
@@ -207,6 +209,87 @@ await client.commands.execute(":h Hey everyone!");
 await client.commands.execute(":log recentban He was trolling!");
 ```
 
+## Map Rendering
+
+Render an ER:LC map (`3121x3121`) with player markers that use Roblox avatars.
+
+```js
+const result = await client.map.render();
+
+// png buffer
+console.log(result.buffer);
+console.log(result.players.length);
+```
+
+`client.map.render()` renders the full map with all players currently in the server.
+
+Render an official season/type map preset:
+
+```js
+const fallBlank = await client.map.render({
+  season: "fall",
+  type: "blank",
+});
+
+const fallPostals = await client.map.render({
+  season: "fall",
+  type: "postals",
+});
+
+const winterBlank = await client.map.render({
+  season: "winter", // alias: "snow"
+  type: "blank",
+});
+
+const winterPostals = await client.map.render({
+  season: "winter",
+  type: "postals",
+});
+```
+
+Use your own map image URL:
+
+```js
+const customMap = await client.map.render({
+  mapUrl: "https://example.com/my-map.png", // mainly used in cases where we fail to add the most recent map when its released (sizing should be 3121x3121)
+});
+```
+
+Render only one player by Roblox user ID:
+
+```js
+const single = await client.map.renderUser(123456789, {
+  season: "winter",
+  type: "postals",
+});
+```
+
+Options:
+
+- `userId?: number | string`
+- `userIds?: Array<number | string>`
+- `players?: any[]` (use your own pre-fetched player payload)
+- `mapUrl?: string` (custom map URL; if set, this overrides `season`/`type`)
+- `season?: string` (`"fall"` or `"winter"`/`"snow"` for official presets)
+- `type?: string` (`"blank"` or `"postals"` for official presets)
+- `mapSeason?: string` (alias of `season`)
+- `mapType?: string` (alias of `type`)
+- `coordinateBounds?: { minX, maxX, minY, maxY, invertY? }`
+- `clampToMap?: boolean` (default: `true`)
+- `robloxHeadshotSize?: string` (default: `"150x150"`)
+- `marker?: { outerRadius, innerRadius, tipLength, tipWidth, fillColor, shadow }`
+
+Map size is fixed to `3121x3121`.
+
+Result shape:
+
+- `buffer` (`image/png`)
+- `map` (`{ url, season, type, width, height }`)
+- `players` (rendered marker metadata)
+- `skipped` (players skipped because coordinates were unavailable/invalid)
+- `requestedUserIds` (IDs requested via `userId` / `userIds`)
+- `unmatchedUserIds` (requested IDs not found in current player payload)
+
 ## Events
 
 - `ready`

package/index.d.ts

@@ -1,4 +1,5 @@
 import { EventEmitter } from "events";
+import { Buffer } from "buffer";
 
 export interface LoggerLike {
   info?: (...args: any[]) => void;
@@ -91,6 +92,71 @@ export interface CommandExecuteResult {
   };
 }
 
+export interface MapCoordinateBounds {
+  minX: number;
+  maxX: number;
+  minY: number;
+  maxY: number;
+  invertY?: boolean;
+}
+
+export interface MapMarkerOptions {
+  outerRadius?: number;
+  innerRadius?: number;
+  tipLength?: number;
+  tipWidth?: number;
+  fillColor?: string;
+  shadow?: boolean;
+}
+
+export interface MapRenderOptions {
+  userId?: number | string;
+  userIds?: Array<number | string>;
+  players?: any[];
+  mapUrl?: string;
+  season?: string;
+  type?: string;
+  mapSeason?: string;
+  mapType?: string;
+  coordinateBounds?: MapCoordinateBounds;
+  clampToMap?: boolean;
+  robloxHeadshotSize?: string;
+  marker?: MapMarkerOptions;
+}
+
+export interface MapRenderedPlayer {
+  userId: number | null;
+  name: string | null;
+  avatarUrl: string | null;
+  sourceX: number;
+  sourceY: number;
+  sourceType: string;
+  pixelX: number;
+  pixelY: number;
+}
+
+export interface MapSkippedPlayer {
+  userId: number | null;
+  name: string | null;
+  reason: string;
+}
+
+export interface MapRenderResult {
+  buffer: Buffer;
+  mimeType: "image/png";
+  map: {
+    url: string;
+    season: string | null;
+    type: string | null;
+    width: number;
+    height: number;
+  };
+  players: MapRenderedPlayer[];
+  skipped: MapSkippedPlayer[];
+  requestedUserIds: number[];
+  unmatchedUserIds: number[];
+}
+
 export interface ServerResponse {
   name: string | null;
   ownerId: number | null;
@@ -164,6 +230,17 @@ export class Client extends EventEmitter {
   players: {
     list: (requestOptions?: RequestOptions) => Promise<any[]>;
   };
+  map: {
+    render: (
+      options?: MapRenderOptions,
+      requestOptions?: RequestOptions,
+    ) => Promise<MapRenderResult>;
+    renderUser: (
+      userId: number | string,
+      options?: Omit<MapRenderOptions, "userId" | "userIds">,
+      requestOptions?: RequestOptions,
+    ) => Promise<MapRenderResult>;
+  };
   staff: {
     list: (requestOptions?: RequestOptions) => Promise<any>;
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "erlc-v2",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.1",
   "description": "Premium, lightweight JavaScript wrapper for the ER:LC API v2.",
   "main": "index.js",
   "module": "index.mjs",
@@ -23,6 +23,12 @@
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "test:map": "node test-map-render.js"
+  },
+  "dependencies": {
+    "@napi-rs/canvas": "^0.1.74"
+  },
   "keywords": [
     "erlc",
     "police-roleplay-community",

package/src/Client.js

@@ -6,6 +6,7 @@ const { DEFAULT_OPTIONS, QUERY_FLAG_MAP } = require("./util/constants");
 const { mergeOptions } = require("./util/options");
 const { createLogger } = require("./util/logger");
 const { normalizeServerResponse } = require("./util/normalize");
+const { renderPlayerMap } = require("./map/renderPlayerMap");
 const { ERLCError } = require("./errors");
 
 const BASE_URL = "https://api.policeroleplay.community";
@@ -104,6 +105,13 @@ class Client extends EventEmitter {
           .then((d) => d.players),
     };
 
+    this.map = {
+      render: (options = {}, requestOptions = {}) =>
+        this._renderMap(options, requestOptions),
+      renderUser: (userId, options = {}, requestOptions = {}) =>
+        this._renderMap({ ...options, userId }, requestOptions),
+    };
+
     this.staff = {
       list: (requestOptions = {}) =>
         this.server.fetch({ staff: true }, requestOptions).then((d) => d.staff),
@@ -341,6 +349,17 @@ class Client extends EventEmitter {
     });
   }
 
+  async _renderMap(options = {}, requestOptions = {}) {
+    if (this.state.disconnected && this.state.disconnectError) {
+      throw this.state.disconnectError;
+    }
+    if (this.state.destroyed) {
+      throw new ERLCError("Client has been destroyed");
+    }
+
+    return renderPlayerMap(this, options, requestOptions);
+  }
+
   _queueCommand(task) {
     const run = this.commandQueue.then(task, task);
     this.commandQueue = run.catch(() => {});

package/src/map/renderPlayerMap.js

@@ -0,0 +1,719 @@
+const { ERLCError } = require("../errors");
+
+const DEFAULT_MAP_URL =
+  "https://api.policeroleplay.community/maps/fall_blank.png";
+const FIXED_MAP_SIZE = 3121;
+const OFFICIAL_MAP_BASE_URL = "https://api.policeroleplay.community/maps";
+const ROBLOX_HEADSHOT_URL = "https://thumbnails.roblox.com/v1/users/avatar";
+const MAP_SEASON_ALIASES = {
+  fall: "fall",
+  autumn: "fall",
+  winter: "snow",
+  snow: "snow",
+};
+const MAP_TYPE_ALIASES = {
+  blank: "blank",
+  none: "blank",
+  postal: "postals",
+  postals: "postals",
+};
+
+let canvasModule = null;
+
+function loadCanvasModule() {
+  if (canvasModule) return canvasModule;
+  try {
+    canvasModule = require("@napi-rs/canvas");
+    return canvasModule;
+  } catch (error) {
+    throw new ERLCError(
+      "Map rendering requires @napi-rs/canvas. Install dependencies and retry.",
+      { cause: error?.message || String(error) },
+    );
+  }
+}
+
+function toFiniteNumber(value) {
+  if (value === null || value === undefined) return null;
+  const numeric =
+    typeof value === "number" ? value : Number(String(value).trim());
+  if (!Number.isFinite(numeric)) return null;
+  return numeric;
+}
+
+function toUserId(value) {
+  const parsed = toFiniteNumber(value);
+  if (parsed === null) return null;
+  if (parsed <= 0) return null;
+  return Math.trunc(parsed);
+}
+
+function normalizeMapSelectionPart(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim().toLowerCase();
+  if (!trimmed) return null;
+  return trimmed.replace(/\s+/g, "_");
+}
+
+function normalizeMapSeason(value) {
+  const normalized = normalizeMapSelectionPart(value);
+  if (!normalized) return null;
+  return MAP_SEASON_ALIASES[normalized] || normalized;
+}
+
+function normalizeMapType(value) {
+  const normalized = normalizeMapSelectionPart(value);
+  if (!normalized) return null;
+  return MAP_TYPE_ALIASES[normalized] || normalized;
+}
+
+function buildOfficialMapUrl(season, type) {
+  if (!season && !type) return null;
+  const resolvedSeason = season || "fall";
+  const resolvedType = type || "blank";
+  return {
+    url: `${OFFICIAL_MAP_BASE_URL}/${resolvedSeason}_${resolvedType}.png`,
+    season: resolvedSeason,
+    type: resolvedType,
+  };
+}
+
+function normalizeFixedMapDimension(value, keyName) {
+  const numeric = toFiniteNumber(value);
+  if (numeric === null) return FIXED_MAP_SIZE;
+  const rounded = Math.round(numeric);
+  if (rounded !== FIXED_MAP_SIZE) {
+    throw new ERLCError(
+      `${keyName} must be ${FIXED_MAP_SIZE}. Custom map sizing is not supported.`,
+    );
+  }
+  return FIXED_MAP_SIZE;
+}
+
+function getValueCaseInsensitive(object, targetKey) {
+  if (!object || typeof object !== "object") return undefined;
+  if (Object.prototype.hasOwnProperty.call(object, targetKey)) {
+    return object[targetKey];
+  }
+
+  const normalizedTarget = String(targetKey).toLowerCase();
+  for (const key of Object.keys(object)) {
+    if (String(key).toLowerCase() === normalizedTarget) {
+      return object[key];
+    }
+  }
+  return undefined;
+}
+
+function getFirstFiniteNumber(object, keys) {
+  for (const key of keys) {
+    const value = getValueCaseInsensitive(object, key);
+    const numeric = toFiniteNumber(value);
+    if (numeric !== null) return numeric;
+  }
+  return null;
+}
+
+function extractUserId(player) {
+  const directUserId = toUserId(
+    getFirstFiniteNumber(player, [
+      "UserID",
+      "UserId",
+      "userId",
+      "userid",
+      "Id",
+      "id",
+    ]),
+  );
+  if (directUserId) return directUserId;
+
+  const playerField =
+    getValueCaseInsensitive(player, "Player") ??
+    getValueCaseInsensitive(player, "Name") ??
+    getValueCaseInsensitive(player, "Username");
+  if (typeof playerField !== "string") return null;
+  const trimmed = playerField.trim();
+  if (!trimmed) return null;
+
+  const colonMatch = trimmed.match(/:(\d+)\s*$/);
+  if (colonMatch) {
+    return toUserId(colonMatch[1]);
+  }
+
+  if (/^\d+$/.test(trimmed)) {
+    return toUserId(trimmed);
+  }
+
+  return null;
+}
+
+function extractName(player) {
+  if (!player || typeof player !== "object") return null;
+  const value =
+    getValueCaseInsensitive(player, "Player") ??
+    getValueCaseInsensitive(player, "Name") ??
+    getValueCaseInsensitive(player, "Username") ??
+    getValueCaseInsensitive(player, "DisplayName");
+  if (typeof value !== "string") return null;
+  let trimmed = value.trim();
+  const compoundMatch = trimmed.match(/^(.+?):\d+\s*$/);
+  if (compoundMatch?.[1]) {
+    trimmed = compoundMatch[1].trim();
+  }
+  return trimmed || null;
+}
+
+function extractAvatarUrlFromPlayer(player) {
+  if (!player || typeof player !== "object") return null;
+  const raw =
+    getValueCaseInsensitive(player, "Avatar") ??
+    getValueCaseInsensitive(player, "AvatarUrl") ??
+    getValueCaseInsensitive(player, "Thumbnail") ??
+    getValueCaseInsensitive(player, "ThumbnailUrl") ??
+    getValueCaseInsensitive(player, "Headshot") ??
+    getValueCaseInsensitive(player, "HeadshotUrl");
+  if (typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  return trimmed;
+}
+
+function parseCoordinateString(value) {
+  if (typeof value !== "string") return null;
+  const matches = value.match(/-?\d+(?:\.\d+)?/g);
+  if (!matches || matches.length < 2) return null;
+  const x = toFiniteNumber(matches[0]);
+  const y = toFiniteNumber(matches[1]);
+  if (x === null || y === null) return null;
+  return { x, y, source: "string" };
+}
+
+function extractCoordinatesFromObject(object) {
+  if (!object || typeof object !== "object") return null;
+
+  const x = getFirstFiniteNumber(object, [
+    "MapX",
+    "mapX",
+    "LocationX",
+    "locationX",
+    "PixelX",
+    "pixelX",
+    "X",
+    "x",
+    "PosX",
+    "posX",
+    "PositionX",
+    "positionX",
+  ]);
+  if (x === null) return null;
+
+  const y = getFirstFiniteNumber(object, [
+    "MapY",
+    "mapY",
+    "LocationY",
+    "locationY",
+    "LocationZ",
+    "locationZ",
+    "PixelY",
+    "pixelY",
+    "Z",
+    "z",
+    "Y",
+    "y",
+    "PosY",
+    "posY",
+    "PosZ",
+    "posZ",
+    "PositionY",
+    "positionY",
+    "PositionZ",
+    "positionZ",
+  ]);
+  if (y === null) return null;
+
+  return { x, y, source: "object" };
+}
+
+function extractCoordinates(player) {
+  if (player && typeof player === "object") {
+    const direct = extractCoordinatesFromObject(player);
+    if (direct) return direct;
+
+    const nestedKeys = [
+      "Location",
+      "location",
+      "Coords",
+      "coords",
+      "Coordinate",
+      "coordinate",
+      "Position",
+      "position",
+      "Pos",
+      "pos",
+    ];
+    for (const key of nestedKeys) {
+      const nested = getValueCaseInsensitive(player, key);
+      if (nested && typeof nested === "object") {
+        const nestedCoordinates = extractCoordinatesFromObject(nested);
+        if (nestedCoordinates) {
+          return {
+            ...nestedCoordinates,
+            source: `nested:${key}`,
+          };
+        }
+      }
+      const parsed = parseCoordinateString(nested);
+      if (parsed) {
+        return {
+          ...parsed,
+          source: `string:${key}`,
+        };
+      }
+    }
+  }
+
+  return parseCoordinateString(player);
+}
+
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+
+function toPixelCoordinate(rawCoordinates, options) {
+  const { mapWidth, mapHeight, coordinateBounds, clampToMap } = options;
+  let x = rawCoordinates.x;
+  let y = rawCoordinates.y;
+
+  if (coordinateBounds) {
+    const minX = toFiniteNumber(coordinateBounds.minX);
+    const maxX = toFiniteNumber(coordinateBounds.maxX);
+    const minY = toFiniteNumber(coordinateBounds.minY);
+    const maxY = toFiniteNumber(coordinateBounds.maxY);
+    if (
+      minX === null ||
+      maxX === null ||
+      minY === null ||
+      maxY === null ||
+      maxX === minX ||
+      maxY === minY
+    ) {
+      throw new ERLCError(
+        "Invalid coordinateBounds. minX/maxX/minY/maxY must be finite and non-equal.",
+      );
+    }
+
+    const normalizedX = (x - minX) / (maxX - minX);
+    let normalizedY = (y - minY) / (maxY - minY);
+    if (coordinateBounds.invertY === true) {
+      normalizedY = 1 - normalizedY;
+    }
+    x = normalizedX * (mapWidth - 1);
+    y = normalizedY * (mapHeight - 1);
+  }
+
+  if (!Number.isFinite(x) || !Number.isFinite(y)) return null;
+
+  if (clampToMap !== false) {
+    x = clamp(x, 0, mapWidth - 1);
+    y = clamp(y, 0, mapHeight - 1);
+  }
+
+  return { x, y };
+}
+
+async function fetchJson(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new ERLCError(`Request failed (${response.status}) for ${url}`);
+  }
+  return response.json();
+}
+
+async function fetchBuffer(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new ERLCError(`Request failed (${response.status}) for ${url}`);
+  }
+  const contentType = response.headers.get("content-type") || "";
+  if (!contentType.startsWith("image/")) {
+    throw new ERLCError(`Expected image response from ${url}`);
+  }
+  const bytes = await response.arrayBuffer();
+  return Buffer.from(bytes);
+}
+
+async function fetchRobloxHeadshots(userIds, size) {
+  if (!Array.isArray(userIds) || userIds.length === 0) {
+    return new Map();
+  }
+
+  const dedupedUserIds = [...new Set(userIds)];
+  const lookup = new Map();
+  const chunkSize = 100;
+
+  for (let index = 0; index < dedupedUserIds.length; index += chunkSize) {
+    const chunk = dedupedUserIds.slice(index, index + chunkSize);
+    const query = new URLSearchParams({
+      userIds: chunk.join(","),
+      size,
+      format: "Png",
+      isCircular: "false",
+    });
+    const payload = await fetchJson(`${ROBLOX_HEADSHOT_URL}?${query}`);
+    const data = Array.isArray(payload?.data) ? payload.data : [];
+    for (const item of data) {
+      const userId = toUserId(item?.targetId);
+      const imageUrl =
+        typeof item?.imageUrl === "string" ? item.imageUrl : null;
+      if (userId && imageUrl) {
+        lookup.set(userId, imageUrl);
+      }
+    }
+  }
+
+  return lookup;
+}
+
+function drawPlaceholderAvatar(ctx, centerX, centerY, radius) {
+  ctx.fillStyle = "#ffffff";
+  ctx.beginPath();
+  ctx.arc(centerX, centerY, radius, 0, Math.PI * 2);
+  ctx.fill();
+}
+
+let markerPath2D = null;
+
+function drawMarker(ctx, avatarImage, position, markerOptions) {
+  const { x, y } = position;
+  const { Path2D } = loadCanvasModule();
+
+  if (!markerPath2D) {
+    markerPath2D = new Path2D(
+      "M12 2c-4.41 0-8 3.59-8 8c-.03 6.44 7.12 11.6 7.42 11.82c.17.12.38.19.58.19s.41-.06.58-.19c.3-.22 7.45-5.37 7.42-11.82c0-4.41-3.59-8-8-8m0 12c-2.21 0-4-1.79-4-4s1.79-4 4-4s4 1.79 4 4s-1.79 4-4 4",
+    );
+  }
+
+  const s = markerOptions.outerRadius / 15;
+
+  ctx.save();
+  ctx.translate(x, y);
+  ctx.scale(s, s);
+  ctx.translate(-12, -22);
+
+  ctx.fillStyle = markerOptions.fillColor;
+  ctx.fill(markerPath2D);
+
+  const avatarRadius = 6.8;
+  const scaledOffset = (markerOptions.avatarYOffset || 0) / s;
+
+  ctx.beginPath();
+  ctx.arc(12, 10 + scaledOffset, avatarRadius, 0, Math.PI * 2);
+  ctx.closePath();
+  ctx.clip();
+
+  ctx.fillStyle = "#ffffff";
+  ctx.fillRect(
+    12 - avatarRadius,
+    10 + scaledOffset - avatarRadius,
+    avatarRadius * 2,
+    avatarRadius * 2,
+  );
+
+  ctx.imageSmoothingEnabled = true;
+  ctx.imageSmoothingQuality = "high";
+
+  if (avatarImage) {
+    ctx.drawImage(
+      avatarImage,
+      12 - avatarRadius,
+      10 + scaledOffset - avatarRadius,
+      avatarRadius * 2,
+      avatarRadius * 2,
+    );
+  } else {
+    drawPlaceholderAvatar(ctx, 12, 10 + scaledOffset, avatarRadius);
+  }
+
+  ctx.restore();
+}
+
+function normalizeMarkerOptions(options = {}) {
+  const scaleRaw = toFiniteNumber(options.scale);
+  const scale = Number.isFinite(scaleRaw)
+    ? Math.max(0.15, Math.min(3, scaleRaw))
+    : 1;
+
+  const baseOuter = toFiniteNumber(options.outerRadius) ?? 45;
+  const baseInner = toFiniteNumber(options.innerRadius) ?? baseOuter * 0.78;
+  const baseTip = toFiniteNumber(options.tipLength) ?? baseOuter * 1.15;
+
+  const outerRadius = Math.max(6, Math.round(baseOuter * scale));
+  const innerRadius = Math.max(
+    4,
+    Math.min(outerRadius - 3, Math.round(baseInner * scale)),
+  );
+  const tipLength = Math.max(8, Math.round(baseTip * scale));
+
+  const strokeWidth = Number.isFinite(toFiniteNumber(options.strokeWidth))
+    ? Math.max(0, Math.round(toFiniteNumber(options.strokeWidth) * scale))
+    : Math.max(2, Math.round(outerRadius * 0.16));
+
+  const baseAngle = Number.isFinite(toFiniteNumber(options.baseAngle))
+    ? Math.max(0.45, Math.min(0.75, toFiniteNumber(options.baseAngle)))
+    : 0.58;
+
+  return {
+    scale,
+    outerRadius,
+    innerRadius,
+    tipLength,
+    baseAngle,
+
+    fillColor:
+      typeof options.fillColor === "string" && options.fillColor.trim()
+        ? options.fillColor
+        : "#ffffff",
+
+    avatarYOffset: Number.isFinite(toFiniteNumber(options.avatarYOffset))
+      ? toFiniteNumber(options.avatarYOffset)
+      : 0,
+  };
+}
+
+function normalizeRenderOptions(input = {}) {
+  const mapWidth = normalizeFixedMapDimension(input.mapWidth, "mapWidth");
+  const mapHeight = normalizeFixedMapDimension(input.mapHeight, "mapHeight");
+  const customMapUrl =
+    typeof input.mapUrl === "string" && input.mapUrl.trim()
+      ? input.mapUrl.trim()
+      : null;
+  const requestedMapSeason = normalizeMapSeason(
+    input.mapSeason ?? input.season,
+  );
+  const requestedMapType = normalizeMapType(input.mapType ?? input.type);
+  const officialMap = customMapUrl
+    ? null
+    : buildOfficialMapUrl(
+        requestedMapSeason || "fall",
+        requestedMapType || "blank",
+      );
+
+  return {
+    mapUrl: customMapUrl || officialMap?.url || DEFAULT_MAP_URL,
+    mapSeason: officialMap?.season || null,
+    mapType: officialMap?.type || null,
+    mapWidth,
+    mapHeight,
+    userId: toUserId(input.userId),
+    userIds: Array.isArray(input.userIds)
+      ? input.userIds.map(toUserId).filter(Boolean)
+      : [],
+    players: Array.isArray(input.players) ? input.players : null,
+    coordinateBounds:
+      input.coordinateBounds && typeof input.coordinateBounds === "object"
+        ? {
+            minX: input.coordinateBounds.minX,
+            maxX: input.coordinateBounds.maxX,
+            minY: input.coordinateBounds.minY,
+            maxY: input.coordinateBounds.maxY,
+            invertY: input.coordinateBounds.invertY === true,
+          }
+        : null,
+    clampToMap: input.clampToMap !== false,
+    robloxHeadshotSize:
+      typeof input.robloxHeadshotSize === "string" &&
+      /^\d+x\d+$/i.test(input.robloxHeadshotSize)
+        ? input.robloxHeadshotSize
+        : "150x150",
+    marker: normalizeMarkerOptions(input.marker),
+  };
+}
+
+function buildPlayerRecords(players, renderOptions) {
+  const records = [];
+  const skipped = [];
+
+  for (const player of players) {
+    const userId = extractUserId(player);
+    const name = extractName(player);
+
+    const rawCoordinates = extractCoordinates(player);
+    if (!rawCoordinates) {
+      skipped.push({
+        userId,
+        name,
+        reason: "missing_coordinates",
+      });
+      continue;
+    }
+
+    const pixelCoordinates = toPixelCoordinate(rawCoordinates, renderOptions);
+    if (!pixelCoordinates) {
+      skipped.push({
+        userId,
+        name,
+        reason: "invalid_coordinates",
+      });
+      continue;
+    }
+
+    records.push({
+      userId,
+      name,
+      player,
+      rawCoordinates,
+      pixelCoordinates,
+      avatarUrl: extractAvatarUrlFromPlayer(player),
+    });
+  }
+
+  return { records, skipped };
+}
+
+function applyUserFilters(records, options) {
+  const targetUserIds = new Set(options.userIds);
+  if (options.userId) {
+    targetUserIds.add(options.userId);
+  }
+  if (targetUserIds.size === 0) {
+    return {
+      records,
+      requestedUserIds: [],
+      unmatchedUserIds: [],
+    };
+  }
+
+  const filteredRecords = records.filter(
+    (record) => record.userId && targetUserIds.has(record.userId),
+  );
+  const matchedUserIds = new Set(
+    filteredRecords.map((record) => record.userId).filter(Boolean),
+  );
+  const unmatchedUserIds = [...targetUserIds].filter(
+    (userId) => !matchedUserIds.has(userId),
+  );
+
+  return {
+    records: filteredRecords,
+    requestedUserIds: [...targetUserIds],
+    unmatchedUserIds,
+  };
+}
+
+async function loadImageSafe(loadImage, urlOrBuffer) {
+  try {
+    return await loadImage(urlOrBuffer);
+  } catch {
+    return null;
+  }
+}
+
+async function renderPlayerMap(client, options = {}, requestOptions = {}) {
+  const { createCanvas, loadImage } = loadCanvasModule();
+  const renderOptions = normalizeRenderOptions(options);
+
+  const rawPlayers =
+    renderOptions.players ||
+    (await client.server
+      .fetch(
+        {
+          players: true,
+        },
+        requestOptions,
+      )
+      .then((snapshot) => snapshot.players));
+
+  if (!Array.isArray(rawPlayers)) {
+    throw new ERLCError("Players response was not an array");
+  }
+
+  const { records, skipped } = buildPlayerRecords(rawPlayers, renderOptions);
+  const filtered = applyUserFilters(records, renderOptions);
+  const filteredRecords = filtered.records;
+
+  const userIdsForHeadshots = filteredRecords
+    .map((record) => record.userId)
+    .filter(Boolean);
+  const robloxHeadshots = await fetchRobloxHeadshots(
+    userIdsForHeadshots,
+    renderOptions.robloxHeadshotSize,
+  );
+
+  const avatarUrlToImage = new Map();
+  const avatarSources = [
+    ...new Set(
+      filteredRecords
+        .map((record) => robloxHeadshots.get(record.userId) || record.avatarUrl)
+        .filter(Boolean),
+    ),
+  ];
+
+  await Promise.all(
+    avatarSources.map(async (avatarUrl) => {
+      const buffer = await fetchBuffer(avatarUrl).catch(() => null);
+      if (!buffer) return;
+      const image = await loadImageSafe(loadImage, buffer);
+      if (image) {
+        avatarUrlToImage.set(avatarUrl, image);
+      }
+    }),
+  );
+
+  const mapBuffer = await fetchBuffer(renderOptions.mapUrl);
+  const mapImage = await loadImageSafe(loadImage, mapBuffer);
+  if (!mapImage) {
+    throw new ERLCError("Failed to decode map image");
+  }
+
+  const canvas = createCanvas(renderOptions.mapWidth, renderOptions.mapHeight);
+  const ctx = canvas.getContext("2d");
+  ctx.drawImage(
+    mapImage,
+    0,
+    0,
+    renderOptions.mapWidth,
+    renderOptions.mapHeight,
+  );
+
+  const renderedPlayers = [];
+  for (const record of filteredRecords) {
+    const resolvedAvatarUrl =
+      robloxHeadshots.get(record.userId) || record.avatarUrl;
+    const avatarImage = resolvedAvatarUrl
+      ? avatarUrlToImage.get(resolvedAvatarUrl) || null
+      : null;
+
+    drawMarker(ctx, avatarImage, record.pixelCoordinates, renderOptions.marker);
+    renderedPlayers.push({
+      userId: record.userId,
+      name: record.name,
+      avatarUrl: resolvedAvatarUrl || null,
+      sourceX: record.rawCoordinates.x,
+      sourceY: record.rawCoordinates.y,
+      sourceType: record.rawCoordinates.source,
+      pixelX: Math.round(record.pixelCoordinates.x * 100) / 100,
+      pixelY: Math.round(record.pixelCoordinates.y * 100) / 100,
+    });
+  }
+
+  return {
+    buffer: canvas.toBuffer("image/png"),
+    mimeType: "image/png",
+    map: {
+      url: renderOptions.mapUrl,
+      season: renderOptions.mapSeason,
+      type: renderOptions.mapType,
+      width: renderOptions.mapWidth,
+      height: renderOptions.mapHeight,
+    },
+    players: renderedPlayers,
+    skipped,
+    requestedUserIds: filtered.requestedUserIds,
+    unmatchedUserIds: filtered.unmatchedUserIds,
+  };
+}
+
+module.exports = {
+  DEFAULT_MAP_URL,
+  renderPlayerMap,
+};