Kaskade API reference

C# scripting in Kaskade

Start here to add a C# component to a project. The HTML API reference covers the public and protected script surface of Kaskade.Managed.API, including overloads, inherited documentation, engine bindings and the Unity compatibility types.

First component

When running the engine from source, build the managed host once with the .NET 10 SDK:

dotnet build managed/Kaskade.Managed.Host/Kaskade.Managed.Host.csproj -c Release

Open a Kaskade project in the editor, create Assets/Scripts/Spinner.cs, and add the component to an object with Add Component or by dropping the script onto it. Press Play to run it. The class name should match the file name for the editor's drag-and-drop workflow.

using Kaskade;

namespace Game;

[KaskadeComponent("0f6edc07-f2fe-40e7-b59c-99b982c27730")]
public sealed class Spinner : Behaviour
{
    [SerializeField, Range(0, 360)]
    private double degreesPerSecond = 90;

    protected override void Update(double deltaTime)
    {
        transform.Rotate(0, degreesPerSecond * deltaTime, 0);
    }
}

Use a new GUID for each component you author. Keeping the same GUID when the class is renamed allows the engine to recognize the existing component during reload. Components can also be discovered by class name without the attribute.

Project compilation and the inspector

A component authored in a scene is stored like this:

[[object.csharp]]
type = "Game.Spinner"
enabled = true

[object.csharp.fields]
degreesPerSecond = 90.0

Lifecycle and world access

Callback When to use it
Awake() Initialize an instance when its object is ready. OnReady() is the earlier lifecycle hook.
OnEnable(), OnDisable() Respond when the component or its object becomes active or inactive.
Start() Set up work that should begin before the first update.
FixedUpdate() Apply forces and perform physics-step work. Read the step interval from Time.fixedDeltaTime.
OnCollisionEnter/Stay/Exit(Collision) Handle solid contacts and inspect their contact points.
OnTriggerEnter/Stay/Exit(Collider) Handle occupants of a trigger volume.
Update(), Update(double) Read frame input and run game logic. The argument is the frame time in seconds.
LateUpdate(), LateUpdate(double) Follow objects after frame updates, for example with a chase camera.
OnGUI() Draw immediate-mode controls.
OnDestroy() Clean up resources owned by the instance.
OnReset() Handle reset to the authored defaults in the editor.
OnBeforeHotReload(), OnAfterHotReload(HotReloadContext) Handle a managed code generation swap.

Override one overload of each update callback you need. The familiar Unity-style message declarations such as void Update() and void OnTriggerEnter(Collider other) also work. See engine lifecycle for the underlying native phases.

Engine-backed operations run on the game thread inside a script callback. The host gives each callback a thread-bound frame token. Pure managed calculations can run elsewhere. Apply the results in a subsequent script callback when they need world access. Many writes are deferred until the current update phase ends. Script-side overlays provide same-frame reads for supported writes, such as transform changes.

A GameObject or engine component is a managed handle to a native instance. Engine object equality and the implicit boolean conversion account for destruction. Check an optional or stored reference before using it. A CLR reference test such as is null tests only the managed wrapper.

Coroutines and time

StartCoroutine runs an IEnumerator. Yield null for the next frame, WaitForSeconds for scaled time, WaitForSecondsRealtime for real time, WaitForFixedUpdate for a physics step, or WaitForEndOfFrame for the end of the frame. The scheduler also accepts WaitUntil, WaitWhile, nested enumerators and another Coroutine. Use StopCoroutine or StopAllCoroutines to cancel owned work. For a named delayed callback, use Invoke, InvokeRepeating and CancelInvoke.

using System.Collections;
using Kaskade;

public sealed class Beacon : Behaviour
{
    [SerializeField] private Light? lamp;

    protected override void OnEnable() => StartCoroutine(Blink());
    protected override void OnDisable() => StopAllCoroutines();

    private IEnumerator Blink()
    {
        while (lamp)
        {
            lamp!.intensity = lamp.intensity > 0 ? 0 : 4;
            yield return new WaitForSeconds(0.5);
        }
    }
}

Objects, transforms and scenes

Input, cameras and physics

Poll pressed, released or held state with Input.GetKeyDown, GetKeyUp or GetKey. Mouse buttons have matching methods. Use Cursor for lock state, Screen for window dimensions and Camera.main for the current main camera when one exists.

The following component picks a visible rigidbody under the cursor and applies one impulse during the next physics step. Attach it to an object in a scene with a camera and colliders.

using Kaskade;

public sealed class ClickImpulse : Behaviour
{
    private Rigidbody? target;
    private Vector3 direction;

    protected override void Update()
    {
        if (!Input.GetMouseButtonDown(MouseButton.Left) || Camera.main is not Camera camera)
            return;

        Ray ray = camera.ScreenPointToRay(Input.mousePosition);
        if (Physics.Raycast(ray, out RaycastHit hit, 50))
        {
            target = hit.collider?.GetComponent<Rigidbody>();
            direction = ray.direction;
        }
    }

    protected override void FixedUpdate()
    {
        if (target)
            target!.AddForce(direction * 5, ForceMode.Impulse);
        target = null;
    }
}

Physics also provides Linecast, sphere/box/capsule casts, overlaps and checks. LayerMask restricts which objects queries consider. Use CharacterController for basic character movement, PlayerController for the Source-style player controller, NavMesh and NavMeshAgent for pathfinding, and Vehicle for driving simulation.

UI, audio and rendering

Area Use
Immediate UI Call GUI for pixel rectangles and GUILayout for layout inside OnGUI. Use Ui or UiApi for the engine UI functions. See SDF UI.
Audio AudioSource plays a clip, a one-shot, or a spatial voice. Prefer an AudioClip Inspector field or AudioClip.Load for project-relative paths. Use AudioListener to position the listener.
Rendering Use MeshRenderer, Light, Camera, Animator and PlayableDirector for scene objects. Use MaterialPropertyBlock to set values on one renderer's material instance.
Script GPU work Shader, Material, RenderTexture, ComputeShader, ComputeBuffer and Graphics.Blit expose shader bindings and GPU commands. The DX11 backend implements the custom shader and compute path. Check support on the selected renderer before depending on a GPU operation.
Environment Weather exposes runtime environment controls. The generated binding classes expose additional engine commands.

Unity compatibility covers the types and members listed in the reference. For example, UnityEngine.InputSystem.Keyboard and Mouse wrap the engine's input snapshots, GUI.matrix only stores the value, and the current GUI.DrawTexture draws a filled rectangle. Use documented Kaskade behavior when porting a script.

Vehicles and networking

Use a Vehicle component on an authored vehicle object. Call SetControls(VehicleInput) to submit throttle, brake, clutch, steering, handbrake and starter together. Read VehicleSnapshot with TryGetSnapshot to get car and wheel values from the same physics step. The type reference covers tuning, gear selection, ignition, parking, tyres and wheel telemetry.

Network supports host/client connections, typed JSON messages, replicated state and player/object association. IsAuthority is true for the host and offline play. Use messages for events and Set/Get/Watch for state that late joiners should receive. Use small payloads and validate game rules on the authority.

using Kaskade;

public sealed class ReadyStatus : Behaviour
{
    protected override void OnEnable() => Network.On<string>("ready", OnPlayerReady);
    protected override void OnDisable() => Network.Off("ready", (System.Action<string?, NetworkPlayer?>)OnPlayerReady);

    public void AnnounceReady() => Network.Send("ready", gameObject.name, NetworkTarget.All);

    private void OnPlayerReady(string? name, NetworkPlayer? sender)
    {
        if (name is not null)
            Debug.Log($"{name} is ready (player {sender?.Id})");
    }
}

Generated engine bindings and Zito

The generated *Api classes expose engine calls from engine.zito. Prefer the typed gameplay surface when it provides the same operation. When a generated binding returns EngineValue, examine its Kind and use the matching projection, such as AsGameObject, AsVector3 or AsArray. A vector crossing the binding boundary is represented as an array of coordinates.

For C# calling a Zito component, the C# source generator consumes .zmeta metadata and emits proxies in Kaskade.Zito.Generated. Retrieve the generated proxy with gameObject.GetComponent<TProxy>() and check IsValid before calling its methods. The interop fixture shows the compiled pattern for a numeric method. The Zito integration guide describes script authoring on the Zito side.

IDE, debugger and tooling

The editor writes an IDE solution and project next to the opened game project. Use the Project panel's C# action or open a script from the Inspector. The generated project references the API assembly and the behaviour source generator. The API XML comments are available to Rider and other IDEs next to Kaskade.Managed.API.dll.

The runtime uses .NET 10 through nethost and hostfxr to start CoreCLR. The engine can use ~/.kaskade/dotnet10 or KASKADE_DOTNET_ROOT for a private installation. KASKADE_NETHOST_PATH overrides the exact nethost.dll path. To debug scripts, attach Rider's .NET Core debugger to kaskade_player.exe. Script builds emit portable PDBs.

The game DLL loads into a collectible assembly load context. The shared API stays in the default context, so behavioural type identity survives a managed generation swap. See runtime API for the engine-side API and handle model.

Regenerate the XML and HTML reference

Run from the repository root with the .NET 10 SDK:

dotnet run --project scripts/csharp-docs/CsharpDocs.csproj -c Release -- `
  scripts/csharp-docs/template.html docs/csharp/index.html

If you use the engine's private SDK, substitute its dotnet.exe for dotnet. The build emits managed/Kaskade.Managed.API/bin/Release/net10.0/Kaskade.Managed.API.xml for IDEs. It pairs that XML with the compiled declarations for the HTML, checking that the script API has documentation. Edit XML doc comments in the API sources and regenerate the HTML. For generated bindings, edit the SDK or its generator and regenerate the bindings first. Open docs/csharp/index.html directly in a browser. The type index, member search and permalink navigation work from a local checkout.

To run the managed compiler, engine-host and hot-reload validation on Windows:

powershell -File scripts/test_managed_scripting.ps1