Scripting Examples
A collection of useful script snippets and examples.
If you are new to scripting we highly recommend reading the following guides first:
Below you will find a few basic scripts as a quick reference.
We also offer a lot of sample scenes and complete projects that you can download and use as a starting point:
Basic component
see scripting for all component events
Reference an Object from Unity
Reference and load an asset from Unity (Prefab or SceneAsset)
Reference and load scenes from Unity
::: tip Find a working example in our samples to download and try :::
Receive Clicks on Objects
Add this script to any object in your scene that you want to be clickable. Make sure to also have an ObjectRaycaster component in the parent hierarchy of that object.
test
Networking Clicks on Objects
Add this script to any object in your scene that you want to be clickable. Make sure to also have an ObjectRaycaster component in the parent hierarchy of that object.
The component will send the received click to all connected clients and will raise an event that you can then react to in your app. If you are using Unity or Blender you can simply assign functions to call to the onClick event to e.g. play an animation or hide objects.
Play Animation on click
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. @code ts twoslash
Create and invoke a UnityEvent
@code ts twoslash ::: 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 forum :::
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) @code ts twoslash
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: @code ts twoslash
In C# in any script: @code
::: 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
Display current time using a Coroutine
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
Switching src attribute
See live example on StackBlitz
Adding new postprocessing effects
Make sure to install npm i postprocessing in your web project. Then you can add new effects by deriving from PostProcessingEffect.
To use the effect add it to the same object as your Volume component.
Here is an example that wraps the Outline postprocessing effect. You can expose variables and settings as usual as any effect is also just a component in your three.js scene.
@code
Custom ParticleSystem Behaviour
Custom 2D Audio Component
This is an example how you could create your own audio component. For most usecases however you can use the core AudioSource component and don't have to write code.
Arbitrary external files
Use the FileReference type to load external files (e.g. a json file) @code ts twoslash
Last updated