Krotox Engine › Docs › Scripting API › Core & Lifecycle

Entity API: transforms, hierarchy & components

The Entity class in full: identity and validity, active state, local and world transforms, parents and children, getting, adding and removing components and scripts, finding entities by name and tag, and physics layers.

Your script is an Entity, so everything on this page is available directly inside a script (Translation, GetComponent<T>(), Destroy()), and on any other entity you hold a reference to (player.Translation).

Identity and validity

An Entity is a lightweight handle around a 64-bit ID. Holding one does not keep the entity alive.

Member	Type	Meaning
`ID`	`ulong`	The entity's UUID.
`Name`	`string`	The name shown in the Hierarchy (get and set). `Entity.Find` matches it.
`IsValid()` / `Exists`	`bool`	True while the entity is alive in the scene.
`Is2D`	`bool`	Whether the entity carries 2D components.

A destroyed entity leaves its ID behind. Check IsValid() before using an entity you did not create this frame, especially one stored in a field.

Active state

Active = false;                    // hide this entity and its children
bool own   = ActiveSelf;           // this entity's own flag (same as Active)
bool shown = ActiveInHierarchy;    // false if this or any parent is inactive

An inactive entity stops rendering, its UI stops receiving clicks, and its children are hidden too. Its scripts keep running, so a script can switch itself back on.

Transforms

Member	Type	Meaning
`Translation`	`Vector3`	Local position, relative to the parent.
`Rotation`	`Vector3`	Local Euler angles in radians. 2D rotation is `Rotation.Z`.
`Scale`	`Vector3`	Local scale.
`WorldPosition`, `WorldRotation`, `WorldScale`	`Vector3`	The world-space result after every parent (get and set).
`TransformPoint(Vector3)` / `InverseTransformPoint(Vector3)`	`Vector3`	A point from local to world space, and back.
`TransformDirection(Vector3)` / `InverseTransformDirection(Vector3)`	`Vector3`	A direction from local to world space, and back (no position; rotation and scale applied).

void OnUpdate(float ts)
{
    // Move right at 3 units per second
    Translation += new Vector3(3.0f * ts, 0, 0);

    // Spin at 90 degrees per second
    Rotation = new Vector3(0, 0, Rotation.Z + 90.0f * Mathf.Deg2Rad * ts);
}

Vector3 muzzle = TransformPoint(new Vector3(0.5f, 0, 0));       // a point on this entity, in world space
Vector3 ahead  = TransformDirection(Vector3.Right);             // this entity's local +X, in world space
Vector3 local  = InverseTransformPoint(target.WorldPosition);   // where the target is, seen from here
WorldPosition  = new Vector3(0, 2, 0);                          // place in world space; Translation is recomputed

Notes:

World values are computed when you ask, so moving a parent and reading a child's WorldPosition in the same OnUpdate gives the new position.
TransformDirection applies scale, so normalize the result if you need a unit vector.
During Play, physics writes the transform of a Dynamic Rigidbody 2D. To move such a body, set its velocity, apply forces, or teleport it with Rigidbody2DComponent.Position.

Parents and children

Member	Meaning
`Parent`	The parent entity, or `null` for a root (get and set; `null` detaches).
`SetParent(Entity parent)`	Reparent, keeping the local transform (the entity jumps to the same offset under the new parent).
`SetParent(Entity parent, bool worldPositionStays)`	With `true`, keeps the world pose instead: no jump.
`Children` / `GetChildren()`	Direct children (`IReadOnlyList<Entity>` / `Entity[]`).
`ChildCount`, `GetChild(int)`	Count, and a child by index.
`this[int]`, `this["Name"]`	Indexers: `this[0]`, `this["Weapon"]`. `null` when missing.
`FindChild(string name, bool recursive = false)`	A child by name, optionally searching the whole subtree.
`FindChildRecursive(string)`	Same as `FindChild(name, true)`.
`IsChildOf(Entity)`	True if the entity is any ancestor, not just the direct parent.
`SiblingIndex`, `SetAsFirstSibling()`, `SetAsLastSibling()`	Position among siblings. In UI, later siblings draw on top.

Entity weapon = this["Weapon"];
Entity muzzle = FindChild("Muzzle", recursive: true);

foreach (Entity child in Children)
    Log.Info(child.Name);

// An arrow sticks into what it hits, without jumping
void OnCollisionEnter2D(Collision2D c)
{
    GetComponent<Rigidbody2DComponent>().Enabled = false;
    SetParent(c.Collider, worldPositionStays: true);
}

Components

Member	Meaning
`GetComponent<T>()`	The component, or `null`.
`TryGetComponent<T>(out T c)`	Test and get in one step.
`HasComponent<T>()`	Whether it is there.
`AddComponent<T>()`	Add it (returns the existing one if already present).
`RemoveComponent<T>()`	Remove it.
`GetComponentInChildren<T>(bool includeInactive = false)`	Depth-first search of this entity and its descendants.
`GetComponentsInChildren<T>(bool includeInactive = false)`	Every match in the subtree.
`GetComponentInParent<T>()`	This entity or the nearest ancestor that has it.

if (TryGetComponent(out Rigidbody2DComponent body))
    body.GravityScale = 0.0f;

if (!HasComponent<SpriteRendererComponent>())
    AddComponent<SpriteRendererComponent>().Color = new Vector4(1, 0, 0, 1);

foreach (var sprite in GetComponentsInChildren<SpriteRendererComponent>())
    sprite.Color = new Vector4(1, 1, 1, 0.5f);

Every component has an Entity property pointing back at its owner (button.Entity.Active = false).

Cache components in OnAwake instead of calling GetComponent every frame.

Scripts on other entities

Member	Meaning
`As<T>()`	The script of type `T` on that entity, or `null`.
`AddScript<T>()`	Attach a script at run time (returns the existing one if attached).
`RemoveScript<T>()` / `RemoveScript()`	Remove a script.
`GetScriptInChildren<T>(bool includeInactive = false)` / `GetScriptsInChildren<T>(...)`	Find scripts in the subtree.

public override void OnTriggerEnter(Entity other)
{
    PlayerController player = other.As<PlayerController>();
    if (player != null)
        player.Heal(10);
}

Finding entities

Member	Meaning
`Entity.Find(string name)`	The first entity with that name, or `null`. (`FindEntityByName` inside a script.)
`Entity.FindAll(string name)`	Every entity with that name.
`Entity.FindWithTag(string tag)`	The first entity with the tag, or `null`.
`Entity.FindAllWithTag(string tag)`	Every entity with the tag.

Finding by name or tag searches the scene, so do it once (in OnCreate) and keep the result, rather than every frame.

Tags and layers

bool isPlayer = HasTag("Player");
AddTag("Invincible");
RemoveTag("Stunned");
Entity[] enemies = Entity.FindAllWithTag("Enemy");

Layer = LayerMask.NameToLayer("Projectiles");   // physics layer; applies when the body is next built
string layerName = LayerName;

Destroying

Destroy() destroys this entity and its children; Entity.Destroy(other) destroys another. It is deferred to the next safe point in the frame, so code later in the same callback can still read the entity. See Prefabs, scenes & saving.

Delayed calls and coroutines

Entities also run coroutines and delayed calls: StartCoroutine, StopCoroutine, StopAllCoroutines, Invoke, InvokeRepeating, CancelInvoke, IsInvoking. See Coroutines, Invoke & tweens.

Camera conversions

Any entity with a Camera component can convert between screen and world space: ScreenToWorldPoint, WorldToScreenPoint, ScreenToViewportPoint, ViewportToWorldPoint. The static Camera class does the same through the primary camera. See Sprites, animation, cameras & effects.