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
- The player discovers project
.csfiles and compiles them using Roslyn. Hidden folders and build output such asbin/andobj/are skipped. The managed game DLL and portable PDB are emitted under the project's.kaskade/csharp/directory. Fix errors reported aspath(line,column): error CSxxxx: message. - Public fields and private fields marked
[SerializeField]appear in the Inspector when their type is supported. Common choices are primitive values, enums, vectors, quaternions, colors, scene object references, and asset-backed values such asAudioClip.Range,Tooltip,Header,Space,HideInInspectorandAssetcontrol the Inspector presentation. - Object references persist as scene hierarchy paths. Drag a scene object onto a field of type
GameObjectorTransform.[Asset]marks a string as a project asset path. - Saving a script in the editor recompiles it. During a structural reload, supported state is
copied to a new managed object while the native object stays in the scene. Use
[FormerlySerializedAs("oldName")]when renaming a stored field andOnBeforeHotReload/OnAfterHotReloadto reconcile script-owned state. A compilation error leaves the running generation in place. - Standalone exports of projects with C# carry the managed host in
managed/and a private .NET runtime indotnet/. See the Windows Build SDK.
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
gameObjectandtransformare the attached object and its transform. UseGetComponent<T>,TryGetComponent<T>or hierarchy variants for lookups.AddComponent<T>accepts recognized engine components and project behaviours.- Create objects with
new GameObject("Name")or clone a scene object or prefab withInstantiate. A clone's handle is available immediately. Its native creation and component initialization participate in the deferred update flow.Destroysupports a delay. Transform.positionandrotationare world-space.localPosition,localRotationandlocalScaleare relative to the parent. UseSetParentto choose whether to preserve the world transform, and theTransformPoint,TransformDirectionandTransformVectorfamilies for coordinate conversion.- Forward is −Z and up is +Y. Euler inputs use degrees and compose X, then Y, then Z. Screen coordinates start at the top left and use window pixels.
SceneManager.LoadScenetakes a scene path.SceneManager.GetActiveSceneexposesGetRootGameObjects.DontDestroyOnLoadmarks a scene object to persist across loads. UsePlayerPrefsfor small persistent values such as user preferences.
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
Kaskade
API reference