Pieces

Piece definition

UPulseBuildPieceDefinition is a primary data asset (type PulseBuildPiece, see Piece ids).

Group Properties
Display DisplayName, Description, Icon, Category (Pulse.Build.Category.*, groups the menu), SortOrder, Tags (free tags for rules, limits, zones, resistances)
Look Mesh, MeshTransform (offset, rotation, scale relative to the piece origin = bottom center), Materials (overrides by slot)
Actor pieces ActorClass: spawned instead of an instance (doors, chests, machines). The actor gets a UPulseBuildPieceComponent if it has none. Mesh is used for the preview.
Shape bOverrideBounds + Bounds (piece space). Without override the mesh bounds are used. Bounds drive overlap, support and integrity.
Placement Placement (mode, see Placement), RotationStep
Sockets Sockets, bUseMeshSockets
Rules Rules, bUseDefaultRules (the rules of the settings on top)
Other bCanBeRemoved, Traits

Instances of simple pieces carry two custom data floats for materials: 0 = construction progress (1 when finished), 1 = health (0 to 1). The example material /PulseBuild/Examples/Materials/M_PulseBuild_Piece uses them for a build-up glow and damage darkening.

Piece ids

Wherever a piece leaves the machine it is named by its definition id (FPulseDefinitionId of PulseFoundation): the kind PulseBuildPiece and the asset name, as text PulseBuildPiece:DA_PulseBuild_Wall. Replication of placed pieces (FPulseBuildPiece::DefinitionId; the pointer Definition is local to each machine and never replicated or saved), saves, requests of clients (FPulseBuildRequest::DefinitionId), blueprint text and the favorites of a player carry only the id. Every machine finds the definition behind it through the definitions of PulseFoundation: a piece the game registered at runtime first, then the piece assets through the asset manager.

  • The kinds PulseBuildPiece (always cooked: saves, blueprint text, cheats and the creative menu find pieces by id), PulseBuildCatalog and PulseBuildBlueprint (cooked through their references) are registered by the plugin in code when the asset manager starts. No entry in Project Settings > Asset Manager is needed; a project entry for one of these kinds with other settings (another base class, Blueprint classes, editor only) is left alone with a warning.
  • Every piece class has the same kind, so the asset name alone makes the id: two piece assets with one name have one id. Data validation reports that as an error, and the editor warns when a new or renamed piece takes a name that is in use. A copy of a plugin piece under /Game (the starter content) may keep its name; the project asset wins.
  • Renaming a piece changes its id: saves and blueprint text with the old id no longer find it. The editor says so; add a Primary Asset Id Redirect from the old to the new id (Project Settings > Asset Manager) to keep them.
  • Code reads and makes ids with Pulse::Build::Pieces (PulseBuildPieces.h): MakePieceId, GetPieceId, ParsePieceId (a name or an id, any case), FindPiece (ready now, never loads), LoadPieceSynchronous, LoadPiece, GetPieceIds, and SetDefinition, which every code that makes a placed piece uses (it sets the pointer and the id together; UPulseBuildSubsystem::AddPiece refuses a piece whose id is not the one of its definition). Blueprints use the Pulse Build Piece Library (Get Piece Id, Find Piece, Get All Piece Ids, Register Piece) and the node Add Piece By Id of the building world.
  • A piece made at runtime (from a database, a mod) is named after its id, the same name on every machine, and registered with Pulse::Build::Pieces::RegisterPiece (node Register Piece) on the server and on every client.
  • Id fields in the editor (blueprint entries, requests) get the definition picker of PulseFoundation (meta PulseDefinitionType = "PulseBuildPiece"); catalogs, adjustments and other authored fields keep asset pickers.

Catalogs

UPulseBuildCatalog is a list of pieces. A builder may build the pieces of its Catalogs, plus the pieces of piece sources (see below). With bRequireCatalog off a builder may build every piece; without catalogs it then lists every piece id in the menu (creative mode, Pulse::Build::Pieces::GetPieceIds): the authority loads them the first time, a client in the background, and the menu hears OnAvailablePiecesChanged when they arrive; the builder keeps what it loaded. On the server such a builder also loads a piece asset a request names by its id, once (FindOrLoadBuildablePiece; never a path, never another kind). The cvar Pulse.Build.Free 1 ignores catalogs, rules and costs for testing. Catalogs are compared by piece id, so a piece the game registered under the id of a catalog piece counts as that piece. The catalog is checked for new pieces only: a placed piece (from a world seed, a save, a catalog that has shrunk since) can be moved and its spline points edited without being in a catalog (CheckPlacement with an IgnorePieceId).

Unlocking pieces later (skills, quests) means adding a catalog to the component, or a piece source.

Locked pieces

A Lock Piece adjustment of the tuning (FPulseAdjustment_BuildPieceLock, in a difficulty level, an event or a reward) locks a piece the catalogs allow: CanBuildPiece is false, selecting, placing and upgrading answer Pulse.Result.Failure.Build.Locked with the reason of the lock, on the client and again on the server. Placed pieces stay and can be moved, repaired and removed. GetAvailablePieces still lists locked pieces; a build menu asks IsPieceLocked(Piece, Reason) to show them greyed out with the reason; the entries of the view models carry both (UMVVMPulseBuildPiece::IsLocked, GetLockReason, see UI). The build component tells its menus (OnAvailablePiecesChanged) when the adjustments change. See Adjustments.

Piece sources

FPulseBuildPieceSource (instanced struct) adds pieces besides the catalogs: GetPieces for the menu and CanBuild for the checks on client and server. Sources come from UPulseBuildSettings::DefaultPieceSources (every builder), the sources bridges registered (Pulse::Build::Registry::RegisterPieceSource, every builder) and UPulseBuildComponent::PieceSources. The PulseGameplay bridge adds Inventory Build Kits: carrying a kit item lets the player build its piece. When a source offers other pieces (an unlock, a kit picked up), it calls NotifyAvailablePiecesChanged on the build component, and the build menu reads the list again.

Sockets

A socket (FPulseBuildSocket) has a name, a transform relative to the piece (X points away from the piece), a Type (Pulse.Build.Socket.*) and the types it Accepts. Two sockets fit when one accepts the type of the other; snapped sockets face each other. With bUseMeshSockets the sockets of the mesh whose tag is a socket type are used as well (they accept their own type).

Built-in socket types: Foundation, Wall, Floor, Roof, Road, Pipe, Fence (all under Pulse.Build.Socket). Add your own tags under that root.

The details panel of a piece shows its sockets as arrows in the 3D preview, and Pulse.Build.Debug 1 draws them in the game.

Traits

Traits are optional data, one per type (FPulseBuildPieceTrait):

Trait Module Purpose Page
Costs PulseBuild What placing costs, refunds, payment stages, repair costs Construction
Construction PulseBuild Build time, auto build, dismantle time, site mesh Construction
Health PulseBuild Max health, what a destroyed piece leaves Construction
Tiers PulseBuild Upgrades (wood, stone, metal) with mesh, materials, health, costs, build time, tags Construction
Decay PulseBuild Health lost per hour (of the day by default, HourUnit) without upkeep Construction
Spline PulseBuild Spline piece: segment, tile and point meshes, limits, connections Splines
Claim PulseBuild The piece claims an area for its owner Permissions and zones
Integrity PulseBuildIntegrity Stability losses, ground support Integrity
Damage Resistance PulseBuildGameplayBridge Damage multipliers per type and tier PulseGameplay integration

Add your own traits by deriving from FPulseBuildPieceTrait in C++ (see Extending).

Validation

Saving a piece runs IsDataValid: missing mesh or actor class, sockets without type, duplicate traits, payment stages without a construction site, decay without health and similar mistakes are reported with a hint how to fix them (see Editor tools).


This site uses Just the Docs, a documentation theme for Jekyll.