Skip to content

Tutorial_EN.md

Latest commit

 

History

History
296 lines (192 loc) · 15.9 KB

Tutorial_EN.md

File metadata and controls

296 lines (192 loc) · 15.9 KB

LUIDA Implementation Template Tutorial

This tutorial guides you through implementing an experiment on LUIDA using this implementation template, by building a simple experiment step by step.

Overview of Using This Implementation Template

  1. Installation, account creation, and learning about CCK
  2. Create a new experiment on the LUIDA Web Console and fill in the required information
  3. Initial setup of this implementation template (Unity)
  4. Configure data collection on in-scene objects
  5. Test locally (in Unity Editor) & preparation before uploading
  6. Upload to cluster as a world and verify operation
  7. Final settings on LUIDA Web Console (World ID registration and avatar settings)
  8. Wait for publication

Prerequisites: Installation, Account Creation, and Learning CCK

Before starting this tutorial, we recommend learning the following basics:

Also, please complete the following preparations before starting the tutorial:

  1. Create a cluster account
  2. Install the required version of Unity for cluster
  3. Log in to the LUIDA Web Console for the first time and submit an approval request. After submitting the request, please contact the administrator (y.hu@cluster.mu).

0. Experiment Plan for This Tutorial

In this experiment, we will examine the priming effect. Participants first watch a randomly selected video — either "an elderly person walking" or "a young person running." After watching the video, two bridges appear: one that looks safe and one that looks dangerous. The participant walks across one of the bridges. This experiment examines whether the content of the video influences the participant's choice of bridge.

  • Experiment procedure
    • Start -> Demographics questionnaire -> Watch video (randomly selected) -> Choose a bridge -> End
  • Recorded data
    • Which video was shown (isElderVideo: true / false)
    • Which bridge was crossed (isSafeRoad: true / false)
  • Questionnaire
    • Demographics (Age)
スクリーンショット 2026-02-12 022027

1. Register Experiment Information on Web Console

Follow these steps to register and configure
  1. Open the LUIDA Web Console.
  2. Create a new experiment: Click "+New Experiment" and register the basic experiment information with the following values:
    1. Title: Priming Effect Experiment
    2. Participation requirements: (optional)
    3. Reward: 0
    4. Image URL: Any string (e.g., https://example.com/image.png)
    5. World ID: Leave blank for now
    6. Room capacity: 1
    7. Status: Testing
New Experiment Button Experiment Registration Form
New experiment button Registration form
  1. Navigate to experiment details page: Once the experiment is registered, click on that experiment's row from the home page to access its details page. Verify the information you just registered.
  2. Create a questionnaire: Scroll down and perform the following operations in the questionnaire registration form:
    1. Click "Add Questionnaire" button -> Do not select a template, enter the title as Demographics -> Click "Add" button
    2. Click the "Question List" button for the added questionnaire and add the following question:
      • Title: Age, Question Type: Text Input, Required: Yes
LUIDA-sample-questionnaire-configuration
  1. Copy experiment ID: Copy the "Experiment ID" displayed at the top of the experiment details page. This ID will be used later in the Unity project. Experiment ID location

2. Download and Initial Setup of Implementation Template (Unity)

Follow these steps to register and configure

 *Some of these steps will be automated in the future. For now, please complete all steps.

  1. Download the latest release of the implementation template.

  2. Open the downloaded Unity project from Unity Hub. Errors may appear in the console when opening the project, but ignore them first and import the following required packages into Unity:

  3. Open the sample scene Assets/_Experiment_/Scenes/Sample/Priming_incomplete.unity and press the Play button in the Unity Editor to get a feel for the scene.

  4. After reviewing the scene, go to LUIDA > Scene > Duplicate current scene from Unity's menu bar. In the dialog that appears, enter your own name to create a new scene. You will work on this new scene from now on.

    スクリーンショット 2026-02-12 023657 スクリーンショット 2026-02-12 023710

  5. Next, link your cluster account to this Unity project. The procedure is as follows (see the image for reference):

    1. From the Unity menu bar, open the LUIDA > Configure experiment identifiers window.
    2. Click the Create Access Token button to open the cluster access token creation page in your web browser.
    3. Click the Create Token button, and then copy and paste the displayed token into the Access Token field in the Configure experiment identifiers window that you just opened in Unity.

    cluster access token registration procedure

  6. With the identifiers configuring window still open, enter the Experiment ID you copied from the web console earlier into the Experiment ID field.

    Luida Editor Experiment ID registration screen

  7. If the Verify Token is not generated yet, click the Generate a new verify token button.

    Verify Token generation

  8. Close the identifiers configuring window.

3. Complete the Experiment (Configure Data Collection)

In the new scene, you will configure components on in-scene objects so that data can be collected and uploaded to LUIDA's backend.

Configure StartVideoButton

Select the in-scene game object StartVideoButton and find its Global Trigger Lottery component.

  1. Click the + button twice to add two choices.
  2. Configure each choice with the following triggers:
    • Choice 1: Global trigger, Key = isElderVideo, Value Type = Bool, Value = true
    • Choice 2: Global trigger, Key = isElderVideo, Value Type = Bool, Value = false

This makes the video selection random when the button is pressed, and records which video was shown as isElderVideo.

スクリーンショット 2026-02-12 020601

Configure SafeRoadCheckPoint

Select the in-scene game object SafeRoadCheckPoint and find its On Collide Item Trigger component.

  1. Click the + button 3 times to add 3 triggers, and set the values as shown in the figure below.
  2. Additionally, add the following 2 components:
    • Luida Process Data And Save To Collection Gimmick
    • Luida Upload Collected Data Gimmick

After configuration, it should look like the figure below:

スクリーンショット 2026-02-12 020954

Figure legend:

  • Red squares: Data collection — when this checkpoint is passed, record isSafeRoad=true
  • Yellow squares: Save data trigger and gimmick — when this checkpoint is passed, save data to collection
  • Green squares: Upload data trigger and gimmick — when this checkpoint is passed, upload collected data

Configure DangerousRoadCheckPoint

Select the in-scene game object DangerousRoadCheckPoint and configure it with the same components and triggers as SafeRoadCheckPoint.

The only difference: Set the value of isSafeRoad to false.

スクリーンショット 2026-02-12 020959

Edit the LUIDA-DataCollector Script

Select the in-scene game object LUIDA-DataCollector and double-click the Script Asset in its Inspector component (see figure below). The script editing screen will open.

スクリーンショット 2026-02-12 030242

Replace the contents with the following script and save the file:

return {
    video: $.getStateCompat("global", "isElderVideo", "boolean") ? "Elder" : "Young", // Which video was shown
    road: $.getStateCompat("global", "isSafeRoad", "boolean") ? "Safe" : "Danger", // Which bridge was crossed
};

This script defines the format of the collected data. It retrieves the isElderVideo and isSafeRoad values sent to Global via CCK components using $.getStateCompat.

Add a Questionnaire
  1. Right-click in the Hierarchy window and select LUIDA > Questionnaire.
  2. In the dialog that appears, enter 1 for qID and press the Create button.

A questionnaire game object will be generated.

  1. Click the generated questionnaire object and add the following components in the Inspector:
    • Global Logic
    • Set Game Object Active Gimmick
  2. Set the values of the added components as shown in the figure below.
スクリーンショット 2026-02-12 022700

This configuration makes the questionnaire automatically hide itself after the participant finishes answering it.

4. Preparation Before Uploading

Follow the steps below to configure
  1. Open Cluster > Settings from Unity's menu bar and check "Use beta features". Enable beta features
  2. Local test play: Press the play button in Unity Editor to verify that the entire experiment flow (video playback, bridge selection, questionnaire display, etc.) works as intended.
  3. Save the scene.

5. Upload to cluster

Follow the steps below to configure
  1. Follow the official cluster documentation Steps to upload a world to upload the created scene as a cluster world.
    • After uploading, enter the world yourself and experience the entire experiment as a participant to verify operation.
    • At this point, normal avatar selection is available, but once you configure avatar settings in the LUIDA web console (described later) and the experiment is officially published, participants will join with the specified avatar (or hidden avatar).
  2. If bugs are found after uploading, we recommend using the "test upload" feature after fixing in the Unity project to verify in cluster's Test Space. This allows testing without affecting the published world.
    • Once fixes are complete and verified in the test space, perform the normal world upload again.
  3. Along with verifying operation in the cluster world, check the LUIDA web console to confirm that experiment data (questionnaire responses, other configured log data, etc.) is correctly recorded and displayed. Data verification example in web console

6. Register World ID

Follow the steps below to configure
  1. Log in to the cluster official website in your web browser and verify that the uploaded experiment world appears in the list on the "My Content" page (or "World" management screen).
  2. Select the relevant world and open the world details page. The alphanumeric string at the end of the page URL is the World ID (e.g., the XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX part of https://cluster.mu/w/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX). Copy this World ID. World verification on cluster My Content screen
  3. Open the experiment information edit screen on the LUIDA web console and register/save the copied World ID in the designated field (e.g., "World ID"). World ID registration in web console

7. Avatar Settings

Follow the steps below to configure

For the experiment in this tutorial, you don't need to configure participant avatars, but if you want to hide avatars or use specific avatars for the experiment, follow these steps:

  1. In the LUIDA web console, click the "Add World-Avatar Set" button in the Avatar Settings section on the experiment settings page.

  2. Enter the experiment world ID you registered earlier in the World ID field.

  3. Configure one of the following and click "Submit" to save:

    • To hide avatars: Only check Hide Avatar. Other fields can be left empty.
    • To specify a particular avatar: Only check Assign Avatar and enter/upload the following information:
      • Avatar Name: Avatar name (for management)
      • VRM Version: VRM model version to use (e.g., 0.x or 1.0)
      • Upload VRM: Avatar VRM file
      • Upload Thumbnail (PNG): Avatar thumbnail image (PNG format recommended)

    Avatar settings screen in LUIDA web console

8. Wait for Publication on LUIDA

Once all the above settings are complete, your experiment is ready to be listed on the LUIDA participant recruitment world. Please allow a few days for publication.

*Note: In the future, we plan to improve LUIDA's experiment information update process so that newly registered experiments can be published more quickly (e.g., within one day).