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() {
// called every frame
}
}
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
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
import { Behaviour } from "@needle-tools/engine";
import { IPointerClickHandler, PointerEventData } from "@needle-tools/engine/engine-components/ui/PointerEvents";
export class ClickExample extends Behaviour implements IPointerClickHandler {
// Make sure to have an ObjectRaycaster component in the parent hierarchy
onPointerClick(_args: PointerEventData) {
console.log("Clicked", this.name);
}
}
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();
}
}
Declare a custom event type
import { Behaviour, EventList, GameObject, serializeable } from "@needle-tools/engine";
// 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 UnityEngine.Events.UnityEvent<string, UnityEngine.GameObject>
@serializeable(EventList)
myEvent: EventList;
// just for testing - could be when a button is clicked, etc.
start() {
this.myEvent.invoke("Hello", this.gameObject);
}
}
export class CustomEventReceiver extends Behaviour {
logStringAndObject(str : string, go : GameObject) {
console.log("From Event: ", str, go);
}
}
Example use: