Improbable Icon

Feedback on the Pirate Tutorial [SpatialOS 11.0.0]



Great tutorial! Found only minor issues, really. Good work!

Lesson 2

“Take a look at the lines that begin playerEntityTemplate.Add.”

Should be: .AddComponent

CreatePirateEntityTemplate method: This method should be named CreatePirateShipTemplate for consistency. Also name method generating the shops for the snapshot as PopulateSnapshotWithPirateShips and so on for consistency.

No explanation on this commonly used expression: CommonRequirementSets.SpecificClientOnly(clientWorkerId)

In step 3 of writing the CreatePirateEntityTemplate method the order of explanation is confusing: .AddComponent is not available on the object returned by .SetPersistence(true). One must add .SetReadAcl(CommonRequirementSets.PhysicsOrVisual) first. Only then .AddComponent is available. This is because of the interface returned by those methods.

In the Populate* methods of the SnapshotMenu class using ref for the snapshotEntities dictionary is unnecessary.

Lesson 3

PlayerInputController is defined under Pirates/Behaviours, which is kind of counter-intuitive. I tried to find it in Player based on the explanation.

Same for ShipMovement.cs. It should be defined at a common place for reuse by both the player and pirate ships.

Brances are not needed due to operator precedence (multiplication is stronger than substraction):


Also, more readable to arrange the code like this:

	new ShipControls.Update()
	.SetTargetSteering(Random.value * 30.0f - 15.0f)

I know, this is not “standard” style, but more readable (at least for me).

“You should use InvokeRepeating in OnEnable(), and cancel it in OnDisable(), in order to prevent unexpected behaviour:”

What unexpected behavior? What happens if we forget to cancel it? A short explanation would help us identifying the issue if it happens due to mistakenly missing those calls out from our code.

2.1: In Unity both the SpatialOS window and its Settings have the same title: SpatialOS. Try to dock them inside a pane next to each other. You get two tabs with the same title, which works, but confusing.

“In the Spatial CLI location field, enter the location of spatial.exe (Windows) / spatial (MacOS) is installed on your machine.”

spatial.exe is on PATH, it says it is “Found” from there. Tutorial does not say that it should be the case (normally).

2.2/2 “Click Add component, and add the new SteerRandomly script to the prefab.” - Now we have this class defined a second time, since it will create a new C# source file. It has already been written in section 1.2. Confused. Should I copy the code here as well?

2.2/3 “Build entity prefabs: In the SpatialOS window (open it using the menu Window > SpatialOS), under Entity prefabs, click Build all.” - It is in the window accessible by clicking on “Settings” in the SpatialOS window. Confused by having the same window title??

Cheat sheet to rebuild this and that: Is it possible (in theory) to automate at least the most common ones of these decisions based on file modification date or diff of some data structures? So they would be built automatically right before starting SpatialOS locally.

Lesson 4

2./2: “Look at this file. At the moment, it contains two properties: targetSteering and targetSpeed.”

Naming is not correct. Quoting from the schema file:

// The speed at which the ship wants to move at
float target_speed = 1;

// The direction the ship wants to be steering in
float target_steering = 2;

2./4: “You’ve changed the schema. Whenever you change schema, you need to run spatial worker codegen.”

It would be nice to clarify which button is that on the SpatialOS window in Unity. (Easy to figure, tough.)

Lesson 5

4./3: “It’s done when: you see the message printed out in Unity:”

Bad advice. This log message does not appear in Unity, since the collision detection is done only on server side. It shows up on the Console window of the UnityWorker:

WARN [improbable.bridge.logging.EngineLogMessageHandler] [Worker: UnityWorker0] Collision 
detected with 44
      in  -[WorkerLogger:Unity]
   > time=2017-07-27T03:46:44+02:00

I wasted some 5 minutes trying to find it in Unity before I figured where to look…

Lesson 7

3/1: InitializeSinkingAnimation method does not exists on the class when the call to it is entered. Adding this function should come first, then its usage in OnEnable.

It would be easier to spot the sinking ships if the cannons would shoot 45 degrees forward.


  • There is a console window opened on pressing “Generate from schema” Build button. It is running the “spatial worker codegen” command. This console window should close automatically on successful (all green) build instead of waiting on a keypress.


Thanks @Viktor! These suggestions are really useful. After running through Pirates so many times it’s easy for me to miss things like these. We’ll definitely tidy these up.

I’m glad you enjoyed the tutorial. If you have any thoughts about how well it taught you the basics, and what other resources you’d like to see to help you further, please do let us know!


You’re welcome. Exciting new technology.


  1. The default snapshot has to be regenerated before testing

The above tutorial page forgets to mention that the default snapshot has to be re-generated before running SpatialOS locally for testing the changes.

I forgot to do it and the AwardPoints command could not be handled due to the missing Score component in the snapshot. What you get is an error message in the local SpatialOS server log. Something like “command 1007 was not handled until timeout”.

Also, the canvas with the score is not displayed due to the score staying at zero, thus updateGUI keeps the canvas disabled.

  1. Entities disappeared from client after a few minutes

While writing my reply I left the client running inside Unity. Just noticed that all gameobjects corresponding to the SpatialOS entities magically disappeared from the client running inside Unity.

Only the blue water and the canvas showing the score (1) remained visible. The Hierarchy pane in Unity contains only the game objects shown while the client is stopped, but the client is still running. No error messages in the client nor inside the SpatialOS console window.


I’ve just deployed the finished tutorial to the cloud for testing:

Deployment: beta_burger_eighteen_480 / pirates_tutorial

  • The deployment went smoothly with no errors, documentation was good.
  • On starting the deployment there is a dialog box to agree with the terms and conditions. It mentions deployment setting “max_players_capacity” which I could not find in the project. Based on documentation it is outdated. There is topology instead, three choices: small, medium and large. Could not find information on their limits.
  • Found a problem: Cannon hits did not have any effect on ship health. So the whole health and score stuff did not work.
  • Verified in the Inspector that the required components exists on the entities: The player ships had Health and Score. The pirate ships had Health.

How can we see logs of the events and commands of the physics worker and the client to debug it further? I tried to find it on the cloud console, but could not find log messages on them.


Hi @Viktor, regarding your first point, the Score component is only added to Player entities which are not persisted. There’s nothing that would require changes to the snapshot - it contains only the player creator, pirate ships and islands and fish which don’t have any new components. I suspect you might have mistakenly added the Score component to pirate ships which would explain the error. If this is not the case, it would be great if you could provide steps to reproduce this or a link to a repository for further investigation.


This issue is still here in 2018,
Tutorial is great, but this point is important for a beginner, as i waste more than five minute to understand the log was in SERVER console.