Entities · Sharkhex Spaces

An entity is an object placed on a map, such as a desk, a plant or a screen. The map's layout places it (Map format); a prefab of the tenant's entity catalogue gives it its image, its size, the cells it blocks and how it sorts against avatars.

Prefabs

Field	Meaning
`id`	a built-in prefab's name, such as `chair-blue-down`, or a UUID for one of the tenant's own
`collection`	the collection the editor offers it in
`name`	what the editor shows; a built-in prefab's is in the language of the request's `Accept-Language`
`variant`	prefabs of one variant differ only in `colour` and `direction`, and the editor offers them as one item
`colour`	a free name of at most 40 characters, the same in every language; empty for a prefab that comes in one colour
`colourName`	the colour as the editor shows it: a built-in prefab's in the language of the request's `Accept-Language`, a tenant's prefab's the same as `colour`
`direction`	where the prefab faces: `down`, `left`, `right` or `up`; empty for one that faces no way
`tags`	at most 10 words of 1 to 32 characters, for search
`width`, `height`	the image's size in pixels
`collision`	a row of 32-pixel cells for every 32 pixels of the image's height, top first, with `1` for a cell that blocks and `0` for one that does not; the last row and column may cover less than 32 pixels
`depth`	pixels from −512 to 512 that move the line the prefab sorts by from its bottom edge
`url`	where browsers fetch the image
`ownerId`	the account that uploaded one of the tenant's prefabs
`removed`	taken out of the catalogue; the entities already placed keep showing it

On the map

The client draws an entity's image with its top-left corner at the entity's x and y, among the avatars. An avatar sorts by the point it stands on and an entity by y + height + depth: an avatar standing below a desk's bottom edge stands in front of it, one standing above it behind it. A rug has a depth of −64 on its 64-pixel height, so it sorts by its top edge and avatars walk over it.
Every cell of the collision grid marked 1 blocks the cell of the map under its middle, so an entity off the map's grid still blocks whole cells. Avatars walk round blocked cells, walks to a point search round them, and a player standing on one walks off it freely.
An entity whose centre lies in an access area that keeps the player out neither shows nor blocks for that player (Map format).
An entity's behaviours act when a player within 48 pixels of it activates it, with the action key or a click (Map format).
The room blocks the same cells, from the tenant's catalogue, so that a player never enters standing on one: in a start area, at its desk, near the map's centre or at the point it left. An editor's change to the entities, and a change to a prefab's collision grid, which every process running a room of the tenant hears, count from the next player who enters; players already standing on a cell an entity takes walk off it freely.

Catalogue

GET /api/v1/entities lists the tenant's collections, the built-in ones first and then the tenant's own (custom), each with its prefabs, those of a variant next to each other. It needs no account. The client loads it with the map and draws the entities once their images arrive.

Images are served at GET /api/v1/entity-images/<file> under names that carry their content hash, so browsers keep them for a year.

Built-in collections

The built-in prefabs are drawn by the product's own code when the process starts. They need no image files. Their ids join the variant, the colour and the direction, such as desk-oak, chair-blue-down or lamp, and stay the same from release to release. Their names, the names of their colours and of the two collections come from the server's catalogues, in the language of the request (Languages); the tenant's own keep the names their uploaders gave them.

Collection	Variant	Size	Colours	Directions	Blocks
`office`	`desk`	64 × 32	oak, walnut, white		all
`office`	`chair`	32 × 32	blue, red, grey, green	down, left, right, up	nothing
`office`	`sofa`	64 × 32	teal, grey, mustard	down, up	all
`office`	`meeting-table`	96 × 64	oak, walnut, white		all
`office`	`bookshelf`	64 × 32	oak, walnut, white		all
`office`	`cabinet`	32 × 32	grey, white		all
`office`	`whiteboard`	64 × 32			all
`office`	`screen`	64 × 32			all
`office`	`lamp`	32 × 32			all
`office`	`plant`	32 × 32	green, olive		all
`office`	`rug`	64 × 64	red, blue, sand		nothing; depth −64
`office`	`coffee-machine`	32 × 32			all
`office`	`water-cooler`	32 × 32			all
`outdoors`	`tree`	64 × 64	green, olive		the trunk's row
`outdoors`	`bush`	32 × 32	green, olive		all
`outdoors`	`flowers`	32 × 32	red, yellow, purple		nothing
`outdoors`	`rock`	32 × 32			all
`outdoors`	`bench`	64 × 32	oak, walnut, white		all

The tenant's prefabs

The editor's entity tool uploads prefabs from an image chosen or dropped. POST /api/v1/entities?collection=…&name=… adds a prefab to one of the tenant's collections, with the image as the body: PNG, JPEG or WebP, at most 512 pixels a side and 1 MiB. The optional parameters variant, colour, direction, tags, collision and depth take the fields above; lists are comma-separated. The answer is the prefab, with a UUID for its id.

The tenant's admins and the editors of any of its worlds may upload; the uploading account owns the prefab.
A collection's id has 1 to 40 lowercase letters, digits and hyphens, and is never a built-in collection's. A collection exists while it holds prefabs.
The variant defaults to the name in lowercase letters and digits joined by hyphens, so that prefabs of one name group together; the collision grid defaults to one that blocks nothing.
PATCH /api/v1/entities/{prefab} changes the fields above but the image, and DELETE /api/v1/entities/{prefab} takes the prefab out of the catalogue, for its owner or the tenant's admins. A removed prefab stays listed with removed set, and the entities placed from it keep showing it, but packages and the editor may no longer place it.
The images live in object storage under tenants/<tenant id>/entities/, named by their SHA-256, with a file_object row of kind entity_image; prefabs are rows of entity_prefab, and every change goes to the audit log.

Layouts

A layout names an entity's prefab by collection and id, and its collections list what the editor offers (Map format). Both are checked against the tenant's catalogue: an upload or a replacement that names an unknown prefab or collection is rejected with layout.unknown-prefab or layout.unknown-collection, and the room refuses an editor command that places an unknown prefab with BAD_REQUEST.