SCRIPTING API / Scripts and entities / EntityScript

EntityScript

The base class of game scripts. Attach a script to an entity in the Inspector; the engine creates one instance per attachment and calls its methods: OnStart once, OnFixedUpdate every fixed step, OnUpdate and OnLateUpdate every frame, and the collision, trigger, animation and network callbacks as they happen.

Kindclass

NamespaceKroys.EngineScripting

Members21

SourceEntityScript.cs

EXAMPLE

In a script

Public fields (and private ones marked SerializeFieldAttribute) of supported types appear in the Inspector and are saved with the scene. The same script runs in the editor's Play mode, the shipped game and, unless it is marked ClientOnlyAttribute, on the dedicated server.

Core.cs

// A script is a class derived from EntityScript, attached to an entity in the Inspector.
// Public fields appear in the Inspector and are saved with the scene.
public sealed class Collectible : EntityScript
{
    [Range(0.0f, 10.0f)]
    public float SpinSpeed = 2.0f;
    public int Points = 10;

    protected override void OnStart()
    {
        Debug.Log($"{Entity.Name} is worth {Points} points");
    }

    protected override void OnUpdate(float deltaTime)
    {
        // Visual only, so every frame is fine.
        Transform transform = Transform;
        transform.Rotation *= Quaternion.CreateFromAxisAngle(Vector3.UnitY, SpinSpeed * deltaTime);
    }

    protected override void OnTriggerEnter(Entity other)
    {
        if (!CharacterController.Has(other)) return;   // only characters collect it
        Debug.Log($"{other.Name} collected {Entity.Name}");
        Entity.Destroy();
    }
}

REFERENCE

Members

Properties

#public Entity Entity { get; }

Gets the entity that owns this script instance.

property

#public Transform Transform { get; }

Gets the owner entity transform.

property

#public bool Enabled { get; set; }

Gets or sets whether this script attachment is enabled.

property

Methods

#protected Coroutine StartCoroutine(IEnumerator routine)

Starts a coroutine owned by this script. The routine runs immediately up to its first yield; after that it continues when its wait is over (null: next frame; WaitForSeconds, WaitForFixedUpdate, WaitForLateUpdate). It pauses while the script is disabled and stops when the entity is destroyed.

routine: A call of a method that returns IEnumerator, for example StartCoroutine(Cycle()).

returns: The coroutine, for StopCoroutine and IsRunning.

methodprotected

#protected void StopCoroutine(Coroutine coroutine)

Stops a coroutine of this script; it never continues. Stopping one that already finished does nothing.

coroutine: The handle StartCoroutine returned.

methodprotected

#protected void StopAllCoroutines()

Stops every coroutine this script started, for example in OnDisable before OnEnable starts new ones.

methodprotected

Callbacks you override

#protected virtual void OnCreate()

Called when the managed script instance is created.

callbackprotected

#protected virtual void OnStart()

Called when the script starts running.

callbackprotected

#protected virtual void OnEnable()

Called when the script becomes enabled.

callbackprotected

#protected virtual void OnDisable()

Called when the script becomes disabled.

callbackprotected

#protected virtual void OnUpdate(float deltaTime)

Called once per runtime update.

deltaTime: Time in seconds since the previous update.

callbackprotected

#protected virtual void OnFixedUpdate(float fixedDeltaTime)

Called once per fixed runtime step before physics simulation.

fixedDeltaTime: Fixed timestep duration in seconds.

callbackprotected

#protected virtual void OnLateUpdate(float deltaTime)

Called once per runtime frame after regular updates and before rendering.

deltaTime: Time in seconds since the previous update.

callbackprotected

#protected virtual void OnAnimationEvent(AnimationEvent animationEvent)

Called immediately when this entity's animator crosses an animation event marker.

animationEvent: Animation event marker data.

callbackprotected

#protected virtual void OnNetworkMessage(NetworkMessage message)

Called when a custom network message is available for the active world. Server scripts receive client-to-server messages. Client scripts receive server-to-client messages.

message: Custom network message data.

callbackprotected

#protected virtual void OnCollisionEnter(Collision collision)

Called after the fixed step in which this entity's body started touching another body.

collision: The other entity and the contact.

callbackprotected

#protected virtual void OnCollisionStay(Collision collision)

Called after every fixed step in which this entity's awake body keeps touching another body.

collision: The other entity and the contact.

callbackprotected

#protected virtual void OnCollisionExit(Collision collision)

Called after the fixed step in which this entity's body stopped touching another body (or one of them was removed). Bodies that fall asleep while touching stay in contact.

collision: The other entity and the last known contact.

callbackprotected

#protected virtual void OnTriggerEnter(Entity other)

Called when another body enters this entity's trigger collider, or when this entity's body enters a trigger.

other: The other entity.

callbackprotected

#protected virtual void OnTriggerExit(Entity other)

Called when another body leaves this entity's trigger collider, or when this entity's body leaves a trigger.

other: The other entity.

callbackprotected

#protected virtual void OnDestroy()

Called before the managed script instance is destroyed.

callbackprotected

Signatures

public Entity Entity { get; }
public Transform Transform { get; }
public bool Enabled { get; set; }
protected virtual void OnCreate()
protected virtual void OnStart()
protected virtual void OnEnable()
protected virtual void OnDisable()
protected virtual void OnUpdate(float deltaTime)
protected virtual void OnFixedUpdate(float fixedDeltaTime)
protected virtual void OnLateUpdate(float deltaTime)
protected virtual void OnAnimationEvent(AnimationEvent animationEvent)
protected virtual void OnNetworkMessage(NetworkMessage message)
protected virtual void OnCollisionEnter(Collision collision)
protected virtual void OnCollisionStay(Collision collision)
protected virtual void OnCollisionExit(Collision collision)
protected virtual void OnTriggerEnter(Entity other)
protected virtual void OnTriggerExit(Entity other)
protected Coroutine StartCoroutine(IEnumerator routine)
protected void StopCoroutine(Coroutine coroutine)
protected void StopAllCoroutines()
protected virtual void OnDestroy()

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