NexusScript basics & lifecycle¶

A NexusScript is a C#‑style class that extends NexusBehaviour. You write it as a .cs file in your project; the SDK compiles it with NexusVM and you assign the result to a NexusComponent on a GameObject.

using UnityEngine;
using NexusVM.Unity;

class DoorController : NexusBehaviour
{
    public float openAngle = 90f;     // public fields show up in the inspector
    public Transform door;

    protected override void Start()
    {
        Debug.Log("Door ready.");
    }

    void OnTriggerEnter(Collider other)
    {
        if (Player.IdOf(other.gameObject) != "")   // a player walked in
            door.localRotation = Quaternion.Euler(0, openAngle, 0);
    }
}

Lifecycle methods¶

The runtime calls these for you (define only the ones you need):

Method	When
`protected override void Awake()`	once, as the script loads
`protected override void Start()`	once, before the first frame it's active
`protected override void OnEnable()` / `OnDisable()`	when enabled / disabled
`protected override void Update()`	every frame
`protected override void FixedUpdate()`	every physics step
`protected override void LateUpdate()`	every frame, after Update
`protected override void OnDestroy()`	when removed
`void OnTriggerEnter/Stay/Exit(Collider other)`	physics trigger overlap
`void OnCollisionEnter/Stay/Exit(Collision c)`	physics collision

Two call styles

Engine lifecycle (Start, Update, …) is declared on NexusBehaviour, so you override it. Physics callbacks (OnTriggerEnter, …) are matched by name, so they're plain methods. Your own custom methods (action handlers, event callbacks like OnPlayerJoined) are also plain public methods.

Public fields → inspector¶

Any public field becomes an inspector slot on the NexusComponent — drag in scene references (a Transform, a Light, an array of NPCs) or set values. This is how you wire a script to your scene without hard‑coding names.

public Light lamp;
public GameObject[] targetNpcs;
public int maxScore = 10;

What you can use¶

Core C# — variables, if/for/while/do/foreach/switch, methods, class/struct/enum/interface, generics, arrays (incl. 2‑D and jagged), List/Dictionary/HashSet/Queue/Stack + LINQ, properties (incl. { get; set; }), try/catch/finally, lambdas + closures, delegate/event, yield iterators.
Modern C# conveniences — interpolated strings $"…", ?? / ?., is Type x patterns, switch expressions (x switch { 1 => "a", _ => "b" }), expression‑bodied members (int Area => w*h;, void Hi() => …;), nameof(x), digit separators (1_000), base.Method() / base.Field, string.Format/Join, int.Parse/.ToString().
Math — Mathf.* (Mathf.Abs, Mathf.Clamp, Mathf.Lerp, Mathf.PI, …). Math.* works too — it's aliased to Mathf, so Math.Abs/Math.Max/Math.PI compile (results are float). Plus full Vector2/3/4, Quaternion, Matrix4x4, Color, Rect, Bounds, and Random.
Unity value types — Vector3, Quaternion, Color, Transform, GameObject, Light, Collider, …
Debug.Log(...) for console output.
The platform APIs — Player.*, NPC.*/Self.*, Storage.*, HTTP.*, Json.*.

struct is a reference type here

NexusScript has no value types, so a struct behaves exactly like a class — reference semantics: assigning one struct to another shares the same object (no value‑copy). Use struct freely for little data bundles; just don't rely on struct copy‑on‑assignment.

Not everything from modern C#

A few conveniences aren't in the subset yet: tuples (a, b), when guards / type‑pattern case, params + optional/named arguments, typeof/default(T). Use the workarounds (an out param or small class/struct for multiple returns; overloads instead of optional args). async/await is replaced by coroutines.

What you can't (the sandbox)¶

NexusScript is deliberately limited so worlds are safe to run:

❌ No file system, no direct OS / process access.
❌ No reflection, no arbitrary .NET libraries.
❌ No raw sockets — use HTTP.* instead.

If something you need isn't reachable, that's usually on purpose — there's typically a safe API for it.

Helpers you'll use a lot¶

Json.FromJsonToDict(jsonString) — parse a JSON string into a dictionary (action params, event data).
GameObject.Find(name) — find a scene object by name.

→ Next: the Player API, or see real scripts in Examples.