= Simulation System Architecture =

''Part of the [wiki:TDD_Simulation simulation documentation]. (See pages linked from there, for details on the implementation of the concepts described here.)''

== Concepts ==

The '''entity system''' is the infrastructure that runs the game's simulation/gameplay code. (The gameplay itself is not part of this system - the system is not even specific to RTS games - but it is all built on top of this system, and influences the system's design.)

The design is based most closely on the one presented in GPG5 (''Bjarne Rene: Component Based Object Management; Game Programming Gems 5, 2005, page 25''). Some other useful references: [http://cowboyprogramming.com/2007/01/05/evolve-your-heirachy/ Evolve Your Hierarchy], [http://www.gamearchitect.net/Articles/GameObjects1.html Game Object Structure: Inheritance vs. Aggregation], Scott Bilas's [http://scottbilas.com/games/dungeon-siege GDC 2002 presentation: A Data-Driven Game Object System], and a few of the things linked from those.

An important concept in the entity system is the '''entity'''. This represents any kind of 'thing' in the simulation world - a person, a tree, a rock, an arrow, and more abstract things like event triggers, players, and player input controllers.

Entities consist of a set of '''components'''. A component is a largely self-contained piece of data and code, responsible for one part of the behaviour of an entity. One component might be responsible for rendering the entity; another for keeping track of its location in the world; another for tracking its health and reducing it when damaged and killing the entity when it reaches zero.

Each component is an object instance in the C++ code. However, there is no C++ object representing an entity - each component is tied to an '''entity ID''' (an arbitrary integer), and an entity exists only as a concept defined by the set of components with the same entity ID.

Components have two communication mechanisms: ''one-to-one'' communication with another component, by retrieving the component with a `QueryInterface` call (described in more detail later) and then calling methods on it; and ''one-to-many'' communication by posting or broadcasting '''messages''', which will be received by any component that has chosen to subscribe to that message type.

The goal of the system is to ease development of moderately complex gameplay code, and to easily adapt to changing gameplay requirements. There is a focus on modularity and flexibility - it should be easy to read, understand, modify and replace a component. Therefore a component should be small, with few dependencies on other components. (These are often conflicting requirements - lots of small components require more dependencies than a few large components. Thoughtful design is needed.)

== Scripting ==

To simplify development, improve iteration times, and avoid crashes, most gameplay code should be written in !JavaScript. Each component can be written either completely in C++, or completely in JS. Native<->scripted component communication is exactly the same as native<->native and scripted<->scripted, except that a native component might expose only a subset of its methods to scripts.

Components should be written in C++ only when necessary for run-time performance, memory usage, or to interact with C++ parts of the game engine (e.g. the renderer). Run-time performance should only be a concern for code that is executed every frame (e.g. position interpolation functions), or executed every simulation turn for a large number of entities (e.g. checking for any unit coming into range). Components should be initially written in JS, and if profiling indicates they are slow, then try to optimise the JS or call it less often (e.g. run on a timer rather than on every simulation turn), and if it's still unfixably slow then it could be rewritten in C++.

Component scripts support ''hotloading'': while the game is running, you can edit and save a script file, and it will be immediately reloaded and used in the game with no need to stop or restart. (The data associated with each component will not be changed at all, only the code.)

== Interfaces ==

Most entities will behave similarly to each other, but there are a few cases where we would like to have differing implementations of one type of component.

For example, most entities should have some kind of `Position` component, which responds to `MoveTo` calls during a simulation update and can be queried by the renderer for the location in the current frame. (Frames are much more frequent than simulation updates). For entities that move smoothly, the component should typically respond to the renderer by interpolating from its position in the previous simulation turn to the current turn, and therefore it needs to remember its previous position at the start of each turn. For entities that are not expected to move in straight lines (e.g. ballistic units like arrows), linear interpolation will be inaccurate. For entities that are not expected to move at all (e.g. trees), remembering the previous position every turn is wastefully inefficient.

It would be possible for a position component implementation to have a flag that switches between linear and parabolic interpolation, but the code would become increasingly complex as more special cases were added, and it would not be able to optimise the storage and computation of positions for non-moving entities (of which there might be tens of thousands).

Instead, we define `Position` as an '''interface'''. An interface does not define any code or data, but does define a list of methods (e.g. `MoveTo` and `GetInterpolatedPosition`). We then define a number of '''component types''' that implement the interface, providing the code and data - e.g. the `PositionInterpolated` and `PositionStatic` component types both implement the `Position` interface. A component is an instance of a component type.

An entity can only have (at most) one component that implements a particular interface (that is, it cannot have both `PositionInterpolated` and `PositionStatic`). Any code that interacts with the entity cannot tell what component types it uses - the code can only use `QueryInterface` to get a pointer to whatever component implements the `Position` interface, and call the common methods declared by that interface.

== Message passing ==

Direct method calls between components are sometimes necessary, but they force component implementations to know details of other components. For example, a `Position` component may want to notify many other components when the entity moves (e.g. any components that want to detect when an entity is within a certain range, or set it on fire if it's walking on lava), and it would be bad (complex, inflexible) if the `Position` component type's code had to know about every other component type it should notify.

The '''message passing''' system helps with this case. Component types can '''subscribe''' to a particular message type, and components can '''post''' or '''broadcast''' a message with a type and associated data, which will be received by all subscribed components. (''Post'' sends the message to the components with a specific entity ID, ''broadcast'' sends to component of all entities). For example, the burn-on-lava component can subscribe to the `PositionChanged` message type, and the `Position` component can then post a `PositionChanged` message to its own entity ID, and the burn component's message handler function will be called. The `Position` component only has to know about this message type, not about any of the components that use it.

Messages are one-to-many communication (any number of components can receive a single posted message), and they are one-way (it is not possible to return a value in response to a message). Components are notified in a consistent but arbitrary order.

(TODO: the post vs broadcast semantics are not very well designed currently.)

== Serialization ==

The simulation system needs to support three related features:
 * Serializing the complete simulation state to a byte stream, for saved games and potentially for joining (or rejoining after disconnection) in-progress games.
 * Computing a checksum of the simulation state in multiplayer games, to detect out-of-sync errors before they lead to significant divergences in gameplay.
 * Dumping the state of the simulation or of a specific entity or component into a roughly human-readable format, for debugging.
Each component therefore has to implement serialization (and deserialization) support, passing its internal data to the serialization API (which will either save it in an efficient byte format, or pass it into a checksum computation, or convert it to human-readable text).

For scripted components this is automatic. But C++ components have to implement it manually. The general rule is that the following series of method calls must result in components that have the same checksum and behave identically:
 * `constructor()` -> `Init(context, paramNode)` -> ...simulation turns... -> `Serialize(stream)`
 * `constructor()` -> `Deserialize(context, paramNode, stream)`
''and'' the serialized data must be identical regardless of the compiler, OS, CPU, etc. That means the component's relevant internal state must not include e.g. `size_t` values (they differ on 32-bit vs 64-bit platforms) or `float`s (we don't trust compilers to treat them precisely).

For components that are large or frequently used, the serialized output for saved games should be as efficient as possible. Any internal caches that can be safely reconstructed after deserialization should be omitted. Any data that was initialised from `paramNode` should not be serialized unless it has changed - store some kind of placeholder value instead and reconstruct the value in `Deserialize`.

== Entity templates ==

Entities are constructed from an '''entity template''', defined in XML (typically in the binaries/data/mods/public/simulation/templates/ directory). The root element of the XML file contains one element per component, giving the component type's name. Each component element contains initialisation data for that component - typically either empty, or a series of elements giving various data fields. This data is passed to the component's `Init` method.

== System entity ==

Some gameplay code is 'global', and it only makes sense to have one copy of it; but it can benefit from being written in the component infrastructure, e.g. for serialization and message passing and script interfacing. This code can be implemented as a ''system'' component, which is like a normal component but (as a convention, not enforced by the system) given the entity ID `SYSTEM_ENTITY`. It can then be accessed and used by any simulation code in the same way as a normal component.