screeps-connectivity 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.5.1
+
+### Patch Changes
+
+- 36673a3: Add `Game.map.visual` rendering support. The map view now subscribes to the `mapVisual` WebSocket channel and renders player-drawn map visuals (lines, circles, rects, polys, text) on the world map canvas using PixiJS.
+
+## 0.5.0
+
+### Minor Changes
+
+- 1e7161f: Add `http.game.roomHistory(room, time, shard?)` to `GameEndpoints` — handles both official server (path-based URL) and private server (query-param URL) automatically. `HistoryPlayer` in `screeps-client` is refactored to use this endpoint instead of a raw `fetch()` with manual token injection.
+
 ## 0.4.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screeps-connectivity",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "license": "ISC",
   "type": "module",
   "repository": {

package/src/ScreepsClient.ts

@@ -13,6 +13,7 @@ import type { LogFn } from './logger.js'
 import type { AuthStrategy } from './http/auth/AuthStrategy.js'
 import type { StorageAdapter } from './storage/StorageAdapter.js'
 import type { Subscription } from './subscription/index.js'
+import type { ApiRoomDecorationsResponse } from './types/api.js'
 
 type WsConstructor = typeof globalThis.WebSocket
 
@@ -39,6 +40,8 @@ export interface ScreepsClientOptions {
    * Pass `false` to disable.
    */
   tokenRefresh?: TokenRefreshOptions | false
+  /** Override the /api/game/room-decorations response with static data (useful for dev/testing when the server doesn't support the endpoint). */
+  decorationsMock?: ApiRoomDecorationsResponse
 }
 
 export class ScreepsClient {
@@ -70,7 +73,7 @@ export class ScreepsClient {
     this.logger = Logger.create(opts.debug)
     this.logger.log(`[screeps:client] init ${opts.url}`)
     this.cache = new Cache(namespace, opts.storage ?? null)
-    this.http = new HttpClient({ url: opts.url, auth: opts.auth, logger: this.logger.child('http'), serverPassword: opts.serverPassword })
+    this.http = new HttpClient({ url: opts.url, auth: opts.auth, logger: this.logger.child('http'), serverPassword: opts.serverPassword, decorationsMock: opts.decorationsMock })
     this.socket = new SocketClient({ url: opts.url, WebSocket: opts.WebSocket, logger: this.logger.child('socket') })
     const map2Storage = new Map2Storage({
       adapter: opts.storage ?? null,

package/src/http/HttpClient.ts

@@ -32,7 +32,7 @@ export class HttpClient extends EventTarget {
   readonly leaderboard: LeaderboardEndpoints
   readonly experimental: ExperimentalEndpoints
 
-  constructor(opts: { url: string; auth: AuthStrategy; logger?: Logger; serverPassword?: string }) {
+  constructor(opts: { url: string; auth: AuthStrategy; logger?: Logger; serverPassword?: string; decorationsMock?: import('../types/api.js').ApiRoomDecorationsResponse }) {
     super()
     this.baseUrl = opts.url.endsWith('/') ? opts.url : `${opts.url}/`
     this.authStrategy = opts.auth
@@ -40,7 +40,7 @@ export class HttpClient extends EventTarget {
     this.serverPassword = opts.serverPassword ?? null
     this.auth = createAuthEndpoints(this)
     this.register = createRegisterEndpoints(this)
-    this.game = createGameEndpoints(this)
+    this.game = createGameEndpoints(this, opts.decorationsMock)
     this.user = createUserEndpoints(this)
     this.leaderboard = createLeaderboardEndpoints(this)
     this.experimental = createExperimentalEndpoints(this)

package/src/http/endpoints/game.ts

@@ -13,6 +13,8 @@ import type {
   ApiGenUniqueObjectNameResponse,
   ApiCheckUniqueObjectNameResponse,
   ApiGameTickResponse,
+  RoomHistoryChunk,
+  ApiRoomDecorationsResponse,
 } from '../../types/api.js'
 import { createPowerCreepsEndpoints, type PowerCreepsEndpoints } from './power-creeps.js'
 
@@ -20,6 +22,7 @@ export interface GameEndpoints {
   roomTerrain(room: string, shard?: string | null): Promise<ApiRoomTerrainResponse>
   /** @deprecated Not available on private servers (backend-local). Room objects are delivered via the `room:<name>` WebSocket channel. */
   roomObjects(room: string, shard?: string | null): Promise<ApiRoomObjectsResponse>
+  roomDecorations(room: string, shard?: string | null): Promise<ApiRoomDecorationsResponse>
   roomStatus(room: string, shard?: string | null): Promise<{ ok: number; status: string; novice?: string }>
   roomOverview(room: string, interval?: number, shard?: string | null): Promise<unknown>
   time(shard?: string | null): Promise<{ ok: number; time: number }>
@@ -39,6 +42,8 @@ export interface GameEndpoints {
   removeConstructionSite(room: string, ids: string[], shard?: string | null): Promise<{ ok: number }>
   addObjectIntent(id: string, room: string, name: string, intent: unknown, shard?: string | null): Promise<{ ok: number }>
   addGlobalIntent(name: string, intent: unknown): Promise<{ ok: number }>
+  /** Fetch a room history chunk. Pass shard for official multi-shard servers; omit for private servers. */
+  roomHistory(room: string, time: number, shard?: string | null): Promise<RoomHistoryChunk>
   setNotifyWhenAttacked(id: string, enabled: boolean): Promise<{ ok: number }>
   createInvader(room: string, x: number, y: number, size: number, type: string, boosted?: boolean): Promise<{ ok: number }>
   removeInvader(id: string): Promise<{ ok: number }>
@@ -59,10 +64,13 @@ function withShard(params: Record<string, unknown>, shard?: string | null): Reco
   return params
 }
 
-export function createGameEndpoints(http: HttpClient): GameEndpoints {
+export function createGameEndpoints(http: HttpClient, decorationsMock?: ApiRoomDecorationsResponse): GameEndpoints {
   return {
     roomTerrain: (room, shard) => http.request('GET', '/api/game/room-terrain', withShard({ room, encoded: 1 }, shard)),
     roomObjects: (room, shard) => http.request('GET', '/api/game/room-objects', withShard({ room }, shard)),
+    roomDecorations: decorationsMock
+      ? () => Promise.resolve(decorationsMock)
+      : (room, shard) => http.request('GET', '/api/game/room-decorations', withShard({ room }, shard)),
     roomStatus: (room, shard) => http.request('GET', '/api/game/room-status', withShard({ room }, shard)),
     roomOverview: (room, interval = 8, shard) => http.request('GET', '/api/game/room-overview', withShard({ room, interval }, shard)),
     time: (shard) => http.request('GET', '/api/game/time', withShard({}, shard)),
@@ -85,6 +93,10 @@ export function createGameEndpoints(http: HttpClient): GameEndpoints {
     removeConstructionSite: (room, ids, shard) => http.request('POST', '/api/game/add-object-intent', withShard({ _id: 'room', room, name: 'removeConstructionSite', intent: ids.map(id => ({ id, roomName: room })) }, shard)),
     addObjectIntent: (id, room, name, intent, shard) => http.request('POST', '/api/game/add-object-intent', withShard({ _id: id, room, name, intent }, shard)),
     addGlobalIntent: (name, intent) => http.request('POST', '/api/game/add-global-intent', { name, intent }),
+    roomHistory: (room, time, shard) =>
+      shard
+        ? http.request('GET', `/room-history/${encodeURIComponent(shard)}/${encodeURIComponent(room)}/${time}.json`)
+        : http.request('GET', '/room-history', { room, time }),
     setNotifyWhenAttacked: (id, enabled) => http.request('POST', '/api/game/set-notify-when-attacked', { _id: id, enabled }),
     createInvader: (room, x, y, size, type, boosted) => http.request('POST', '/api/game/create-invader', { room, x, y, size, type, ...(boosted != null ? { boosted } : {}) }),
     removeInvader: (id) => http.request('POST', '/api/game/remove-invader', { _id: id }),

package/src/index.ts

@@ -35,10 +35,13 @@ export type {
   Badge,
   VisualStyle,
   RoomVisualEntry,
+  MapVisualEntry,
 } from './types/game.js'
 
 export { fetchServerVersion, fetchAuthModInfo, checkUsername, checkEmail, registerUser, getServerFeature, getScreepsmodAuth } from './http/fetchServerVersion.js'
 export type { ApiAuthModInfoResponse } from './http/fetchServerVersion.js'
+export type { RoomHistoryChunk, ApiRoomDecorationsResponse, ApiRoomDecorationItem, ApiRoomDecorationDef, ApiRoomDecorationGraphic, ApiRoomDecorationActive } from './types/api.js'
+export { ROOM_DECORATIONS_MOCK } from './mocks/roomDecorations.js'
 
 export { badgeToSvg } from './badge/index.js'
 export { BadgeColors } from './badge/colors.js'

package/src/mocks/roomDecorations.ts

@@ -0,0 +1,140 @@
+import type { ApiRoomDecorationsResponse } from '../types/api.js'
+
+/**
+ * Example /api/game/room-decorations response captured from the official Screeps server.
+ * Use as `decorationsMock` in ScreepsClientOptions to test decoration rendering locally.
+ *
+ * Contains: wallLandscape (W-00031), floorLandscape (F-00065), creep overlay (C-00071).
+ */
+export const ROOM_DECORATIONS_MOCK: ApiRoomDecorationsResponse = {
+  ok: 1,
+  decorations: [
+    {
+      _id: '5fd719f496a97dbdd2f57bea',
+      user: '58356f6fc8012784246abb7e',
+      active: {
+        strokeWidth: '30',
+        foregroundColor: '#6A88FF',
+        foregroundAlpha: 1,
+        backgroundColor: '#5261A0',
+        backgroundBrightness: '1',
+        strokeColor: '#465EC4',
+        strokeBrightness: '1',
+        strokeLighting: '1',
+        foregroundBrightness: '1',
+        world: true,
+        tileScale: 1,
+        shard: 'shard1',
+        room: 'E2S49',
+      },
+      decoration: {
+        _id: '5eea71d952fdab816c74e50c',
+        graphics: [],
+        description: 'звездочки',
+        rarityMultiplier: 1,
+        type: 'wallLandscape',
+        foregroundUrl: 'https://s3.amazonaws.com/static.screeps.com/decorations/0e53bc662a2688275b9c6766cf946031b19bf0b.png',
+        theme: '5e908ece62339b0045ac2d0e',
+        rarity: 4,
+        name: 'W-00031:WI:X',
+        group: '5edf121e1f95b4047880e2ef',
+        steamItemDefId: 4415,
+        enabled: true,
+        groupDescription: 'Controllable brightness.',
+        preview: {
+          original: 'https://s3.amazonaws.com/static.screeps.com/decorations/6c5533fd1f83ecadb8cf105fdda95fa4687114b.png',
+          '128x128': 'https://s3.amazonaws.com/static.screeps.com/decorations/919410fbd3c74c697d7396ba0636b2d33ca3fa5.png',
+          '256x256': 'https://s3.amazonaws.com/static.screeps.com/decorations/16f3453e69387abfe110050532d9e7c67e8fc41.png',
+        },
+      },
+    },
+    {
+      _id: '60086a96a6ad8c744554e05c',
+      user: '58356f6fc8012784246abb7e',
+      active: {
+        floorBackgroundColor: '#F67BFF',
+        floorBackgroundBrightness: 0.98,
+        floorForegroundColor: '#F67BFF',
+        floorForegroundAlpha: 0.87,
+        swampColor: '#4073A3',
+        swampStrokeColor: '#CC7DD2',
+        swampStrokeWidth: 30,
+        roadsColor: '#E9A7EE',
+        roadsBrightness: 0.41,
+        tileScale: 1,
+        floorForegroundBrightness: 0.42,
+        world: true,
+        shard: 'shard1',
+        room: 'E2S49',
+      },
+      decoration: {
+        _id: '5eea668452fdab5ea674e1ca',
+        graphics: [],
+        description: 'калейдоскоп',
+        rarityMultiplier: 1,
+        type: 'floorLandscape',
+        floorForegroundUrl: 'https://s3.amazonaws.com/static.screeps.com/decorations/7e3d680d2f48b1ff244a95e564275536fe4ed61.png',
+        theme: '5e908ed162339b0045ac2d0f',
+        rarity: 4,
+        name: 'F-00065:AL:X',
+        group: '5ee9016d961c4e27734cf301',
+        steamItemDefId: 3606,
+        enabled: true,
+        groupDescription: 'Adjustable brightness.',
+        preview: {
+          original: 'https://s3.amazonaws.com/static.screeps.com/decorations/da7256631a2a2c8568221ad1f0bef0bb5525a7.png',
+          '128x128': 'https://s3.amazonaws.com/static.screeps.com/decorations/3c0f0da6b41e413bdc4f66a01eed62b5b252c29.png',
+          '256x256': 'https://s3.amazonaws.com/static.screeps.com/decorations/80c9978b58403e13b4a28f47ef1422e895c04fe.png',
+        },
+      },
+    },
+    {
+      _id: '5fbab429b2f60e0fae891bcb',
+      user: '58356f6fc8012784246abb7e',
+      active: {
+        lighting: true,
+        position: 'below',
+        width: 256,
+        height: 256,
+        syncRotate: true,
+        animation: 'blink',
+        brightness: '1',
+        nameFilter: 'ecarry*',
+        exclude: false,
+        firstColor: '#FFFFFF',
+        firstAlpha: 1,
+        secondColor: '#FFFFFF',
+        secondAlpha: '1',
+        flip: false,
+        color: '#1fe265',
+        alpha: 0.79,
+      },
+      decoration: {
+        _id: '5f2ab6c1ad10bf3222df1b4f',
+        graphics: [
+          {
+            url: 'https://s3.amazonaws.com/static.screeps.com/decorations/a23d96123d27bf163babe0a29a54de003aea568.svg',
+            color: 'color',
+            alpha: 'alpha',
+            visible: '',
+          },
+        ],
+        description: '38.svg',
+        rarityMultiplier: 1,
+        type: 'creep',
+        theme: '5ee3db64961c4e98dc4cf121',
+        rarity: 5,
+        name: 'C-00071:CC:X',
+        group: '5eec306d0042094b2845f7d6',
+        steamItemDefId: 57779,
+        enabled: true,
+        groupDescription: 'Choose your own color.',
+        preview: {
+          original: 'https://s3.amazonaws.com/static.screeps.com/decorations/3a7853ca055d7ae5738852f6f73f27389594e2e.png',
+          '128x128': 'https://s3.amazonaws.com/static.screeps.com/decorations/8557cffe9216525092427f90b9847ef5bdcd6c8.png',
+          '256x256': 'https://s3.amazonaws.com/static.screeps.com/decorations/e198e4f909cdb99f11a8cc7bc9f7e7a733faeca.png',
+        },
+      },
+    },
+  ],
+}

package/src/stores/UserStore.ts

@@ -200,6 +200,41 @@ export class UserStore extends TypedStore<UserStoreEvents> {
     }
   }
 
+  subscribeMapVisual(shard: string | null): Subscription {
+    this.logger.log('subscribe mapVisual', shard)
+    let socketSub: Subscription | null = null
+    let listenerSub: Subscription | null = null
+    let disposed = false
+
+    const setup = async () => {
+      try {
+        const uid = this._userId ?? (await this.me())._id
+        if (disposed) return
+        // Official multi-shard servers use mapVisual:${uid}/${shard}; unofficial use mapVisual:${uid}.
+        const fullChannel = shard ? `mapVisual:${uid}/${shard}` : `mapVisual:${uid}`
+        socketSub = this.socket.subscribe(fullChannel)
+        listenerSub = this.socket.on(fullChannel, (data) => {
+          this.emit('user:mapVisual', { shard, data: typeof data === 'string' ? data : '' })
+        })
+      } catch (err) {
+        if (!disposed) {
+          this.dispatchEvent(new ErrorEvent('error', { error: err instanceof Error ? err : new Error(String(err)) }))
+        }
+      }
+    }
+
+    void setup()
+
+    return {
+      dispose: () => {
+        this.logger.log('unsubscribe mapVisual', shard)
+        disposed = true
+        socketSub?.dispose()
+        listenerSub?.dispose()
+      },
+    }
+  }
+
   /** Subscribe to the general user stream to receive global data like flags. */
   subscribeUserStream(): Subscription {
     this.logger.log('subscribe user stream')

package/src/types/api.ts

@@ -2,6 +2,13 @@ export interface ApiOkResponse {
   ok: number
 }
 
+export interface RoomHistoryChunk {
+  timestamp: number
+  room: string
+  base: number
+  ticks: Record<string, import('./game.js').RoomObjectDiff>
+}
+
 export interface ApiAuthSigninResponse {
   ok: number
   token: string
@@ -250,3 +257,71 @@ export interface ApiUserMessagesUnreadCountResponse {
   ok: number
   count: number
 }
+
+export interface ApiRoomDecorationGraphic {
+  url: string
+  color?: string
+  alpha?: string
+  visible?: string
+}
+
+export interface ApiRoomDecorationDef {
+  _id: string
+  type: 'floorLandscape' | 'wallLandscape' | 'wallGraffiti' | 'creep' | 'object' | 'metadata'
+  graphics?: ApiRoomDecorationGraphic[]
+  foregroundUrl?: string
+  floorForegroundUrl?: string
+  tileScale?: number | string
+  [key: string]: unknown
+}
+
+/** User-configured properties for an activated decoration. Number fields may arrive as strings from the API. */
+export interface ApiRoomDecorationActive {
+  // floorLandscape
+  floorBackgroundColor?: string
+  floorBackgroundBrightness?: number | string
+  floorForegroundColor?: string
+  floorForegroundBrightness?: number | string
+  floorForegroundAlpha?: number | string
+  swampColor?: string
+  swampStrokeColor?: string
+  swampStrokeWidth?: number | string
+  roadsColor?: string
+  roadsBrightness?: number | string
+  // wallLandscape
+  backgroundColor?: string
+  backgroundBrightness?: number | string
+  strokeColor?: string
+  strokeBrightness?: number | string
+  strokeWidth?: number | string
+  strokeLighting?: number | string
+  foregroundColor?: string
+  foregroundAlpha?: number | string
+  foregroundBrightness?: number | string
+  // creep / object
+  user?: string
+  nameFilter?: string
+  exclude?: boolean
+  width?: number | string
+  height?: number | string
+  brightness?: number | string
+  lighting?: boolean
+  animation?: string
+  position?: string
+  syncRotate?: boolean
+  flip?: boolean
+  [key: string]: unknown
+}
+
+/** Raw decoration item as returned by /api/game/room-decorations. */
+export interface ApiRoomDecorationItem {
+  _id: string
+  user: string
+  active: ApiRoomDecorationActive
+  decoration: ApiRoomDecorationDef
+}
+
+export interface ApiRoomDecorationsResponse {
+  ok: number
+  decorations: ApiRoomDecorationItem[]
+}

package/src/types/events.ts

@@ -42,6 +42,7 @@ export interface UserStoreEvents {
     'user:code': { branch: string; modules: Record<string, string> }
     'user:stream': Record<string, unknown>
     'user:memory': { path: string; shard: string | null; value: unknown }
+    'user:mapVisual': { shard: string | null; data: string }
 }
 
 export interface ServerStoreEvents {

package/src/types/game.ts

@@ -150,6 +150,10 @@ export interface VisualStyle {
     width?: number
     radius?: number
     font?: string | number
+    fontSize?: number
+    fontFamily?: string
+    fontStyle?: string
+    fontVariant?: string
 }
 
 export type RoomVisualEntry =
@@ -158,3 +162,10 @@ export type RoomVisualEntry =
     | { t: 'r'; x: number; y: number; w: number; h: number; s: VisualStyle }
     | { t: 'p'; points: [number, number][]; s: VisualStyle }
     | { t: 'l'; x1: number; y1: number; x2: number; y2: number; s: VisualStyle }
+
+export type MapVisualEntry =
+    | { t: 't'; n: string; x: number; y: number; text: string; s: VisualStyle }
+    | { t: 'c'; n: string; x: number; y: number; s: VisualStyle }
+    | { t: 'r'; n: string; x: number; y: number; w: number; h: number; s: VisualStyle }
+    | { t: 'p'; points: Array<{ n: string; x: number; y: number }>; s: VisualStyle }
+    | { t: 'l'; n1: string; x1: number; y1: number; n2: string; x2: number; y2: number; s: VisualStyle }

package/tests/http/endpoints/game.test.ts

@@ -207,4 +207,32 @@ describe('game endpoints', () => {
     expect(url).toContain('/api/game/tick')
     expect(res.tick).toBe(500)
   })
+
+  it('roomHistory uses path URL for official server (shard provided)', async () => {
+    const chunk = { timestamp: 1000, room: 'W1N1', base: 1000, ticks: {} }
+    fetchMock.mockResolvedValue(mockResponse(chunk))
+    const http = new HttpClient({ url: 'http://test.local', auth: new TokenAuth({ token: 't' }) })
+
+    const res = await http.game.roomHistory('W1N1', 1000, 'shard0')
+
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit]
+    expect(init.method).toBe('GET')
+    expect(url).toBe('http://test.local/room-history/shard0/W1N1/1000.json')
+    expect(res.base).toBe(1000)
+  })
+
+  it('roomHistory uses query params for private server (no shard)', async () => {
+    const chunk = { timestamp: 1000, room: 'W1N1', base: 1000, ticks: {} }
+    fetchMock.mockResolvedValue(mockResponse(chunk))
+    const http = new HttpClient({ url: 'http://test.local', auth: new TokenAuth({ token: 't' }) })
+
+    const res = await http.game.roomHistory('W1N1', 1000)
+
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit]
+    expect(init.method).toBe('GET')
+    expect(url).toMatch(/\/room-history/)
+    expect(url).toContain('room=W1N1')
+    expect(url).toContain('time=1000')
+    expect(res.base).toBe(1000)
+  })
 })