Definitions
Items, recipes, quests and other data that plugins save, replicate or point to are definitions. Every definition has an id, FPulseDefinitionId (Definitions/PulseDefinitionId.h): its kind and a name unique within the kind, written as Type:Name (PulseItem:Sword). A save keeps the id, a client gets the id, and the definitions of the game find the object behind it again.
Without any setup a definition is a data asset and its id is its primary asset id: the kind is the primary asset type, the name the primary asset name. Nothing changes for a project that keeps its definitions as data assets.
Finding and loading a definition
C++ (Definitions/PulseDefinitions.h):
const FPulseDefinitionId swordId(TEXT("PulseItem"), TEXT("Sword"));
// Ready now (registered by the game, or in memory), without loading
UMyItemDefinition* sword = Pulse::Definitions::FindDefinition<UMyItemDefinition>(this, swordId);
// Loaded without a hitch; the callback may run inside the call
Pulse::Definitions::LoadDefinition(this, swordId, [weakThis = TWeakObjectPtr<UMyComponent>(this)](const FPulseResult& InResult, UObject* InDefinition)
{
if (UMyComponent* self = weakThis.Get(); self && InResult.IsSuccess())
self->UseItem(Cast<UMyItemDefinition>(InDefinition));
});
// The id of a definition, to save it or send it to another machine
const FPulseDefinitionId savedId = Pulse::Definitions::GetDefinitionId(this, sword);
LoadDefinitionSynchronous loads at once and lets the game wait; use it only where nothing else is possible (a save that is read in one call). GetDefinitionIds(this, TEXT("PulseItem")) lists every id of a kind, loaded or not, for cheats, tools and menus.
Blueprint: Find Pulse Definition and Load Pulse Definition Synchronous (the output has the class you pick), the async node Load Pulse Definition (On Loaded, On Failed with the reason), Get Pulse Definition Id, Get Pulse Definition Ids and the conversions to and from text and primary asset ids.
A load that fails answers with a reason: Pulse.Result.Failure.Invalid (an invalid id), NotFound (no definition with this id, or the kind has no catalog), Timeout or Cancelled.
Where definitions come from
UPulseDefinitionSubsystem (game instance) answers every question in this order:
- Definitions the game registered at runtime (
RegisterDefinition(Id, Object)): definitions from a database, a live-ops update or made at start-up. A registered definition hides an asset with the same id. The subsystem keeps it alive untilUnregisterDefinitionor the end of the game instance. One object per id and one id per object; a definition that was destroyed can be replaced. Register it on every machine that needs it (server and clients). - The catalog of its kind, a provider (
UPulseDefinitionCatalog). The default catalog asks the asset manager; a renamed asset is found through the Primary Asset Id Redirects of the asset manager.
Registering a kind in code
A plugin registers the primary asset type of its kind in code, so a project needs no entry in Project Settings > Asset Manager. Pulse::Definitions::RegisterAssetType(Type, BaseClass, bAlwaysCook) scans /Game and the content root of every enabled plugin with content (MakeAssetTypeScanPaths), without Blueprint classes and not editor only:
void FMyPluginModule::StartupModule()
{
UAssetManager::CallOrRegister_OnAssetManagerCreated(FSimpleMulticastDelegate::FDelegate::CreateLambda([]()
{
Pulse::Definitions::RegisterAssetType(UMyDefinition::PrimaryAssetType, UMyDefinition::StaticClass(), true);
}));
}
- Always cook: pass
truefor definitions found by id and never referenced (quests by tag, sound events, theme extensions), so the cook packs them;falsewhen assets reference them anyway. - Listed by the project: a kind the project lists with other settings (another base class, Blueprint classes, editor only) is left alone with a warning that names the entry; other settings would make the engine ensure. The check is the pure
IsAssetTypeConflicting(Listed, BaseClass). - It returns false without an asset manager, without a base class or on such a conflict.
Two assets with one id
A copy of a plugin example in the project (Add Starter Content copies examples to /Game/Pulse/<Plugin>) keeps the id of the example. The asset manager keeps only one asset per id, so the default catalog decides itself which one it takes (Pulse::Definitions::GetAssetPath):
- Project content wins. When exactly one of the assets is under
/Game, the catalog takes it, and the plugin example stays as it is. You can change the copy without giving it an id of its own. - Otherwise (two assets of plugins, or several under
/Game) the catalog takes the asset of the asset manager as before and the log warns once per id. Give the assets ids of their own; the Check of a plugin reports two project assets with one id as an error (quest tags, speaker names).
The asset manager itself still logs that it found the id twice. Pulse::Definitions::MayShareDefinitionId(PackageA, PackageB) tells checks of your own whether two assets may share an id: one under /Game, the other not.
OnDefinitionsChanged (Blueprint) and OnDefinitionsChangedNative tell when the definitions of a kind changed: one was registered or unregistered, the kind got another catalog, or its catalog got new content. A catalog reports new content (a server pushed definitions, a mod was loaded) with Notify Changed; code outside the catalog calls NotifyDefinitionsChanged(Type) of the subsystem.
The id of a definition comes from its registration, else from the catalog of its primary asset type, else from another active catalog; a catalog’s answer only counts for its own kind.
Definitions on the network
Plugins replicate and save the id of a definition, never the object: a client finds the definition behind the id with its own definitions, so definitions made at runtime and those of a catalog of your own reach clients and saves too.
- Same id on every machine. A definition the game makes at runtime is registered on the server and on every client with the same id. When the definition has a primary asset id (a data asset made with
NewObject), its object name is the name of its id: plugins that save it ask the object for its id. - Resolving on the client.
FPulseDefinitionResolver(Definitions/PulseDefinitionResolver.h) is what components use for the ids they receive: the definition ready now, else loaded at once by the catalog of its kind (the default catalog loads assets at once, as replicated object pointers do), else loaded asynchronously. Waits for the same id share one load, callbacks run on the game thread,CancelAllinEndPlaydrops the waits. - Checked ids. A definition with a primary asset id that differs from the id it was found with (and is no redirect of it) is not used. The log warns once per id and names the catalog of the kind; the warnings of a kind come again after it changed.
FPulseDefinitionResolver::CheckDefinitionIdruns the same check for code of your own.
// A member of the component (not of a struct): FPulseDefinitionResolver Resolver;
if (UMyItemDefinition* item = Resolver.Resolve<UMyItemDefinition>(this, entry.DefinitionId, [weakThis = TWeakObjectPtr<UMyComponent>(this), id = entry.DefinitionId](UMyItemDefinition* InItem)
{
if (UMyComponent* self = weakThis.Get())
self->OnItemArrived(id, InItem);
}))
entry.Definition = item;
Resolve returns the definition when it is ready, otherwise null: while IsPending(Id) is true the callback follows (with null when the definition did not load), otherwise it failed at once. An entry whose definition still loads is not shown yet; owners whose ids did not load ask again on OnDefinitionsChanged of their kind.
Picking an id in the editor
An FPulseDefinitionId property shows two fields, Type and Name. Give it the meta data PulseDefinitionType and the details panel shows a picker for that kind instead:
/** Who speaks: a speaker of the dialog catalog. */
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Dialog", meta = (PulseDefinitionType = "PulseDialogSpeaker"))
FPulseDefinitionId Speaker;
/** Arrays, sets and maps of ids: every element gets the picker. */
UPROPERTY(EditAnywhere, Category = "Dialog", meta = (PulseDefinitionType = "PulseDialogSpeaker"))
TArray<FPulseDefinitionId> Listeners;
- The list shows the names of every id of the kind (
GetDefinitionIds): the assets of the asset manager, and while Play in Editor runs, what the definitions of the first game instance know, registered definitions included. Type in the search box to filter: every word must be part of the name, case does not matter. Enter takes the first row, None clears the id. - A name the list does not have (a catalog of your own that only knows it at runtime) can still be written: type it and pick Use “Name”. The field marks such an id with “(not found)” and an id of another kind with “(another kind)”, both in the warning color.
- Use selected takes the first asset of the kind that is selected in the Content Browser; Browse shows the asset of the id there.
The picker writes the kind and the name together (one undo step) and works with several selected objects. It is part of PulseFoundationEditor; the meta data does nothing in a game build.
A catalog of your own
A game that keeps definitions elsewhere (a database of the studio, a live-ops service) derives a catalog from UPulseDefinitionCatalog in C++ or Blueprint and overrides:
| Function | What it does |
|---|---|
FindDefinition(Id) | The definition when it is ready now, without loading |
LoadDefinitionSynchronous(Id) | The definition, loaded at once; a catalog that only loads asynchronously gives what Find Definition gives |
LoadDefinition(RequestId, Id) | Starts loading and answers with Finish Load Definition, at once or later |
GetDefinitionId(Definition) | The id of an object this catalog knows |
GetDefinitionIds(Type) | Every id of the kind this catalog knows |
Call the parent function (Super) for ids that are still assets. A catalog keeps the definitions it makes alive (in a UPROPERTY) and gives them the same id every time. Pick the class in Project Settings > Pulse > Foundation > Definitions: Default Definition Catalog for every kind, Definition Catalogs for one kind (an entry without class turns the kind off: only registered definitions are found). At runtime SetCatalog, SetCatalogClass and ResetCatalog change the catalog of a kind. A catalog object serves one kind; give each kind its class, the subsystem makes one object per kind. When the catalog gets definitions it did not have (a server pushed them, a mod was loaded), it calls Notify Changed, so owners of ids that did not load ask again.
Rules
- Definitions are asked for on the game thread.
- Plugins never ask a catalog directly: they use
Pulse::Definitions(or the subsystem), so registered definitions and the catalog of the game both work. - Callers keep the definitions they use (a
UPROPERTY); an answer that waits for the next tick keeps its definition alive until it is delivered. - The Pulse Debugger shows the catalog of every kind with how many of its ids are loaded, the loaded ids of each kind with the object they found (its path tells a copy under
/Gamefrom the plugin example) and the registered definitions (category Definitions).