Blueprints, undo and hotbar
Building blueprints
A building blueprint (not to be confused with Unreal Blueprints) is a group of pieces with transforms relative to an origin: a house, a wall section, a factory module. FPulseBuildBlueprintData holds the entries (the definition id of the piece, PulseBuildPiece:<name>, see Pieces; relative transform, spline points, tier). In a UPulseBuildBlueprint asset the id fields have the definition picker of PulseFoundation.
| Source | How |
|---|---|
| Copy tool | SetTool(Copy) and confirm on a structure: all touching pieces become the current blueprint |
| Code | CopyPieces(Ids) |
| Asset | UPulseBuildBlueprint data asset, placed with SelectBlueprint(Asset) |
| Text | ExportCurrentBlueprint() gives a text players can share; ImportBlueprint(Text) reads it |
Blueprint text is version 2: entries name their pieces by id, and text of another version or with more entries than Blueprint::MaxEntries (what a capture makes and a server takes) is refused (FromString and ImportBlueprint return false). ImportBlueprint and SelectBlueprint load the definitions of the entries first (Pulse::Build::Blueprint::LoadDefinitions, one load per id) and start placing when they are there, at once when they are ready; when a piece is not known, the builder answers InvalidPiece with the ids in its message (OnBuildResult) and selects nothing. Pulse::Build::Blueprint::MakePieces(Context, Data, Origin, OutPieces, OutMissing) only takes definitions that are ready and lists the ids it did not find; the server never loads a path for blueprint text of a client, so a blueprint with an unknown piece is refused as a whole (InvalidPiece). Only a builder that may build every piece loads the piece assets of the ids once first, as for Place. A selected blueprint (SelectBlueprintData) keeps the definitions of its pieces while it is selected.
SelectBlueprintData starts placing data; the PlaceBlueprint tool shows a ghost of all pieces and the total costs. MirrorCurrentBlueprint swaps left and right. Placing places all or none in one request (RequestPlaceBlueprint) and one undo step. Every piece runs the checks of placing a single piece (PlacePiece) before anything is placed or paid: the placement mode, catalog and lock, the range of the builder (every piece, every spline point), the rules with the ground below, zones, claims, permissions and the piece limits. The limits are then counted for the whole group (the player limit and every zone with a piece limit). Pieces of a blueprint support each other before they exist: a piece its mode refuses in the world still passes when one of its sockets fits a socket of another piece of the blueprint at exactly its transform, and a grid piece passes when it is turned like the grid (the blueprint keeps the grid offset it was captured with). Pieces never get a scale from a blueprint. The preview of the PlaceBlueprint tool runs the same checks, so it shows the reason of the first piece that would be refused.
On the authority the building world tells which pieces form one blueprint: OnBlueprintPlacementStarted(Blueprint, Origin, Instigator) after every check and the payment, then OnPieceAdded for each piece (IsPlacingBlueprint() is true meanwhile), then OnBlueprintPlaced(Pieces, Instigator) with the ids of the pieces that were added (each also as ...Native). Code that places blueprints itself wraps its AddPiece calls in BeginBlueprintPlacement and EndBlueprintPlacement, best with the scope FPulseBuildBlueprintPlacementScope(Subsystem, Blueprint, Origin, Instigator): it begins in its constructor and ends in its destructor with the ids given to AddPlaced, so no early return leaves the building world inside a blueprint. An EndBlueprintPlacement without its begin ensures and sends nothing. Undo and redo do not send them. The Blueprint of the event holds the states of the text without progress and health, but the text comes from players: bridges read the placed pieces and check their copied states on the server (see below).
Blueprints never carry runtime states: construction progress and health are stripped on the server, so a copied site is a new site and a copied damaged wall is new.
Data of other systems in blueprints
Piece states with ShouldCopy true come along by themselves. Data another system keeps outside the piece (the recipe of a factory machine, the filter of a sorter) goes in through Pulse::Build::Blueprint::OnCaptureEntryNative(): Capture calls it for every entry with the building world, the piece and the entry, and the listener adds a piece state of its own (FPulseBuildPieceState, ShouldCopy true) to Entry.State. The state is part of the blueprint text and becomes a state of the placed piece. The hook runs wherever Capture runs (the copy tool runs on the player’s machine, also on a client) and must not change pieces.
- The state overrides
ShouldSave()to return false:Capturethen skips the copy on the placed piece (the hook adds the current data again, so an entry never holds a stale copy next to it), and saves never hold it. - The system reads it on the authority in
OnPieceAddedNativewhileIsPlacingBlueprint()is true.OnPieceAddedalso fires on load, on redo and on every client, where the state must not overwrite data changed since. - Blueprint text comes from players, so the system checks the state there before it applies it (the builder has unlocked the recipe, the filter names items that exist).
USTRUCT()
struct FMyRecipeState : public FPulseBuildPieceState
{
GENERATED_BODY()
UPROPERTY()
FName Recipe;
virtual bool ShouldSave() const override { return false; }
};
Pulse::Build::Blueprint::OnCaptureEntryNative().AddLambda([](const UPulseBuildSubsystem& InWorld, const FPulseBuildPiece& InPiece, FPulseBuildBlueprintEntry& InOutEntry)
{
FMyRecipeState state;
state.Recipe = FindRecipe(InPiece.Id);
InOutEntry.State.Add(FInstancedStruct::Make(state));
});
Undo and redo
Every action of a player (place, drag, blueprint, remove, move, rotate, upgrade, spline edits) is recorded on the server per player, up to UndoHistorySize steps (settings). RequestUndo / RequestRedo replay them; GetUndoCount is replicated to the owner for the UI.
Undo never creates or loses resources: a step pays or refunds the difference in value, scaled like the original action (a removal that gave back half refunds half again) and rounded the other way. Cancelling a construction site gives back exactly what it took, also through undo and redo. A step fails as a whole when a piece of it changed in the meantime or something else stands there now.
A step runs the checks of the direct actions before it changes anything: a piece it takes away needs the right to remove it (CanRemovePiece, as the Remove tool), a piece it sets back needs the right to change it and its old place must still be allowed (zones, claims), and a piece it brings back is checked like a new piece (zones, claims, the piece limits of the player and of zones, counted for all pieces of the step together). The rules of the pieces do not run again, so a step still works after a rule was added, and there is no range check.
Hotbar, favorites and recent pieces
| Function | What it does |
|---|---|
SetHotbarSlot(Index, Piece), SelectHotbarSlot(Index) | HotbarSize slots (default 10) |
ToggleFavorite(Piece) | Favorites show first in the menu |
GetRecentPieces() | Pieces the player placed last, newest first |
ExportUserData(), ImportUserData(Data) | All of it as FPulseBuildUserData for saving, the pieces by their definition ids (the builder saves it itself, see Save and load) |