SCRIPTING API / Scripts and entities / Transform

Transform

Position, rotation and scale of one entity, local (relative to its parent) and in world space. A Transform is a handle, not a copy: reading a property asks the engine, writing one moves the entity at once. Vectors and quaternions are System.Numerics types; forward is -Z, right is +X, up is +Y.

Kindstruct

NamespaceKroys.EngineScripting

Members20

SourceTransform.cs

EXAMPLE

In a script

In OnFixedUpdate read WorldPosition (the exact simulation pose); in OnUpdate and OnLateUpdate read InterpolatedPosition for anything visual, because characters and bodies move in fixed steps. Writes are always exact.

Core.cs

public sealed class Hover : EntityScript
{
    public float Height = 0.25f;
    public float Speed = 2.0f;
    private Vector3 start;
    private float time;

    protected override void OnStart() => start = Transform.WorldPosition;

    protected override void OnUpdate(float deltaTime)
    {
        time += deltaTime;
        Transform transform = Transform;   // a handle: writes go straight to the entity
        transform.WorldPosition = start + Vector3.UnitY * MathF.Sin(time * Speed) * Height;
        transform.WorldRotation = Quaternion.CreateFromAxisAngle(Vector3.UnitY, time);
    }
}

REFERENCE

Members

Properties

#public Vector3 Position { get; set; }

Gets or sets the entity local position. This is the same value shown in the local transform inspector.

property

#public Quaternion Rotation { get; set; }

Gets or sets the entity local rotation. This is the same value shown in the local transform inspector.

property

#public Vector3 Scale { get; set; }

Gets or sets the entity local scale. This is the same value shown in the local transform inspector.

property

#public Vector3 LocalPosition { get; set; }

Gets or sets the position relative to the parent entity.

property

#public Quaternion LocalRotation { get; set; }

Gets or sets the rotation relative to the parent entity.

property

#public Vector3 LocalScale { get; set; }

Gets or sets the scale relative to the parent entity.

property

#public Vector3 WorldPosition { get; set; }

Gets or sets the position in world space.

property

#public Quaternion WorldRotation { get; set; }

Gets or sets the rotation in world space.

property

#public Vector3 InterpolatedPosition { get; }

World position as rendered this frame. Characters, rigid bodies and FixedUpdate scripts move entities at the fixed step; read from Update or LateUpdate, WorldPosition repeats between steps and then jumps, so a speed measured from it judders. This value is interpolated between the last two fixed steps exactly as the renderer draws the entity (up to one fixed step behind the simulation), so it moves smoothly at any frame rate. Inside FixedUpdate, for an entity at rest, one moved outside the fixed step, or without a renderer (dedicated server, headless) it equals WorldPosition. Read-only: write WorldPosition; keep gameplay decisions on the exact pose in FixedUpdate.

property

#public Quaternion InterpolatedRotation { get; }

World rotation as rendered this frame; see InterpolatedPosition.

property

#public Vector3 WorldScale { get; set; }

Gets or sets the scale in world space.

property

#public Vector3 Forward { get; }

Gets the entity forward direction derived from its current rotation.

property

#public Vector3 Right { get; }

Gets the entity right direction derived from its current rotation.

property

#public Vector3 Up { get; }

Gets the entity up direction derived from its current rotation.

property

#public Vector3 WorldForward { get; }

Gets the entity forward direction derived from its current world rotation.

property

#public Vector3 WorldRight { get; }

Gets the entity right direction derived from its current world rotation.

property

#public Vector3 WorldUp { get; }

Gets the entity up direction derived from its current world rotation.

property

#public Entity Parent { get; }

Gets the parent entity for this transform's entity.

property

Methods

#public static Entity GetParent(Entity entity)

Returns the parent entity, or Entity.Invalid when the entity has no parent.

methodstatic

#public static void SetParent(Entity entity, Entity parent)

Parents the entity under parent. Pass Entity.Invalid to unparent.

methodstatic

Signatures

public Vector3 Position { get; set; }
public Quaternion Rotation { get; set; }
public Vector3 Scale { get; set; }
public Vector3 LocalPosition { get; set; }
public Quaternion LocalRotation { get; set; }
public Vector3 LocalScale { get; set; }
public Vector3 WorldPosition { get; set; }
public Quaternion WorldRotation { get; set; }
public Vector3 InterpolatedPosition { get; }
public Quaternion InterpolatedRotation { get; }
public Vector3 WorldScale { get; set; }
public Vector3 Forward { get; }
public Vector3 Right { get; }
public Vector3 Up { get; }
public Vector3 WorldForward { get; }
public Vector3 WorldRight { get; }
public Vector3 WorldUp { get; }
public Entity Parent { get; }
public static Entity GetParent(Entity entity)
public static void SetParent(Entity entity, Entity parent)

KroysEngine 0.1.0 documentation, built from the engine repository by Tools/BuildDocsSite.py.