Skip to main content

FAQ & Troubleshooting

This page provides answers to frequently asked questions and solutions for common issues you may encounter when using FactsDB.

Common Issues​

Q: My "Value" pin on a Get Fact or Update Fact node is a gray wildcard. Why?

A: The node cannot determine the data type of the fact. This is almost always because the node's configuration in the Details panel is incomplete.

Solution:

  1. Select the node in your Blueprint graph.
  2. In the Details panel, ensure you have selected both a valid Schema For Type Resolution and a valid Fact To Access.
  3. Once both are set, the "Value" pin will automatically change to the correct data type. If it doesn't, right-click the node and select "Refresh Nodes".

Q: My Update Fact node isn't changing the value when I play.

A: This usually happens for one of three reasons, all related to authority and configuration.

Solutions:

  1. Check Network Authority: For replicated facts, updates can only be performed by the server. Make sure your Update Fact node is being called from a server context. Use an Has Authority switch node to route the logic correctly.
  2. Check Read-Only Status: The fact might be marked as read-only. Check the bIsReadOnly flag in the FFactDefinition row within its source UDataTable. You can also verify this in the FactsDB Debugger—read-only facts will have a lock icon next to them.
  3. Check for a Valid Context: Ensure the Context ID you are passing to the node is valid and that a UFactsComponent with that ID is currently registered and active in the world. Use the IsValid function on the Context ID struct and check the bSuccess result of the update operation.

Q: I try to Play-In-Editor (PIE), but it gets blocked by a "FactsDB Validation" error window.

A: This is an intentional safety feature. The system has detected a critical error in your data configuration that would likely cause crashes or major bugs at runtime.

Solution:

  • Do not ignore the window. The error message list tells you exactly what is wrong (e.g., a circular schema dependency, a duplicate fact tag, or a type mismatch).
  • Use the "Go to Asset" button next to each error. It will take you directly to the UDataTable or UDataAsset that contains the problem, allowing you to fix it quickly.
  • Once all errors are resolved, you will be able to start PIE.

Q: I can't edit a fact's value in the debugger's Details panel.

A: This is the same issue as the Update Fact node not working. Live editing follows the same rules as runtime updates.

  • You must be in PIE.
  • You must have network authority.
  • The fact cannot be defined as read-only. The Details panel will display a warning banner at the top explaining why editing is disabled.

Frequently Asked Questions​

Q: Can a Fact hold a UObject pointer (like a pointer to an Actor)?

A: No, and this is by design. FInstancedStruct (which is what FactsDB uses to store values) does not support holding direct UObject pointers. This restriction is beneficial because it prevents you from creating strong references that could complicate garbage collection and networking.

Best Practice: Instead of storing a direct pointer, store an identifier.

  • To reference another actor with a UFactsComponent, store its FFactContextID.
  • For other actors, store a FGameplayTag or FName that you can use with a manager system to look up the actor at runtime.

Q: What is the performance impact of using FactsDB?

A: The core system is designed to be highly performant.

  • Reading facts is very fast, typically an O(1) map lookup.
  • Writing facts is also fast, but it triggers delegates. The main performance consideration is the complexity of the logic that responds to those delegates.
  • The Debugger has a performance cost when open, especially with real-time updates and history tracking enabled. It should be closed or have these features disabled during performance-critical profiling.
  • Queries are evaluated on demand. A very complex, deeply nested query that is evaluated every frame could be slow. Use the Query Explorer's timing information to identify and optimize expensive queries.

Q: How do I decide what should be a Fact versus a normal Blueprint variable?

A: Use this checklist. A piece of data is a good candidate for a Fact if:

  • It needs to be accessed by multiple, unrelated systems. (e.g., Health is read by UI, AI, and damage systems).
  • You want designers to be able to easily tweak its default value. (e.g., base stats in a Data Table).
  • You want to listen for changes to it in an event-driven way.
  • It needs to be saved and loaded as part of a game state snapshot.
  • It needs to be efficiently replicated to clients.

A normal Blueprint variable is fine for data that is truly temporary or internal to a single Actor's logic.