Kroys.EngineScripting

C# Scripting API Wiki

This page documents the public scripting surface available to gameplay code today: lifecycle callbacks, serialized fields, entity handles, transforms, input, time, logging, asset references, scene spawning, and native-backed physics raycasts.

Quick Start

Scripts use Kroys.EngineScripting and usually System.Numerics for vectors and quaternions.

using Kroys.EngineScripting;
using System.Numerics;

[ScriptDisplayName("Gameplay/Keyboard Mover")]
public sealed class KeyboardMover : EntityScript
{
    [SerializeField]
    [Range(0.0f, 12.0f)]
    private float speed = 4.0f;

    protected override void OnUpdate(float deltaTime)
    {
        if (Input.IsKeyDown(KeyCode.W))
        {
            Transform.Position += Transform.Forward * speed * deltaTime;
        }

        if (Input.IsKeyDown(KeyCode.S))
        {
            Transform.Position -= Transform.Forward * speed * deltaTime;
        }
    }
}

EntityScript Lifecycle

Properties

Entity returns the owner entity.
Transform returns the owner transform wrapper.
Enabled gets or sets whether this script attachment is enabled.

Callbacks

OnCreate() runs when the managed instance is created.
OnStart() runs when the script starts.
OnEnable() and OnDisable() follow enabled-state changes.
OnUpdate(float deltaTime) runs during runtime updates.
OnDestroy() runs before the instance is destroyed.

Serialized Fields

Public fields are serialized automatically. Private fields need [SerializeField].

Category	Supported Types
Primitive	`bool`, integers, `float`, `double`, `string`, enums
Math	`Vector2`, `Vector3`, `Vector4`, `Quaternion`, `Color`
References	`EntityRef`, `AssetRef<MaterialAsset>`, `AssetRef<TextureAsset>`, `AssetRef<MeshAsset>`

Inspector Attributes

[SerializeField] exposes a private field.
[HideInInspector] keeps a serialized field hidden.
[ReadOnly] makes an Inspector field read-only.
[Range(min, max)] gives numeric fields slider limits.

Metadata Attributes

[ScriptDisplayName("Category/Name")] controls editor display.
[DefaultExecutionOrder(order)] sets script ordering metadata.
[FormerTypeName] and [FormerlySerializedAs] support migration.

Entities And Transforms

Entity

IsAlive checks whether the native entity still exists.
Name returns the entity name.
Transform returns a transform wrapper.
Destroy() destroys the entity.

Transform

Position, Rotation, and Scale are local transform values.
Forward, Right, and Up are derived from rotation.

Scene

Scene.Spawn(string name) creates a new entity in the active scene.

Input, Time, And Debug

Input

Input.IsKeyDown(KeyCode) checks whether a keyboard key is currently held.

Time

Time.DeltaTime returns seconds since the previous runtime update.
Time.FixedDeltaTime exposes the fixed timestep value.

Debug

Debug.Log(string)
Debug.LogWarning(string)
Debug.LogError(string)

Asset References

AssetRef<TAsset> stores a serialized reference to an engine asset and exposes AssetId and IsValid.

using Kroys.EngineScripting;

public sealed class AssetReferencePrinter : EntityScript
{
    [SerializeField]
    private AssetRef<MaterialAsset> material = default;

    protected override void OnCreate()
    {
        if (material.IsValid)
        {
            Debug.Log($"Material: {material.AssetId}");
        }
    }
}

Physics

Physics.Raycast queries the active native physics world and returns a RaycastHit on success.

Raycast Overloads

Raycast(origin, direction, distance, out hit)
Raycast(origin, direction, distance, out hit, debugDraw)
Raycast(origin, direction, distance, out hit, debugDrawDurationSeconds)
Raycast(origin, direction, distance, out hit, debugDraw, debugDrawDurationSeconds)

RaycastHit

Entity hit entity.
Point world-space hit point.
Normal world-space hit normal.
Distance distance from the ray origin.

Examples

Raycast With Debug Draw

using Kroys.EngineScripting;
using System.Numerics;

public sealed class RayProbe : EntityScript
{
    protected override void OnUpdate(float deltaTime)
    {
        Vector3 origin = Transform.Position + Vector3.UnitY;
        Vector3 direction = Transform.Forward;

        if (Physics.Raycast(origin, direction, 20.0f, out RaycastHit hit, true, 2.0f))
        {
            Debug.Log($"Hit {hit.Entity.Name} at {hit.Distance:0.00}m");
        }
    }
}

Spawn Runtime Entity

using Kroys.EngineScripting;
using System.Numerics;

public sealed class SpawnOnStart : EntityScript
{
    protected override void OnCreate()
    {
        Entity spawned = Scene.Spawn("Runtime Entity");
        spawned.Transform.Position = Transform.Position + new Vector3(0.0f, 1.0f, 0.0f);
        Debug.Log($"Spawned: {spawned.Name}");
    }
}

Current Limits

OnFixedUpdate and OnLateUpdate are present in the managed base class, but the native runtime currently invokes the main lifecycle and OnUpdate path.
Managed physics exposes raycasts today. Layer masks, trigger inclusion, overlaps, and sweeps are not exposed in the C# API yet.
The current input API is keyboard-focused through Input.IsKeyDown(KeyCode).