From f272257cb3ac63109e9dd69ff870a301d780b62e Mon Sep 17 00:00:00 2001 From: Lefteris Notas Date: Tue, 19 May 2026 18:14:11 +0300 Subject: [PATCH] fix: Update data asset documentation for clarity and consistency in type definitions --- .../blueprints/01-core/02_FL_GameUtilities.md | 43 +++++++++++++++---- .../04-inventory/27_BPC_CollectibleTracker.md | 2 +- .../118_DA_DataAssetArchitecture.md | 19 ++++++-- .../14-data-assets/119_DA_EncounterData.md | 28 ++++++------ .../14-data-assets/123_DA_ObjectiveData.md | 22 +++++----- 5 files changed, 75 insertions(+), 39 deletions(-) diff --git a/docs/blueprints/01-core/02_FL_GameUtilities.md b/docs/blueprints/01-core/02_FL_GameUtilities.md index 6b213c2..c60369e 100644 --- a/docs/blueprints/01-core/02_FL_GameUtilities.md +++ b/docs/blueprints/01-core/02_FL_GameUtilities.md @@ -6,6 +6,8 @@ |----------|-------| | **Class** | [`FL_GameUtilities`] | | **Parent** | [`BlueprintFunctionLibrary`] | + +> **⚠️ UE5 BP Limitation:** `BlueprintFunctionLibrary` requires C++ to create. This is the ONE file in the framework that needs a minimal C++ class. See Section "Blueprint-Only Alternative" below for the pure BP workaround using Macro Library + direct engine nodes. | **Folder** | [`Framework/Core/`] | | **Categorization** | [Core\Framework] | @@ -88,9 +90,9 @@ This is a pure Function Library. It has **no variables, no event dispatchers, no | Function | Category | Inputs | Outputs | Description | |----------|----------|--------|---------|-------------| -| [`LogDebug`] | Debug\Logging | `Category: Name`, `Message: String`, `Color: LinearColor` | — | Conditional screen + log output. Only fires in editor/development builds. Stripped in shipping builds via `DO_CHECK` flag. | -| [`DrawDebugSphere`] | Debug\Drawing | `WorldContext: Object`, `Center: Vector`, `Radius: Float`, `Color: LinearColor`, `Duration: Float` | — | Draws a debug sphere for visual debugging in-editor. Stripped in shipping builds. | -| [`DrawDebugString3D`] | Debug\Drawing | `WorldContext: Object`, `Location: Vector`, `Text: String`, `Color: LinearColor`, `Duration: Float` | — | Draws a 3D world-space debug string. Stripped in shipping builds. | +| [`LogDebug`] | Debug\Logging | `Category: Name`, `Message: String`, `Color: LinearColor`, `WorldContext: Object` | — | Conditional screen + log output. Uses `Branch: Is Editor Build` → then Print String + Draw Debug String. Inactive in shipping builds. | +| [`DrawDebugSphere`] | Debug\Drawing | `WorldContext: Object`, `Center: Vector`, `Radius: Float`, `Color: LinearColor`, `Duration: Float` | — | Draws a debug sphere. **BP node exists:** `Draw Debug Sphere`. Stripped in shipping. | +| [`DrawDebugString3D`] | Debug\Drawing | `WorldContext: Object`, `Location: Vector`, `Text: String`, `Color: LinearColor`, `Duration: Float` | — | Draws 3D world-space debug string. **BP node exists:** `Draw Debug String`. Stripped in shipping. | ## Blueprint Flow @@ -126,18 +128,41 @@ All functions can be called from Construction Scripts since they are pure (no wo ## Reuse Notes -- This library ships verbatim to every project. -- Add project-specific helpers in a separate `FL_ProjectUtilities` child library that references this one. -- Do **not** add game-specific functions here — extend with a new Function Library inheriting from this pattern. -- Debug functions are automatically stripped in Shipping builds via `DO_CHECK` preprocessor — no manual removal needed. +- This library ships as a minimal C++ `BlueprintFunctionLibrary` (required for static function libraries in UE5). +- Add project-specific helpers in a separate child library or Macro Library. +- Do **not** add game-specific functions here — extend with a new library. +- For a 100% Blueprint approach, see "Blueprint-Only Alternative" below. ## Success Criteria -1. Any Blueprint in the project can call `RemapFloat` from the Math category without errors. +1. Any Blueprint can call `RemapFloat` from the Math category without errors. 2. `GetSubsystemSafe` returns `None` instead of crashing when a subsystem doesn't exist. 3. `FormatTime(3661.0)` returns `01:01:01`. 4. `LogDebug` prints to both the output log and the viewport in editor builds. -5. `LogDebug` produces no output in a shipping build. +5. `LogDebug` produces no output in a shipping build (via `Is Editor Build` branch). + +## Blueprint-Only Alternative + +If you cannot compile C++, replace `FL_GameUtilities` with direct Blueprint nodes or a **Blueprint Macro Library**: + +| FL_GameUtilities Function | Pure BP Equivalent (no C++ needed) | +|--------------------------|-----------------------------------| +| `GetSubsystemSafe` | `Get Game Instance` → `Get Subsystem (Class)` → `Is Valid` branch | +| `GetGameFramework` | `Get Game Instance` → `Cast to GI_GameFramework` | +| `GetPlayerController` | `Get Player Controller (0)` → `Cast to PC_CoreController` | +| `HasGameplayTag` | `Does Actor Have Tag` (BP node) | +| `AddGameplayTagToActor` | `Get Actor Gameplay Tag Container` → `Add Tag` | +| `RemoveGameplayTagFromActor` | `Get Actor Gameplay Tag Container` → `Remove Tag` | +| `MakeTagFromString` | `Make Literal Gameplay Tag` OR `Get Gameplay Tag from Name` | +| `FindComponentByInterface` | `Get Component by Class` + `Does Implement Interface` | +| `RemapFloat` | `Map Range Clamped` (built-in BP math node) | +| `LerpClamped` | `Lerp` + `Clamp (Float)` | +| `FormatTime` | Custom BP function using division/modulo | +| `LogDebug` | `Branch: Is Editor Build` → `Print String` | +| `DrawDebugSphere` | `Draw Debug Sphere` (built-in BP node) | +| `DrawDebugString3D` | `Draw Debug String` (built-in BP node) | + +**Blueprint Macro Library:** Create a **Macro Library** asset (`Content/Framework/Core/ML_GameUtilities`). Macros support `WorldContext`, execution pins, and can call engine nodes — no C++ required. The trade-off: macros are NOT "static pure" — they need execution flow pins. --- diff --git a/docs/blueprints/04-inventory/27_BPC_CollectibleTracker.md b/docs/blueprints/04-inventory/27_BPC_CollectibleTracker.md index 5b6f896..617e1d4 100644 --- a/docs/blueprints/04-inventory/27_BPC_CollectibleTracker.md +++ b/docs/blueprints/04-inventory/27_BPC_CollectibleTracker.md @@ -16,7 +16,7 @@ | `CollectionProgress` | `TMap` | Collected count per collection type | | `CollectionTargets` | `TMap` | Total items per collection | | `bShowCollectibleNotifications` | `bool` | Toast on collectible pickup | -| `CompletionRewards` | `TMap>` | Items granted on collection completion | +| `CompletionRewards` | `Map>` | Items granted on collection completion | ## 3. Functions diff --git a/docs/blueprints/14-data-assets/118_DA_DataAssetArchitecture.md b/docs/blueprints/14-data-assets/118_DA_DataAssetArchitecture.md index 6b5f863..a13fcf1 100644 --- a/docs/blueprints/14-data-assets/118_DA_DataAssetArchitecture.md +++ b/docs/blueprints/14-data-assets/118_DA_DataAssetArchitecture.md @@ -13,15 +13,26 @@ The Modular Game Framework uses `UDataAsset` (and subclass `UPrimaryDataAsset` w ### Conventions - **Naming:** `DA_` — e.g., `DA_WeaponData`, `DA_AIProfile`, `DA_AtmosphereProfile` - **Storage:** All DA files live in `Content/DataAssets//` in-engine -- **Loading:** Use `UAssetManager` with `FPrimaryAssetType` and `FPrimaryAssetId` for async loading -- **Validation:** Each DA implements `ValidateData()` for editor-time data integrity checks -- **Gameplay Tags:** All DAs carry a `FGameplayTagContainer` for query and filtering +- **Parent Class:** `Primary Data Asset` (Blueprint class). Maps to C++ `UPrimaryDataAsset`. +- **Loading:** Use `Async Load Primary Asset` node with `Primary Asset Id` and `Primary Asset Type` +- **Validation:** Each DA implements a `ValidateData()` function for editor-time data integrity checks +- **Gameplay Tags:** All DAs carry a `Gameplay Tag Container` for query and filtering ### Dependency Rules -1. DAs reference other DAs by `FPrimaryAssetId` or `TSoftObjectPtr`, never by hard pointer +1. DAs reference other DAs by `Primary Asset Id` or `Soft Object Reference`, never by hard pointer 2. No DA may reference a runtime system; only other DAs 3. Circular DA references are prohibited — use `World Context Object` for runtime resolution 4. All DA types are registered in `DefaultGame.ini` under `[/Script/Engine.AssetManagerSettings]` + - In BP: configure via **Project Settings → Asset Manager → Primary Asset Types to Scan** + +### BP Type Reference +| C++ Type | Blueprint Variable Type | BP Node | +|----------|------------------------|---------| +| `FPrimaryAssetId` | `Primary Asset Id` | `Make Primary Asset Id`, `Break Primary Asset Id` | +| `FPrimaryAssetType` | `Primary Asset Type` | `Make Primary Asset Type` | +| `TSoftObjectPtr` | `Soft Object Reference` | `Async Load Primary Asset`, `Resolve Soft Reference` | +| `FGameplayTagContainer` | `Gameplay Tag Container` | `Has Tag`, `Add Tag`, `Has Any` | +| `UPrimaryDataAsset` | `Primary Data Asset` (parent class) | Right-click → Miscellaneous → Data Asset → PrimaryDataAsset | ### Registered DA Types (Section 13 of Master) diff --git a/docs/blueprints/14-data-assets/119_DA_EncounterData.md b/docs/blueprints/14-data-assets/119_DA_EncounterData.md index b8785a8..db22666 100644 --- a/docs/blueprints/14-data-assets/119_DA_EncounterData.md +++ b/docs/blueprints/14-data-assets/119_DA_EncounterData.md @@ -1,7 +1,7 @@ # DA_EncounterData — Data Asset -**Parent Class:** `UDataAsset` -**Dependencies:** [`BPC_ProceduralEncounter`](../10-adaptive/70_BPC_ProceduralEncounter.md) +**Parent Class:** `Primary Data Asset` (Blueprint: `PrimaryDataAsset`) +**Dependencies:** [`BPC_ProceduralEncounter`](../10-adaptive/92_BPC_ProceduralEncounter.md) **Purpose:** Defines procedural encounter configurations — enemy types, spawn rules, difficulty scaling, and encounter triggers. --- @@ -10,18 +10,18 @@ | Field | Type | Description | |-------|------|-------------| -| `EncounterTag` | `FGameplayTag` | Unique encounter identifier | -| `EnemyArchetypes` | `TArray` | Allowed enemy DA_AIProfile references | -| `MinEnemies` | `int32` | Minimum spawn count | -| `MaxEnemies` | `int32` | Maximum spawn count | -| `SpawnRadius` | `float` | Radius around trigger point (cm) | -| `SpawnDelay` | `float` | Time between individual spawns | -| `bTriggerOnOverlap` | `bool` | Auto-trigger on player overlap | -| `bTriggerOnAlert` | `bool` | Trigger when alert level reaches threshold | -| `RequiredAlertLevel` | `float` | Alert threshold (0.0-1.0) | -| `EncounterCooldown` | `float` | Min time between encounters | -| `DifficultyScaling` | `UCurveFloat*` | Curve for scaling enemy count/strength by difficulty | -| `NarrativePrerequisites` | `TArray` | Narrative flags required | +| `EncounterTag` | `Gameplay Tag` | Unique encounter identifier | +| `EnemyArchetypes` | `Array` | Allowed enemy `DA_BehaviourVariant` references | +| `MinEnemies` | `Integer` | Minimum spawn count | +| `MaxEnemies` | `Integer` | Maximum spawn count | +| `SpawnRadius` | `Float` | Radius around trigger point (cm) | +| `SpawnDelay` | `Float` | Time between individual spawns | +| `bTriggerOnOverlap` | `Boolean` | Auto-trigger on player overlap | +| `bTriggerOnAlert` | `Boolean` | Trigger when alert level reaches threshold | +| `RequiredAlertLevel` | `Float` | Alert threshold (0.0-1.0) | +| `EncounterCooldown` | `Float` | Min time between encounters | +| `DifficultyScaling` | `Curve Float` (Object Reference) | Curve for scaling enemy count/strength by difficulty | +| `NarrativePrerequisites` | `Array` | Narrative flags required | --- diff --git a/docs/blueprints/14-data-assets/123_DA_ObjectiveData.md b/docs/blueprints/14-data-assets/123_DA_ObjectiveData.md index d817907..bd22113 100644 --- a/docs/blueprints/14-data-assets/123_DA_ObjectiveData.md +++ b/docs/blueprints/14-data-assets/123_DA_ObjectiveData.md @@ -1,7 +1,7 @@ # DA_ObjectiveData — Data Asset -**Parent Class:** `UDataAsset` -**Dependencies:** [`BPC_ObjectiveSystem`](../07-narrative/39_BPC_ObjectiveSystem.md), [`WBP_ObjectiveDisplay`](../06-ui/WBP_ObjectiveDisplay.md) +**Parent Class:** `Primary Data Asset` (Blueprint: `PrimaryDataAsset`) +**Dependencies:** [`BPC_ObjectiveSystem`](../07-narrative/59_BPC_ObjectiveSystem.md), [`WBP_ObjectiveDisplay`](../06-ui/54_WBP_ObjectiveDisplay.md) **Purpose:** Defines objective content — objective text, requirements, completion conditions, linked narrative flags, and reward data. --- @@ -10,16 +10,16 @@ | Field | Type | Description | |-------|------|-------------| -| `ObjectiveTag` | `FGameplayTag` | Unique tag for this objective | -| `ObjectiveText` | `FText` | Display text for HUD/journal | +| `ObjectiveTag` | `Gameplay Tag` | Unique tag for this objective | +| `ObjectiveText` | `Text` | Display text for HUD/journal | | `ObjectiveCategory` | `EObjectiveCategory` | Main, Side, Hidden, Tutorial | -| `PrerequisiteFlags` | `TArray` | Narrative flags required before objective activates | -| `CompletionFlags` | `TArray` | Flags set when objective completes | -| `bIsOptional` | `bool` | Objective can be skipped | -| `ObjectiveLocation` | `FVector` | World location for marker | -| `RewardItems` | `TArray` | Items granted on completion | -| `RewardExperience` | `int32` | XP awarded | -| `LinkedEndingWeight` | `float` | Score contribution to ending evaluation | +| `PrerequisiteFlags` | `Array` | Narrative flags required before objective activates | +| `CompletionFlags` | `Array` | Flags set when objective completes | +| `bIsOptional` | `Boolean` | Objective can be skipped | +| `ObjectiveLocation` | `Vector` | World location for marker | +| `RewardItems` | `Array` | Items granted on completion | +| `RewardExperience` | `Integer` | XP awarded | +| `LinkedEndingWeight` | `Float` | Score contribution to ending evaluation | ---