Introduction

The RC Together API uses a combination of REST and Action Cable. Action Cable is a protocol built on top of WebSockets. Both the REST and Action Cable APIs use JSON for data encoding and TLS for encryption (HTTPS for REST and WSS for Action Cable).

For example, you might write an app that uses the ActionCable API to be notified whenever someone mentions your bot in a message, and then use the REST API to have your bot do something in response, like moving, or sending a message back.

The REST API is read/write and the Action Cable API is read only. In general, your app will start by connecting to the ActionCable API to get updates when the world changes, and then use the REST API to take actions that change the world in response to those updates.

Replace example with your subdomain: For example, if the URL you use to access RC Together is https://recurse.rctogether.com/ then your API urls would be https://recurse.rctogether.com/api and wss://recurse.rctogether.com/cable.

Apps and bots

To use the RC Together API, you'll need an app. You can create an app on the apps page (https://example.rctogether.com/apps). Your app needs a name and can have an optional source URL for others to view your app’s source code.

You can use your app’s credentials to create bots. Bots show up in the user's browser the same way that avatars and different types of blocks show up. There is no limit on the number of bots your app can create. Bots are drawn with an emoji of your choice. If you don't specify an emoji when creating your bot, 🤖 (the robot emoji) will be used.

The only thing your app can do on its own is create, read and delete bots. You perform all other actions through bots. When you make a request to the API, you specify the bot that is going to perform the action. A bot can only perform actions on entities that are directly adjacent to its position. "Directly adjacent" means one square directly north, south, east or west of the bot's position. This does not include diagonally adjacent squares (e.g. northeast, southwest, etc.).

Safe mode

When you create an app, you choose whether or not to put it in safe mode. Safe mode is on by default.

When an app is in safe mode, it can only update and delete blocks that it creates. You can use this to ensure you don't accidentally delete blocks you didn't intend to while you're testing your app, or just leave it on if your app never needs to edit blocks it didn't create.

Authentication

For example, if your app id is 123 and your app secret is abc and you want to create a new bot, you can authenticate using HTTP Basic Auth like this:

curl --user 123:abc \
  -X POST https://example.rctogether.com/api/bots \
  -d bot[name]='TestBot'\
  -d bot[x]=1 \
  -d bot[y]=1

or using URL params like this:

curl -X POST \
  'https://example.rctogether.com/api/bots?app_id=123&app_secret=abc' \
  -d bot[name]='TestBot' \
  -d bot[x]=3 \
  -d bot[y]=3

Make sure to replace 123 with your app id and abc with your app secret.

To authenticate with the API, you use your app’s app id and app secret, which you can find on the apps page (https://example.rctogether.com/apps).

You can authenticate using HTTP Basic Auth, using the app id as the username and app secret as the password, or by passing them in the app_id and app_secret URL params.

Entities

An example message you might recieve from ActionCable for a Note:

{
  "type": "entity",
  "payload": {
    "id": 4492,
    "type": "Note",
    "pos": {
      "x": 13,
      "y": 37
    },
    "color": "gray",
    "note_text": "Hello world!",
    "updated_by": {
      "name": "James Porter",
      "id": 1
    },
    "note_updated_at": "2020-12-10T17:32:27Z"
  }
}

The "type": "entity" indicates that this message is about a single entity, and the payload contains the entity representation.

Most things in RC Together are entities. The entity types are:

Once your app is connected to the API's ActionCable endpoint and subscribed to ApiChannel, you will recieve a message containing a JSON representation of an entity whenever that entity changes.

The message does not indicate which fields have changed, and always includes all of the entity's fields. If your app needs to know which fields have changed, you should keep track of the current state of all entities locally and compare incoming messages with your local state. When you subscribe to ApiChannel, the first message you recieve is always a message containing the current state of every entity in the world, so you have a place to start from.

Shared entity properties

All entities have the following properties:

Inspecting RC Together

To make debugging easier, you can click on a square while holding down Windows and Alt on a PC, or Command and Option on a Mac to print a description of that square in your JavaScript console. This works on empty spaces and blocks.

Visibility

This example code is extracted from RC Together and can be used determine visiblity

const AVATAR_OFFLINE_TIMEOUT_SECONDS = 140

isVisible(entity) {
  if (entity.deleted) {
    return false
  } else if (entity.type === "Avatar") {
    const active = Date.now() - Date.parse(entity.last_present_at) < AVATAR_OFFLINE_TIMEOUT_SECONDS*1000
    const idle = Date.now() - Date.parse(entity.last_idle_at) < AVATAR_OFFLINE_TIMEOUT_SECONDS*1000

    return !!entity.zoom_user_display_name || active || idle
  } else if (entity.type === "UnknownAvatar"){
    return !!entity.zoom_user_display_name
  } else if (entity.type === "AudioRoom") {
    return !entity.expires_at || Date.now() < Date.parse(entity.expires_at)
  } else {
    return true
  }
}

Not all entities are visible on the screen. If your bot needs to interact with things in the world, you need to figure out whether those things are visible. Whether or not something is visible depends on its type:

If an entity gets removed from the world, it will have a deleted property set to true.

Using the ActionCable API

Action Cable is a PubSub + RPC framework for real time communication built on top of WebSockets. Action Cable has three primary concepts: connections, channels, and subscriptions. To use Action Cable, you make a single connection to the Action Cable endpoint. This connection is backed by a single WebSocket. You can then subscribe to one or more channels. Channels are named endpoints that you can use to send and receive messages. The RC Together API has one channel called "ApiChannel". All subscriptions are multiplexed over a single Action Cable connection, and thus a single WebSocket connection.

Client libraries

Here is an example of connecting to the Action Cable API with the actioncable-nodejs library.

const ActionCable = require('actioncable-nodejs/src/actioncable.js')

const APP_ID = "123"
const APP_SECRET = "abc"

const uri = `wss://example.rctogether.com/cable?app_id=${APP_ID}&app_secret=${APP_SECRET}`

let cable = new ActionCable(uri, {
  origin: 'https://example.rctogether.com',
})

let subscription = cable.subscribe('ApiChannel', {
  connected() {
    console.log("connected");
  },

  disconnected() {
    console.log("disconnected");
  },

  rejected() {
    console.log("rejected");
  },

  received(data) {
    console.log("received", data);
  },
})

You can either use an Action Cable client library or roll your own. We've included links to some client libraries below, as well as a description of Action Cable internals if you'd like to write one yourself. The state of Action Cable client libraries is decidedly mixed.

If you use a client library, you can skip down to the API Messages section to see what kind of messages your app will receive from the Action Cable API.

When you create your connection, you must set the Origin header to https://example.rctogether.com or Action Cable will reject your connection. You must also present your app id and your app secret, either in the Authorization header or in the query string using the keys app_id and app_secret.

Identifiers

An example identifier

"{\"channel\":\"ApiChannel\"}"

An identifier in Action Cable identifies a channel. Identifiers are strings containing a JSON encoded object of the format {"channel": "FooChannel"}. They are used by control, data, and command messages.

Action Cable Messages

An example command message (sent by the client)

{
  "command": "subscribe",
  "identifier": "{\"channel\":\"ApiChannel\"}"
}

An example control message (sent by the server)

{
  "identifier": "{\"channel\":\"ApiChannel\"}",
  "type":"confirm_subscription"
}

An example data message (sent by the server)

{
  "identifier": "{\"channel\":\"ApiChannel\"}",
  "message": {
    "type": "entity",
    "payload": {
      "id": 4492,
      "type": "Note",
      "pos": {
        "x": 13,
        "y": 37
      },
      "color": "gray",
      "note_text": "Hello world!",
      "updated_by": {
        "name": "James Porter",
        "id": 1
      },
      "note_updated_at": "2020-12-10T17:32:27Z"
    }
  }
}

All Action Cable WebSocket messages are JSON encoded. There is one type of Action Cable message that you will send to the server: a command message. Command messages are remote procedure calls that you send to the server. They always contain the command key. The only command that you will need to send to the Action Cable server is the subscribe command.

There are two types of Action Cable messages that you will receive from the server: control messages and data messages. Control messages can be identified by having a type key in the top level object. They perform signaling for connection and subscription maintenance. Data messages are messages from the server that do not have a type key. Data messages contain the actual data from the RC Together API.

Subscribing to the ApiChannel

The lifecycle of a connection, from initial HTTP request to data from the RC Together API. Rightward facing arrows indicate data sent by the client. Leftward facing arrows indicate data received by the client. Some HTTP headers have been left out for brevity.

The WebSocket connection is negotiated.

> GET wss://example.rctogether.com/cable HTTP/1.1
> Host: example.rctogether.com
> Conection: Upgrade
> Upgrade: websocket
> Origin: https://example.rctogether.com
> Authorization: Basic aGVsbG86d29ybGQ=

< HTTP/1.1 101 Switching Protocols
< Upgrade: websocket
< Connection: Upgrade

The server sends a welcome control message.

< {
<   "type": "welcome"
< }

We send a command message asking to subscribe to the ApiChannel.

> {
>   "command": "subscribe",
>   "identifier":"{\"channel\":\"ApiChannel\"}"
> }

The server confirms our subscription with a command message

< {
<   "identifier":
<   "{\"channel\":\"DeactivationsChannel\"}",
<   "type":"confirm_subscription"
< }

The server then sends us the state of the world and begins streaming entities as they are updated.

< {
<   "identifier": "{\"channel\":\"GridWorldChannel\"}",
<   "message": {
<     "type": "world",
<     "payload": {
<       "entities": [],
<       "rows": 50,
<       "cols", 80,
<     }
<   }
< }

< {
<   "identifier": "{\"channel\":\"ApiChannel\"}",
<   "message": {
<     "type": "entity",
<     "payload": {
<       "id": 4492,
<       "type": "Note",
<       "pos": {
<         "x": 13,
<         "y": 37
<       },
<       "color": "gray",
<       "note_text": "Hello world!",
<       "updated_by": {
<         "name": "James Porter",
<         "id": 1
<       },
<       "note_updated_at": "2020-12-10T17:32:27Z"
<     }
<   }
< }

Finally, the server begins sending us ping control messages to help us monitor whether the underlying WebSocket connection is alive or dead. These ping messages can come before we are fully subscribed to ApiChannel.

< {
<   "type": "ping",
<   "message": 1607629291
< }

To start, create a WebSocket connection to wss://example.rctogether.com/cable. When you create your connection, you must set the Origin header to https://example.rctogether.com or Action Cable will reject your connection. You must also present your app id and your app secret, either in the Authorization header or in the query string using the keys app_id and app_secret.

When you successfully connect and authenticate, the server will send you a welcome control message. After you have received your welcome message, you can send a subscribe command message to join the ApiChannel. The server will then send you a confirm_subscription command message, and begin to send you data messages.

Connection monitoring

A ping control message.

{
  "type": "ping",
  "message": 1607633186
}

WebSockets don't provide a good way to figure out if your connection is alive or dead. Action Cable sends you ping control messages for this purpose.

Ping messages are sent every three seconds. The message field contains a Unix timestamp – the number of seconds since 00:00:00 UTC on January 1st, 1970.

Rails's Action Cable client considers a connection dead and tries to make a new connection if it misses two consecutive ping messages.

API Messages

An example world message (entities are elided for consission).

{
  "type": "world",
  "payload": {
    "entities": [...]
    "rows": 50,
    "cols", 80,
  }
}

An example entity message.

{
  "type": "entity",
  "payload": {
    "id": 4492,
    "type": "Note",
    "pos": {
      "x": 13,
      "y": 37
    },
    "color": "gray",
    "note_text": "Hello world!",
    "updated_by": {
      "name": "James Porter",
      "id": 1
    },
    "note_updated_at": "2020-12-10T17:32:27Z"
  }
}

API messages are the actual data that your app will care about. They are contained within the message field of Action Cable data messages. API messages have two fields: type and payload. Type can either be world or entity.

Immediately upon connecting, you will receive one world message whose payload contains the entire state of the world: the size of the world in rows and cols and all of the entities in the world. After that, you will receive entity messages for each entity that changes, with the entity stored in the payload.

The entities key in the world message contains an array of entities. In the RC Together client in the browser, we make two indexes of this data: one by position, and another by ID, to make finding entities easier. You may want to do the same.

You will only get a world message once. The easiest way to get a second world message is to close your Action Cable connection and connect again.

Using the REST API

The REST API examples that follow assume your app id is stored in the environment variable $APP_ID and your app secret is stored in the environment variable $APP_SECRET.

If you're modifying or deleting something, the examples assume that its id is stored in a environment variable. For example, if you're updating a wall, we assume its id is stored in $WALL_ID.

The REST API uses the standard HTTP POST, PATCH and DELETE methods for creating, updating, and deleting resources respectively. For PATCH and DELETE requests, you specify what you'd like to update or delete by including its id in the URL path of your request. For example, if you wanted to update the wall with id 456, you would make a PATCH request to https://example.rctogether.com/api/walls/456. When describing routes in the REST API documentation below, we used :id as a placeholder for the id of whatever you want to update or delete.

The REST API only supports working with the Bot, Wall, Note, Link, and Desk entity types. Other types of entities cannot be created, updated, or deleted by the API. The API also has an endpoint for sending messages.

Parameters

An example of a request using form encoding (curl form-encodes parameters passed with -d):

curl --user $APP_ID:$APP_SECRET \
  -X POST https://example.rctogether.com/api/bots \
  -d bot[name]='TestBot'\
  -d bot[x]=1 \
  -d bot[y]=1

The same request using JSON encoding:

curl --user $APP_ID:$APP_SECRET \
  -X POST https://example.rctogether.com/api/bots \
  -H 'Content-Type: application/json' \
  --data '{"bot": {"name": "TestBot", "x": 1, "y": 1}}'

You pass paramters to the REST API endpoints in the request body, encoded either as form data or as JSON. When passing paramters, you nest them under the resource they describe. For example, when using form encoding to specify a bot's name, you use -d bot[name]=TestBot rather than just -d name=TestBot. Or when using JSON encoding, you use {"bot": {"name": "TestBot"}}, rather than {"name": "TestBot"}.

Responses

On success, all API endpoints respond with the status code 200, and a JSON representation of the modified entity in the body.

On failure, all endpoints respond with the appropriate HTTP status code (e.g. 401 if authentication failed, 422 if you failed to pass a required paramter), and a JSON representation of the error in the body.

Specifying a bot

For example, to make a wall green using the bot with id 4321:

curl --user $APP_ID:$APP_SECRET \
  -X PATCH https://example.rctogether.com/api/walls/$WALL_ID \
  -d bot_id=4321 \
  -d wall[color]='green'

The bot must be adjacent to the wall in order to this request to succeed.

All REST endpoints besides /api/bots require you to specify a bot that will perform the requested action. You do this by using the bot_id paramter.

Bots

Bots are how your app represents itself in the world and manipulates other entities. To do anything to the world (e.g. create or update blocks), you first need to create a bot. Your app can have any number of bots.

Bots are always visible in the world, so if you want a bot to disappear, you have to delete it.

If you move a bot more than one square away from it's current position, it will animate through the world in the same way that avatars do when moved by double-clicking.

Bots cannot share a space with blocks, but can share a space with other bots and avatars.

Bot fields

An example of a JSON object representing a bot:

{
  "id": 4455,
  "type": "Bot",
  "pos": {
    "x": 9,
    "y": 37
  },
  "emoji": "🐶",
  "direction": "right",
  "can_be_mentioned": true,
  "app": {
    "name": "DogApp",
    "id": 1
  },
  "name": "DogBot",
  "display_name": "DogBot (bot)",
  "message": {
    "text": "woof!",
    "sent_at": "2020-12-09T22:48:33Z",
    "mentioned_agent_ids": []
  }
}

Create a bot

An example request for creating a bot:

curl --user $APP_ID:$APP_SECRET \
  -X POST https://example.rctogether.com/api/bots \
  -d bot[name]='SmileBot'\
  -d bot[x]=1 \
  -d bot[y]=1 \
  -d bot[emoji]="🙂" \
  -d bot[direction]=up \
  -d bot[can_be_mentioned]=true

HTTP request

POST https://example.rctogether.com/api/bots

Parameters

Update a bot

An example request to move a bot to position 3,5 and make it face down:

curl --user $APP_ID:$APP_SECRET \
  -X PATCH https://example.rctogether.com/api/bots/$BOT_ID \
  -d bot[x]=3 \
  -d bot[y]=5 \
  -d bot[direction]=down

An example request to change a bot's name to CatBot and its emoji to 🐱:

curl --user $APP_ID:$APP_SECRET \
  -X PATCH https://example.rctogether.com/api/bots/$BOT_ID \
  -d bot[name]=CatBot \
  -d bot[emoji]='🐱'

HTTP reuqest

PATCH https://example.rctogether.com/api/bots/:id

Parameters

All paramters are optional

Delete a bot

curl --user $APP_ID:$APP_SECRET \
  -X DELETE https://example.rctogether.com/api/bots/$BOT_ID

HTTP reuqest

DELETE https://example.rctogether.com/api/bots/:id

Parameters

This method does not take any parameters

Walls

Walls are the most basic kind of block. Most of the world is usually made of walls.

Wall fields

An example of a JSON object representing a wall:

{
  "id": 3040,
  "type": "Wall",
  "pos": {
    "x": 11,
    "y": 43
  },
  "color": "purple",
  "wall_text": "M"
}

Create a wall

An example request for creating a wall:

curl --user $APP_ID:$APP_SECRET \
  -X POST https://example.rctogether.com/api/walls \
  -d bot_id=$BOT_ID \
  -d wall[x]=2 \
  -d wall[y]=1 \
  -d wall[color]="purple" \
  -d wall[wall_text]='a'

HTTP request

POST https://example.rctogether.com/api/walls

Parameters

Update a wall

An example request for updating a wall to be green:

curl --user $APP_ID:$APP_SECRET \
  -X PATCH https://example.rctogether.com/api/walls/$WALL_ID \
  -d bot_id=$BOT_ID \
  -d wall[color]="green" \

An example request for updating a wall to display the letter 'b':

curl --user $APP_ID:$APP_SECRET \
  -X PATCH https://example.rctogether.com/api/walls/$WALL_ID \
  -d bot_id=$BOT_ID \
  -d wall[wall_text]='b'

HTTP request

PATCH https://example.rctogether.com/api/walls/:id

Parameters

Delete a wall

An example request to delete a wall:

curl --user $APP_ID:$APP_SECRET \
  -X DELETE https://example.rctogether.com/api/walls/$WALL_ID \
  -d bot_id=$BOT_ID \

HTTP request

DELETE https://example.rctogether.com/api/walls/:id

Parameters

This method does not take any parameters

Notes

Notes are blocks with text content that gets rendered as Markdown when you click on them. They're depicted as sticky notes in the world, and can be used to label areas, provide instructions, etc.

Note fields

An example of a JSON object representing a note:

{
  "id": 4492,
  "type": "Note",
  "pos": {
    "x": 13,
    "y": 37
  },
  "color": "gray",
  "note_text": "Hello world!",
  "updated_by": {
    "name": "James Porter",
    "id": 1
  },
  "note_updated_at": "2020-12-10T17:32:27Z"
}

Create a note

An example request for creating a note:

curl --user $APP_ID:$APP_SECRET \
  -X POST https://example.rctogether.com/api/notes \
  -d bot_id=$BOT_ID \
  -d note[x]=2 \
  -d note[y]=1 \
  -d note[note_text]='Hello, world!'

HTTP request

POST https://example.rctogether.com/api/notes

Parameters

Update a note

An example request to update a note:

curl --user $APP_ID:$APP_SECRET \
  -X PATCH https://example.rctogether.com/api/notes/$NOTE_ID \
  -d bot_id=$BOT_ID \
  -d note[note_text]='Something else'

HTTP request

PATCH https://example.rctogether.com/api/notes/:id

Parameters

Delete a note

An example request to delete a note:

curl --user $APP_ID:$APP_SECRET \
  -X DELETE https://example.rctogether.com/api/notes/$NOTE_ID \
  -d bot_id=$BOT_ID

HTTP request

DELETE https://example.rctogether.com/api/notes/:id

Parameters

This method does not take any parameters

Links

Links are blocks that display URLs.

Link fields

An example of a JSON object representing a link:

{
  "id": 2217,
  "type": "Link",
  "pos": {
    "x": 40,
    "y": 33
  },
  "color": "gray",
  "url": "https://livebook.manning.com/book/grokking-algorithms/about-this-book/"
}

Create a link

An example request for creating a link:

curl --user $APP_ID:$APP_SECRET \
  -X POST https://example.rctogether.com/api/links \
  -d bot_id=$BOT_ID \
  -d link[x]=2 \
  -d link[y]=1 \
  -d link[url]='https://www.example.com'

HTTP request

POST https://example.rctogether.com/api/links

Parameters

Update a link

An example request to update a link:

curl --user $APP_ID:$APP_SECRET \
  -X PATCH https://example.rctogether.com/api/links/$LINK_ID \
  -d bot_id=$BOT_ID \
  -d link[url]='https://www.recurse.com'

HTTP request

PATCH https://example.rctogether.com/api/links/:id

Parameters

Delete a link

An example request to delete a link:

curl --user $APP_ID:$APP_SECRET \
  -X DELETE https://example.rctogether.com/api/links/$LINK_ID \
  -d bot_id=$BOT_ID

HTTP request

DELETE https://example.rctogether.com/api/links/:id

Parameters

This method does not take any parameters

Desks

Desks are blocks that represent your "home" in RC Together. Desks are owned by one person, and can be used to update their owner's status. A status consists of some text, an emoji, and an expiry time.

Desk fields

An example of a JSON object representing a desk:

{
  "id": 4328,
  "type": "Desk",
  "pos": {
    "x": 22,
    "y": 3
  },
  "color": "orange",
  "emoji": "🥪",
  "status": "Eating lunch",
  "expires_at": "2020-12-10T23:13:28.563Z",
  "profile_url": null,
  "owner": {
    "id": 1,
    "name": "James Porter",
    "image_url": "https://d29xw0ra2h4o4u.cloudfront.net/assets/people/james_j_porter_150-e1c536c6a92cc966a8667a9bee8de0bd2d4cf8ad76674a856596c6660d251628.jpg"
  }
}

Create a desk

An example request for creating a desk:

curl --user $APP_ID:$APP_SECRET \
  -X POST https://example.rctogether.com/api/desks \
  -d bot_id=$BOT_ID \
  -d desk[x]=2 \
  -d desk[y]=1 \
  -d desk[owner_id]=1 \
  -d desk[status]='Writing' \
  -d desk[emoji]='✏️' \
  -d desk[expires_at]='2020-12-11T19:03:25Z'

HTTP request

POST https://example.rctogether.com/api/desks

Parameters

Update a desk

An example request for updating a desk:

curl --user $APP_ID:$APP_SECRET \
  -X PATCH https://example.rctogether.com/api/desks/$DESK_ID \
  -d bot_id=$BOT_ID \
  -d desk[status]='Tired...' \
  -d desk[emoji]='😴' \
  -d desk[expires_at]='2020-12-11T19:03:25Z'

HTTP request

PATCH https://example.rctogether.com/api/desks/:id

Parameters

Delete a desk

An example request for deleting a desk:

curl --user $APP_ID:$APP_SECRET \
  -X DELETE https://example.rctogether.com/api/desks/$DESK_ID \
  -d bot_id=$BOT_ID \

HTTP request

DELETE https://example.rctogether.com/api/desks/:id

Parameters

This method does not take any parameters

Cleanup a desk

Cleaning up a desk sets its status, emoji, and owner to null.

An example request for cleaning up a desk:

curl --user $APP_ID:$APP_SECRET \
  -X PATCH https://example.rctogether.com/api/desks/$DESK_ID/cleanup \
  -d bot_id=$BOT_ID \

HTTP request

PATCH https://example.rctogether.com/api/desks/:id/cleanup

Parameters

Parameters

List desks

An example request for listing all desks:

curl --user $APP_ID:$APP_SECRET \
  -X GET https://example.rctogether.com/api/desks

HTTP request

GET https://example.rctogether.com/api/desks

Parameters

This method does not take any parameters

Messages

Just as you can send messages in the chat panel when using RC Together, your bots can send messages using the API.

Message fields

An example of a JSON object representing a message:

{
  "id": 29,
  "text": "@**James Porter** hi",
  "mentioned_agent_ids": [
    5
  ],
  "created_at": "2021-02-15T21:16:37Z",
  "sender": {
    "id": 1,
    "name": "David Albert"
  }
}

Create a message

An example request for creating a message:

curl --user $APP_ID:$APP_SECRET \
  -X POST https://example.rctogether.com/api/messages \
  -d bot_id=$BOT_ID \
  -d message[text]='hello'

HTTP request

POST https://example.rctogether.com/api/messages

Parameters

Changelog

• 2/18/21 - Added a Messages endpoint that should be used for sending messages instead of updating the message property on bots. The message property on bots is now read-only.
• 2/5/21 - The visible property of all entities has been removed. You should now compute visibility of entities as described in Visibility.