| | 49 | == Serialization == |
| | 50 | |
| | 51 | The simulation system needs to support three related features: |
| | 52 | * Serializing the complete simulation state to a byte stream, for saved games and potentially for joining (or rejoining after disconnection) in-progress games. |
| | 53 | * Computing a checksum of the simulation state in multiplayer games, to detect out-of-sync errors before they lead to significant divergences in gameplay. |
| | 54 | * Dumping the state of the simulation or of a specific entity or component into a roughly human-readable format, for debugging. |
| | 55 | 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). |
| | 56 | |
| | 57 | 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: |
| | 58 | * `constructor()` -> `Init(context, paramNode)` -> ...simulation turns... -> `Serialize(stream)` |
| | 59 | * `constructor()` -> `Deserialize(context, paramNode, stream)` |
| | 60 | ''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). |
| | 61 | |
| | 62 | 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`. |
| | 63 | |
| | 64 | (TODO: the serialization API should expose some way to detect when efficiency is required, vs when the full state should be dumped for checksumming or debugging.) |
| | 65 | |
