Skip to main content

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" and clamp= on numeric props so the editor shows the right context and clamps in the Details panel.

Version control hygiene​

  • Commit your .tps sources.
  • You can commit generated C++ too (good for reviewing diffs), but consider .gitignore-ing TpsGenerated if 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.