Make Things Ring with Scriptable Items! [Copy & Pasteable Sample Code Included]

Cluster Creators Guide

Scriptable Item, which allows you to control gimmicks, etc. with JavaScript, can now play sound from scripts!

💡 All code is in Java Script

With this feature, you can also control sound in World Craft.

The following is a detailed explanation of the functionality.

Necessary Components to Make Things Ring Using Scripts

In order to play audio from a script, it is necessary to register an audio file using the “Item Audio Set List” component in addition to the Scriptable Item.

Let’s actually try it out.

• In the Inspector of the object with the Scriptable Item, add the Item Audio Set List component from Add Component.
• Once added, press the + button in the Item Audio Set List component, and in the “Audio Clip” section of the added item, select an audio file by clicking the ◎ button or dragging and dropping it.
• Give the “Id” a name that is easy to understand. In this example, “Audio1” is used.
• The script will call the audio file with the name you set in “Id”.
• If you want to loop the audio, tick “Loop”.

💡 If the added item shows only “Element 0” or the part of the name you set for Id, you can expand it by clicking on it.

⚠️ When using World Craft, the length limit of each audio file is 5 seconds, and the number of audio files is limited to 5.

Once the audio data has been set up, the next step is to actually play the sound with the script.

Ring on Click

First, let’s try to make it sound when clicked.

• After adding the appearance and collider to the item, enter the following code in Scriptable Item.

💡 In order for an item to be clickable, it must have a collider, either on the item itself or on its children.

const se = $.audio("Audio1");

$.onInteract(() => {
  se.play();
});

In the first line $.audio(“Audio1”);, the audio registered in the Item Audio Set List is loaded with the ID “Audio1”.

In $.onInteract, the action when the item is clicked is written.

Here, the play() function is executed on the loaded audio data to play the audio.

Let’s upload the file and check it out.

The sound is now played when the item is clicked.

Turn Sound On and Off Every Time You Click

The audio handled by the script can be stopped as well as played.
Let’s make it so that it sounds and stops with each click.

Rewrite the previous code as follows:

const se = $.audio("Audio1");


$.onInteract(() => {
  let playing = $.state.playing;
  if(playing == null) playing = false;

  if(playing) se.stop();
  else se.play();
  playing = !playing;
  
  $.state.playing = playing;
});

We rewrote the contents of $.onInteract.
First, $.state.playing is loaded, where a flag is stored to indicate whether it is currently playing or not. If it is playing, it is true; if not, it is false.
If it is not initialized, it is initialized to false in the next line.

The audio is then played or stopped according to the current state.
If playback is stopped, play() plays the audio, and if it is being played, stop() is called to stop the audio being played.
It then changes the flags according to the updated playback state.
Writing !playing returns false if the current value of playing is true, and true if it is false.

Finally, it stores the changed playing state flag in $.state.playing.
The value of the variable is not saved until it is written to $.state.

Once you have rewritten the script, upload it and check it out.
The audio will play and stop with each click.

Changing Volume

You can also change the audio playback volume with a script.
Try rewriting the previous script as follows:

const se = $.audio("Audio1");


$.onInteract(() => {
    let playing = $.state.playing;
    if(playing == null) playing = false;
 
    playing = !playing;
    if(playing) {
        se.volume = Math.random() * 2.5;
        se.play();
    }
    else se.stop();


    $.state.playing = playing;
});

A small addition is made before play().
The playback volume can be changed by changing the value of volume for the loaded audio.
The value of volume can be set in the range of 0.0 to 2.5.

Math.random() returns a random number (random value) in the range 0.0 to 1.0. Multiply this by 2.5 to convert it to a range of 0.0 to 2.5 and then set it to the value of volume, which will randomly change the volume each time it is played.

Let’s upload the file and check it.
As before, it will play and stop each time it is clicked, but the volume will change randomly each time it is played.

Change the position of the sound source

Earlier, the sound was played from the item’s position, but the position of the sound can be changed to any child object’s position.

• First, prepare a child object that will be the playback position. Add an empty object to the item’s children, name it “AudioPosition,” and move it to the desired position.

Once the child object has been added, rewrite the script as follows:

const se = $.audio("Audio1");
const audioPosition = $.subNode("AudioPosition");


$.onInteract(() => {
    let playing = $.state.playing;
    if(playing == null) playing = false;
 
    playing = !playing;
    if(playing) {
        se.attach(audioPosition);
        se.play();
    }
    else se.stop();


    $.state.playing = playing;
});

First, the $.subNode(“AudioPosition”) added in the second line retrieves the AudioPosition object added earlier.
When the object is passed to the loaded audio with attach(), the position of the sound source is changed to the position of that object.

When uploaded and checked, the sound is heard from the position where the AudioPosition was placed, not from the position of the item itself.

The ability to use audio in scripts not only expands the scope of world creation with the Cluster Creator Kit, but also makes it possible to create items with sound effects in crafted items.

By getting creative, you can create all sorts of items! Items that make sound when clicked, items that make sound when held or used, or even items that make sounds at certain times of the day…!
Let’s experiment with various ways of expression by making good use of sounds!