|
Nebula
|
#include <levelextension.h>
A feature's contribution to the level formats.
The formats know an extension by name and treat what it produces as text they do not interpret, which is what lets a feature serialize something the engine has no type knowledge of.
The formats do not need the extension to write or read: they write the text capture produced as a node under the entity, and they hand the text they read back to apply. That is also what makes an extension the file carries but this build does not have survive a save, because the text is kept whether or not an extension can be found for it.
The hooks the merge needs are the ones that let the formats say something about text they cannot read: which keys the text carries, what the text looks like with only those keys, what one text gives when another text is put over it, and what one text gives for a named key when it does not carry it. They are used the way component reflection is used for a component's fields, and an extension without them is written whole, which is what a feature that has no authored fields gets.
Every hook that writes a text writes it in the same order: the nodes by name and the keys inside a node by name. The formats compare texts as bytes, because they cannot read them, and an order that differed between the hooks would read as a change that no value changed.
One text, one shape: the entity as one node per feature thing. The formats cannot read the text, so they cannot group it, and that is the only shape a file can carry. Everything that composes a text works in this shape, and an editor command holds this shape as well.
The formats also hand the extension the file's guid map, because the extension cannot resolve what its own text names. A text that names entities is written as the guids the file names them by, and the map is only valid for the duration of the one call that needs it.
Public Types | |
| using | CaptureFunc = void(*)(Game::Entity, Util::String&) |
| using | ApplyFunc = void(*)(Game::Entity, const char*) |
| the entity, put back from the text. | |
| using | CaptureKeysFunc = void(*)(Game::Entity, const Util::Array<Util::String>& keys, Util::String& out) |
| the text with only the named keys, which is what a linked entity writes and what a merge composes from. | |
| using | KeysFunc = void(*)(const char* text, Util::Array<Util::String>& out) |
| the keys the given text carries. | |
| using | MergeFunc = void(*)(const char* base, const char* over, Util::String& out) |
| what the base text gives when the keys the other text carries are put over it | |
| using | ResolveFunc = void(*)(const char* base, const Util::Array<Util::String>& keys, Util::String& out) |
| the text for the named keys, each value read from the given base text, or the field's default when the base has nothing. | |
| using | RefContextFunc = void(*)(const char* pairs) |
| the file's guid map as "guid:entityId" pairs, for the duration of one capture or apply | |
Public Attributes | |
| Util::StringAtom | name |
| the node name the extension writes under an entity | |
| CaptureFunc | capture = nullptr |
| the text for one entity, produced from what the feature holds | |
| ApplyFunc | apply = nullptr |
| one entity, put back from the text the file carried for it | |
| CaptureKeysFunc | captureKeys = nullptr |
| KeysFunc | keys = nullptr |
| MergeFunc | merge = nullptr |
| ResolveFunc | resolve = nullptr |
| RefContextFunc | refContext = nullptr |
| using Game::LevelExtension::ApplyFunc = void(*)(Game::Entity, const char*) |
the entity, put back from the text.
Exact: what the text names is what the entity has, and what it does not name is taken off. A command holds the entity's whole text, so this is what makes a change that took one thing off read as a change rather than as an addition
| using Game::LevelExtension::CaptureFunc = void(*)(Game::Entity, Util::String&) |
| using Game::LevelExtension::CaptureKeysFunc = void(*)(Game::Entity, const Util::Array<Util::String>& keys, Util::String& out) |
the text with only the named keys, which is what a linked entity writes and what a merge composes from.
Null when the extension has no keys to answer with
| using Game::LevelExtension::KeysFunc = void(*)(const char* text, Util::Array<Util::String>& out) |
the keys the given text carries.
The formats cannot see inside the text, so this is how they know which part of it an entity authored
| using Game::LevelExtension::MergeFunc = void(*)(const char* base, const char* over, Util::String& out) |
what the base text gives when the keys the other text carries are put over it
| using Game::LevelExtension::RefContextFunc = void(*)(const char* pairs) |
the file's guid map as "guid:entityId" pairs, for the duration of one capture or apply
| using Game::LevelExtension::ResolveFunc = void(*)(const char* base, const Util::Array<Util::String>& keys, Util::String& out) |
the text for the named keys, each value read from the given base text, or the field's default when the base has nothing.
A revert to the prefab needs this, because a key the base does not carry has no value to put back, and only the extension knows what its field's default is
| ApplyFunc Game::LevelExtension::apply = nullptr |
one entity, put back from the text the file carried for it
| CaptureFunc Game::LevelExtension::capture = nullptr |
the text for one entity, produced from what the feature holds
| CaptureKeysFunc Game::LevelExtension::captureKeys = nullptr |
| KeysFunc Game::LevelExtension::keys = nullptr |
| MergeFunc Game::LevelExtension::merge = nullptr |
| Util::StringAtom Game::LevelExtension::name |
the node name the extension writes under an entity
| RefContextFunc Game::LevelExtension::refContext = nullptr |
| ResolveFunc Game::LevelExtension::resolve = nullptr |