Foreword

EntityComposer was created with an Entity Component System (aka ECS) in mind, but it can also be used for classical inheritance-based architectures.

What is an ECS?

ECS is a software architectural pattern that is commonly found in video game development. It follows the principle of “composition over inheritance”, so an entity is not defined by its type/class, but by a set of data (components).

The Editor

When you start EntityComposer for the first time you will start with an empty project, so the first thing to do is to save this project somewhere on your filesystem. All file references will be relative to your save location, so for example if you have an entity referencing a sprite, the path will be relative from the project location to the asset.

The editor is composed of five different areas:

  • Top: Toolbar
    • Save/Load
    • Data import/export
    • Theme switching
  • Left: Entity Hierarchy
    • This area shows the hierarchy of your entities
    • Each entity can have any number of child entities
  • Center: Main Editing Area
    • This area contains the actual editor
    • Depending on the selected item (Entity/Enum/Custom Type/Compoennt) a different editor is shown
  • Right: Data Types and Components
    • All enums/types/components you have created are shown here
  • Bottom: Collapsible Logs
    • This area will show all logging messages
    • It can be collapsed to save screen-space

Editor Overview

Composition

Since entities are just simple container for components, they don’t do anything on their own. In order to give them meaning, you need to add components to them.

Creating Custom Types and Components

Clicking the plus icon on the Custom Types/Components tab will create and empty instance and already open it for editing.

Type Editor

First of all you should give your new type/compoenent a meaningful name, then you can add fields to it, by simply clicking the New button at the bottom of the editing area. All fields are listed in the center table and have at least three properties:

  • Name: Just the name of the field
  • Type: The data type of the field, can be a primitive type (int, float, etc.) or even user defined custom types (Vector3D, etc.)
  • Layout: Only relevant for the editor. Describes where this field should be placed. (see below)

Some types also have an additional settings button. For example the Int types lets you provide min/max values.

Reordering and Deleting Fields

Fields can be easily reordered by simple using drag&drop. Of course you can also delete a field by selecting it and clicking the Delete button at the bottom.

Layout

The layout property is a simple enumeration (Center, Top, Bottom, Leftand Right), which defines where in the editor this field should be placed.

So when you’re editing an entity, the fields of the component are placed according to their layout property:

Layout

Fields in the Top and Bottom area are placed horizontally, while the fields in Left, Center and Right areas are placed vertically. This is pretty useful to create compact types and components, for example when creating a Vector3D type you want to have the x, y and z fields in a single line. You can do this by setting the layout of the fields to Top:

Position Layout

Difference between Custom Types and Components

Custom Types and Components are basically the same. They only have two important differences:

  • Only Components can be added directly to an Entity
  • Only Custom Types can be added as fields to other Custom Types/Components

When to use a Custom Type vs Component?

Custom Types should be used for basic types, that will be used inside of other types and components. A classic example are simple structs/classes like a Vector2D or Vector3D.

Components on the other hand can directly be added to an entity and might be more complex. In most Game Engines these Components are special classes that must implement some specific interface.

Creating Enums

Clicking the plus icon on the Enums tab will create and empty instance and already open it for editing. By default a new enum is baked by an integer, but you can also use floats and strings as the actual enum value.