Script Examples
Basic component
import { Behaviour, serializable } from "@needle-tools/engine"
import { Object3D } from "three"
export class MyComponent extends Behaviour {
@serializable(Object3D)
myObjectReference?: Object3D;
start() {
console.log("Hello world", this);
}
update() {
this.gameObject.rotateY(this.context.time.deltaTime);
}
}
see scripting for all component events
Reference an Object from Unity
import { Behaviour, serializable } from "@needle-tools/engine";
import { Object3D } from "three"
export class MyClass extends Behaviour {
// this will be a "Transform" field in Unity
@serializable(Object3D)
myObjectReference: Object3D | null = null;
// this will be a "Transform" array field in Unity
// Note that the @serializable decorator contains the array content type! (Object3D and not Object3D[])
@serializable(Object3D)
myObjectReferenceList: Object3D[] | null = null;
}
Reference and load an asset from Unity (Prefab or SceneAsset)
import { Behaviour, serializable, AssetReference } from "@needle-tools/engine";
export class MyClass extends Behaviour {
// if you export a prefab or scene as a reference from Unity you'll get a path to that asset
// which you can de-serialize to AssetReference for convenient loading
@serializable(AssetReference)
myPrefab?: AssetReference;
async start() {
// directly instantiate
const myInstance = await this.myPrefab?.instantiate();
// you can also just load and instantiate later
// const myInstance = await this.myPrefab.loadAssetAsync();
// this.gameObject.add(myInstance)
// this is useful if you know that you want to load this asset only once because it will not create a copy
// since ``instantiate()`` does create a copy of the asset after loading it
}
}
Reference and load scenes from Unity
TIP
Find a working example in our samples to download and try
import { Behaviour, serializable, AssetReference } from "@needle-tools/engine";
export class LoadingScenes extends Behaviour {
// tell the component compiler that we want to reference an array of SceneAssets
// @type UnityEditor.SceneAsset[]
@serializable(AssetReference)
myScenes?: AssetReference[];
async awake() {
if (!this.myScenes) {
return;
}
for (const scene of this.myScenes) {
// check if it is assigned in unity
if(!scene) continue;
// load the scene once
const myScene = await scene.loadAssetAsync();
// add it to the threejs scene
this.gameObject.add(myScene);
// of course you can always just load one at a time
// and remove it from the scene when you want
// myScene.removeFromParent();
// this is the same as scene.asset.removeFromParent()
}
}
onDestroy(): void {
if (!this.myScenes) return;
for (const scene of this.myScenes) {
scene?.unload();
}
}
}
Receive Clicks on Objects
TIP
Make sure you have an ObjectRaycaster component in your parent hierarchy (or on the object that should receive clicks)
import { Behaviour, IPointerClickHandler, PointerEventData, showBalloonMessage } from "@needle-tools/engine";
export class ClickExample extends Behaviour implements IPointerClickHandler {
// Make sure to have an ObjectRaycaster component in the parent hierarchy
onPointerClick(_args: PointerEventData) {
showBalloonMessage("Clicked " + this.name);
}
}
Play Animation on click
import { Behaviour, serializable, Animation, IPointerClickHandler, PointerEventData } from "@needle-tools/engine";
export class PlayAnimationOnClick extends Behaviour implements IPointerClickHandler {
@serializable(Animation)
animation?: Animation;
awake() {
if (this.animation) {
this.animation.playAutomatically = false;
this.animation.loop = false;
}
}
onPointerClick(_args: PointerEventData) {
if (this.animation) {
this.animation.play();
}
}
}
Reference an Animation Clip
This can be useful if you want to run your custom animation logic.
You can also export an array of clips.
import { Behaviour, serializable } from "@needle-tools/engine";
import { AnimationClip } from "three"
export class ExportAnimationClip extends Behaviour {
@serializable(AnimationClip)
animation?: AnimationClip;
awake() {
console.log("My referenced animation clip", this.animation);
}
}
Create and invoke a UnityEvent
import { Behaviour, serializable, EventList } from "@needle-tools/engine"
export class MyComponent extends Behaviour {
@serializable(EventList)
myEvent? : EventList;
start() {
this.myEvent?.invoke();
}
}
TIP
EventList events are also invoked on the component level. This means you can also subscribe to the event declared above using myComponent.addEventListener("my-event", evt => {...})
as well.
This is an experimental feature: please provide feedback in our discord
Declare a custom event type
This is useful for when you want to expose an event to Unity or Blender with some custom arguments (like a string)
import { Behaviour, serializable, EventList } from "@needle-tools/engine";
import { Object3D } from "three";
/*
Make sure to have a c# file in your project with the following content:
using UnityEngine;
using UnityEngine.Events;
[System.Serializable]
public class MyCustomUnityEvent : UnityEvent<string>
{
}
Unity documentation about custom events:
https://docs.unity3d.com/ScriptReference/Events.UnityEvent_2.html
*/
// Documentation → https://docs.needle.tools/scripting
export class CustomEventCaller extends Behaviour {
// The next line is not just a comment, it defines
// a specific type for the component generator to use.
//@type MyCustomUnityEvent
@serializable(EventList)
myEvent!: EventList;
// just for testing - could be when a button is clicked, etc.
start() {
this.myEvent.invoke("Hello");
}
}
export class CustomEventReceiver extends Behaviour {
logStringAndObject(str: string) {
console.log("From Event: ", str);
}
}
Example use:
Use nested objects and serialization
You can nest objects and their data. With properly matching @serializable(SomeType)
decorators, the data will be serialized and deserialized into the correct types automatically.
In your typescript component:
import { Behaviour, serializable } from "@needle-tools/engine";
// Documentation → https://docs.needle.tools/scripting
class CustomSubData {
@serializable()
subString: string = "";
@serializable()
subNumber: number = 0;
}
class CustomData {
@serializable()
myStringField: string = "";
@serializable()
myNumberField: number = 0;
@serializable()
myBooleanField: boolean = false;
@serializable(CustomSubData)
subData: CustomSubData | undefined = undefined;
someMethod() {
console.log("My string is " + this.myStringField, "my sub data", this.subData)
}
}
export class SerializedDataSample extends Behaviour {
@serializable(CustomData)
myData: CustomData | undefined;
onEnable() {
console.log(this.myData);
this.myData?.someMethod();
}
}
In C# in any script:
using System;
[Serializable]
public class CustomSubData
{
public string subString;
public float subNumber;
}
[Serializable]
public class CustomData
{
public string myStringField;
public float myNumberField;
public bool myBooleanField;
public CustomSubData subData;
}
TIP
Without the correct type decorators, you will still get the data, but just as a plain object. This is useful when you're porting components, as you'll have access to all data and can add types as required.
Use Web APIs
TIP
Keep in mind that you still have access to all web apis and npm packages!
That's the beauty of Needle Engine if we're allowed to say this here 😊
Display current location
import { Behaviour, showBalloonMessage } from "@needle-tools/engine";
export class WhereAmI extends Behaviour {
start() {
navigator.geolocation.getCurrentPosition((position) => {
console.log("Navigator response:", position);
const latlong = position.coords.latitude + ", " + position.coords.longitude;
showBalloonMessage("You are at\nLatLong " + latlong);
});
}
}
Display current time using a Coroutine
import { Behaviour, Text, serializable, WaitForSeconds } from "@needle-tools/engine";
export class DisplayTime extends Behaviour {
@serializable(Text)
text?: Text;
onEnable(): void {
this.startCoroutine(this.updateTime())
}
private *updateTime() {
while (true) {
if (this.text) {
this.text.text = new Date().toLocaleTimeString();
console.log(this.text.text)
}
yield WaitForSeconds(1)
}
};
}
Change custom shader property
Assuming you have a custom shader with a property name _Speed
that is a float value this is how you would change it from a script.
You can find a live example to download in our samples.
import { Behaviour, serializable } from "@needle-tools/engine";
import { Material } from "three";
declare type MyCustomShaderMaterial = Material & {
_Speed: number;
};
export class IncreaseShaderSpeedOverTime extends Behaviour {
//@type UnityEngine.Material
@serializable(Material)
myMaterial?: MyCustomShaderMaterial;
update() {
if (this.myMaterial) {
this.myMaterial._Speed *= 1 + this.context.time.deltaTime;
if(this.myMaterial._Speed > 1) this.myMaterial._Speed = .0005;
}
}
}
Switching src attribute
See live example on StackBlitz