admin/UE5-Modular-Game-Framework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: Update data asset documentation for clarity and consistency in type definitions

Browse Source
This commit is contained in:
Lefteris Notas
2026-05-19 18:14:11 +03:00
parent bc8ab7c48f
commit f272257cb3
5 changed files with 75 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
docs/blueprints/01-core/02_FL_GameUtilities.md
View File

@@ -6,6 +6,8 @@
|----------|-------| |----------|-------|
| **Class** | [`FL_GameUtilities`] | | **Class** | [`FL_GameUtilities`] |
| **Parent** | [`BlueprintFunctionLibrary`] | | **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/`] | | **Folder** | [`Framework/Core/`] |
| **Categorization** | [Core\Framework] | | **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 | | 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. | | [`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 for visual debugging in-editor. Stripped 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 a 3D world-space debug string. Stripped in shipping builds. | | [`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 ## Blueprint Flow
@@ -126,18 +128,41 @@ All functions can be called from Construction Scripts since they are pure (no wo
## Reuse Notes ## Reuse Notes
- This library ships verbatim to every project. - This library ships as a minimal C++ `BlueprintFunctionLibrary` (required for static function libraries in UE5).
- Add project-specific helpers in a separate `FL_ProjectUtilities` child library that references this one. - Add project-specific helpers in a separate child library or Macro Library.
- Do **not** add game-specific functions here — extend with a new Function Library inheriting from this pattern. - Do **not** add game-specific functions here — extend with a new library.
- Debug functions are automatically stripped in Shipping builds via `DO_CHECK` preprocessor — no manual removal needed. - For a 100% Blueprint approach, see "Blueprint-Only Alternative" below.
## Success Criteria ## 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. 2. `GetSubsystemSafe` returns `None` instead of crashing when a subsystem doesn't exist.
3. `FormatTime(3661.0)` returns `01:01:01`. 3. `FormatTime(3661.0)` returns `01:01:01`.
4. `LogDebug` prints to both the output log and the viewport in editor builds. 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.
--- ---

2
docs/blueprints/04-inventory/27_BPC_CollectibleTracker.md
View File

@@ -16,7 +16,7 @@
| `CollectionProgress` | `TMap<FGameplayTag, int32>` | Collected count per collection type | | `CollectionProgress` | `TMap<FGameplayTag, int32>` | Collected count per collection type |
| `CollectionTargets` | `TMap<FGameplayTag, int32>` | Total items per collection | | `CollectionTargets` | `TMap<FGameplayTag, int32>` | Total items per collection |
| `bShowCollectibleNotifications` | `bool` | Toast on collectible pickup | | `bShowCollectibleNotifications` | `bool` | Toast on collectible pickup |
| `CompletionRewards` | `TMap<FGameplayTag, TArray<FPrimaryAssetId>>` | Items granted on collection completion | | `CompletionRewards` | `Map<Gameplay Tag, Array<Primary Asset Id>>` | Items granted on collection completion |
## 3. Functions ## 3. Functions

19
docs/blueprints/14-data-assets/118_DA_DataAssetArchitecture.md
View File

@@ -13,15 +13,26 @@ The Modular Game Framework uses `UDataAsset` (and subclass `UPrimaryDataAsset` w
### Conventions ### Conventions
- **Naming:** `DA_<Domain><Subtype>` — e.g., `DA_WeaponData`, `DA_AIProfile`, `DA_AtmosphereProfile` - **Naming:** `DA_<Domain><Subtype>` — e.g., `DA_WeaponData`, `DA_AIProfile`, `DA_AtmosphereProfile`
- **Storage:** All DA files live in `Content/DataAssets/<Domain>/` in-engine - **Storage:** All DA files live in `Content/DataAssets/<Domain>/` in-engine
- **Loading:** Use `UAssetManager` with `FPrimaryAssetType` and `FPrimaryAssetId` for async loading - **Parent Class:** `Primary Data Asset` (Blueprint class). Maps to C++ `UPrimaryDataAsset`.
- **Validation:** Each DA implements `ValidateData()` for editor-time data integrity checks - **Loading:** Use `Async Load Primary Asset` node with `Primary Asset Id` and `Primary Asset Type`
- **Gameplay Tags:** All DAs carry a `FGameplayTagContainer` for query and filtering - **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 ### 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 2. No DA may reference a runtime system; only other DAs
3. Circular DA references are prohibited — use `World Context Object` for runtime resolution 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]` 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<T>` | `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) ### Registered DA Types (Section 13 of Master)

28
docs/blueprints/14-data-assets/119_DA_EncounterData.md
View File

@@ -1,7 +1,7 @@
# DA_EncounterData — Data Asset # DA_EncounterData — Data Asset
**Parent Class:** `UDataAsset` **Parent Class:** `Primary Data Asset` (Blueprint: `PrimaryDataAsset`)
**Dependencies:** [`BPC_ProceduralEncounter`](../10-adaptive/70_BPC_ProceduralEncounter.md) **Dependencies:** [`BPC_ProceduralEncounter`](../10-adaptive/92_BPC_ProceduralEncounter.md)
**Purpose:** Defines procedural encounter configurations — enemy types, spawn rules, difficulty scaling, and encounter triggers. **Purpose:** Defines procedural encounter configurations — enemy types, spawn rules, difficulty scaling, and encounter triggers.
--- ---
@@ -10,18 +10,18 @@
| Field | Type | Description | | Field | Type | Description |
|-------|------|-------------| |-------|------|-------------|
| `EncounterTag` | `FGameplayTag` | Unique encounter identifier | | `EncounterTag` | `Gameplay Tag` | Unique encounter identifier |
| `EnemyArchetypes` | `TArray<FPrimaryAssetId>` | Allowed enemy DA_AIProfile references | | `EnemyArchetypes` | `Array<Primary Asset Id>` | Allowed enemy `DA_BehaviourVariant` references |
| `MinEnemies` | `int32` | Minimum spawn count | | `MinEnemies` | `Integer` | Minimum spawn count |
| `MaxEnemies` | `int32` | Maximum spawn count | | `MaxEnemies` | `Integer` | Maximum spawn count |
| `SpawnRadius` | `float` | Radius around trigger point (cm) | | `SpawnRadius` | `Float` | Radius around trigger point (cm) |
| `SpawnDelay` | `float` | Time between individual spawns | | `SpawnDelay` | `Float` | Time between individual spawns |
| `bTriggerOnOverlap` | `bool` | Auto-trigger on player overlap | | `bTriggerOnOverlap` | `Boolean` | Auto-trigger on player overlap |
| `bTriggerOnAlert` | `bool` | Trigger when alert level reaches threshold | | `bTriggerOnAlert` | `Boolean` | Trigger when alert level reaches threshold |
| `RequiredAlertLevel` | `float` | Alert threshold (0.0-1.0) | | `RequiredAlertLevel` | `Float` | Alert threshold (0.0-1.0) |
| `EncounterCooldown` | `float` | Min time between encounters | | `EncounterCooldown` | `Float` | Min time between encounters |
| `DifficultyScaling` | `UCurveFloat*` | Curve for scaling enemy count/strength by difficulty | | `DifficultyScaling` | `Curve Float` (Object Reference) | Curve for scaling enemy count/strength by difficulty |
| `NarrativePrerequisites` | `TArray<FGameplayTag>` | Narrative flags required | | `NarrativePrerequisites` | `Array<Gameplay Tag>` | Narrative flags required |
--- ---

22
docs/blueprints/14-data-assets/123_DA_ObjectiveData.md
View File

@@ -1,7 +1,7 @@
# DA_ObjectiveData — Data Asset # DA_ObjectiveData — Data Asset
**Parent Class:** `UDataAsset` **Parent Class:** `Primary Data Asset` (Blueprint: `PrimaryDataAsset`)
**Dependencies:** [`BPC_ObjectiveSystem`](../07-narrative/39_BPC_ObjectiveSystem.md), [`WBP_ObjectiveDisplay`](../06-ui/WBP_ObjectiveDisplay.md) **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. **Purpose:** Defines objective content — objective text, requirements, completion conditions, linked narrative flags, and reward data.
--- ---
@@ -10,16 +10,16 @@
| Field | Type | Description | | Field | Type | Description |
|-------|------|-------------| |-------|------|-------------|
| `ObjectiveTag` | `FGameplayTag` | Unique tag for this objective | | `ObjectiveTag` | `Gameplay Tag` | Unique tag for this objective |
| `ObjectiveText` | `FText` | Display text for HUD/journal | | `ObjectiveText` | `Text` | Display text for HUD/journal |
| `ObjectiveCategory` | `EObjectiveCategory` | Main, Side, Hidden, Tutorial | | `ObjectiveCategory` | `EObjectiveCategory` | Main, Side, Hidden, Tutorial |
| `PrerequisiteFlags` | `TArray<FGameplayTag>` | Narrative flags required before objective activates | | `PrerequisiteFlags` | `Array<Gameplay Tag>` | Narrative flags required before objective activates |
| `CompletionFlags` | `TArray<FGameplayTag>` | Flags set when objective completes | | `CompletionFlags` | `Array<Gameplay Tag>` | Flags set when objective completes |
| `bIsOptional` | `bool` | Objective can be skipped | | `bIsOptional` | `Boolean` | Objective can be skipped |
| `ObjectiveLocation` | `FVector` | World location for marker | | `ObjectiveLocation` | `Vector` | World location for marker |
| `RewardItems` | `TArray<FPrimaryAssetId>` | Items granted on completion | | `RewardItems` | `Array<Primary Asset Id>` | Items granted on completion |
| `RewardExperience` | `int32` | XP awarded | | `RewardExperience` | `Integer` | XP awarded |
| `LinkedEndingWeight` | `float` | Score contribution to ending evaluation | | `LinkedEndingWeight` | `Float` | Score contribution to ending evaluation |
--- ---