Nebula
Loading...
Searching...
No Matches
Game::LevelExtension Class Reference

#include <levelextension.h>

Detailed Description

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.

See also
Game::LevelExtensionRegistry

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

Member Typedef Documentation

◆ ApplyFunc

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

◆ CaptureFunc

◆ CaptureKeysFunc

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

◆ KeysFunc

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

◆ MergeFunc

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

◆ RefContextFunc

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

◆ ResolveFunc

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

Member Data Documentation

◆ apply

ApplyFunc Game::LevelExtension::apply = nullptr

one entity, put back from the text the file carried for it

◆ capture

CaptureFunc Game::LevelExtension::capture = nullptr

the text for one entity, produced from what the feature holds

◆ captureKeys

CaptureKeysFunc Game::LevelExtension::captureKeys = nullptr

◆ keys

KeysFunc Game::LevelExtension::keys = nullptr

◆ merge

MergeFunc Game::LevelExtension::merge = nullptr

◆ name

Util::StringAtom Game::LevelExtension::name

the node name the extension writes under an entity

◆ refContext

RefContextFunc Game::LevelExtension::refContext = nullptr

◆ resolve

ResolveFunc Game::LevelExtension::resolve = nullptr

The documentation for this class was generated from the following file: