WebSocket contract · Bitcraftopia

Client → server

Connect to /ws, then send a subscribe or unsubscribe JSON text frame.

{
  "action": "subscribe",
  "channels": [
    "player:576460752303423488:state",
    "craft:576460752955699184:craft_progress"
  ]
}

{
  "action": "subscribed",
  "channels": [
    "craft:576460752955699184:craft_progress",
    "player:576460752303423488:state"
  ]
}

{
  "action": "unsubscribe",
  "channels": [
    "craft:576460752955699184:craft_progress"
  ]
}

{
  "event": "error",
  "error": {
    "code": "invalid_channel",
    "message": "unknown channel event: bad_event"
  }
}

Channels

player:<playerId>:stateplayer:<playerId>:statsplayer:<playerId>:xpplayer:<playerId>:inventory_changeplayer:<playerId>:passive_craft_createdplayer:<playerId>:passive_craft_finishedplayer:<playerId>:craft_createdplayer:<playerId>:craft_finishedplayer:<playerId>:craft_startplayer:<playerId>:craft_endcraft:<craftId>:craft_progresscraft:<craftId>:craft_finished

Shared output objects

Object	Exact fields	Notes
`PlayerIdentity`	`id: string, name: string`	Ids are canonical positive numeric strings.
`RecipeIdentity`	`id: number, name: string`	Static recipe identity.
`CraftItem`	`name: string, quantity: integer, recipe: RecipeIdentity`	quantity is the recipe output per execution; the enclosing craft carries craftCount.
`CraftProgress`	`completed: integer, required: integer`	Current completed effort and total required effort.
`Contributor`	`actionsContributed: integer, player: PlayerIdentity`	Contribution count for one correlated player.
`ClaimIdentity`	`id: string, name: string`	Owning claim identity.
`BuildingIdentity`	`id: string, name: string, claim: ClaimIdentity`	Craft lifecycle events require a claimed building.
`ActivityBuildingIdentity`	`id: string, name: string, claim: ClaimIdentity \| null`	Player activity may occur at an unclaimed building.

craftCount and item.quantity are separate

A craft producing 90 Sturdy Cloth carries craftCount: 90 and quantity: 1. Multiply them only when the total output amount is needed.

Server → client events

`craft_created`

A progressive craft first appeared at a claimed building.

Channelplayer:<playerId>:craft_created

Required

{
  "event": "craft_created",
  "startedAt": "2026-07-30T18:00:00Z",
  "regionId": 8,
  "player": {
    "id": "576460752303423488",
    "name": "Ada"
  },
  "craft": {
    "id": "576460752955699184",
    "craftCount": 90,
    "item": {
      "name": "Sturdy Cloth",
      "quantity": 1,
      "recipe": {
        "id": 409001,
        "name": "Weave Sturdy Cloth"
      }
    },
    "progress": {
      "completed": 0,
      "required": 13676
    },
    "contributors": [],
    "building": {
      "id": "576460752303423500",
      "name": "Fine Tailoring Station",
      "claim": {
        "id": "576460752303423510",
        "name": "Workshop"
      }
    }
  }
}

Payload fields

Field	Type	Required	Description
`event`	`"craft_created"`	Yes	Exact event discriminator.
`startedAt`	`string`	Yes	UTC ISO 8601 timestamp for the start of the craft.
`regionId`	`integer`	Yes	Numeric BitCraft region id.
`player`	`PlayerIdentity`	Yes	Player identity with a numeric string id and display name.
`craft`	`ProgressiveCraftWithBuilding`	Yes	Progressive craft with its building and owning claim.