Best practices
Guidelines for keeping your TPScript and its generated C++ healthy as a project grows.
Pick a style per file
High-level (class x extends actor) and low-level (uclass AX : AActor) are both first-class, but mixing them within one file is harder to read. Choose high-level for digging into a mechanic quickly and low-level when you need exact C++ types or networking specifiers.
Match the API macro
Always keep meta: api=<MODULE>_API in sync with the module you're generating into:
- Module
TpsGenerated→TPSGENERATED_API - Module
TpscriptKit→TPSCRIPTKIT_API - Module
Examples→EXAMPLES_API
A mismatch shows up as an unresolved symbol when another module consumes the class.
One mechanic per file
Regen granularity works best when each .tps file is one self-contained mechanic. This makes regen this file fast, diffs small, and file-status markers ([NEW]/[UPD]/[==]/[DEL]) meaningful.
Prefer lifecycle overrides over Tick
For logic that doesn't need to run every frame, use timers instead of Tick (see Recipes: Timer instead of Tick). It's cheap to leave bCanEverTick off.
Expose deliberately
Only add BlueprintReadWrite / BlueprintCallable / BlueprintAssignable to what Blueprints actually need. Over-exposing surfaces clutter and makes the API harder to reason about. Use internal/field private for implementation details.
Use data structs for parameters
Group related data into ustruct values (like FWeaponStats) instead of piling up scalar props. It reads better and serializes as a unit.
Keep default values in .tps
Put default values in default= and let the emitter write C++ initializers. Avoid hand-editing generated headers, or your defaults will drift on the next regen.
Don't hand-edit generated C++
Generated files are recreated on every regen. If you need to customize, add the code in the .tps body (sugar + raw C++) or extend the generated class from a hand-written subclass.
Comments and units
- Use
//comments generously - they're preserved. - Use
units="seconds"andclamp=on numeric props so the editor shows the right context and clamps in the Details panel.
Version control hygiene
- Commit your
.tpssources. - You can commit generated C++ too (good for reviewing diffs), but consider
.gitignore-ingTpsGeneratedif you always regenerate. Pick one and be consistent.
Example
uclass AHero : ACharacter meta: api=MYGAME_API
{
// tuning - exposed deliberately
prop public float MaxHealth EditAnywhere BlueprintReadOnly category="Hero" default=100.0f clamp=[1.0f, 1000.0f] units="hp"
// implementation detail
field private float Health;
method public virtual void BeginPlay() override {
Super::BeginPlay();
Health = MaxHealth;
}
}
Next: Recipes & patterns.