Improbable Icon

Example for javascript/c++/java stand alone SDK's?


Hi there,

I am having a tinker with spatialos using the Javascript SDK. I have successfully got to the stage where I am built, connected and have a worker adding entities to the simulation.

My issue is that I simply can’t find any documentation/code examples of the next step. All the resources refer to the Unity SDK or when they don’t, they don’t show the next step of development! I am assuming that the unity SDK handles a lot of the client side of things, but how do I do this with your native SDK’s?

So, how do I go about having my worker subscribe to the existing simulation? When I connect my second client worker, I don’t seem to recieve any info on the pre existing entities. I can’t find docs on how to receive information about the simulation? E.g. am I meant to manually query the simulation? Is this delivered to me as part of the connection process? etc? etc?

Do entities that the worker have authority over, receive information about other entities near by? The docs talk about the workers “view”; the inspector shows a worker position in the simulation; but how do I modify said workers position? How do I recieve a lsit of entities near the workers view? Am I supposed to designate a particular entity for the worker? Or something else?

Your help is appreciated.



Hello @skn3

Great to hear that you are making progress. I am happy to help you out and provide some pointers about the questions you are having for the next steps of your development.

A good starter, even if you have probably already read it, is to go (again) over:

By there I mean that even if you have already gotten the initial grasp on the concepts, a second (or further) read might give you a better feeling for some of the underlying subtleties that you will always miss when encountering SpatialOS for the first time. :slightly_smiling_face:

That said, let’s move on some of the more detailed points you raise:

The Unity SDK is not capable of anything more than the other more “low-level” language SDKs such as C++, C# or Java. The only difference is that the Unity and Unreal SDKs abstract some of the boiler-plate logic away via higher-level APIs and functionalities. That said the JavaScript SDK is somewhat of a special case as it does not have full feature-parity yet with the other language ones, so expect to not have all features at-the-ready yet going forward.

Depending off course on what you are trying to do and make the next steps can be:

  • Creating managed workers (i.e the ones running in the cloud) to take care of all you simulation / game-logic as well as anything that you do not want your external workers (i.e game clients connecting from outside) to be authoritative over. Examples would be the position of entities (to not allow external clients to override laws of physics and other rules of your simulation, etc.). Important point: the JavaScript SDK can not yet be used to make managed workers and is only capable of being used for external workers. You will need to use either the Unity or Unreal integrations or go with the C#, C++ or Java SDKs.
  • Extending the variety of entities that you have in your world, adding new components to enable different behaviours, etc.

The second worker that you connect does not receive any information about pre-existing entities if it is not itself authoritative over at least one component of one entity.

This is strongly tied to your last question: you cannot modify the position of a worker in the simulation, it is rather automatically calculated and updated by the SpatialOS runtime and a worker’s position is sort-of the barycentre of the position of the components (or rather the component’s entities) that it is authoritative over. Hence if a worker is not authoritative over anything it does not have a position and as such will not receive updates about the current state of nearby entities as what “nearby” is, is yet undefined.

Once your worker is authoritative over at least one component and thus has a position then it will start receiving updates about components of other entities nearby according to the bridge configuration of its worker type and any potential ACL settings. A long in-depth post about this was recently posted on the forums. It contains a lot of details that are of importance when scaling-up but it is never too early to read it nonetheless.

Feel free to ask any further questions that may arise. The community and Improbable will be happy to help you out!

Best regards,


Hi @skn3, in addition to what @dvanamst said, here’s a little example I made using the JS API.

All of the code used in this example is present in some form on the JavaScript worker API docs. Feel free to clone it and you should be able to run it using spatial worker build WebClient && spatial local launch. Every time an entity is added to a client’s view of the world the number of entities it sees is logged in the console. In addition, every time a client connects a new entity is created.

You can see me refreshing the worker page several times here:

The important parts (which map directly to the concepts which @dvanamst explained) are:

  1. Making sure your worker is authoritative over something:
// index.js
let clientAttributeSet = createWorkerAttributeSet(["client"]);

let entityAcl = new EntityAclData();
entityAcl.readAcl = new WorkerRequirementSet();
entityAcl.readAcl.attributeSet = [clientAttributeSet];

entityAcl.componentWriteAcl = new Map();

// This is the line which makes this entity require a client worker for its Position component.
entityAcl.componentWriteAcl.set(Position.COMPONENT_ID, entityAcl.readAcl);

entity.add(EntityAcl.COMPONENT, entityAcl);
  1. Creating entities (the worker needs to have permission):
// default_launch.json
      "worker_type": "WebClient",
      "permissions": [{
          "entity_creation": {
          "allow": true
        "entity_deletion": {
          "allow": false
        "entity_query": {
          "allow": true,
          "components": [
  1. Doing something when a new entity is added to the view of your worker:
// index.js
dispatcher.onAddEntity(op => {
  entityCount += 1;

I’ll be glad to assist if you need more help :slight_smile:


Thanks, for the example, I was just about to start looking at javascript workers.

Question, are javascript workers going to be available to run as managed workers eventually?




Trying to build the example, but I’m getting a build error at the npm install stage.

Codegen (0.1s)
[1/3] < Build Codegen (0.1s)
[2/3] > Build NPM Install
npm ERR! path C:\SpaJavaScript\workers\js\node_modules\fsevents\node_modules\abbrev\package.json
npm ERR! code EPERM
npm ERR! errno -4048
npm ERR! syscall unlink
npm ERR! Error: EPERM: operation not permitted, unlink 'C:\SpaJavaScript\workers\js\node_modules\fsevents\node_modules\abbrev\package.json’
npm ERR! at Error (native)
npm ERR! { Error: EPERM: operation not permitted, unlink 'C:\SpaJavaScript\workers\js\node_modules\fsevents\node_modules\abbrev\package.json’
npm ERR! at Error (native)
npm ERR! stack: ‘Error: EPERM: operation not permitted, unlink ‘C:\SpaJavaScript\workers\js\node_modules\fsevents\node_modules\abbrev\package.json’\n at Error (native)’,
npm ERR! errno: -4048,
npm ERR! code: ‘EPERM’,
npm ERR! syscall: ‘unlink’,
npm ERR! path: ‘C:\SpaJavaScript\workers\js\node_modules\fsevents\node_modules\abbrev\package.json’ }
npm ERR!
npm ERR! Please try running this command again as root/Administrator.
.: SpatialOS -
npm ERR! A complete log of this run can be found in:
npm ERR! C:\Users\Phil Harvey\AppData\Roaming\npm-cache_logs\2017-09-14T19_14_43_164Z-debug.log
[2/3] x Build NPM Install (1m:34s)

Build (1m:34s)

Error: exit status 4294963248

This is on windows 10.



Did you see the “Please try running this command again as root/Administrator.” message in the error log? Does it still fail if you execute the command with the required permissions?

I would say it’s highly unlikely that JS managed workers would be available anytime soon, but who knows… Do you have a use case for managed JS workers? The only thing you gain by having a managed worker is load-balancing and you normally want that to deal with the heavy load you put on C++ / C# workers. JS workers in their current form can be used for a variety of purposes beyond player clients.