Get SpatialOS


You are viewing the docs for 11.0, an old version of SpatialOS. 12.1 is the newest →

Designing entities

This page is about the things you need to consider when designing entities.

Thinking about entity design

You need to work out what things you want to populate your world with, and decide which to model as entities, and which as components on another entity. There aren’t any hard and fast rules for which things should be which, but here are some principles.

Something should be an entity if:

  • it can exist on its own
  • it will be around for a while
  • it will interact with other things in the world

Something should probably not be an entity if:

  • it is purely a rendering object that does not affect the world, like particle effects and small pieces of rubble
  • it is always part of another object, like ammo in gun


For example, let’s consider a hat in the context of an online game, where players can collect different hats and chose one to wear on their character. Should the hats be entities?

It depends on how hats work in the game. If hats are purely a cosmetic enhancement, then it might be best to simply have the type of hat you are wearing as an enum stored as a component. However, if a hat can be shot off a player’s head, kicked around or piled into hat-towers, then it should be an entity in its own right.

For what you need to consider when designing components, see Designing components.

For information on how you actually create an entity, see the docs on creating entities in your SDK:

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums